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