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 \helpref{Create}{wxwizardcreate} function. Then you should add all pages
  25 you want the wizard to show and call \helpref{RunWizard}{wxwizardrunwizard}.
  26 Finally, don't forget to call {\tt wizard->Destroy()}.
  27
  28 \wxheading{Derived from}
  29
  30 \helpref{wxDialog}{wxdialog}\\
  31 \helpref{wxPanel}{wxpanel}\\
  32 \helpref{wxWindow}{wxwindow}\\
  33 \helpref{wxEvtHandler}{wxevthandler}\\
  34 \helpref{wxObject}{wxobject}
  35
  36 \wxheading{Include files}
  37
  38 <wx/wizard.h>
  39
  40 \wxheading{Event table macros}
  41
  42 To process input from a wizard dialog, use these event handler macros to
  43 direct input to member functions that take a
  44 \helpref{wxWizardEvent}{wxwizardevent} argument. For some events,
  45 \helpref{Veto()}{wxnotifyeventveto} can be called to prevent the event from
  46 happening.
  47
  48 \twocolwidtha{7cm}
  49 \begin{twocollist}\itemsep=2pt
  50 \twocolitem{{\bf EVT\_WIZARD\_PAGE\_CHANGED(id, func)}}{The page has been just
  51 changed (this event can not be vetoed).}
  52 \twocolitem{{\bf EVT\_WIZARD\_PAGE\_CHANGING(id, func)}}{The page is being
  53 changed (this event can be vetoed).}
  54 \twocolitem{{\bf EVT\_WIZARD\_CANCEL(id, func)}}{The user attempted to cancel
  55 the wizard (this event may also be vetoed).}
  56 \twocolitem{{\bf EVT\_WIZARD\_HELP(id, func)}}{The wizard help button was pressed.}
  57 \end{twocollist}%
  58
  59 \wxheading{Extended styles}
  60
  61 Use the \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle} function to set the following
  62 style. You will need to use two-step construction (use the default constructor, call {\bf SetExtraStyle}, then call {\bf Create}).
  63
  64 \twocolwidtha{5cm}%
  65 \begin{twocollist}\itemsep=0pt
  66 \twocolitem{\windowstyle{wxWIZARD\_EX\_HELPBUTTON}}{Shows a Help button using wxID\_HELP.}
  67 \end{twocollist}
  68
  69 See also \helpref{wxDialog}{wxdialog} for other extended styles.
  70
  71 \wxheading{See also}
  72
  73 \helpref{wxWizardEvent}{wxwizardevent}, \helpref{wxWizardPage}{wxwizardpage}, \helpref{wxWizard sample}{samplewizard}
  74
  75 \latexignore{\rtfignore{\wxheading{Members}}}
  76
  77 \membersection{wxWizard::wxWizard}\label{wxwizardctor}
  78
  79 \func{}{wxWizard}{\void}
  80
  81 Default constructor. Use this if you wish to derive from wxWizard and then call {\bf Create}, for example
  82 if you wish to set an extra style with \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle}.
  83
  84 \func{}{wxWizard}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}}
  85
  86 Creates the wizard dialog. The wizard should not be deleted
  87 directly, you should rather call {\tt Destroy()} on it and wxWindows will
  88 delete it itself.
  89
  90 Notice that unlike almost all other wxWindows classes, there is no {\it size}
  91 parameter in wxWizard constructor because the wizard will have a predefined
  92 default size by default. If you want to change this, you should use the
  93 \helpref{SetPageSize}{wxwizardsetpagesize} function.
  94
  95 \wxheading{Parameters}
  96
  97 \docparam{parent}{The parent window, may be NULL.}
  98
  99 \docparam{id}{The id of the dialog, will usually be just $-1$.}
 100
 101 \docparam{title}{The title of the dialog.}
 102
 103 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 104 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 105
 106 \docparam{pos}{The position of the dialog, it will be centered on the screen
 107 by default.}
 108
 109 \membersection{wxWizard::Create}\label{wxwizardcreate}
 110
 111 \func{static wxWizard*}{Create}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}}
 112
 113 Creates the wizard dialog. The returned pointer should not be deleted
 114 directly, you should rather call {\tt Destroy()} on it and wxWindows will
 115 delete it itself.
 116
 117 Notice that unlike almost all other wxWindows classes, there is no {\it size}
 118 parameter in wxWizard constructor because the wizard will have a predefined
 119 default size by default. If you want to change this, you should use the
 120 \helpref{SetPageSize}{wxwizardsetpagesize} function.
 121
 122 \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}}
 123
 124 Alternative, non-static constructor for two-step construction of a class derived from wxWizard.
 125
 126 \wxheading{Parameters}
 127
 128 \docparam{parent}{The parent window, may be NULL.}
 129
 130 \docparam{id}{The id of the dialog, will usually be just $-1$.}
 131
 132 \docparam{title}{The title of the dialog.}
 133
 134 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 135 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 136
 137 \docparam{pos}{The position of the dialog, it will be centered on the screen
 138 by default.}
 139
 140 \membersection{wxWizard::Fit}\label{wxwizardfit}
 141
 142 \func{void}{Fit}{\param{const wxWizardPage* }{firstPage}}
 143
 144 Sets the page size to be big enough for all the pages accessible via the
 145 given {\it firstPage}, i.e. this page, its next page and so on.
 146
 147 This method may be called more than once and it will only change the page size
 148 if the size required by the new page is bigger than the previously set one.
 149 This is useful if the decision about which pages to show is taken during the
 150 run-time as in this case, the wizard won't be able to get to all pages starting
 151 from a single one and you should call {\it Fit} separately for the others.
 152
 153 \membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
 154
 155 \constfunc{wxWizardPage*}{GetCurrentPage}{\void}
 156
 157 Get the current page while the wizard is running. {\tt NULL} is returned if
 158 \helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
 159
 160 \membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
 161
 162 \constfunc{wxSize}{GetPageSize}{\void}
 163
 164 Returns the size available for the pages.
 165
 166 \membersection{wxWizard::RunWizard}\label{wxwizardrunwizard}
 167
 168 \func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
 169
 170 Executes the wizard starting from the given page, returns {\tt TRUE} if it was
 171 successfully finished or {\tt FALSE} if user cancelled it. The {\it firstPage}
 172 can not be {\tt NULL}.
 173
 174 \membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
 175
 176 \func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
 177
 178 Sets the minimal size to be made available for the wizard pages. The wizard
 179 will take into account the size of the bitmap (if any) itself. Also, the
 180 wizard will never be smaller than the default size.
 181
 182 The recommended way to use this function is to layout all wizard pages using
 183 the sizers (even though the wizard is not resizeable) and then use
 184 \helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
 185 of minimal sizes of the pages and pass it to SetPageSize().
 186