Added wxPropertySheetDialog for implementing settings dialogs

in the appropriate way on small devices and desktop platforms
(abstracting is the only way to unify the API)


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@32832 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

build/bakefiles/files.bkl

@@ -2312,6 +2312,7 @@ IMPORTANT: please read docs/tech/tn0016.txt before modifying this file!
     src/generic/gridsel.cpp
     src/generic/helpext.cpp
     src/generic/laywin.cpp
+    src/generic/propdlg.cpp
     src/generic/sashwin.cpp
     src/generic/splash.cpp
     src/generic/tipdlg.cpp
@@ -2329,12 +2330,14 @@ IMPORTANT: please read docs/tech/tn0016.txt before modifying this file!
     wx/generic/gridsel.h
     wx/generic/helpext.h
     wx/generic/laywin.h
+    wx/generic/propdlg.h
     wx/generic/sashwin.h
     wx/generic/splash.h
     wx/generic/wizard.h
     wx/grid.h
     wx/joystick.h
     wx/laywin.h
+    wx/propdlg.h
     wx/sashwin.h
     wx/sound.h
     wx/splash.h

docs/latex/wx/category.tex

@@ -19,6 +19,7 @@ Frames and dialogs are similar in wxWidgets, but only dialogs may be modal.
 \twocolitem{\helpref{wxMDIParentFrame}{wxmdiparentframe}}{MDI parent frame}
 \twocolitem{\helpref{wxMiniFrame}{wxminiframe}}{A frame with a small title bar}
 \twocolitem{\helpref{wxSplashScreen}{wxsplashscreen}}{Splash screen class}
+\twocolitem{\helpref{wxPropertySheetDialog}{wxpropertysheetdialog}}{Property sheet dialog}
 %\twocolitem{\helpref{wxTabbedDialog}{wxtabbeddialog}}{Tabbed dialog
 %(deprecated, use wxNotebook instead)}
 \twocolitem{\helpref{wxTipWindow}{wxtipwindow}}{Shows text in a small window}

docs/latex/wx/classes.tex

@@ -250,6 +250,7 @@
 \input process.tex
 \input procevt.tex
 \input progdlg.tex
+\input propdlg.tex
 \input protocol.tex
 \input quantize.tex
 \input qylayevt.tex

docs/latex/wx/propdlg.tex

