interface/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     @wxheader{propdlg.h}
  62
  63     This class represents a property sheet dialog: a tabbed dialog
  64     for showing settings. It is optimized to show flat tabs
  65     on PocketPC devices, and can be customized to use different
  66     controllers instead of the default notebook style.
  67
  68     To use this class, call Create() from your own Create function.
  69     Then call CreateButtons(), and create pages, adding them to the book control.
  70     Finally call LayoutDialog().
  71
  72     For example:
  73
  74     @code
  75     bool MyPropertySheetDialog::Create(...)
  76     {
  77         if (!wxPropertySheetDialog::Create(...))
  78             return @false;
  79
  80         CreateButtons(wxOK|wxCANCEL|wxHELP);
  81
  82         // Add page
  83         wxPanel* panel = new wxPanel(GetBookCtrl(), ...);
  84         GetBookCtrl()->AddPage(panel, wxT("General"));
  85
  86         LayoutDialog();
  87         return @true;
  88     }
  89     @endcode
  90
  91     If necessary, override CreateBookCtrl() and AddBookCtrl() to create and add a
  92     different kind of book control. You will then need to use two-step construction
  93     for the dialog or change the style of the book control by calling SetSheetStyle()
  94     before calling Create().
  95
  96     The @ref page_samples_dialogs shows this class being used with notebook and toolbook
  97     controllers (for Windows-style and Mac-style settings dialogs).
  98
  99     To make pages of the dialog scroll when the display is too small to fit the
 100     whole dialog, you can switch layout adaptation on globally with
 101     wxDialog::EnableLayoutAdaptation() or per dialog with
 102     wxDialog::SetLayoutAdaptationMode().
 103
 104     For more about layout adaptation, see @ref overview_dialog_autoscrolling.
 105
 106     @library{wxadv}
 107     @category{managedwnd}
 108 */
 109 class wxPropertySheetDialog : public wxDialog
 110 {
 111 public:
 112     /**
 113         Constructor.
 114     */
 115     wxPropertySheetDialog(wxWindow* parent, wxWindowID id,
 116                           const wxString& title,
 117                           const wxPoint& pos = wxDefaultPosition,
 118                           const wxSize& size = wxDefaultSize,
 119                           long style = wxDEFAULT_DIALOG_STYLE,
 120                           const wxString& name = "dialogBox");
 121
 122     /**
 123         Override this if you wish to add the book control in a way different from the
 124         standard way (for example, using different spacing).
 125     */
 126     virtual void AddBookCtrl(wxSizer* sizer);
 127
 128     /**
 129         Call this from your own Create function, before adding buttons and pages.
 130     */
 131     bool Create(wxWindow* parent, wxWindowID id,
 132                 const wxString& title,
 133                 const wxPoint& pos = wxDefaultPosition,
 134                 const wxSize& size = wxDefaultSize,
 135                 long style = wxDEFAULT_DIALOG_STYLE,
 136                 const wxString& name = "dialogBox");
 137
 138     /**
 139         Override this if you wish to create a different kind of book control; by
 140         default, the value passed to SetSheetStyle() is used to determine the control.
 141
 142         The default behaviour is to create a notebook except on Smartphone, where a
 143         choicebook is used.
 144     */
 145     virtual wxBookCtrlBase* CreateBookCtrl();
 146
 147     /**
 148         Call this to create the buttons for the dialog.
 149         This calls wxDialog::CreateButtonSizer(), and the flags are the same.
 150
 151         @note On PocketPC, no buttons are created.
 152     */
 153     void CreateButtons(int flags = wxOK|wxCANCEL);
 154
 155     /**
 156         Returns the book control that will contain your settings pages.
 157     */
 158     wxBookCtrlBase* GetBookCtrl() const;
 159
 160     /**
 161         Returns the inner sizer that contains the book control and button sizer.
 162     */
 163     wxSizer* GetInnerSizer() const;
 164
 165     /**
 166         Returns the sheet style.
 167
 168         See SetSheetStyle() for allowed values.
 169     */
 170     long GetSheetStyle() const;
 171
 172     /**
 173         Call this to lay out the dialog.
 174
 175         @note On PocketPC, this does nothing, since the dialog will be shown full-screen,
 176               and the layout will be done when the dialog receives a size event.
 177     */
 178     void LayoutDialog(int centreFlags = wxBOTH);
 179
 180     /**
 181         Sets the book control used for the dialog.
 182
 183         You will normally not need to use this.
 184     */
 185     void SetBookCtrl(wxBookCtrlBase* bookCtrl);
 186
 187     /**
 188         Sets the inner sizer that contains the book control and button sizer.
 189
 190         You will normally not need to use this.
 191     */
 192     void SetInnerSizer(wxSizer* sizer);
 193
 194     /**
 195         You can customize the look and feel of the dialog by setting the sheet style.
 196         It is a bit list of the ::wxPropertySheetDialogFlags values.
 197     */
 198     void SetSheetStyle(long style);
 199 };
 200