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