]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/wizard.tex
TRUE/FALSE -> true/false in documentation
[wxWidgets.git] / 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