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