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