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 \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}}
  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 wxWindows classes, there is no {\it size}
  94 parameter in 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{SetPageSize}{wxwizardsetpagesize} 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 \membersection{wxWizard::Create}\label{wxwizardcreate}
 113
 114 \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}}
 115
 116 Creates the wizard dialog. Must be called if the default constructor had been
 117 used to create the object.
 118
 119 Notice that unlike almost all other wxWindows classes, there is no {\it size}
 120 parameter in wxWizard constructor because the wizard will have a predefined
 121 default size by default. If you want to change this, you should use the
 122 \helpref{SetPageSize}{wxwizardsetpagesize} function.
 123
 124 \wxheading{Parameters}
 125
 126 \docparam{parent}{The parent window, may be NULL.}
 127
 128 \docparam{id}{The id of the dialog, will usually be just $-1$.}
 129
 130 \docparam{title}{The title of the dialog.}
 131
 132 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 133 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 134
 135 \docparam{pos}{The position of the dialog, it will be centered on the screen
 136 by default.}
 137
 138 \membersection{wxWizard::FitToPage}\label{wxwizardfittopage}
 139
 140 \func{void}{FittoPage}{\param{const wxWizardPage* }{firstPage}}
 141
 142 Sets the page size to be big enough for all the pages accessible via the
 143 given {\it firstPage}, i.e. this page, its next page and so on.
 144
 145 This method may be called more than once and it will only change the page size
 146 if the size required by the new page is bigger than the previously set one.
 147 This is useful if the decision about which pages to show is taken during the
 148 run-time as in this case, the wizard won't be able to get to all pages starting
 149 from a single one and you should call {\it Fit} separately for the others.
 150
 151 \membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
 152
 153 \constfunc{wxWizardPage*}{GetCurrentPage}{\void}
 154
 155 Get the current page while the wizard is running. {\tt NULL} is returned if
 156 \helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
 157
 158 \membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
 159
 160 \constfunc{wxSize}{GetPageSize}{\void}
 161
 162 Returns the size available for the pages.
 163
 164 \membersection{wxWizard::HasNextPage}\label{wxwizardhasnextpage}
 165
 166 \func{virtual bool}{HasNextPage}{\param{wxWizardPage *}{page}}
 167
 168 Return {\tt true} if this page is not the last one in the wizard. The base
 169 class version implements this by calling
 170 \helpref{page->GetNext}{wxwizardpagegetnext} but this could be undesirable if,
 171 for example, the pages are created on demand only.
 172
 173 \wxheading{See also}
 174
 175 \helpref{HasPrevPage}{wxwizardhasprevpage}
 176
 177 \membersection{wxWizard::HasPrevPage}\label{wxwizardhasprevpage}
 178
 179 \func{virtual bool}{HasPrevPage}{\param{wxWizardPage *}{page}}
 180
 181 Return {\tt true} if this page is not the last one in the wizard. The base
 182 class version implements this by calling
 183 \helpref{page->GetPrev}{wxwizardpagegetprev} but this could be undesirable if,
 184 for example, the pages are created on demand only.
 185
 186 \wxheading{See also}
 187
 188 \helpref{HasNextPage}{wxwizardhasnextpage}
 189
 190 \membersection{wxWizard::RunWizard}\label{wxwizardrunwizard}
 191
 192 \func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
 193
 194 Executes the wizard starting from the given page, returns {\tt true} if it was
 195 successfully finished or {\tt false} if user cancelled it. The {\it firstPage}
 196 can not be {\tt NULL}.
 197
 198 \membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
 199
 200 \func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
 201
 202 Sets the minimal size to be made available for the wizard pages. The wizard
 203 will take into account the size of the bitmap (if any) itself. Also, the
 204 wizard will never be smaller than the default size.
 205
 206 The recommended way to use this function is to layout all wizard pages using
 207 the sizers (even though the wizard is not resizeable) and then use
 208 \helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
 209 of minimal sizes of the pages and pass it to SetPageSize().
 210