interface/wizard.h

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