]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/wizard.h
Document that throwing exceptions from wxTimer::Notify() is unsupported.
[wxWidgets.git] / interface / wx / wizard.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wizard.h
3 // Purpose: interface of wxWizardPage, wxWizardEvent,
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxWizardPage
11
12 wxWizardPage is one of the screens in wxWizard: it must know what are the
13 following and preceding pages (which may be @NULL for the first/last page).
14 Except for this extra knowledge, wxWizardPage is just a
15 panel, so the controls may be placed directly on it in the usual way.
16
17 This class allows the programmer to decide the order of pages in the wizard
18 dynamically (during run-time) and so provides maximal flexibility.
19 Usually, however, the order of pages is known in advance in which case
20 wxWizardPageSimple class is enough and it is simpler to use.
21
22
23 @section wizardpage_virtuals Virtual functions to override
24
25 To use this class, you must override wxWizardPage::GetPrev() and
26 wxWizardPage::GetNext() pure virtual functions (or you may use
27 wxWizardPageSimple instead).
28 wxWizardPage::GetBitmap() can also be overridden, but this should be very
29 rarely needed.
30
31 @library{wxadv}
32 @category{miscwnd}
33
34 @see wxWizard, @ref page_samples_wizard
35 */
36 class wxWizardPage : public wxPanel
37 {
38 public:
39 /**
40 Constructor accepts an optional bitmap which will be used for this page
41 instead of the default one for this wizard (note that all bitmaps used should
42 be of the same size). Notice that no other parameters are needed because the
43 wizard will resize and reposition the page anyhow.
44
45 @param parent
46 The parent wizard
47 @param bitmap
48 The page-specific bitmap if different from the global one
49 */
50 wxWizardPage(wxWizard* parent,
51 const wxBitmap& bitmap = wxNullBitmap);
52
53 /**
54 This method is called by wxWizard to get the bitmap to display alongside the page.
55 By default, @c m_bitmap member variable which was set in the
56 @ref wxWizardPage() constructor.
57
58 If the bitmap was not explicitly set (i.e. if ::wxNullBitmap is returned),
59 the default bitmap for the wizard should be used.
60
61 The only cases when you would want to override this function is if the page
62 bitmap depends dynamically on the user choices, i.e. almost never.
63 */
64 virtual wxBitmap GetBitmap() const;
65
66 /**
67 Get the page which should be shown when the user chooses the @c "Next"
68 button: if @NULL is returned, this button will be disabled.
69 The last page of the wizard will usually return @NULL from here, but
70 the others will not.
71
72 @see GetPrev()
73 */
74 virtual wxWizardPage* GetNext() const = 0;
75
76 /**
77 Get the page which should be shown when the user chooses the @c "Back"
78 button: if @NULL is returned, this button will be disabled.
79 The first page of the wizard will usually return @NULL from here, but
80 the others will not.
81
82 @see GetNext()
83 */
84 virtual wxWizardPage* GetPrev() const = 0;
85 };
86
87
88
89 /**
90 @class wxWizardEvent
91
92 wxWizardEvent class represents an event generated by the wxWizard: this event
93 is first sent to the page itself and, if not processed there, goes up the
94 window hierarchy as usual.
95
96 @beginEventTable{wxWizardEvent}
97 @event{EVT_WIZARD_PAGE_CHANGED(id, func)}
98 The page has been just changed (this event can not be vetoed).
99 @event{EVT_WIZARD_PAGE_CHANGING(id, func)}
100 The page is being changed (this event can be vetoed).
101 @event{EVT_WIZARD_CANCEL(id, func)}
102 The user attempted to cancel the wizard (this event may also be vetoed).
103 @event{EVT_WIZARD_HELP(id, func)}
104 The wizard help button was pressed.
105 @event{EVT_WIZARD_FINISHED(id, func)}
106 The wizard finished button was pressed.
107 @endEventTable
108
109 @library{wxadv}
110 @category{events}
111
112 @see wxWizard, @ref page_samples_wizard
113 */
114 class wxWizardEvent : public wxNotifyEvent
115 {
116 public:
117 /**
118 Constructor.
119
120 It is not normally used by the user code as the objects of this
121 type are constructed by wxWizard.
122 */
123 wxWizardEvent(wxEventType type = wxEVT_NULL, int id = wxID_ANY,
124 bool direction = true, wxWizardPage* page = 0);
125
126 /**
127 Return the direction in which the page is changing: for
128 @c EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or
129 @false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if we
130 came from the previous page and @false if we returned from the next one.
131 */
132 bool GetDirection() const;
133
134 /**
135 Returns the wxWizardPage which was active when this event was generated.
136 */
137 wxWizardPage* GetPage() const;
138 };
139
140
141
142 /**
143 @class wxWizardPageSimple
144
145 wxWizardPageSimple is the simplest possible wxWizardPage implementation:
146 it just returns the pointers given to its constructor from wxWizardPage::GetNext()
147 and wxWizardPage::GetPrev() functions.
148
149 This makes it very easy to use the objects of this class in the wizards where
150 the pages order is known statically - on the other hand, if this is not the
151 case you must derive your own class from wxWizardPage instead.
152
153 @library{wxadv}
154 @category{miscwnd}
155
156 @see wxWizard, @ref page_samples_wizard
157 */
158 class wxWizardPageSimple : public wxWizardPage
159 {
160 public:
161 /**
162 Constructor takes the previous and next pages.
163 They may be modified later by SetPrev() or SetNext().
164 */
165 wxWizardPageSimple(wxWizard* parent,
166 wxWizardPage* prev = NULL,
167 wxWizardPage* next = NULL,
168 const wxBitmap& bitmap = wxNullBitmap);
169
170 /**
171 A convenience function to make the pages follow each other.
172 Example:
173
174 @code
175 wxRadioboxPage *page3 = new wxRadioboxPage(wizard);
176 wxValidationPage *page4 = new wxValidationPage(wizard);
177
178 wxWizardPageSimple::Chain(page3, page4);
179 @endcode
180 */
181 static void Chain(wxWizardPageSimple* first,
182 wxWizardPageSimple* second);
183
184 /**
185 Sets the next page.
186 */
187 void SetNext(wxWizardPage* next);
188
189 /**
190 Sets the previous page.
191 */
192 void SetPrev(wxWizardPage* prev);
193 };
194
195
196
197 /**
198 @class wxWizard
199
200 wxWizard is the central class for implementing 'wizard-like' dialogs.
201 These dialogs are mostly familiar to Windows users and are nothing other than a
202 sequence of 'pages', each displayed inside a dialog which has the buttons to
203 navigate to the next (and previous) pages.
204
205 The wizards are typically used to decompose a complex dialog into several
206 simple steps and are mainly useful to the novice users, hence it is important
207 to keep them as simple as possible.
208
209 To show a wizard dialog, you must first create an instance of the wxWizard class
210 using either the non-default constructor or a default one followed by call to the
211 wxWizard::Create function. Then you should add all pages you want the wizard to
212 show and call wxWizard::RunWizard().
213 Finally, don't forget to call @c "wizard->Destroy()", otherwise your application
214 will hang on exit due to an undestroyed window.
215
216 You can supply a bitmap to display on the left of the wizard, either for all pages
217 or for individual pages. If you need to have the bitmap resize to the height of
218 the wizard, call wxWizard::SetBitmapPlacement() and if necessary,
219 wxWizard::SetBitmapBackgroundColour() and wxWizard::SetMinimumBitmapWidth().
220
221 To make wizard pages scroll when the display is too small to fit the whole
222 dialog, you can switch layout adaptation on globally with
223 wxDialog::EnableLayoutAdaptation() or per dialog with wxDialog::SetLayoutAdaptationMode().
224 For more about layout adaptation, see @ref overview_dialog_autoscrolling.
225
226 @beginEventEmissionTable{wxWizardEvent}
227 For some events, Veto() can be called to prevent the event from happening.
228 @event{EVT_WIZARD_PAGE_CHANGED(id, func)}
229 The page has just been changed (this event cannot be vetoed).
230 @event{EVT_WIZARD_PAGE_CHANGING(id, func)}
231 The page is being changed (this event can be vetoed).
232 @event{EVT_WIZARD_CANCEL(id, func)}
233 The user attempted to cancel the wizard (this event may also be vetoed).
234 @event{EVT_WIZARD_HELP(id, func)}
235 The wizard help button was pressed.
236 @event{EVT_WIZARD_FINISHED(id, func)}
237 The wizard finished button was pressed.
238 @endEventTable
239
240
241 @section wizard_extstyles Extended styles
242
243 Use the wxWindow::SetExtraStyle() function to set the following style.
244 You will need to use two-step construction (use the default constructor,
245 call SetExtraStyle(), then call Create).
246
247 @beginExtraStyleTable
248 @style{wxWIZARD_EX_HELPBUTTON}
249 Shows a Help button using wxID_HELP.
250 @endExtraStyleTable
251
252 See also wxDialog for other extended styles.
253
254 @library{wxadv}
255 @category{cmndlg}
256
257 @see wxWizardEvent, wxWizardPage, @ref page_samples_wizard
258 */
259 class wxWizard : public wxDialog
260 {
261 public:
262 /**
263 Default constructor.
264
265 Use this if you wish to derive from wxWizard and then call Create(),
266 for example if you wish to set an extra style with wxWindow::SetExtraStyle()
267 between the two calls.
268 */
269 wxWizard();
270
271 /**
272 Constructor which really creates the wizard -- if you use this constructor, you
273 shouldn't call Create().
274
275 Notice that unlike almost all other wxWidgets classes, there is no @e size
276 parameter in the wxWizard constructor because the wizard will have a predefined
277 default size by default.
278 If you want to change this, you should use the GetPageAreaSizer() function.
279
280 @param parent
281 The parent window, may be @NULL.
282 @param id
283 The id of the dialog, will usually be just wxID_ANY.
284 @param title
285 The title of the dialog.
286 @param bitmap
287 The default bitmap used in the left side of the wizard. See also GetBitmap().
288 @param pos
289 The position of the dialog, it will be centered on the screen by default.
290 @param style
291 Window style is passed to wxDialog.
292 */
293 wxWizard(wxWindow* parent, int id = wxID_ANY,
294 const wxString& title = wxEmptyString,
295 const wxBitmap& bitmap = wxNullBitmap,
296 const wxPoint& pos = wxDefaultPosition,
297 long style = wxDEFAULT_DIALOG_STYLE);
298
299 /**
300 Creates the wizard dialog.
301 Must be called if the default constructor had been used to create the object.
302
303 Notice that unlike almost all other wxWidgets classes, there is no @e size
304 parameter in the wxWizard constructor because the wizard will have a predefined
305 default size by default.
306 If you want to change this, you should use the GetPageAreaSizer() function.
307
308 @param parent
309 The parent window, may be @NULL.
310 @param id
311 The id of the dialog, will usually be just -1.
312 @param title
313 The title of the dialog.
314 @param bitmap
315 The default bitmap used in the left side of the wizard. See also GetBitmap().
316 @param pos
317 The position of the dialog, it will be centered on the screen by default.
318 @param style
319 Window style is passed to wxDialog.
320 */
321 bool Create(wxWindow* parent, int id = wxID_ANY,
322 const wxString& title = wxEmptyString,
323 const wxBitmap& bitmap = wxNullBitmap,
324 const wxPoint& pos = wxDefaultPosition, long style = 536877056);
325
326 /**
327 This method is obsolete, use GetPageAreaSizer() instead.
328
329 Sets the page size to be big enough for all the pages accessible via the
330 given @e firstPage, i.e. this page, its next page and so on.
331
332 This method may be called more than once and it will only change the page size
333 if the size required by the new page is bigger than the previously set one.
334 This is useful if the decision about which pages to show is taken during
335 run-time, as in this case, the wizard won't be able to get to all pages starting
336 from a single one and you should call @e Fit separately for the others.
337 */
338 virtual void FitToPage(const wxWizardPage* firstPage);
339
340 /**
341 Returns the bitmap used for the wizard.
342 */
343 const wxBitmap& GetBitmap() const;
344
345 /**
346 Returns the colour that should be used to fill the area not taken up by the
347 wizard or page bitmap, if a non-zero bitmap placement flag has been set.
348
349 See also SetBitmapPlacement().
350 */
351 const wxColour& GetBitmapBackgroundColour() const;
352
353 /**
354 Returns the flags indicating how the wizard or page bitmap should be expanded
355 and positioned to fit the page height. By default, placement is 0 (no expansion is done).
356
357 See also SetBitmapPlacement() for the possible values.
358 */
359 int GetBitmapPlacement() const;
360
361 /**
362 Get the current page while the wizard is running.
363 @NULL is returned if RunWizard() is not being executed now.
364 */
365 virtual wxWizardPage* GetCurrentPage() const;
366
367 /**
368 Returns the minimum width for the bitmap that will be constructed to contain
369 the actual wizard or page bitmap if a non-zero bitmap placement flag has been set.
370
371 See also SetBitmapPlacement().
372 */
373 int GetMinimumBitmapWidth() const;
374
375 /**
376 Returns pointer to page area sizer. The wizard is laid out using sizers and
377 the page area sizer is the place-holder for the pages. All pages are resized
378 before being shown to match the wizard page area.
379
380 Page area sizer has a minimal size that is the maximum of several values.
381 First, all pages (or other objects) added to the sizer. Second, all pages reachable
382 by repeatedly applying wxWizardPage::GetNext() to any page inserted into the sizer.
383
384 Third, the minimal size specified using SetPageSize() and FitToPage().
385 Fourth, the total wizard height may be increased to accommodate the bitmap height.
386 Fifth and finally, wizards are never smaller than some built-in minimal size to
387 avoid wizards that are too small.
388
389 The caller can use wxSizer::SetMinSize to enlarge it beyond the minimal size.
390 If @c wxRESIZE_BORDER was passed to constructor, user can resize wizard and
391 consequently the page area (but not make it smaller than the minimal size).
392
393 It is recommended to add the first page to the page area sizer.
394 For simple wizards, this will enlarge the wizard to fit the biggest page.
395
396 For non-linear wizards, the first page of every separate chain should be added.
397 Caller-specified size can be accomplished using wxSizer::SetMinSize().
398 Adding pages to the page area sizer affects the default border width around page
399 area that can be altered with SetBorder().
400 */
401 virtual wxSizer* GetPageAreaSizer() const;
402
403 /**
404 Returns the size available for the pages.
405 */
406 virtual wxSize GetPageSize() const;
407
408 /**
409 Return @true if this page is not the last one in the wizard.
410 The base class version implements this by calling
411 @ref wxWizardPage::GetNext "page->GetNext" but this could be
412 undesirable if, for example, the pages are created on demand only.
413
414 @see HasPrevPage()
415 */
416 virtual bool HasNextPage(wxWizardPage* page);
417
418 /**
419 Returns @true if this page is not the last one in the wizard.
420 The base class version implements this by calling
421 @ref wxWizardPage::GetPrev "page->GetPrev" but this could be
422 undesirable if, for example, the pages are created on demand only.
423
424 @see HasNextPage()
425 */
426 virtual bool HasPrevPage(wxWizardPage* page);
427
428 /**
429 Executes the wizard starting from the given page, returning @true if it was
430 successfully finished or @false if user cancelled it.
431 The @a firstPage can not be @NULL.
432 */
433 virtual bool RunWizard(wxWizardPage* firstPage);
434
435 /**
436 Sets the bitmap used for the wizard.
437 */
438 void SetBitmap(const wxBitmap& bitmap);
439
440 /**
441 Sets the colour that should be used to fill the area not taken up by the wizard
442 or page bitmap, if a non-zero bitmap placement flag has been set.
443
444 See also SetBitmapPlacement().
445 */
446 void SetBitmapBackgroundColour(const wxColour& colour);
447
448 /**
449 Sets the flags indicating how the wizard or page bitmap should be expanded and
450 positioned to fit the page height.
451
452 By default, placement is 0 (no expansion is done). @a placement is a bitlist with the
453 following possible values:
454
455 - @b wxWIZARD_VALIGN_TOP: Aligns the bitmap at the top.
456 - @b wxWIZARD_VALIGN_CENTRE: Centres the bitmap vertically.
457 - @b wxWIZARD_VALIGN_BOTTOM: Aligns the bitmap at the bottom.
458 - @b wxWIZARD_HALIGN_LEFT: Left-aligns the bitmap.
459 - @b wxWIZARD_HALIGN_CENTRE: Centres the bitmap horizontally.
460 - @b wxWIZARD_HALIGN_RIGHT: Right-aligns the bitmap.
461 - @b wxWIZARD_TILE: @todo describe this
462
463 See also SetMinimumBitmapWidth().
464 */
465 void SetBitmapPlacement(int placement);
466
467 /**
468 Sets width of border around page area. Default is zero.
469 For backward compatibility, if there are no pages in GetPageAreaSizer(),
470 the default is 5 pixels.
471
472 If there is a five point border around all controls in a page and the border
473 around page area is left as zero, a five point white space along all dialog borders
474 will be added to the control border in order to space page controls ten points
475 from the dialog border and non-page controls.
476 */
477 virtual void SetBorder(int border);
478
479 /**
480 Sets the minimum width for the bitmap that will be constructed to contain the
481 actual wizard or page bitmap if a non-zero bitmap placement flag has been set.
482 If this is not set when using bitmap placement, the initial layout may be incorrect.
483
484 See also SetBitmapPlacement().
485 */
486 void SetMinimumBitmapWidth(int width);
487
488 /**
489 Sets the minimal size to be made available for the wizard pages.
490 The wizard will take into account the size of the bitmap (if any) itself.
491 Also, the wizard will never be smaller than the default size.
492
493 The recommended way to use this function is to lay out all wizard pages
494 using the sizers (even though the wizard is not resizeable) and then use
495 wxSizer::CalcMin() in a loop to calculate the maximum of minimal sizes of
496 the pages and pass it to SetPageSize().
497 */
498 virtual void SetPageSize(const wxSize& sizePage);
499 };
500