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