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::RunWizard}\label{wxwizardrunwizard}
 141
 142 \func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
 143
 144 Executes the wizard starting from the given page, returns {\tt TRUE} if it was
 145 successfully finished or {\tt FALSE} if user cancelled it. The {\it firstPage}
 146 can not be {\tt NULL}.
 147
 148 \membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
 149
 150 \constfunc{wxWizardPage*}{GetCurrentPage}{\void}
 151
 152 Get the current page while the wizard is running. {\tt NULL} is returned if
 153 \helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
 154
 155 \membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
 156
 157 \constfunc{wxSize}{GetPageSize}{\void}
 158
 159 Returns the size available for the pages.
 160
 161 \membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
 162
 163 \func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
 164
 165 Sets the minimal size to be made available for the wizard pages. The wizard
 166 will take into account the size of the bitmap (if any) itself. Also, the
 167 wizard will never be smaller than the default size.
 168
 169 The recommended way to use this function is to layout all wizard pages using
 170 the sizers (even though the wizard is not resizeable) and then use
 171 \helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
 172 of minimal sizes of the pages and pass it to SetPageSize().
 173