@@ -0,0 +1,120 @@
+\section{\class{wxPropertySheetDialog}}\label{wxpropertysheetdialog}
+
+This class represents a property sheet dialog: a tabbed dialog
+for showing settings. It is optimized to show with flat tabs
+on PocketPC devices.
+
+To use this class, call \helpref{wxPropertySheetDialog::Create}{wxpropertysheetdialogcreate} from your own
+Create function. Then call \helpref{CreateButtons}{wxpropertysheetdialogcreatebuttons}, and create pages, adding them to the book control.
+Finally call \helpref{LayoutDialog}{wxpropertysheetdialoglayoutdialog}.
+
+For example:
+
+\begin{verbatim}
+bool MyPropertySheetDialog::Create(...)
+{
+    if (!wxPropertySheetDialog::Create(...))
+        return false;
+
+    CreateButtons(wxOK|wxCANCEL|wxHELP);
+
+    // Add page
+    wxPanel* panel = new wxPanel(GetBookCtrl(), ...);
+    GetBookCtrl()->AddPage(panel, wxT("General"));
+
+    LayoutDialog();
+    return true;
+}
+\end{verbatim}
+
+If necessary, override CreateBookCtrl and AddBookCtrl to create and add a different
+kind of book control. You would then need to use two-step construction for the dialog.
+
+\wxheading{Derived from}
+
+\helpref{wxDialog}{wxdialog}\\
+\helpref{wxWindow}{wxwindow}\\
+\helpref{wxEvtHandler}{wxevthandler}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/propdlg.h>
+<wx/generic/propdlg.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxPropertySheetDialog::wxPropertySheetDialog}\label{wxpropertysheetdialogctor}
+
+\func{}{wxPropertySheetDialog}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
+\param{const wxString\& }{title},\rtfsp
+\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
+\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
+\param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
+\param{const wxString\& }{name = ``dialogBox"}}
+
+Constructor.
+
+\membersection{wxPropertySheetDialog::AddBookCtrl}\label{wxpropertysheetdialogaddbookctrl}
+
+\func{virtual void}{AddBookCtrl}{\param{wxSizer* }{sizer}}
+
+Override this if you wish to add the book control in a way different from the
+standard way (for example, using different spacing).
+
+\membersection{wxPropertySheetDialog::Create}\label{wxpropertysheetdialogcreate}
+
+\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
+\param{const wxString\& }{title},\rtfsp
+\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
+\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
+\param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
+\param{const wxString\& }{name = ``dialogBox"}}
+
+Call this from your own Create function, before adding buttons and pages.
+
+\membersection{wxPropertySheetDialog::CreateBookCtrl}\label{wxpropertysheetdialogcreatebookctrl}
+
+\func{virtual wxBookCtrlBase*}{CreateBookCtrl}{\void}
+
+Override this if you wish to create a different kind of book control; by default, a wxNotebook
+is created.
+
+\membersection{wxPropertySheetDialog::CreateButtons}\label{wxpropertysheetdialogcreatebuttons}
+
+\func{void}{CreateButtons}{\param{int }{flags=wxOK|wxCANCEL}}
+
+Call this to create the buttons for the dialog. This calls \helpref{wxDialog::CreateButtonSizer}{wxdialogcreatebuttonsizer}, and
+the flags are the same. On PocketPC, no buttons are created.
+
+\membersection{wxPropertySheetDialog::GetBookCtrl}\label{wxpropertysheetdialoggetbookctrl}
+
+\constfunc{wxBookCtrlBase*}{GetBookCtrl}{\void}
+
+Returns the book control that will contain your settings pages.
+
+\membersection{wxPropertySheetDialog::GetInnerSizer}\label{wxpropertysheetdialoggetinnersizer}
+
+\constfunc{wxSizer*}{GetInnerSizer}{\void}
+
+Returns the inner sizer that contains the book control and button sizer.
+
+\membersection{wxPropertySheetDialog::LayoutDialog}\label{wxpropertysheetdialoglayoutdialog}
+
+\func{void}{LayoutDialog}{\void}
+
+Call this to lay out the dialog. On PocketPC, this does nothing, since the dialog will be shown
+full-screen, and the layout will be done when the dialog receives a size event.
+
+\membersection{wxPropertySheetDialog::SetBookCtrl}\label{wxpropertysheetdialogsetbookctrl}
+
+\func{void}{SetBookCtrl}{\param{wxBookCtrlBase* }{bookCtrl}}
+
+Sets the book control used for the dialog. You will normally not need to use this.
+
+\membersection{wxPropertySheetDialog::SetInnerSizer}\label{wxpropertysheetdialogsetinnersizer}
+
+\func{void}{SetInnerSizer}{\param{wxSizer*}{ sizer}}
+
+Sets the inner sizer that contains the book control and button sizer. You will normally not need to use this.
+

docs/latex/wx/wxmsw.tex

@@ -113,8 +113,8 @@ and wxTopLevelWindow::SetRightMenu, for example:
 For implementing property sheets (flat tabs), use a wxNotebook with wxNB_FLAT|wxNB_BOTTOM
 and have the notebook left, top and right sides overlap the dialog by about 3 pixels
 to eliminate spurious borders. You can do this by using a negative spacing in your
-sizer Add() call. A cross-platform property sheet dialog will be implemented in the
-future, so you only need to provide the dialog's pages.
+sizer Add() call. The cross-platform property sheet dialog \helpref{wxPropertySheetDialog}{wxpropertysheetdialog} is
+provided, to show settings in the correct style on PocketPC and on other platforms.
 
 Notifications (bubble HTML text with optional buttons and links) will also be
 implemented in the future for PocketPC.
@@ -170,8 +170,6 @@ standard identifiers can be used.
 needs to be simplified (and speeded up).
 \item {\bf Sizer speed.} Particularly for dialogs containing notebooks,
 layout seems slow. Some analysis is required.
-\item {\bf Property sheets.} We should have a class for handling property sheets
-on WinCE and desktop platforms (see previous section on dialogs).
 \item {\bf Notification boxes.} The balloon-like notification messages, and their
 icons, should be implemented. This will be quite straightforward.
 \item {\bf WM\_SETTINGCHANGE.} This message needs to be handled by calling SHHandleWMSettingChange.

include/wx/generic/propdlg.h

@@ -0,0 +1,111 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        wx/generic/propdlg.h
+// Purpose:     wxPropertySheetDialog
+// Author:      Julian Smart
+// Modified by:
+// Created:     2005-03-12
+// RCS-ID:      $Id$
+// Copyright:   (c) Julian Smart
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+#ifndef _WX_PROPDLG_H_
+#define _WX_PROPDLG_H_
+
+#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
+#pragma interface "propdlg.h"
+#endif
+
+class WXDLLEXPORT wxBookCtrlBase;
+
+//-----------------------------------------------------------------------------
+// wxPropertySheetDialog
+// A platform-independent properties dialog.
+//
+//   * on PocketPC, a flat-look 'property sheet' notebook will be used, with
+//     no OK/Cancel/Help buttons
+//   * on other platforms, a normal notebook will be used, with standard buttons
+//
+// To use this class, call Create from your derived class.
+// Then create pages and add to the book control. Finally call CreateButtons and
+// LayoutDialog.
+//
+// For example:
+//
+// MyPropertySheetDialog::Create(...)
+// {
+//     wxPropertySheetDialog::Create(...);
+//
+//     // Add page
+//     wxPanel* panel = new wxPanel(GetBookCtrl(), ...);
+//     GetBookCtrl()->AddPage(panel, wxT("General"));
+//
+//     CreateButtons();
+//     LayoutDialog();
+// }
+//
+// Override CreateBookCtrl and AddBookCtrl to create and add a different
+// kind of book control.
+//-----------------------------------------------------------------------------
+
+class WXDLLEXPORT wxPropertySheetDialog : public wxDialog
+{
+public:
+    wxPropertySheetDialog() : wxDialog() { Init(); }
+
+    wxPropertySheetDialog(wxWindow* parent, wxWindowID id,
+                       const wxString& title,
+                       const wxPoint& pos = wxDefaultPosition,
+                       const wxSize& sz = wxDefaultSize,
+                       long style = wxDEFAULT_DIALOG_STYLE,
+                       const wxString& name = wxDialogNameStr)
+    {
+        Init();
+        Create(parent, id, title, pos, sz, style, name);
+    }
+
+    bool Create(wxWindow* parent, wxWindowID id,
+                       const wxString& title,
+                       const wxPoint& pos = wxDefaultPosition,
+                       const wxSize& sz = wxDefaultSize,
+                       long style = wxDEFAULT_DIALOG_STYLE,
+                       const wxString& name = wxDialogNameStr);
+
+    void Init();
+
+//// Accessors
+
+    // Set and get the notebook
+    void SetBookCtrl(wxBookCtrlBase* book) { m_bookCtrl = book; }
+    wxBookCtrlBase* GetBookCtrl() const { return m_bookCtrl; }
+
+    // Set and get the inner sizer
+    void SetInnerSize(wxSizer* sizer) { m_innerSizer = sizer; }
+    wxSizer* GetInnerSizer() const { return m_innerSizer ; }
+
+/// Operations
+
+    // Creates the buttons (none on PocketPC)
+    virtual void CreateButtons(int flags = wxOK|wxCANCEL);
+
+    // Lay out the dialog, to be called after pages have been created
+    virtual void LayoutDialog();
+
+/// Implementation
+
+    // Creates the book control. If you want to use a different kind of
+    // control, override.
+    virtual wxBookCtrlBase* CreateBookCtrl();
+
+    // Adds the book control to the inner sizer.
+    virtual void AddBookCtrl(wxSizer* sizer);
+
+protected:
+    wxBookCtrlBase* m_bookCtrl;
+    wxSizer*        m_innerSizer; // sizer for extra space
+
+    DECLARE_DYNAMIC_CLASS(wxPropertySheetDialog)
+};
+
+#endif // _WX_PROPDLG_H_
+

include/wx/propdlg.h

@@ -0,0 +1,8 @@
+#ifndef _WX_PROPDLG_H_BASE_
+#define _WX_PROPDLG_H_BASE_
+
+#include "wx/generic/propdlg.h"
+
+#endif
+    // _WX_PROPDLG_H_BASE_
+

src/generic/propdlg.cpp

@@ -0,0 +1,112 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        propdlg.cpp
+// Purpose:     wxPropertySheetDialog
+// Author:      Julian Smart
+// Modified by:
+// Created:     2005-03-12
+// RCS-ID:      $Id$
+// Copyright:   (c) Julian Smart
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
+#pragma implementation "propdlg.h"
+#endif
+
+// For compilers that support precompilation, includes "wx.h".
+#include "wx/wxprec.h"
+
+#ifdef __BORLANDC__
+#pragma hdrstop
+#endif
+
+#include "wx/defs.h"
+
+#ifndef WX_PRECOMP
+    #include "wx/button.h"
+    #include "wx/sizer.h"
+    #include "wx/intl.h"
+    #include "wx/log.h"
+    #include "wx/msgdlg.h"
+#endif
+
+#include "wx/notebook.h"
+#include "wx/generic/propdlg.h"
+
+//-----------------------------------------------------------------------------
+// wxPropertySheetDialog
+//-----------------------------------------------------------------------------
+
+IMPLEMENT_DYNAMIC_CLASS(wxPropertySheetDialog, wxDialog)
+
+bool wxPropertySheetDialog::Create(wxWindow* parent, wxWindowID id, const wxString& title, 
+                                       const wxPoint& pos, const wxSize& sz, long style,
+                                       const wxString& name)
+{
+    if (!wxDialog::Create(parent, id, title, pos, sz, style, name))
+        return false;
+    
+    wxBoxSizer *topSizer = new wxBoxSizer( wxVERTICAL );
+    SetSizer(topSizer);
+
+    // This gives more space around the edges
+    m_innerSizer = new wxBoxSizer( wxVERTICAL );
+
+    int extraSpace = 5;
+#ifdef __WXWINCE__
+    extraSpace=0;
+#endif
+    topSizer->Add(m_innerSizer, 1, wxGROW|wxALL, extraSpace);
+
+    m_bookCtrl = CreateBookCtrl();
+    AddBookCtrl(m_innerSizer);
+
+    return true;
+}
+
+void wxPropertySheetDialog::Init()
+{
+    m_innerSizer = NULL;
+    m_bookCtrl = NULL;
+}
+
+// Layout the dialog, to be called after pages have been created
+void wxPropertySheetDialog::LayoutDialog()
+{
+#ifndef __WXWINCE__
+    GetSizer()->Fit(this);
+    Centre(wxBOTH);
+#endif
+}
+
+// Creates the buttons, if any
+void wxPropertySheetDialog::CreateButtons(int flags)
+{
+#ifndef __WXWINCE__
+    wxSizer* sizer = CreateButtonSizer(flags);
+    m_innerSizer->Add( sizer, 0, wxGROW|wxALIGN_CENTER_VERTICAL|wxTOP|wxBOTTOM, 5);
+#endif
+}
+
+// Creates the book control
+wxBookCtrlBase* wxPropertySheetDialog::CreateBookCtrl()
+{
+    int style = 0;
+#ifdef __WXWINCE__
+    style |= wxNB_BOTTOM|wxNB_FLAT;
+#endif
+    return new wxNotebook(this, wxID_ANY, wxDefaultPosition, wxDefaultSize, style );
+}
+
+// Adds the book control to the inner sizer.
+void wxPropertySheetDialog::AddBookCtrl(wxSizer* sizer)
+{
+#ifdef __WXWINCE__
+    // The book control has to be sized larger than the dialog because of a border bug
+    // in WinCE
+    sizer->Add( m_bookCtrl, 1, wxGROW|wxALIGN_CENTER_VERTICAL|wxLEFT|wxTOP|wxRIGHT, -3 );
+#else
+    sizer->Add( m_bookCtrl, 1, wxGROW|wxALIGN_CENTER_VERTICAL|wxALL, 5 );
+#endif
+}
+