interface/propdlg.h

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