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