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 \end{twocollist}%
  57
  58 \wxheading{Extended styles}
  59
  60 Use the \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle} function to set the following
  61 style. You will need to use two-step construction (use the default constructor, call {\bf SetExtraStyle}, then call {\bf Create}).
  62
  63 \twocolwidtha{5cm}%
  64 \begin{twocollist}\itemsep=0pt
  65 \twocolitem{\windowstyle{wxWIZARD\_EX\_HELPBUTTON}}{Shows a Help button using wxID\_HELP.}
  66 \end{twocollist}
  67
  68 See also \helpref{wxDialog}{wxdialog} for other extended styles.
  69
  70 \wxheading{See also}
  71
  72 \helpref{wxWizardEvent}{wxwizardevent}, \helpref{wxWizardPage}{wxwizardpage}, \helpref{wxWizard sample}{samplewizard}
  73
  74 \latexignore{\rtfignore{\wxheading{Members}}}
  75
  76 \membersection{wxWizard::wxWizard}\label{wxwizardctor}
  77
  78 \func{}{wxWizard}{\void}
  79
  80 Default constructor. Use this if you wish to derive from wxWizard and then call {\bf Create}, for example
  81 if you wish to set an extra style with \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle}.
  82
  83 \func{}{wxWizard}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}}
  84
  85 Creates the wizard dialog. The wizard should not be deleted
  86 directly, you should rather call {\tt Destroy()} on it and wxWindows will
  87 delete it itself.
  88
  89 Notice that unlike almost all other wxWindows classes, there is no {\it size}
  90 parameter in wxWizard constructor because the wizard will have a predefined
  91 default size by default. If you want to change this, you should use the
  92 \helpref{SetPageSize}{wxwizardsetpagesize} function.
  93
  94 \wxheading{Parameters}
  95
  96 \docparam{parent}{The parent window, may be NULL.}
  97
  98 \docparam{id}{The id of the dialog, will usually be just $-1$.}
  99
 100 \docparam{title}{The title of the dialog.}
 101
 102 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 103 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 104
 105 \docparam{pos}{The position of the dialog, it will be centered on the screen
 106 by default.}
 107
 108 \membersection{wxWizard::Create}\label{wxwizardcreate}
 109
 110 \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}}
 111
 112 Creates the wizard dialog. The returned pointer should not be deleted
 113 directly, you should rather call {\tt Destroy()} on it and wxWindows will
 114 delete it itself.
 115
 116 Notice that unlike almost all other wxWindows classes, there is no {\it size}
 117 parameter in wxWizard constructor because the wizard will have a predefined
 118 default size by default. If you want to change this, you should use the
 119 \helpref{SetPageSize}{wxwizardsetpagesize} function.
 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}}
 122
 123 Alternative, non-static constructor for two-step construction of a class derived from wxWizard.
 124
 125 \wxheading{Parameters}
 126
 127 \docparam{parent}{The parent window, may be NULL.}
 128
 129 \docparam{id}{The id of the dialog, will usually be just $-1$.}
 130
 131 \docparam{title}{The title of the dialog.}
 132
 133 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
 134 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
 135
 136 \docparam{pos}{The position of the dialog, it will be centered on the screen
 137 by default.}
 138
 139 \membersection{wxWizard::RunWizard}\label{wxwizardrunwizard}
 140
 141 \func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
 142
 143 Executes the wizard starting from the given page, returns {\tt TRUE} if it was
 144 successfully finished or {\tt FALSE} if user cancelled it. The {\it firstPage}
 145 can not be {\tt NULL}.
 146
 147 \membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
 148
 149 \constfunc{wxWizardPage*}{GetCurrentPage}{\void}
 150
 151 Get the current page while the wizard is running. {\tt NULL} is returned if
 152 \helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
 153
 154 \membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
 155
 156 \constfunc{wxSize}{GetPageSize}{\void}
 157
 158 Returns the size available for the pages.
 159
 160 \membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
 161
 162 \func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
 163
 164 Sets the minimal size to be made available for the wizard pages. The wizard
 165 will take into account the size of the bitmap (if any) itself. Also, the
 166 wizard will never be smaller than the default size.
 167
 168 The recommended way to use this function is to layout all wizard pages using
 169 the sizers (even though the wizard is not resizeable) and then use
 170 \helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
 171 of minimal sizes of the pages and pass it to SetPageSize().
 172