interface/wizard.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wizard.h
   3 // Purpose:     interface of wxWizardPage
   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     @see wxWizard, @ref overview_samplewizard "wxWizard sample"
  28 */
  29 class wxWizardPage : public wxPanel
  30 {
  31 public:
  32     /**
  33         Constructor accepts an optional bitmap which will be used for this page
  34         instead of the default one for this wizard (note that all bitmaps used should
  35         be of the same size). Notice that no other parameters are needed because the
  36         wizard will resize and reposition the page anyhow.
  37
  38         @param parent
  39             The parent wizard
  40         @param bitmap
  41             The page-specific bitmap if different from the global one
  42     */
  43     wxWizardPage(wxWizard* parent,
  44                  const wxBitmap& bitmap = wxNullBitmap);
  45
  46     /**
  47         This method is called by wxWizard to get the bitmap to display alongside the
  48         page. By default, @c m_bitmap member variable which was set in the
  49         @ref wxwizardpage() constructor.
  50         If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned),
  51         the default bitmap for the wizard should be used.
  52         The only cases when you would want to override this function is if the page
  53         bitmap depends dynamically on the user choices, i.e. almost never.
  54     */
  55     wxBitmap GetBitmap() const;
  56
  57     /**
  58         Get the page which should be shown when the user chooses the @c "Next"
  59         button: if @NULL is returned, this button will be disabled. The last
  60         page of the wizard will usually return @NULL from here, but the others
  61         will not.
  62
  63         @see GetPrev()
  64     */
  65     wxWizardPage* GetNext() const;
  66
  67     /**
  68         Get the page which should be shown when the user chooses the @c "Back"
  69         button: if @NULL is returned, this button will be disabled. The first
  70         page of the wizard will usually return @NULL from here, but the others
  71         will not.
  72
  73         @see GetNext()
  74     */
  75     wxWizardPage* GetPrev() const;
  76 };
  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     @see wxWizard, @ref overview_samplewizard "wxWizard sample"
  92 */
  93 class wxWizardEvent : public wxNotifyEvent
  94 {
  95 public:
  96     /**
  97         Constructor. It is not normally used by the user code as the objects of this
  98         type are constructed by wxWizard.
  99     */
 100     wxWizardEvent(wxEventType type = wxEVT_NULL, int id = -1,
 101                   bool direction = true);
 102
 103     /**
 104         Return the direction in which the page is changing: for @c
 105         EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or
 106         @false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if
 107         we came from the previous page and @false if we returned from the next
 108         one.
 109     */
 110     bool GetDirection() const;
 111
 112     /**
 113         Returns the wxWizardPage which was active when this
 114         event was generated.
 115     */
 116     wxWizardPage* GetPage() const;
 117 };
 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     @see wxWizard, @ref overview_samplewizard "wxWizard sample"
 138 */
 139 class wxWizardPageSimple : public wxWizardPage
 140 {
 141 public:
 142     /**
 143         Constructor takes the previous and next pages. They may be modified later by
 144         SetPrev() or
 145         SetNext().
 146     */
 147     wxWizardPageSimple(wxWizard* parent = NULL,
 148                        wxWizardPage* prev = NULL,
 149                        wxWizardPage* next = NULL,
 150                        const wxBitmap& bitmap = wxNullBitmap);
 151
 152     /**
 153         A convenience function to make the pages follow each other.
 154         Example:
 155     */
 156     static void Chain(wxWizardPageSimple* first,
 157                       wxWizardPageSimple* second);
 158
 159     /**
 160         Sets the next page.
 161     */
 162     void SetNext(wxWizardPage* next);
 163
 164     /**
 165         Sets the previous page.
 166     */
 167     void SetPrev(wxWizardPage* prev);
 168 };
 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     @see wxWizardEvent, wxWizardPage, @ref overview_samplewizard "wxWizard sample"
 211 */
 212 class wxWizard : public wxDialog
 213 {
 214 public:
 215     //@{
 216     /**
 217         Constructor which really creates the wizard -- if you use this constructor, you
 218         shouldn't call Create().
 219         Notice that unlike almost all other wxWidgets classes, there is no @e size
 220         parameter in the wxWizard constructor because the wizard will have a predefined
 221         default size by default. If you want to change this, you should use the
 222         GetPageAreaSizer() function.
 223
 224         @param parent
 225             The parent window, may be @NULL.
 226         @param id
 227             The id of the dialog, will usually be just -1.
 228         @param title
 229             The title of the dialog.
 230         @param bitmap
 231             The default bitmap used in the left side of the wizard. See
 232             also GetBitmap.
 233         @param pos
 234             The position of the dialog, it will be centered on the screen
 235             by default.
 236         @param style
 237             Window style is passed to wxDialog.
 238     */
 239     wxWizard();
 240     wxWizard(wxWindow* parent, int id = -1,
 241              const wxString& title = wxEmptyString,
 242              const wxBitmap& bitmap = wxNullBitmap,
 243              const wxPoint& pos = wxDefaultPosition,
 244              long style = wxDEFAULT_DIALOG_STYLE);
 245     //@}
 246
 247     /**
 248         Creates the wizard dialog. Must be called if the default constructor had been
 249         used to create the object.
 250         Notice that unlike almost all other wxWidgets classes, there is no @e size
 251         parameter in the wxWizard constructor because the wizard will have a predefined
 252         default size by default. If you want to change this, you should use the
 253         GetPageAreaSizer() function.
 254
 255         @param parent
 256             The parent window, may be @NULL.
 257         @param id
 258             The id of the dialog, will usually be just -1.
 259         @param title
 260             The title of the dialog.
 261         @param bitmap
 262             The default bitmap used in the left side of the wizard. See
 263             also GetBitmap.
 264         @param pos
 265             The position of the dialog, it will be centered on the screen
 266             by default.
 267         @param style
 268             Window style is passed to wxDialog.
 269     */
 270     bool Create(wxWindow* parent, int id = -1,
 271                 const wxString& title = wxEmptyString,
 272                 const wxBitmap& bitmap = wxNullBitmap,
 273                 const wxPoint& pos = wxDefaultPosition,
 274                 long style = wxDEFAULT_DIALOG_STYLE);
 275
 276     /**
 277         This method is obsolete, use
 278         GetPageAreaSizer() instead.
 279         Sets the page size to be big enough for all the pages accessible via the
 280         given @e firstPage, i.e. this page, its next page and so on.
 281         This method may be called more than once and it will only change the page size
 282         if the size required by the new page is bigger than the previously set one.
 283         This is useful if the decision about which pages to show is taken during
 284         run-time, as in this case, the wizard won't be able to get to all pages starting
 285         from a single one and you should call @e Fit separately for the others.
 286     */
 287     void FitToPage(const wxWizardPage* firstPage);
 288
 289     /**
 290         Returns the bitmap used for the wizard.
 291     */
 292     const wxBitmap GetBitmap() const;
 293
 294     /**
 295         Returns the colour that should be used to fill the area not taken up by the
 296         wizard or page bitmap,
 297         if a non-zero bitmap placement flag has been set.
 298         See also SetBitmapPlacement().
 299     */
 300     const wxColour GetBitmapBackgroundColour() const;
 301
 302     /**
 303         Returns the flags indicating how the wizard or page bitmap should be expanded
 304         and positioned to fit the
 305         page height. By default, placement is 0 (no expansion is done).
 306         See also SetBitmapPlacement() for the possible values.
 307     */
 308     int GetBitmapPlacement();
 309
 310     /**
 311         Get the current page while the wizard is running. @NULL is returned if
 312         RunWizard() is not being executed now.
 313     */
 314     wxWizardPage* GetCurrentPage() const;
 315
 316     /**
 317         Returns the minimum width for the bitmap that will be constructed to contain
 318         the actual wizard or page bitmap
 319         if a non-zero bitmap placement flag has been set.
 320         See also SetBitmapPlacement().
 321     */
 322     int GetMinimumBitmapWidth() const;
 323
 324     /**
 325         Returns pointer to page area sizer. The wizard is laid out using sizers and
 326         the page area sizer is the place-holder for the pages. All pages are resized
 327         before
 328         being shown to match the wizard page area.
 329         Page area sizer has a minimal size that is the maximum of several values. First,
 330         all pages (or other objects) added to the sizer. Second, all pages reachable
 331         by repeatedly applying
 332         wxWizardPage::GetNext to
 333         any page inserted into the sizer. Third,
 334         the minimal size specified using SetPageSize() and
 335         FitToPage(). Fourth, the total wizard height may
 336         be increased to accommodate the bitmap height. Fifth and finally, wizards are
 337         never smaller than some built-in minimal size to avoid wizards that are too
 338         small.
 339         The caller can use wxSizer::SetMinSize to enlarge it
 340         beyond the minimal size. If @c wxRESIZE_BORDER was passed to constructor, user
 341         can resize wizard and consequently the page area (but not make it smaller than
 342         the
 343         minimal size).
 344         It is recommended to add the first page to the page area sizer. For simple
 345         wizards,
 346         this will enlarge the wizard to fit the biggest page. For non-linear wizards,
 347         the first page of every separate chain should be added. Caller-specified size
 348         can be accomplished using wxSizer::SetMinSize.
 349         Adding pages to the page area sizer affects the default border width around page
 350         area that can be altered with SetBorder().
 351     */
 352     virtual wxSizer* GetPageAreaSizer() const;
 353
 354     /**
 355         Returns the size available for the pages.
 356     */
 357     wxSize GetPageSize() const;
 358
 359     /**
 360         Return @true if this page is not the last one in the wizard. The base
 361         class version implements this by calling
 362         @ref wxWizardPage::getnext page-GetNext but this could be undesirable if,
 363         for example, the pages are created on demand only.
 364
 365         @see HasPrevPage()
 366     */
 367     virtual bool HasNextPage(wxWizardPage* page);
 368
 369     /**
 370         Returns @true if this page is not the last one in the wizard. The base
 371         class version implements this by calling
 372         @ref wxWizardPage::getprev page-GetPrev but this could be undesirable if,
 373         for example, the pages are created on demand only.
 374
 375         @see HasNextPage()
 376     */
 377     virtual bool HasPrevPage(wxWizardPage* page);
 378
 379     /**
 380         Executes the wizard starting from the given page, returning @true if it was
 381         successfully finished or @false if user cancelled it. The @a firstPage
 382         can not be @NULL.
 383     */
 384     bool RunWizard(wxWizardPage* firstPage);
 385
 386     /**
 387         Sets the bitmap used for the wizard.
 388     */
 389     void SetBitmap(const wxBitmap& bitmap);
 390
 391     /**
 392         Sets the colour that should be used to fill the area not taken up by the wizard
 393         or page bitmap,
 394         if a non-zero bitmap placement flag has been set.
 395         See also SetBitmapPlacement().
 396     */
 397     void SetBitmapBackgroundColour(const wxColour& colour);
 398
 399     /**
 400         Sets the flags indicating how the wizard or page bitmap should be expanded and
 401         positioned to fit the
 402         page height. By default, placement is 0 (no expansion is done). @a placement is
 403         a bitlist with the
 404         following possible values:
 405
 406         @b wxWIZARD_VALIGN_TOP
 407
 408         Aligns the bitmap at the top.
 409
 410         @b wxWIZARD_VALIGN_CENTRE
 411
 412         Centres the bitmap vertically.
 413
 414         @b wxWIZARD_VALIGN_BOTTOM
 415
 416         Aligns the bitmap at the bottom.
 417
 418         @b wxWIZARD_HALIGN_LEFT
 419
 420         Left-aligns the bitmap.
 421
 422         @b wxWIZARD_HALIGN_CENTRE
 423
 424         Centres the bitmap horizontally.
 425
 426         @b wxWIZARD_HALIGN_RIGHT
 427
 428         Right-aligns the bitmap.
 429
 430         @b wxWIZARD_TILE
 431
 432
 433         See also SetMinimumBitmapWidth().
 434     */
 435     void SetBitmapPlacement(int placement);
 436
 437     /**
 438         Sets width of border around page area. Default is zero. For backward
 439         compatibility, if there are no pages in
 440         GetPageAreaSizer(), the default is 5 pixels.
 441         If there is a five point border around all controls in a page and the border
 442         around
 443         page area is left as zero, a five point white space along all dialog borders
 444         will be added to the control border in order to space page controls ten points
 445         from the dialog
 446         border and non-page controls.
 447     */
 448     void SetBorder(int border);
 449
 450     /**
 451         Sets the minimum width for the bitmap that will be constructed to contain the
 452         actual wizard or page bitmap
 453         if a non-zero bitmap placement flag has been set. If this is not set when using
 454         bitmap placement, the initial
 455         layout may be incorrect.
 456         See also SetBitmapPlacement().
 457     */
 458     void SetMinimumBitmapWidth(int width);
 459
 460     /**
 461         This method is obsolete, use
 462         GetPageAreaSizer() instead.
 463         Sets the minimal size to be made available for the wizard pages. The wizard
 464         will take into account the size of the bitmap (if any) itself. Also, the
 465         wizard will never be smaller than the default size.
 466         The recommended way to use this function is to lay out all wizard pages using
 467         the sizers (even though the wizard is not resizeable) and then use
 468         wxSizer::CalcMin in a loop to calculate the maximum
 469         of minimal sizes of the pages and pass it to SetPageSize().
 470     */
 471     void SetPageSize(const wxSize& sizePage);
 472 };
 473