interface/wx/wizard.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wizard.h
   3 // Purpose:     interface of wxWizardPage, wxWizardEvent,
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxWizardPage
  11
  12     wxWizardPage is one of the screens in wxWizard: it must know what are the
  13     following and preceding pages (which may be @NULL for the first/last page).
  14     Except for this extra knowledge, wxWizardPage is just a
  15     panel, so the controls may be placed directly on it in the usual way.
  16
  17     This class allows the programmer to decide the order of pages in the wizard
  18     dynamically (during run-time) and so provides maximal flexibility.
  19     Usually, however, the order of pages is known in advance in which case
  20     wxWizardPageSimple class is enough and it is simpler to use.
  21
  22
  23     @section wizardpage_virtuals Virtual functions to override
  24
  25     To use this class, you must override wxWizardPage::GetPrev() and
  26     wxWizardPage::GetNext() pure virtual functions (or you may use
  27     wxWizardPageSimple instead).
  28     wxWizardPage::GetBitmap() can also be overridden, but this should be very
  29     rarely needed.
  30
  31     @library{wxadv}
  32     @category{miscwnd}
  33
  34     @see wxWizard, @ref page_samples_wizard
  35 */
  36 class wxWizardPage : public wxPanel
  37 {
  38 public:
  39     /**
  40         Constructor accepts an optional bitmap which will be used for this page
  41         instead of the default one for this wizard (note that all bitmaps used should
  42         be of the same size). Notice that no other parameters are needed because the
  43         wizard will resize and reposition the page anyhow.
  44
  45         @param parent
  46             The parent wizard
  47         @param bitmap
  48             The page-specific bitmap if different from the global one
  49     */
  50     wxWizardPage(wxWizard* parent,
  51                  const wxBitmap& bitmap = wxNullBitmap);
  52
  53     /**
  54         This method is called by wxWizard to get the bitmap to display alongside the page.
  55         By default, @c m_bitmap member variable which was set in the
  56         @ref wxWizardPage() constructor.
  57
  58         If the bitmap was not explicitly set (i.e. if ::wxNullBitmap is returned),
  59         the default bitmap for the wizard should be used.
  60
  61         The only cases when you would want to override this function is if the page
  62         bitmap depends dynamically on the user choices, i.e. almost never.
  63     */
  64     wxBitmap GetBitmap() const;
  65
  66     /**
  67         Get the page which should be shown when the user chooses the @c "Next"
  68         button: if @NULL is returned, this button will be disabled.
  69         The last page of the wizard will usually return @NULL from here, but
  70         the others will not.
  71
  72         @see GetPrev()
  73     */
  74     wxWizardPage* GetNext() const;
  75
  76     /**
  77         Get the page which should be shown when the user chooses the @c "Back"
  78         button: if @NULL is returned, this button will be disabled.
  79         The first page of the wizard will usually return @NULL from here, but
  80         the others will not.
  81
  82         @see GetNext()
  83     */
  84     wxWizardPage* GetPrev() const;
  85 };
  86
  87
  88
  89 /**
  90     @class wxWizardEvent
  91
  92     wxWizardEvent class represents an event generated by the wxWizard: this event
  93     is first sent to the page itself and, if not processed there, goes up the
  94     window hierarchy as usual.
  95
  96     @beginEventTable{wxWizardEvent}
  97     @event{EVT_WIZARD_PAGE_CHANGED(id, func)}
  98         The page has been just changed (this event can not be vetoed).
  99     @event{EVT_WIZARD_PAGE_CHANGING(id, func)}
 100         The page is being changed (this event can be vetoed).
 101     @event{EVT_WIZARD_CANCEL(id, func)}
 102         The user attempted to cancel the wizard (this event may also be vetoed).
 103     @event{EVT_WIZARD_HELP(id, func)}
 104         The wizard help button was pressed.
 105     @event{EVT_WIZARD_FINISHED(id, func)}
 106         The wizard finished button was pressed.
 107     @endEventTable
 108
 109     @library{wxadv}
 110     @category{events}
 111
 112     @see wxWizard, @ref page_samples_wizard
 113 */
 114 class wxWizardEvent : public wxNotifyEvent
 115 {
 116 public:
 117     /**
 118         Constructor.
 119
 120         It is not normally used by the user code as the objects of this
 121         type are constructed by wxWizard.
 122     */
 123     wxWizardEvent(wxEventType type = wxEVT_NULL, int id = -1,
 124                   bool direction = true);
 125
 126     /**
 127         Return the direction in which the page is changing: for
 128         @c EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or
 129         @false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if we
 130         came from the previous page and @false if we returned from the next one.
 131     */
 132     bool GetDirection() const;
 133
 134     /**
 135         Returns the wxWizardPage which was active when this event was generated.
 136     */
 137     wxWizardPage* GetPage() const;
 138 };
 139
 140
 141
 142 /**
 143     @class wxWizardPageSimple
 144
 145     wxWizardPageSimple is the simplest possible wxWizardPage implementation:
 146     it just returns the pointers given to its constructor from wxWizardPage::GetNext()
 147     and wxWizardPage::GetPrev() functions.
 148
 149     This makes it very easy to use the objects of this class in the wizards where
 150     the pages order is known statically - on the other hand, if this is not the
 151     case you must derive your own class from wxWizardPage instead.
 152
 153     @library{wxadv}
 154     @category{miscwnd}
 155
 156     @see wxWizard, @ref page_samples_wizard
 157 */
 158 class wxWizardPageSimple : public wxWizardPage
 159 {
 160 public:
 161     /**
 162         Constructor takes the previous and next pages.
 163         They may be modified later by SetPrev() or SetNext().
 164     */
 165     wxWizardPageSimple(wxWizard* parent = NULL,
 166                        wxWizardPage* prev = NULL,
 167                        wxWizardPage* next = NULL,
 168                        const wxBitmap& bitmap = wxNullBitmap);
 169
 170     /**
 171         A convenience function to make the pages follow each other.
 172         Example:
 173
 174         @code
 175         wxRadioboxPage *page3 = new wxRadioboxPage(wizard);
 176         wxValidationPage *page4 = new wxValidationPage(wizard);
 177
 178         wxWizardPageSimple::Chain(page3, page4);
 179         @endcode
 180     */
 181     static void Chain(wxWizardPageSimple* first,
 182                       wxWizardPageSimple* second);
 183
 184     /**
 185         Sets the next page.
 186     */
 187     void SetNext(wxWizardPage* next);
 188
 189     /**
 190         Sets the previous page.
 191     */
 192     void SetPrev(wxWizardPage* prev);
 193 };
 194
 195
 196
 197 /**
 198     @class wxWizard
 199
 200     wxWizard is the central class for implementing 'wizard-like' dialogs.
 201     These dialogs are mostly familiar to Windows users and are nothing other than a
 202     sequence of 'pages', each displayed inside a dialog which has the buttons to
 203     navigate to the next (and previous) pages.
 204
 205     The wizards are typically used to decompose a complex dialog into several
 206     simple steps and are mainly useful to the novice users, hence it is important
 207     to keep them as simple as possible.
 208
 209     To show a wizard dialog, you must first create an instance of the wxWizard class
 210     using either the non-default constructor or a default one followed by call to the
 211     wxWizard::Create function. Then you should add all pages you want the wizard to
 212     show and call wxWizard::RunWizard().
 213     Finally, don't forget to call @c "wizard->Destroy()", otherwise your application
 214     will hang on exit due to an undestroyed window.
 215
 216     You can supply a bitmap to display on the left of the wizard, either for all pages
 217     or for individual pages. If you need to have the bitmap resize to the height of
 218     the wizard, call wxWizard::SetBitmapPlacement() and if necessary,
 219     wxWizard::SetBitmapBackgroundColour() and wxWizard::SetMinimumBitmapWidth().
 220
 221     To make wizard pages scroll when the display is too small to fit the whole
 222     dialog, you can switch layout adaptation on globally with
 223     wxDialog::EnableLayoutAdaptation() or per dialog with wxDialog::SetLayoutAdaptationMode().
 224     For more about layout adaptation, see @ref overview_dialog_autoscrolling.
 225
 226     @beginEventTable{wxWizardEvent}
 227     For some events, Veto() can be called to prevent the event from happening.
 228     @event{EVT_WIZARD_PAGE_CHANGED(id, func)}
 229         The page has just been changed (this event cannot be vetoed).
 230     @event{EVT_WIZARD_PAGE_CHANGING(id, func)}
 231         The page is being changed (this event can be vetoed).
 232     @event{EVT_WIZARD_CANCEL(id, func)}
 233         The user attempted to cancel the wizard (this event may also be vetoed).
 234     @event{EVT_WIZARD_HELP(id, func)}
 235         The wizard help button was pressed.
 236     @event{EVT_WIZARD_FINISHED(id, func)}
 237         The wizard finished button was pressed.
 238     @endEventTable
 239
 240
 241     @section wizard_extstyles Extended styles
 242
 243     Use the wxWindow::SetExtraStyle() function to set the following style.
 244     You will need to use two-step construction (use the default constructor,
 245     call SetExtraStyle(), then call Create).
 246
 247     @beginExtraStyleTable
 248     @style{wxWIZARD_EX_HELPBUTTON}
 249         Shows a Help button using wxID_HELP.
 250     @endExtraStyleTable
 251
 252     See also wxDialog for other extended styles.
 253
 254     @library{wxadv}
 255     @category{cmndlg}
 256
 257     @see wxWizardEvent, wxWizardPage, @ref page_samples_wizard
 258 */
 259 class wxWizard : public wxDialog
 260 {
 261 public:
 262     /**
 263         Default constructor.
 264
 265         Use this if you wish to derive from wxWizard and then call Create(),
 266         for example if you wish to set an extra style with wxWindow::SetExtraStyle()
 267         between the two calls.
 268     */
 269     wxWizard();
 270
 271     /**
 272         Constructor which really creates the wizard -- if you use this constructor, you
 273         shouldn't call Create().
 274
 275         Notice that unlike almost all other wxWidgets classes, there is no @e size
 276         parameter in the wxWizard constructor because the wizard will have a predefined
 277         default size by default.
 278         If you want to change this, you should use the GetPageAreaSizer() function.
 279
 280         @param parent
 281             The parent window, may be @NULL.
 282         @param id
 283             The id of the dialog, will usually be just -1.
 284         @param title
 285             The title of the dialog.
 286         @param bitmap
 287             The default bitmap used in the left side of the wizard. See also GetBitmap().
 288         @param pos
 289             The position of the dialog, it will be centered on the screen by default.
 290         @param style
 291             Window style is passed to wxDialog.
 292     */
 293     wxWizard(wxWindow* parent, int id = -1,
 294              const wxString& title = wxEmptyString,
 295              const wxBitmap& bitmap = wxNullBitmap,
 296              const wxPoint& pos = wxDefaultPosition,
 297              long style = wxDEFAULT_DIALOG_STYLE);
 298
 299     /**
 300         Creates the wizard dialog.
 301         Must be called if the default constructor had been used to create the object.
 302
 303         Notice that unlike almost all other wxWidgets classes, there is no @e size
 304         parameter in the wxWizard constructor because the wizard will have a predefined
 305         default size by default.
 306         If you want to change this, you should use the GetPageAreaSizer() function.
 307
 308         @param parent
 309             The parent window, may be @NULL.
 310         @param id
 311             The id of the dialog, will usually be just -1.
 312         @param title
 313             The title of the dialog.
 314         @param bitmap
 315             The default bitmap used in the left side of the wizard. See also GetBitmap().
 316         @param pos
 317             The position of the dialog, it will be centered on the screen by default.
 318         @param style
 319             Window style is passed to wxDialog.
 320     */
 321     bool Create(wxWindow* parent, int id = -1,
 322                 const wxString& title = wxEmptyString,
 323                 const wxBitmap& bitmap = wxNullBitmap,
 324                 const wxPoint& pos = wxDefaultPosition,
 325                 long style = wxDEFAULT_DIALOG_STYLE);
 326
 327     /**
 328         This method is obsolete, use GetPageAreaSizer() instead.
 329
 330         Sets the page size to be big enough for all the pages accessible via the
 331         given @e firstPage, i.e. this page, its next page and so on.
 332
 333         This method may be called more than once and it will only change the page size
 334         if the size required by the new page is bigger than the previously set one.
 335         This is useful if the decision about which pages to show is taken during
 336         run-time, as in this case, the wizard won't be able to get to all pages starting
 337         from a single one and you should call @e Fit separately for the others.
 338     */
 339     void FitToPage(const wxWizardPage* firstPage);
 340
 341     /**
 342         Returns the bitmap used for the wizard.
 343     */
 344     const wxBitmap& GetBitmap() const;
 345
 346     /**
 347         Returns the colour that should be used to fill the area not taken up by the
 348         wizard or page bitmap, if a non-zero bitmap placement flag has been set.
 349
 350         See also SetBitmapPlacement().
 351     */
 352     const wxColour& GetBitmapBackgroundColour() const;
 353
 354     /**
 355         Returns the flags indicating how the wizard or page bitmap should be expanded
 356         and positioned to fit the page height. By default, placement is 0 (no expansion is done).
 357
 358         See also SetBitmapPlacement() for the possible values.
 359     */
 360     int GetBitmapPlacement();
 361
 362     /**
 363         Get the current page while the wizard is running.
 364         @NULL is returned if RunWizard() is not being executed now.
 365     */
 366     wxWizardPage* GetCurrentPage() const;
 367
 368     /**
 369         Returns the minimum width for the bitmap that will be constructed to contain
 370         the actual wizard or page bitmap if a non-zero bitmap placement flag has been set.
 371
 372         See also SetBitmapPlacement().
 373     */
 374     int GetMinimumBitmapWidth() const;
 375
 376     /**
 377         Returns pointer to page area sizer. The wizard is laid out using sizers and
 378         the page area sizer is the place-holder for the pages. All pages are resized
 379         before being shown to match the wizard page area.
 380
 381         Page area sizer has a minimal size that is the maximum of several values.
 382         First, all pages (or other objects) added to the sizer. Second, all pages reachable
 383         by repeatedly applying wxWizardPage::GetNext() to any page inserted into the sizer.
 384
 385         Third, the minimal size specified using SetPageSize() and FitToPage().
 386         Fourth, the total wizard height may be increased to accommodate the bitmap height.
 387         Fifth and finally, wizards are never smaller than some built-in minimal size to
 388         avoid wizards that are too small.
 389
 390         The caller can use wxSizer::SetMinSize to enlarge it beyond the minimal size.
 391         If @c wxRESIZE_BORDER was passed to constructor, user can resize wizard and
 392         consequently the page area (but not make it smaller than the minimal size).
 393
 394         It is recommended to add the first page to the page area sizer.
 395         For simple wizards, this will enlarge the wizard to fit the biggest page.
 396
 397         For non-linear wizards, the first page of every separate chain should be added.
 398         Caller-specified size can be accomplished using wxSizer::SetMinSize().
 399         Adding pages to the page area sizer affects the default border width around page
 400         area that can be altered with SetBorder().
 401     */
 402     virtual wxSizer* GetPageAreaSizer() const;
 403
 404     /**
 405         Returns the size available for the pages.
 406     */
 407     wxSize GetPageSize() const;
 408
 409     /**
 410         Return @true if this page is not the last one in the wizard.
 411         The base class version implements this by calling
 412         @ref wxWizardPage::GetNext "page->GetNext" but this could be
 413         undesirable if, for example, the pages are created on demand only.
 414
 415         @see HasPrevPage()
 416     */
 417     virtual bool HasNextPage(wxWizardPage* page);
 418
 419     /**
 420         Returns @true if this page is not the last one in the wizard.
 421         The base class version implements this by calling
 422         @ref wxWizardPage::GetPrev "page->GetPrev" but this could be
 423         undesirable if, for example, the pages are created on demand only.
 424
 425         @see HasNextPage()
 426     */
 427     virtual bool HasPrevPage(wxWizardPage* page);
 428
 429     /**
 430         Executes the wizard starting from the given page, returning @true if it was
 431         successfully finished or @false if user cancelled it.
 432         The @a firstPage can not be @NULL.
 433     */
 434     bool RunWizard(wxWizardPage* firstPage);
 435
 436     /**
 437         Sets the bitmap used for the wizard.
 438     */
 439     void SetBitmap(const wxBitmap& bitmap);
 440
 441     /**
 442         Sets the colour that should be used to fill the area not taken up by the wizard
 443         or page bitmap, if a non-zero bitmap placement flag has been set.
 444
 445         See also SetBitmapPlacement().
 446     */
 447     void SetBitmapBackgroundColour(const wxColour& colour);
 448
 449     /**
 450         Sets the flags indicating how the wizard or page bitmap should be expanded and
 451         positioned to fit the page height.
 452
 453         By default, placement is 0 (no expansion is done). @a placement is a bitlist with the
 454         following possible values:
 455
 456         - @b wxWIZARD_VALIGN_TOP: Aligns the bitmap at the top.
 457         - @b wxWIZARD_VALIGN_CENTRE: Centres the bitmap vertically.
 458         - @b wxWIZARD_VALIGN_BOTTOM: Aligns the bitmap at the bottom.
 459         - @b wxWIZARD_HALIGN_LEFT: Left-aligns the bitmap.
 460         - @b wxWIZARD_HALIGN_CENTRE: Centres the bitmap horizontally.
 461         - @b wxWIZARD_HALIGN_RIGHT: Right-aligns the bitmap.
 462         - @b wxWIZARD_TILE: @todo describe this
 463
 464         See also SetMinimumBitmapWidth().
 465     */
 466     void SetBitmapPlacement(int placement);
 467
 468     /**
 469         Sets width of border around page area. Default is zero.
 470         For backward compatibility, if there are no pages in GetPageAreaSizer(),
 471         the default is 5 pixels.
 472
 473         If there is a five point border around all controls in a page and the border
 474         around page area is left as zero, a five point white space along all dialog borders
 475         will be added to the control border in order to space page controls ten points
 476         from the dialog border and non-page controls.
 477     */
 478     void SetBorder(int border);
 479
 480     /**
 481         Sets the minimum width for the bitmap that will be constructed to contain the
 482         actual wizard or page bitmap if a non-zero bitmap placement flag has been set.
 483         If this is not set when using bitmap placement, the initial layout may be incorrect.
 484
 485         See also SetBitmapPlacement().
 486     */
 487     void SetMinimumBitmapWidth(int width);
 488
 489     /**
 490         Sets the minimal size to be made available for the wizard pages.
 491         The wizard will take into account the size of the bitmap (if any) itself.
 492         Also, the wizard will never be smaller than the default size.
 493
 494         The recommended way to use this function is to lay out all wizard pages
 495         using the sizers (even though the wizard is not resizeable) and then use
 496         wxSizer::CalcMin() in a loop to calculate the maximum of minimal sizes of
 497         the pages and pass it to SetPageSize().
 498
 499         @deprecated
 500         This method is obsolete, use GetPageAreaSizer() instead.
 501     */
 502     void SetPageSize(const wxSize& sizePage);
 503 };
 504