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 convenience function to make the pages follow each other.
 231         Example:
 232
 233         @code
 234         wxRadioboxPage *page3 = new wxRadioboxPage(wizard);
 235         wxValidationPage *page4 = new wxValidationPage(wizard);
 236
 237         wxWizardPageSimple::Chain(page3, page4);
 238         @endcode
 239     */
 240     static void Chain(wxWizardPageSimple* first,
 241                       wxWizardPageSimple* second);
 242
 243     /**
 244         Sets the next page.
 245     */
 246     void SetNext(wxWizardPage* next);
 247
 248     /**
 249         Sets the previous page.
 250     */
 251     void SetPrev(wxWizardPage* prev);
 252 };
 253
 254
 255
 256 /**
 257     @class wxWizard
 258
 259     wxWizard is the central class for implementing 'wizard-like' dialogs.
 260     These dialogs are mostly familiar to Windows users and are nothing other than a
 261     sequence of 'pages', each displayed inside a dialog which has the buttons to
 262     navigate to the next (and previous) pages.
 263
 264     The wizards are typically used to decompose a complex dialog into several
 265     simple steps and are mainly useful to the novice users, hence it is important
 266     to keep them as simple as possible.
 267
 268     To show a wizard dialog, you must first create an instance of the wxWizard class
 269     using either the non-default constructor or a default one followed by call to the
 270     wxWizard::Create function. Then you should add all pages you want the wizard to
 271     show and call wxWizard::RunWizard().
 272     Finally, don't forget to call @c "wizard->Destroy()", otherwise your application
 273     will hang on exit due to an undestroyed window.
 274
 275     You can supply a bitmap to display on the left of the wizard, either for all pages
 276     or for individual pages. If you need to have the bitmap resize to the height of
 277     the wizard, call wxWizard::SetBitmapPlacement() and if necessary,
 278     wxWizard::SetBitmapBackgroundColour() and wxWizard::SetMinimumBitmapWidth().
 279
 280     To make wizard pages scroll when the display is too small to fit the whole
 281     dialog, you can switch layout adaptation on globally with
 282     wxDialog::EnableLayoutAdaptation() or per dialog with wxDialog::SetLayoutAdaptationMode().
 283     For more about layout adaptation, see @ref overview_dialog_autoscrolling.
 284
 285     @beginEventEmissionTable{wxWizardEvent}
 286     For some events, Veto() can be called to prevent the event from happening.
 287     @event{EVT_WIZARD_PAGE_CHANGED(id, func)}
 288         The page has just been changed (this event cannot be vetoed).
 289     @event{EVT_WIZARD_PAGE_CHANGING(id, func)}
 290         The page is being changed (this event can be vetoed).
 291     @event{EVT_WIZARD_BEFORE_PAGE_CHANGED(id, func)}
 292         Called after Next is clicked but before GetNext is called. Unlike EVT_WIZARD_CHANGING,
 293         the handler for this function can change state that might affect the return value of
 294         GetNext. This event can be vetoed.
 295     @event{EVT_WIZARD_PAGE_SHOWN(id, func)}
 296         The page was shown and laid out (this event cannot be vetoed).
 297     @event{EVT_WIZARD_CANCEL(id, func)}
 298         The user attempted to cancel the wizard (this event may also be vetoed).
 299     @event{EVT_WIZARD_HELP(id, func)}
 300         The wizard help button was pressed.
 301     @event{EVT_WIZARD_FINISHED(id, func)}
 302         The wizard finished button was pressed.
 303     @endEventTable
 304
 305
 306     @section wizard_extstyles Extended styles
 307
 308     Use the wxWindow::SetExtraStyle() function to set the following style.
 309     You will need to use two-step construction (use the default constructor,
 310     call SetExtraStyle(), then call Create).
 311
 312     @beginExtraStyleTable
 313     @style{wxWIZARD_EX_HELPBUTTON}
 314         Shows a Help button using wxID_HELP.
 315     @endExtraStyleTable
 316
 317     See also wxDialog for other extended styles.
 318
 319     @library{wxadv}
 320     @category{cmndlg}
 321
 322     @see wxWizardEvent, wxWizardPage, @ref page_samples_wizard
 323 */
 324 class wxWizard : public wxDialog
 325 {
 326 public:
 327     /**
 328         Default constructor.
 329
 330         Use this if you wish to derive from wxWizard and then call Create(),
 331         for example if you wish to set an extra style with wxWindow::SetExtraStyle()
 332         between the two calls.
 333     */
 334     wxWizard();
 335
 336     /**
 337         Constructor which really creates the wizard -- if you use this constructor, you
 338         shouldn't call Create().
 339
 340         Notice that unlike almost all other wxWidgets classes, there is no @e size
 341         parameter in the wxWizard constructor because the wizard will have a predefined
 342         default size by default.
 343         If you want to change this, you should use the GetPageAreaSizer() function.
 344
 345         @param parent
 346             The parent window, may be @NULL.
 347         @param id
 348             The id of the dialog, will usually be just wxID_ANY.
 349         @param title
 350             The title of the dialog.
 351         @param bitmap
 352             The default bitmap used in the left side of the wizard. See also GetBitmap().
 353         @param pos
 354             The position of the dialog, it will be centered on the screen by default.
 355         @param style
 356             Window style is passed to wxDialog.
 357     */
 358     wxWizard(wxWindow* parent, int id = wxID_ANY,
 359              const wxString& title = wxEmptyString,
 360              const wxBitmap& bitmap = wxNullBitmap,
 361              const wxPoint& pos = wxDefaultPosition,
 362              long style = wxDEFAULT_DIALOG_STYLE);
 363
 364     /**
 365         Creates the wizard dialog.
 366         Must be called if the default constructor had been used to create the object.
 367
 368         Notice that unlike almost all other wxWidgets classes, there is no @e size
 369         parameter in the wxWizard constructor because the wizard will have a predefined
 370         default size by default.
 371         If you want to change this, you should use the GetPageAreaSizer() function.
 372
 373         @param parent
 374             The parent window, may be @NULL.
 375         @param id
 376             The id of the dialog, will usually be just -1.
 377         @param title
 378             The title of the dialog.
 379         @param bitmap
 380             The default bitmap used in the left side of the wizard. See also GetBitmap().
 381         @param pos
 382             The position of the dialog, it will be centered on the screen by default.
 383         @param style
 384             Window style is passed to wxDialog.
 385     */
 386     bool Create(wxWindow* parent, int id = wxID_ANY,
 387                 const wxString& title = wxEmptyString,
 388                 const wxBitmap& bitmap = wxNullBitmap,
 389                 const wxPoint& pos = wxDefaultPosition, long style = wxDEFAULT_DIALOG_STYLE);
 390
 391     /**
 392         This method is obsolete, use GetPageAreaSizer() instead.
 393
 394         Sets the page size to be big enough for all the pages accessible via the
 395         given @e firstPage, i.e. this page, its next page and so on.
 396
 397         This method may be called more than once and it will only change the page size
 398         if the size required by the new page is bigger than the previously set one.
 399         This is useful if the decision about which pages to show is taken during
 400         run-time, as in this case, the wizard won't be able to get to all pages starting
 401         from a single one and you should call @e Fit separately for the others.
 402     */
 403     virtual void FitToPage(const wxWizardPage* firstPage);
 404
 405     /**
 406         Returns the bitmap used for the wizard.
 407     */
 408     const wxBitmap& GetBitmap() const;
 409
 410     /**
 411         Returns the colour that should be used to fill the area not taken up by the
 412         wizard or page bitmap, if a non-zero bitmap placement flag has been set.
 413
 414         See also SetBitmapPlacement().
 415     */
 416     const wxColour& GetBitmapBackgroundColour() const;
 417
 418     /**
 419         Returns the flags indicating how the wizard or page bitmap should be expanded
 420         and positioned to fit the page height. By default, placement is 0 (no expansion is done).
 421
 422         See also SetBitmapPlacement() for the possible values.
 423     */
 424     int GetBitmapPlacement() const;
 425
 426     /**
 427         Get the current page while the wizard is running.
 428         @NULL is returned if RunWizard() is not being executed now.
 429     */
 430     virtual wxWizardPage* GetCurrentPage() const;
 431
 432     /**
 433         Returns the minimum width for the bitmap that will be constructed to contain
 434         the actual wizard or page bitmap if a non-zero bitmap placement flag has been set.
 435
 436         See also SetBitmapPlacement().
 437     */
 438     int GetMinimumBitmapWidth() const;
 439
 440     /**
 441         Returns pointer to page area sizer. The wizard is laid out using sizers and
 442         the page area sizer is the place-holder for the pages. All pages are resized
 443         before being shown to match the wizard page area.
 444
 445         Page area sizer has a minimal size that is the maximum of several values.
 446         First, all pages (or other objects) added to the sizer. Second, all pages reachable
 447         by repeatedly applying wxWizardPage::GetNext() to any page inserted into the sizer.
 448
 449         Third, the minimal size specified using SetPageSize() and FitToPage().
 450         Fourth, the total wizard height may be increased to accommodate the bitmap height.
 451         Fifth and finally, wizards are never smaller than some built-in minimal size to
 452         avoid wizards that are too small.
 453
 454         The caller can use wxSizer::SetMinSize to enlarge it beyond the minimal size.
 455         If @c wxRESIZE_BORDER was passed to constructor, user can resize wizard and
 456         consequently the page area (but not make it smaller than the minimal size).
 457
 458         It is recommended to add the first page to the page area sizer.
 459         For simple wizards, this will enlarge the wizard to fit the biggest page.
 460
 461         For non-linear wizards, the first page of every separate chain should be added.
 462         Caller-specified size can be accomplished using wxSizer::SetMinSize().
 463         Adding pages to the page area sizer affects the default border width around page
 464         area that can be altered with SetBorder().
 465     */
 466     virtual wxSizer* GetPageAreaSizer() const;
 467
 468     /**
 469         Returns the size available for the pages.
 470     */
 471     virtual wxSize GetPageSize() const;
 472
 473     /**
 474         Return @true if this page is not the last one in the wizard.
 475         The base class version implements this by calling
 476         @ref wxWizardPage::GetNext "page->GetNext" but this could be
 477         undesirable if, for example, the pages are created on demand only.
 478
 479         @see HasPrevPage()
 480     */
 481     virtual bool HasNextPage(wxWizardPage* page);
 482
 483     /**
 484         Returns @true if this page is not the last one in the wizard.
 485         The base class version implements this by calling
 486         @ref wxWizardPage::GetPrev "page->GetPrev" but this could be
 487         undesirable if, for example, the pages are created on demand only.
 488
 489         @see HasNextPage()
 490     */
 491     virtual bool HasPrevPage(wxWizardPage* page);
 492
 493     /**
 494         Executes the wizard starting from the given page, returning @true if it was
 495         successfully finished or @false if user cancelled it.
 496         The @a firstPage cannot be @NULL.
 497     */
 498     virtual bool RunWizard(wxWizardPage* firstPage);
 499
 500     /**
 501         Sets the bitmap used for the wizard.
 502     */
 503     void SetBitmap(const wxBitmap& bitmap);
 504
 505     /**
 506         Sets the colour that should be used to fill the area not taken up by the wizard
 507         or page bitmap, if a non-zero bitmap placement flag has been set.
 508
 509         See also SetBitmapPlacement().
 510     */
 511     void SetBitmapBackgroundColour(const wxColour& colour);
 512
 513     /**
 514         Sets the flags indicating how the wizard or page bitmap should be expanded and
 515         positioned to fit the page height.
 516
 517         By default, placement is 0 (no expansion is done). @a placement is a bitlist with the
 518         following possible values:
 519
 520         - @b wxWIZARD_VALIGN_TOP: Aligns the bitmap at the top.
 521         - @b wxWIZARD_VALIGN_CENTRE: Centres the bitmap vertically.
 522         - @b wxWIZARD_VALIGN_BOTTOM: Aligns the bitmap at the bottom.
 523         - @b wxWIZARD_HALIGN_LEFT: Left-aligns the bitmap.
 524         - @b wxWIZARD_HALIGN_CENTRE: Centres the bitmap horizontally.
 525         - @b wxWIZARD_HALIGN_RIGHT: Right-aligns the bitmap.
 526         - @b wxWIZARD_TILE: @todo describe this
 527
 528         See also SetMinimumBitmapWidth().
 529     */
 530     void SetBitmapPlacement(int placement);
 531
 532     /**
 533         Sets width of border around page area. Default is zero.
 534         For backward compatibility, if there are no pages in GetPageAreaSizer(),
 535         the default is 5 pixels.
 536
 537         If there is a five point border around all controls in a page and the border
 538         around page area is left as zero, a five point white space along all dialog borders
 539         will be added to the control border in order to space page controls ten points
 540         from the dialog border and non-page controls.
 541     */
 542     virtual void SetBorder(int border);
 543
 544     /**
 545         Sets the minimum width for the bitmap that will be constructed to contain the
 546         actual wizard or page bitmap if a non-zero bitmap placement flag has been set.
 547         If this is not set when using bitmap placement, the initial layout may be incorrect.
 548
 549         See also SetBitmapPlacement().
 550     */
 551     void SetMinimumBitmapWidth(int width);
 552
 553     /**
 554         Sets the minimal size to be made available for the wizard pages.
 555         The wizard will take into account the size of the bitmap (if any) itself.
 556         Also, the wizard will never be smaller than the default size.
 557
 558         The recommended way to use this function is to lay out all wizard pages
 559         using the sizers (even though the wizard is not resizable) and then use
 560         wxSizer::CalcMin() in a loop to calculate the maximum of minimal sizes of
 561         the pages and pass it to SetPageSize().
 562     */
 563     virtual void SetPageSize(const wxSize& sizePage);
 564 };
 565