interface/wx/propdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        propdlg.h
   3 // Purpose:     interface of wxPropertySheetDialog
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     Values used by wxPropertySheetDialog::SetSheetStyle
  12 */
  13 enum wxPropertySheetDialogFlags
  14 {
  15     /**
  16         Uses the default look and feel for the controller window,
  17         normally a notebook except on Smartphone where a choice control is used.
  18     */
  19     wxPROPSHEET_DEFAULT = 0x0001,
  20
  21     /**
  22         Uses a notebook for the controller window.
  23     */
  24     wxPROPSHEET_NOTEBOOK = 0x0002,
  25
  26     /**
  27         Uses a toolbook for the controller window.
  28     */
  29     wxPROPSHEET_TOOLBOOK = 0x0004,
  30
  31     /**
  32         Uses a choicebook for the controller window.
  33     */
  34     wxPROPSHEET_CHOICEBOOK = 0x0008,
  35
  36     /**
  37         Uses a listbook for the controller window.
  38     */
  39     wxPROPSHEET_LISTBOOK = 0x0010,
  40
  41     /**
  42         Uses a button toolbox for the controller window.
  43     */
  44     wxPROPSHEET_BUTTONTOOLBOOK = 0x0020,
  45
  46     /**
  47         Uses a treebook for the controller window.
  48     */
  49     wxPROPSHEET_TREEBOOK = 0x0040,
  50
  51     /**
  52         Shrinks the dialog window to fit the currently selected page
  53         (common behaviour for property sheets on Mac OS X).
  54     */
  55     wxPROPSHEET_SHRINKTOFIT = 0x0100,
  56 };
  57
  58
  59 /**
  60     @class wxPropertySheetDialog
  61
  62     This class represents a property sheet dialog: a tabbed dialog
  63     for showing settings. It is optimized to show flat tabs
  64     on PocketPC devices, and can be customized to use different
  65     controllers instead of the default notebook style.
  66
  67     To use this class, call Create() from your own Create function.
  68     Then call CreateButtons(), and create pages, adding them to the book control.
  69     Finally call LayoutDialog().
  70
  71     For example:
  72
  73     @code
  74     bool MyPropertySheetDialog::Create(...)
  75     {
  76         if (!wxPropertySheetDialog::Create(...))
  77             return false;
  78
  79         CreateButtons(wxOK|wxCANCEL|wxHELP);
  80
  81         // Add page
  82         wxPanel* panel = new wxPanel(GetBookCtrl(), ...);
  83         GetBookCtrl()->AddPage(panel, wxT("General"));
  84
  85         LayoutDialog();
  86         return true;
  87     }
  88     @endcode
  89
  90     If necessary, override CreateBookCtrl() and AddBookCtrl() to create and add a
  91     different kind of book control. You will then need to use two-step construction
  92     for the dialog or change the style of the book control by calling SetSheetStyle()
  93     before calling Create().
  94
  95     The @ref page_samples_dialogs shows this class being used with notebook and toolbook
  96     controllers (for Windows-style and Mac-style settings dialogs).
  97
  98     To make pages of the dialog scroll when the display is too small to fit the
  99     whole dialog, you can switch layout adaptation on globally with
 100     wxDialog::EnableLayoutAdaptation() or per dialog with
 101     wxDialog::SetLayoutAdaptationMode().
 102
 103     For more about layout adaptation, see @ref overview_dialog_autoscrolling.
 104
 105     @library{wxadv}
 106     @category{managedwnd}
 107 */
 108 class wxPropertySheetDialog : public wxDialog
 109 {
 110 public:
 111     /**
 112         Constructor.
 113     */
 114     wxPropertySheetDialog(wxWindow* parent, wxWindowID id,
 115                           const wxString& title,
 116                           const wxPoint& pos = wxDefaultPosition,
 117                           const wxSize& size = wxDefaultSize,
 118                           long style = wxDEFAULT_DIALOG_STYLE,
 119                           const wxString& name = "dialogBox");
 120
 121     /**
 122         Override this if you wish to add the book control in a way different from the
 123         standard way (for example, using different spacing).
 124     */
 125     virtual void AddBookCtrl(wxSizer* sizer);
 126
 127     /**
 128         Call this from your own Create function, before adding buttons and pages.
 129     */
 130     bool Create(wxWindow* parent, wxWindowID id,
 131                 const wxString& title,
 132                 const wxPoint& pos = wxDefaultPosition,
 133                 const wxSize& size = wxDefaultSize,
 134                 long style = wxDEFAULT_DIALOG_STYLE,
 135                 const wxString& name = "dialogBox");
 136
 137     /**
 138         Override this if you wish to create a different kind of book control; by
 139         default, the value passed to SetSheetStyle() is used to determine the control.
 140
 141         The default behaviour is to create a notebook except on Smartphone, where a
 142         choicebook is used.
 143     */
 144     virtual wxBookCtrlBase* CreateBookCtrl();
 145
 146     /**
 147         Call this to create the buttons for the dialog.
 148         This calls wxDialog::CreateButtonSizer(), and the flags are the same.
 149
 150         @note On PocketPC, no buttons are created.
 151     */
 152     virtual void CreateButtons(int flags = wxOK|wxCANCEL);
 153
 154     /**
 155         Returns the book control that will contain your settings pages.
 156     */
 157     wxBookCtrlBase* GetBookCtrl() const;
 158
 159     /**
 160         Returns the inner sizer that contains the book control and button sizer.
 161     */
 162     wxSizer* GetInnerSizer() const;
 163
 164     /**
 165         Returns the sheet style.
 166
 167         See SetSheetStyle() for allowed values.
 168     */
 169     long GetSheetStyle() const;
 170
 171     /**
 172         Call this to lay out the dialog.
 173
 174         @note On PocketPC, this does nothing, since the dialog will be shown full-screen,
 175               and the layout will be done when the dialog receives a size event.
 176     */
 177     virtual void LayoutDialog(int centreFlags = wxBOTH);
 178
 179     /**
 180         Sets the book control used for the dialog.
 181
 182         You will normally not need to use this.
 183     */
 184     void SetBookCtrl(wxBookCtrlBase* bookCtrl);
 185
 186     /**
 187         Sets the inner sizer that contains the book control and button sizer.
 188
 189         You will normally not need to use this.
 190     */
 191     void SetInnerSizer(wxSizer* sizer);
 192
 193     /**
 194         You can customize the look and feel of the dialog by setting the sheet style.
 195         It is a bit list of the ::wxPropertySheetDialogFlags values.
 196     */
 197     void SetSheetStyle(long style);
 198 };
 199