docs/latex/wx/wizard.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        wizard.tex
   3 %% Purpose:     wxWizard class documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   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 else but a
  16 sequence of `pages' each of them displayed inside a dialog which has the
  17 buttons to pass 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 object of wxWizard class
  24 using either the non default constructor or a default one followed by call to
  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()}.
  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 been just
  52 changed (this event can not 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 \end{twocollist}%
  59
  60 \wxheading{Extended styles}
  61
  62 Use the \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle} function to set the following
  63 style. You will need to use two-step construction (use the default constructor, call {\bf SetExtraStyle}, then call {\bf Create}).
  64
  65 \twocolwidtha{5cm}%
  66 \begin{twocollist}\itemsep=0pt
  67 \twocolitem{\windowstyle{wxWIZARD\_EX\_HELPBUTTON}}{Shows a Help button using wxID\_HELP.}
  68 \end{twocollist}
  69
  70 See also \helpref{wxDialog}{wxdialog} for other extended styles.
  71
  72 \wxheading{See also}
  73
  74 \helpref{wxWizardEvent}{wxwizardevent}, \helpref{wxWizardPage}{wxwizardpage}, \helpref{wxWizard sample}{samplewizard}
  75
  76 \latexignore{\rtfignore{\wxheading{Members}}}
  77
  78 \membersection{wxWizard::wxWizard}\label{wxwizardctor}
  79
  80 \func{}{wxWizard}{\void}
  81
  82 Default constructor. Use this if you wish to derive from wxWizard and then call
  83 \helpref{Create}{wxwizardcreate}, for example if you wish to set an extra style
  84 with \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle} between the two
  85 calls.
  86
  87 \func{}{wxWizard}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}}
  88
  89 Constructor which really creates the wizard -- if you use this constructor, you
  90 shouldn't call \helpref{Create}{wxwizardcreate}.
  91
  92 Notice that unlike almost all other wxWindows classes, there is no {\it size}
  93 parameter in wxWizard constructor because the wizard will have a predefined
  94 default size by default. If you want to change this, you should use the
  95 \helpref{SetPageSize}{wxwizardsetpagesize} function.
  96
  97 \wxheading{Parameters}
  98
  99 \docparam{parent}{The parent window, may be NULL.}
 100
 101 \docparam{id}{The id of the dialog, will usually be just $-1$.}
 102
 103 \docparam{title}{The title of the dialog.}
 104
 105 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 106 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 107
 108 \docparam{pos}{The position of the dialog, it will be centered on the screen
 109 by default.}
 110
 111 \membersection{wxWizard::Create}\label{wxwizardcreate}
 112
 113 \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}}
 114
 115 Creates the wizard dialog. Must be called if the default constructor had been
 116 used to create the object.
 117
 118 Notice that unlike almost all other wxWindows classes, there is no {\it size}
 119 parameter in wxWizard constructor because the wizard will have a predefined
 120 default size by default. If you want to change this, you should use the
 121 \helpref{SetPageSize}{wxwizardsetpagesize} function.
 122
 123 \wxheading{Parameters}
 124
 125 \docparam{parent}{The parent window, may be NULL.}
 126
 127 \docparam{id}{The id of the dialog, will usually be just $-1$.}
 128
 129 \docparam{title}{The title of the dialog.}
 130
 131 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 132 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 133
 134 \docparam{pos}{The position of the dialog, it will be centered on the screen
 135 by default.}
 136
 137 \membersection{wxWizard::FitToPage}\label{wxwizardfittopage}
 138
 139 \func{void}{FittoPage}{\param{const wxWizardPage* }{firstPage}}
 140
 141 Sets the page size to be big enough for all the pages accessible via the
 142 given {\it firstPage}, i.e. this page, its next page and so on.
 143
 144 This method may be called more than once and it will only change the page size
 145 if the size required by the new page is bigger than the previously set one.
 146 This is useful if the decision about which pages to show is taken during the
 147 run-time as in this case, the wizard won't be able to get to all pages starting
 148 from a single one and you should call {\it Fit} separately for the others.
 149
 150 \membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
 151
 152 \constfunc{wxWizardPage*}{GetCurrentPage}{\void}
 153
 154 Get the current page while the wizard is running. {\tt NULL} is returned if
 155 \helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
 156
 157 \membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
 158
 159 \constfunc{wxSize}{GetPageSize}{\void}
 160
 161 Returns the size available for the pages.
 162
 163 \membersection{wxWizard::HasNextPage}\label{wxwizardhasnextpage}
 164
 165 \func{virtual bool}{HasNextPage}{\param{wxWizardPage *}{page}}
 166
 167 Return {\tt TRUE} if this page is not the last one in the wizard. The base
 168 class version implements this by calling
 169 \helpref{page->GetNext}{wxwizardpagegetnext} but this could be undesirable if,
 170 for example, the pages are created on demand only.
 171
 172 \wxheading{See also}
 173
 174 \helpref{HasPrevPage}{wxwizardhasprevpage}
 175
 176 \membersection{wxWizard::HasPrevPage}\label{wxwizardhasprevpage}
 177
 178 \func{virtual bool}{HasPrevPage}{\param{wxWizardPage *}{page}}
 179
 180 Return {\tt TRUE} if this page is not the last one in the wizard. The base
 181 class version implements this by calling
 182 \helpref{page->GetPrev}{wxwizardpagegetprev} but this could be undesirable if,
 183 for example, the pages are created on demand only.
 184
 185 \wxheading{See also}
 186
 187 \helpref{HasNextPage}{wxwizardhasnextpage}
 188
 189 \membersection{wxWizard::RunWizard}\label{wxwizardrunwizard}
 190
 191 \func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
 192
 193 Executes the wizard starting from the given page, returns {\tt TRUE} if it was
 194 successfully finished or {\tt FALSE} if user cancelled it. The {\it firstPage}
 195 can not be {\tt NULL}.
 196
 197 \membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
 198
 199 \func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
 200
 201 Sets the minimal size to be made available for the wizard pages. The wizard
 202 will take into account the size of the bitmap (if any) itself. Also, the
 203 wizard will never be smaller than the default size.
 204
 205 The recommended way to use this function is to layout all wizard pages using
 206 the sizers (even though the wizard is not resizeable) and then use
 207 \helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
 208 of minimal sizes of the pages and pass it to SetPageSize().
 209