wxRuby Documentation Home

# Wx::Wizard

Wizard is the central class for implementing `wizard-like’ dialogs. These
dialogs are mostly familiar to Windows users and are nothing other than a
sequence of `pages’, each displayed inside a dialog which has the
buttons to navigate to the next (and previous) pages.

The wizards are typically used to decompose a complex dialog into several
simple steps and are mainly useful to the novice users, hence it is important
to keep them as simple as possible.

To show a wizard dialog, you must first create an instance of the Wizard class
using either the non-default constructor or a default one followed by call to the
Create function. Then you should add all pages you
want the wizard to show and call run_wizard.
Finally, don’t forget to call `wizard->Destroy()`, otherwise your application will hang on exit due to an undestroyed window.

## Derived from

Dialog

Panel

Window

EvtHandler

Object

## Event table macros

To process input from a wizard dialog, use these event handler macros to
direct input to member functions that take a
WizardEvent argument. For some events,
Veto can be called to prevent the event from
happening.

evt_wizard_page_changed(id) { | event | … } | The page has just beenchanged (this event cannot be vetoed).
evt_wizard_page_changing(id) { | event | … } | The page is beingchanged (this event can be vetoed).
evt_wizard_cancel(id) { | event | … } | The user attempted to cancelthe wizard (this event may also be vetoed).
evt_wizard_help(id) { | event | … } | The wizard help button was pressed.
evt_wizard_finished(id) { | event | … } | The wizard finished button was pressed.

## Extended styles

Use the Window#set_extra_style function to set the following
style. You will need to use two-step construction (use the default constructor, call SetExtraStyle, then call Create).

`WIZARD_EX_HELPBUTTON` | Shows a Help button using ID_HELP.

See also Dialog for other extended styles.

## See also

WizardEvent, WizardPage, Wizard sample

## Methods

- Wizard.new
- Wizard#create
- Wizard#fit_to_page
- Wizard#get_current_page
- Wizard#get_page_area_sizer
- Wizard#get_page_size
- Wizard#has_next_page
- Wizard#has_prev_page
- Wizard#run_wizard
- Wizard#set_page_size
- Wizard#set_border

### Wizard.new

Wizard.new(%(arg-type)Window% parent, Integer id = -1, String title = ’’, Bitmap bitmap = NullBitmap, Point pos = DEFAULT_POSITION, Integer style = DEFAULT_DIALOG_STYLE)

Constructor which really creates the wizard — if you use this constructor, you
shouldn’t call Create.

Notice that unlike almost all other Widgets classes, there is no size
parameter in the Wizard constructor because the wizard will have a predefined
default size by default. If you want to change this, you should use the
get_page_area_sizer function.

#### Parameters

- parent The parent window, may be NULL.
- id The id of the dialog, will usually be just $-1$.
- title The title of the dialog.
- bitmap The default bitmap used in the left side of the wizard. See
  also get_bitmap.
- pos The position of the dialog, it will be centered on the screen
  by default.
- style Window style is passed to Dialog.

### Wizard#create

Boolean create(%(arg-type)Window% parent, Integer id = -1, String title = ’’, Bitmap bitmap = NullBitmap, Point pos = DEFAULT_POSITION, Integer style = DEFAULT_DIALOG_STYLE)

Creates the wizard dialog. Must be called if the default constructor had been
used to create the object.

Notice that unlike almost all other Widgets classes, there is no size
parameter in the Wizard constructor because the wizard will have a predefined
default size by default. If you want to change this, you should use the
get_page_area_sizer function.

#### Parameters

- parent The parent window, may be NULL.
- id The id of the dialog, will usually be just $-1$.
- title The title of the dialog.
- bitmap The default bitmap used in the left side of the wizard. See
  also get_bitmap.
- pos The position of the dialog, it will be centered on the screen
  by default.
- style Window style is passed to Dialog.

### Wizard#fit_to_page

fit_to_page(%(arg-type)WizardPage% firstPage)

This method is obsolete, use
get_page_area_sizer instead.

Sets the page size to be big enough for all the pages accessible via the
given firstPage, i.e. this page, its next page and so on.

This method may be called more than once and it will only change the page size
if the size required by the new page is bigger than the previously set one.
This is useful if the decision about which pages to show is taken during
run-time, as in this case, the wizard won’t be able to get to all pages starting
from a single one and you should call Fit separately for the others.

### Wizard#get_current_page

WizardPage get_current_page()

Get the current page while the wizard is running. `NULL` is returned if
run_wizard is not being executed now.

### Wizard#get_page_area_sizer

Sizer get_page_area_sizer()

Returns pointer to page area sizer. The wizard is laid out using sizers and
the page area sizer is the place-holder for the pages. All pages are resized before
being shown to match the wizard page area.

Page area sizer has a minimal size that is the maximum of several values. First,
all pages (or other objects) added to the sizer. Second, all pages reachable
by repeatedly applying
WizardPage#get_next to
any page inserted into the sizer. Third,
the minimal size specified using set_page_size and
fit_to_page. Fourth, the total wizard height may
be increased to accommodate the bitmap height. Fifth and finally, wizards are
never smaller than some built-in minimal size to avoid wizards that are too small.

The caller can use Sizer#set_min_size to enlarge it
beyond the minimal size. If `RESIZE_BORDER` was passed to constructor, user
can resize wizard and consequently the page area (but not make it smaller than the
minimal size).

It is recommended to add the first page to the page area sizer. For simple wizards,
this will enlarge the wizard to fit the biggest page. For non-linear wizards,
the first page of every separate chain should be added. Caller-specified size
can be accomplished using Sizer#set_min_size.

Adding pages to the page area sizer affects the default border width around page
area that can be altered with set_border.

### Wizard#get_page_size

Size get_page_size()

Returns the size available for the pages.

### Wizard#has_next_page

Boolean has_next_page(%(arg-type)WizardPage% page)

Return `true` if this page is not the last one in the wizard. The base
class version implements this by calling
“page→GetNext”:wizardpagegetnext.html but this could be undesirable if,
for example, the pages are created on demand only.

#### See also

has_prev_page

### Wizard#has_prev_page

Boolean has_prev_page(%(arg-type)WizardPage% page)

Returns `true` if this page is not the last one in the wizard. The base
class version implements this by calling
“page→GetPrev”:wizardpagegetprev.html but this could be undesirable if,
for example, the pages are created on demand only.

#### See also

has_next_page

### Wizard#run_wizard

Boolean run_wizard(%(arg-type)WizardPage% firstPage)

Executes the wizard starting from the given page, returning `true` if it was
successfully finished or `false` if user cancelled it. The firstPage
can not be `NULL`.

### Wizard#set_page_size

set_page_size(%(arg-type)Size% sizePage)

This method is obsolete, use
get_page_area_sizer instead.

Sets the minimal size to be made available for the wizard pages. The wizard
will take into account the size of the bitmap (if any) itself. Also, the
wizard will never be smaller than the default size.

The recommended way to use this function is to lay out all wizard pages using
the sizers (even though the wizard is not resizeable) and then use
Sizer#calc_min in a loop to calculate the maximum
of minimal sizes of the pages and pass it to SetPageSize().

### Wizard#set_border

set_border(%(arg-type)Integer% border)

Sets width of border around page area. Default is zero. For backward
compatibility, if there are no pages in
get_page_area_sizer, the default is $5$ pixels.

If there is a five point border around all controls in a page and the border around
page area is left as zero, a five point white space along all dialog borders
will be added to the control border in order to space page controls ten points from the dialog
border and non-page controls.

[This page automatically generated from the Textile source at 2023-06-09 00:45:29 +0000]