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

diff --git a/build/bakefiles/files.bkl b/build/bakefiles/files.bkl
index a94e44478f8a44690753906b5bcd9ad95c1cae9c..51e1d571db5e21ac0242868891224bc91e58d2c0 100644 (file)
--- a/build/bakefiles/files.bkl
+++ b/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/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
     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/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/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
     wx/sashwin.h
     wx/sound.h
     wx/splash.h

diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex
index 367f939a6f66291d32c9654a3be5d5602ef142dc..4a96e517ffba322dce698a6934f3d4bc59b4b9b1 100644 (file)
--- a/docs/latex/wx/category.tex
+++ b/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{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}
 %\twocolitem{\helpref{wxTabbedDialog}{wxtabbeddialog}}{Tabbed dialog
 %(deprecated, use wxNotebook instead)}
 \twocolitem{\helpref{wxTipWindow}{wxtipwindow}}{Shows text in a small window}

diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index 10b9d36ec92e146267a53836b629fc77a73c8757..c06621e332594724a264db051f281222bfff5638 100644 (file)
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -250,6 +250,7 @@
 \input process.tex
 \input procevt.tex
 \input progdlg.tex
 \input process.tex
 \input procevt.tex
 \input progdlg.tex

+\input propdlg.tex

 \input protocol.tex
 \input quantize.tex
 \input qylayevt.tex
 \input protocol.tex
 \input quantize.tex
 \input qylayevt.tex

diff --git a/docs/latex/wx/propdlg.tex b/docs/latex/wx/propdlg.tex
new file mode 100644 (file)
index 0000000..a7e3c42
--- /dev/null
+++ b/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.
+

diff --git a/docs/latex/wx/wxmsw.tex b/docs/latex/wx/wxmsw.tex
index 3388eacf53f3d10ed24e32a6a355bbfaa496d0b4..c69159ebc097cb5025c0dfca70ad2ff09ee8fe6b 100644 (file)
--- a/docs/latex/wx/wxmsw.tex
+++ b/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
 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.
 
 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.
 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.
 \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.

diff --git a/include/wx/generic/propdlg.h b/include/wx/generic/propdlg.h
new file mode 100644 (file)
index 0000000..9559d8d
--- /dev/null
+++ b/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_
+

diff --git a/include/wx/propdlg.h b/include/wx/propdlg.h
new file mode 100644 (file)
index 0000000..72116b7
--- /dev/null
+++ b/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_
+

diff --git a/src/generic/propdlg.cpp b/src/generic/propdlg.cpp
new file mode 100644 (file)
index 0000000..90b72aa
--- /dev/null
+++ b/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
+}
+