interface/wx/wizard.h

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