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 licence
   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, "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 = wxDialogNameStr);
 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, const wxString& title,
 131                 const wxPoint& pos = wxDefaultPosition,
 132                 const wxSize& size = wxDefaultSize,
 133                 long style = wxDEFAULT_DIALOG_STYLE,
 134                 const wxString& name = wxDialogNameStr);
 135
 136     /**
 137         Override this if you wish to create a different kind of book control; by
 138         default, the value passed to SetSheetStyle() is used to determine the control.
 139
 140         The default behaviour is to create a notebook except on Smartphone, where a
 141         choicebook is used.
 142     */
 143     virtual wxBookCtrlBase* CreateBookCtrl();
 144
 145     /**
 146         Call this to create the buttons for the dialog.
 147         This calls wxDialog::CreateButtonSizer(), and the flags are the same.
 148
 149         @note On PocketPC, no buttons are created.
 150     */
 151     virtual void CreateButtons(int flags = wxOK|wxCANCEL);
 152
 153     /**
 154         Returns the book control that will contain your settings pages.
 155     */
 156     wxBookCtrlBase* GetBookCtrl() const;
 157
 158     /**
 159         Returns the inner sizer that contains the book control and button sizer.
 160     */
 161     wxSizer* GetInnerSizer() const;
 162
 163     /**
 164         Returns the sheet style.
 165
 166         See SetSheetStyle() for allowed values.
 167     */
 168     long GetSheetStyle() const;
 169
 170     /**
 171         Call this to lay out the dialog.
 172
 173         @note On PocketPC, this does nothing, since the dialog will be shown full-screen,
 174               and the layout will be done when the dialog receives a size event.
 175     */
 176     virtual void LayoutDialog(int centreFlags = wxBOTH);
 177
 178     /**
 179         Sets the book control used for the dialog.
 180
 181         You will normally not need to use this.
 182     */
 183     void SetBookCtrl(wxBookCtrlBase* bookCtrl);
 184
 185     /**
 186         You can customize the look and feel of the dialog by setting the sheet style.
 187         It is a bit list of the ::wxPropertySheetDialogFlags values.
 188     */
 189     void SetSheetStyle(long style);
 190 };
 191