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 \membersection{wxWizard::GetBitmap}\label{wxwizardgetbitmap}
 161
 162 \constfunc{const wxBitmap\&}{GetBitmap}{\void}
 163
 164 Returns the bitmap used for the wizard.
 165
 166 \membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
 167
 168 \constfunc{wxWizardPage*}{GetCurrentPage}{\void}
 169
 170 Get the current page while the wizard is running. {\tt NULL} is returned if
 171 \helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
 172
 173
 174 \membersection{wxWizard::GetPageAreaSizer}\label{wxwizardgetpageareasizer}
 175
 176 \constfunc{virtual wxSizer*}{GetPageAreaSizer}{\void}
 177
 178 Returns pointer to page area sizer. The wizard is laid out using sizers and
 179 the page area sizer is the place-holder for the pages. All pages are resized before
 180 being shown to match the wizard page area.
 181
 182 Page area sizer has a minimal size that is the maximum of several values. First,
 183 all pages (or other objects) added to the sizer. Second, all pages reachable
 184 by repeatedly applying
 185 \helpref{wxWizardPage::GetNext}{wxwizardpagegetnext} to
 186 any page inserted into the sizer. Third,
 187 the minimal size specified using \helpref{SetPageSize}{wxwizardsetpagesize} and
 188 \helpref{FitToPage}{wxwizardfittopage}. Fourth, the total wizard height may
 189 be increased to accommodate the bitmap height. Fifth and finally, wizards are
 190 never smaller than some built-in minimal size to avoid wizards that are too small.
 191
 192 The caller can use \helpref{wxSizer::SetMinSize}{wxsizersetminsize} to enlarge it
 193 beyond the minimal size. If {\tt wxRESIZE\_BORDER} was passed to constructor, user
 194 can resize wizard and consequently the page area (but not make it smaller than the
 195 minimal size).
 196
 197 It is recommended to add the first page to the page area sizer. For simple wizards,
 198 this will enlarge the wizard to fit the biggest page. For non-linear wizards,
 199 the first page of every separate chain should be added. Caller-specified size
 200 can be accomplished using \helpref{wxSizer::SetMinSize}{wxsizersetminsize}.
 201
 202 Adding pages to the page area sizer affects the default border width around page
 203 area that can be altered with \helpref{SetBorder}{wxwizardsetborder}.
 204
 205
 206 \membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
 207
 208 \constfunc{wxSize}{GetPageSize}{\void}
 209
 210 Returns the size available for the pages.
 211
 212
 213 \membersection{wxWizard::HasNextPage}\label{wxwizardhasnextpage}
 214
 215 \func{virtual bool}{HasNextPage}{\param{wxWizardPage *}{page}}
 216
 217 Return {\tt true} if this page is not the last one in the wizard. The base
 218 class version implements this by calling
 219 \helpref{page->GetNext}{wxwizardpagegetnext} but this could be undesirable if,
 220 for example, the pages are created on demand only.
 221
 222 \wxheading{See also}
 223
 224 \helpref{HasPrevPage}{wxwizardhasprevpage}
 225
 226
 227 \membersection{wxWizard::HasPrevPage}\label{wxwizardhasprevpage}
 228
 229 \func{virtual bool}{HasPrevPage}{\param{wxWizardPage *}{page}}
 230
 231 Returns {\tt true} if this page is not the last one in the wizard. The base
 232 class version implements this by calling
 233 \helpref{page->GetPrev}{wxwizardpagegetprev} but this could be undesirable if,
 234 for example, the pages are created on demand only.
 235
 236 \wxheading{See also}
 237
 238 \helpref{HasNextPage}{wxwizardhasnextpage}
 239
 240
 241 \membersection{wxWizard::RunWizard}\label{wxwizardrunwizard}
 242
 243 \func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
 244
 245 Executes the wizard starting from the given page, returning {\tt true} if it was
 246 successfully finished or {\tt false} if user cancelled it. The {\it firstPage}
 247 can not be {\tt NULL}.
 248
 249 \membersection{wxWizard::SetBitmap}\label{wxwizardsetbitmap}
 250
 251 \func{void}{SetBitmap}{\param{const wxBitmap\& }{bitmap}}
 252
 253 Sets the bitmap used for the wizard.
 254
 255 \membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
 256
 257 \func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
 258
 259 This method is obsolete, use
 260 \helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} instead.
 261
 262 Sets the minimal size to be made available for the wizard pages. The wizard
 263 will take into account the size of the bitmap (if any) itself. Also, the
 264 wizard will never be smaller than the default size.
 265
 266 The recommended way to use this function is to lay out all wizard pages using
 267 the sizers (even though the wizard is not resizeable) and then use
 268 \helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
 269 of minimal sizes of the pages and pass it to SetPageSize().
 270
 271
 272 \membersection{wxWizard::SetBorder}\label{wxwizardsetborder}
 273
 274 \func{void}{SetBorder}{\param{int }{border}}
 275
 276 Sets width of border around page area. Default is zero. For backward
 277 compatibility, if there are no pages in
 278 \helpref{GetPageAreaSizer}{wxwizardgetpageareasizer}, the default is $5$ pixels.
 279
 280 If there is a five point border around all controls in a page and the border around
 281 page area is left as zero, a five point white space along all dialog borders
 282 will be added to the control border in order to space page controls ten points from the dialog
 283 border and non-page controls.
 284