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