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