interface/wx/propdlg.h

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