docs/latex/wx/wizard.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        wizard.tex
   3 %% Purpose:     wxWizard class documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by: Robert Vazan (sizers)
   6 %% Created:     02.04.00
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxWizard}}\label{wxwizard}
  13
  14 wxWizard is the central class for implementing `wizard-like' dialogs. These
  15 dialogs are mostly familiar to Windows users and are nothing other than a
  16 sequence of `pages', each displayed inside a dialog which has the
  17 buttons to navigate to the next (and previous) pages.
  18
  19 The wizards are typically used to decompose a complex dialog into several
  20 simple steps and are mainly useful to the novice users, hence it is important
  21 to keep them as simple as possible.
  22
  23 To show a wizard dialog, you must first create an instance of the wxWizard class
  24 using either the non-default constructor or a default one followed by call to the
  25 \helpref{Create}{wxwizardcreate} function. Then you should add all pages you
  26 want the wizard to show and call \helpref{RunWizard}{wxwizardrunwizard}.
  27 Finally, don't forget to call {\tt wizard->Destroy()}, otherwise your application will hang on exit due to an undestroyed window.
  28
  29 \wxheading{Derived from}
  30
  31 \helpref{wxDialog}{wxdialog}\\
  32 \helpref{wxPanel}{wxpanel}\\
  33 \helpref{wxWindow}{wxwindow}\\
  34 \helpref{wxEvtHandler}{wxevthandler}\\
  35 \helpref{wxObject}{wxobject}
  36
  37 \wxheading{Include files}
  38
  39 <wx/wizard.h>
  40
  41 \wxheading{Event table macros}
  42
  43 To process input from a wizard dialog, use these event handler macros to
  44 direct input to member functions that take a
  45 \helpref{wxWizardEvent}{wxwizardevent} argument. For some events,
  46 \helpref{Veto()}{wxnotifyeventveto} can be called to prevent the event from
  47 happening.
  48
  49 \twocolwidtha{7cm}
  50 \begin{twocollist}\itemsep=2pt
  51 \twocolitem{{\bf EVT\_WIZARD\_PAGE\_CHANGED(id, func)}}{The page has just been
  52 changed (this event cannot be vetoed).}
  53 \twocolitem{{\bf EVT\_WIZARD\_PAGE\_CHANGING(id, func)}}{The page is being
  54 changed (this event can be vetoed).}
  55 \twocolitem{{\bf EVT\_WIZARD\_CANCEL(id, func)}}{The user attempted to cancel
  56 the wizard (this event may also be vetoed).}
  57 \twocolitem{{\bf EVT\_WIZARD\_HELP(id, func)}}{The wizard help button was pressed.}
  58 \twocolitem{{\bf EVT\_WIZARD\_FINISHED(id, func)}}{The wizard finished button was pressed.}
  59 \end{twocollist}
  60
  61 \wxheading{Extended styles}
  62
  63 Use the \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle} function to set the following
  64 style. You will need to use two-step construction (use the default constructor, call {\bf SetExtraStyle}, then call {\bf Create}).
  65
  66 \twocolwidtha{5cm}%
  67 \begin{twocollist}\itemsep=0pt
  68 \twocolitem{\windowstyle{wxWIZARD\_EX\_HELPBUTTON}}{Shows a Help button using wxID\_HELP.}
  69 \end{twocollist}
  70
  71 See also \helpref{wxDialog}{wxdialog} for other extended styles.
  72
  73 \wxheading{See also}
  74
  75 \helpref{wxWizardEvent}{wxwizardevent}, \helpref{wxWizardPage}{wxwizardpage}, \helpref{wxWizard sample}{samplewizard}
  76
  77 \latexignore{\rtfignore{\wxheading{Members}}}
  78
  79 \membersection{wxWizard::wxWizard}\label{wxwizardctor}
  80
  81 \func{}{wxWizard}{\void}
  82
  83 Default constructor. Use this if you wish to derive from wxWizard and then call
  84 \helpref{Create}{wxwizardcreate}, for example if you wish to set an extra style
  85 with \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle} between the two
  86 calls.
  87
  88 \func{}{wxWizard}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{long }{style = wxDEFAULT\_DIALOG\_STYLE}}
  89
  90 Constructor which really creates the wizard -- if you use this constructor, you
  91 shouldn't call \helpref{Create}{wxwizardcreate}.
  92
  93 Notice that unlike almost all other wxWidgets classes, there is no {\it size}
  94 parameter in the wxWizard constructor because the wizard will have a predefined
  95 default size by default. If you want to change this, you should use the
  96 \helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} function.
  97
  98 \wxheading{Parameters}
  99
 100 \docparam{parent}{The parent window, may be NULL.}
 101
 102 \docparam{id}{The id of the dialog, will usually be just $-1$.}
 103
 104 \docparam{title}{The title of the dialog.}
 105
 106 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 107 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 108
 109 \docparam{pos}{The position of the dialog, it will be centered on the screen
 110 by default.}
 111
 112 \docparam{style}{Window style is passed to wxDialog.}
 113
 114
 115 \membersection{wxWizard::Create}\label{wxwizardcreate}
 116
 117 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{long }{style = wxDEFAULT\_DIALOG\_STYLE}}
 118
 119 Creates the wizard dialog. Must be called if the default constructor had been
 120 used to create the object.
 121
 122 Notice that unlike almost all other wxWidgets classes, there is no {\it size}
 123 parameter in the wxWizard constructor because the wizard will have a predefined
 124 default size by default. If you want to change this, you should use the
 125 \helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} function.
 126
 127 \wxheading{Parameters}
 128
 129 \docparam{parent}{The parent window, may be NULL.}
 130
 131 \docparam{id}{The id of the dialog, will usually be just $-1$.}
 132
 133 \docparam{title}{The title of the dialog.}
 134
 135 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 136 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 137
 138 \docparam{pos}{The position of the dialog, it will be centered on the screen
 139 by default.}
 140
 141 \docparam{style}{Window style is passed to wxDialog.}
 142
 143
 144 \membersection{wxWizard::FitToPage}\label{wxwizardfittopage}
 145
 146 \func{void}{FitToPage}{\param{const wxWizardPage* }{firstPage}}
 147
 148 This method is obsolete, use
 149 \helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} instead.
 150
 151 Sets the page size to be big enough for all the pages accessible via the
 152 given {\it firstPage}, i.e. this page, its next page and so on.
 153
 154 This method may be called more than once and it will only change the page size
 155 if the size required by the new page is bigger than the previously set one.
 156 This is useful if the decision about which pages to show is taken during
 157 run-time, as in this case, the wizard won't be able to get to all pages starting
 158 from a single one and you should call {\it Fit} separately for the others.
 159
 160
 161 \membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
 162
 163 \constfunc{wxWizardPage*}{GetCurrentPage}{\void}
 164
 165 Get the current page while the wizard is running. {\tt NULL} is returned if
 166 \helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
 167
 168
 169 \membersection{wxWizard::GetPageAreaSizer}\label{wxwizardgetpageareasizer}
 170
 171 \constfunc{virtual wxSizer*}{GetPageAreaSizer}{\void}
 172
 173 Returns pointer to page area sizer. The wizard is laid out using sizers and
 174 the page area sizer is the place-holder for the pages. All pages are resized before
 175 being shown to match the wizard page area.
 176
 177 Page area sizer has a minimal size that is the maximum of several values. First,
 178 all pages (or other objects) added to the sizer. Second, all pages reachable
 179 by repeatedly applying
 180 \helpref{wxWizardPage::GetNext}{wxwizardpagegetnext} to
 181 any page inserted into the sizer. Third,
 182 the minimal size specified using \helpref{SetPageSize}{wxwizardsetpagesize} and
 183 \helpref{FitToPage}{wxwizardfittopage}. Fourth, the total wizard height may
 184 be increased to accommodate the bitmap height. Fifth and finally, wizards are
 185 never smaller than some built-in minimal size to avoid wizards that are too small.
 186
 187 The caller can use \helpref{wxSizer::SetMinSize}{wxsizersetminsize} to enlarge it
 188 beyond the minimal size. If {\tt wxRESIZE\_BORDER} was passed to constructor, user
 189 can resize wizard and consequently the page area (but not make it smaller than the
 190 minimal size).
 191
 192 It is recommended to add the first page to the page area sizer. For simple wizards,
 193 this will enlarge the wizard to fit the biggest page. For non-linear wizards,
 194 the first page of every separate chain should be added. Caller-specified size
 195 can be accomplished using \helpref{wxSizer::SetMinSize}{wxsizersetminsize}.
 196
 197 Adding pages to the page area sizer affects the default border width around page
 198 area that can be altered with \helpref{SetBorder}{wxwizardsetborder}.
 199
 200
 201 \membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
 202
 203 \constfunc{wxSize}{GetPageSize}{\void}
 204
 205 Returns the size available for the pages.
 206
 207
 208 \membersection{wxWizard::HasNextPage}\label{wxwizardhasnextpage}
 209
 210 \func{virtual bool}{HasNextPage}{\param{wxWizardPage *}{page}}
 211
 212 Return {\tt true} if this page is not the last one in the wizard. The base
 213 class version implements this by calling
 214 \helpref{page->GetNext}{wxwizardpagegetnext} but this could be undesirable if,
 215 for example, the pages are created on demand only.
 216
 217 \wxheading{See also}
 218
 219 \helpref{HasPrevPage}{wxwizardhasprevpage}
 220
 221
 222 \membersection{wxWizard::HasPrevPage}\label{wxwizardhasprevpage}
 223
 224 \func{virtual bool}{HasPrevPage}{\param{wxWizardPage *}{page}}
 225
 226 Returns {\tt true} if this page is not the last one in the wizard. The base
 227 class version implements this by calling
 228 \helpref{page->GetPrev}{wxwizardpagegetprev} but this could be undesirable if,
 229 for example, the pages are created on demand only.
 230
 231 \wxheading{See also}
 232
 233 \helpref{HasNextPage}{wxwizardhasnextpage}
 234
 235
 236 \membersection{wxWizard::RunWizard}\label{wxwizardrunwizard}
 237
 238 \func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
 239
 240 Executes the wizard starting from the given page, returning {\tt true} if it was
 241 successfully finished or {\tt false} if user cancelled it. The {\it firstPage}
 242 can not be {\tt NULL}.
 243
 244
 245 \membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
 246
 247 \func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
 248
 249 This method is obsolete, use
 250 \helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} instead.
 251
 252 Sets the minimal size to be made available for the wizard pages. The wizard
 253 will take into account the size of the bitmap (if any) itself. Also, the
 254 wizard will never be smaller than the default size.
 255
 256 The recommended way to use this function is to lay out all wizard pages using
 257 the sizers (even though the wizard is not resizeable) and then use
 258 \helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
 259 of minimal sizes of the pages and pass it to SetPageSize().
 260
 261
 262 \membersection{wxWizard::SetBorder}\label{wxwizardsetborder}
 263
 264 \func{void}{SetBorder}{\param{int }{border}}
 265
 266 Sets width of border around page area. Default is zero. For backward
 267 compatibility, if there are no pages in
 268 \helpref{GetPageAreaSizer}{wxwizardgetpageareasizer}, the default is $5$ pixels.
 269
 270 If there is a five point border around all controls in a page and the border around
 271 page area is left as zero, a five point white space along all dialog borders
 272 will be added to the control border in order to space page controls ten points from the dialog
 273 border and non-page controls.
 274