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