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

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.