Magic Logo
top
wizard pages
notifications
methods
properties
events
Class WizardControl
The WizardControl should be used when you need to guide the user through a series of steps. Simple examples include creating an installation program or allowing the creation a new items by answering a series of questions. In most situations you will want to use a modal dialog to host an instance of the WizardControl. Rather than create your own Form the library already includes a Form called WizardDialog.

Please read the documentation article for the WizardDialog for more details on how to use it. You should also run and examine the source code for the SampleWizard which gives a detailed example of how to create a installation style wizard.

Profiles

The Profile property of the control is used to configure the appearance and operation of the wizard. The three available options are: -

Install

As the name implies, this profile should be used to create a series of steps that perform an installation process. In this scenario the ordering of the wizard pages is very important and the control will make assumptions about the purpose of pages.

The last page is always used to report the end result of the install attempt. Therefore the last page will by default only display the Close button as that is the only possible action. It makes no difference if your page is reporting a success or failure result the only possible action is to close down the installation process.

The second to last page is used to perform the actual install action and so the only available button will be Cancel. Once the install attempt has begun it makes no sense allowing the user to move Back to previous pages or to move past the current page. When the install action has completed you should manually move the wizard onto the last page useing the SelectedIndex property in order to report the outcome.

All the preceding pages are assumed to be used in gathering information from the user and so the Next and Back buttons will be shown depending on the appropriate availability. The Cancel button is always shown so that the user can exit the wizard at this time.

Configure

Use this profile to gather information needed to perform a custom action that is conducted once the user clicks the Finish button. A good example would be adding a new item to your project. Every page has the Cancel, Next, Back and Finish buttons displayed with the Next and Back only enabled when appropriate for the selected page. The user can use the Finish button at any time to accept all the default values and have the custom action performed immediately. Alternatively they can move through the series of pages and customize the values.

If you need to enfore some mandatory fields before the Finish button is enabled then change the EnableFinishButton property to Status.No when the control is created. Once you notice that all mandatory fields have been supplied change the property to Status.Yes to allow the user to select the Finish button.

Controller

Unlike the previous profiles this one does not show the heading portion at the top of the control and does show the individual tab headers. This allows the user to click between pages in a random order to select and modify the contents as required. There are only two buttons presented by default, Update and Cancel. Use this profile when the user needs to see and modify a group of related settings. They can use the Update button to apply the changes in an appropriate way or use the Cancel button to discard any changes made.

Customization

If none of the above profiles does exactly what you need then you have scope to customize the the profile that comes closest. Each button has a set of three properties used to control when the button is displayed, when the button is enabled and the text shown on the button. For example, the properties for the Update button are called ShowUpdateButton, EnableUpdateButton and ButtonUpdateText respectively.

Imagine you are using the Controller profile to present a dialog box of project settings to the user. The user can move between pages and change the settings as desired. When they press the Update button you apply those changes immediately. However, you might prefer to have the button called Apply rather than Update. Simply set the ButtonUpdateText property to the required string to change the button text. But you must remember that the event generated when the button is pressed is still called UpdateClick.

In another situation you might have a Cofigure profile used to setup a new item within your project. But you do not want the Cancel button availale to the user, instead you want to force your user to move through the whole process and use the Finish button. In this case you would set the ShowFinishButton property to Status.No which prevents the button from being displayed on any page. If you need a button displayed all the time then assign the Status.Yes value to the appropriate button show property. By default each buttons show and enable properties has the Status.Default value that indicates the control should calculate the correct state depending on the currently seleted Profile and page index.

Often you will want to change the displayed/enabled state of buttons on a per-page basis. In this case you need to hook into the WizardPageEnter and WizardPageLeaveevents and set the appropriate values depending on the page selected.

Default Buttons

By default the AssignDefaultButton property is defined as False and so the control will not make any attempt to assign a default button for the Form the control is contained inside. If you decide to enable this property the following logic is used to determine which button should become the default.

Install Profile
On the last page the only button displayed by default is Close and so this will be used as the default. On the second to last page the only button is Cancel which is therefore the default. All other pages assign the Next button as the default.

Configure Profile
The last page will use the Finish button as the default and all other pages the Next button.

Controller Profile
The Update button is always designated the default in this profile.

Wizard Pages

The WizardPage class derives from the TabPage class and so exposes all the same properties along with two additional ones specific to the WizardPage. The extra propeties are: -

public string SubTile
Define the sub-title for display when this page is selected.
Default: "(Page Description not defined)"

public bool FullPage
When defined the header will be removed so the page has maximum space.
Default: False

In Install and Configure profiles the SubTitle property is used in the header portion of the control for the sub-title display. You should define a page description for each wizard page instance. When the FullPage property is defined the header portion of the control is hidden so that the page takes up the extra space.

When the Controller profile is defined these properties have no effect because the header portion is always hidden meaning the SubTitlecan never be seen and all pages are implicity already FullPage.

Notifications
Each button managed by the control generates an event when clicked. You should hook into these to perform the appropriate action, for example the CancelClick event should be trapped to ensure that when pressed the wizard performs the kind of action expected by the user. The BackClick and NextClick events allow the click to be cancelled and prevent the page transition from occuring.

The most useful events are WizardPageEnter and WizardPageLeave which as the names imply, are fired on entry and exit from an individual WizardPage You can hook into this event and enable/disable buttons in order to prevent page transitions until the user has entered some mandatory fields. Also use this event to override the default decisions made by the selected profile about which buttons are displayed.

Methods
public void ResetProfile()
Resets the Profile property to its default value.

public void ResetPicture()
Resets the Picture property to its default value.

public void ResetTitle()
Resets the Title property to its default value.

public void ResetTitleFont()
Resets the TitleFont property to its default value.

public void ResetSubTitleFont()
Resets the SubTitleFont property to its default value.

public void ResetTitleColor()
Resets the TitleColor property to its default value.

public void ResetSubTitleColor()
Resets the SubTitleColor property to its default value.
Properties
public Controls.TabControl TabControl
Readonly property used to directly access the TabControl using within the WizardControl. This should only be used for customizing the appearance and operation of the TabControl and not alter the contents of the TabControl.TabPages directly.

public Panel HeaderPanel
Readonly property used to directly access the header panel.

public Panel TrailerPanel
Readonly property used to directly access the trailer panel.

public WizardPageCollection WizardPages
Provides access to the list of wizard pages.

public Profiles Profile
Use to define the default operation of buttons and pages.
Default: Profiles.Configure

public int SelectedIndex
Use to discover/set the current wizard page for display.

public Image Picture
Define the picture to draw in the top-right corner of control.
Default: Built in picture

public string Title
Define the text for drawing the main title.
Default: "Welcome to the Wizard Control"

public Font TitleFont
Define the font for drawing the main title.
Default: "Tahoma", 10points, Regular

public Font SubTitleFont
Define the font for drawing the selected pages sub-title.
Default: "Tahoma", 8points, Regular

public Color TitleColor
Define the color for drawing the main title.
Default: base.ForeColor

public Color SubTitleColor
Define the color for drawing the selected pages sub-title.
Default: base.ForeColor

public bool AssignDefaultButton
Determine if the control should automatically assign an appropriate default button.
Default: False

public Status ShowHelpButton
Define when the Help button should be displayed.
Default: Status.Default

public Status ShowUpdateButton
Define when the Update button should be displayed.
Default: Status.Default

public Status ShowCancelButton
Define when the Cancel button should be displayed.
Default: Status.Default

public Status ShowBackButton
Define when the Back button should be displayed.
Default: Status.Default

public Status ShowNextButton
Define when the Next button should be displayed.
Default: Status.Default

public Status ShowFinishButton
Define when the Finish button should be displayed.
Default: Status.Default

public Status ShowCloseButton
Define when the Close button should be displayed.
Default: Status.Default

public Status EnableHelpButton
Define when the Help button should be enabled.
Default: Status.Default

public Status EnableUpdateButton
Define when the Update button should be enabled.
Default: Status.Default

public Status EnableCancelButton
Define when the Cancel button should be enabled.
Default: Status.Default

public Status EnableBackButton
Define when the Back button should be enabled.
Default: Status.Default

public Status EnableNextButton
Define when the Next button should be enabled.
Default: Status.Default

public Status EnableFinishButton
Define when the Finish button should be enabled.
Default: Status.Default

public Status EnableCloseButton
Text displayed in the Close button.
Default: "Close"

public string ButtonHelpText
Text displayed in the Help button.
Default: "Help"

public string ButtonUpdateText
Text displayed in the Update button.
Default: "Update"

public string ButtonCancelText
Text displayed in the Cancel button.
Default: "Cancel"

public string ButtonBackText
Text displayed in the Back button.
Default: "< Back"

public string ButtonNextText
Text displayed in the Next button.
Default: "Next >"

public string ButtonFinishText
Text displayed in the Finish button.
Default: "Finish"

public string ButtonCloseText
Text displayed in the Close button.
Default: "Close"

Events
public event WizardPageHandler WizardPageEnter
Fired when the user moves into a new WizardPage.

public event WizardPageHandler WizardPageLeave
Fired when the user leaves the current WizardPage.

public event EventArgs WizardCaptionTitleChanged
Fired when the CaptionTitle property of a WizardPage changes.

public event EventArgs SelectionChanged
Fired after a change in selected WizardPage occurs.

public event EventArgs CloseClick
Fired when the user clicks the Close button.

public event EventArgs FinishClick
Fired when the user clicks the Finish button.

public event CancelEventArgs NextClick
Fired when the user clicks the Next button.

public event CancelEventArgs BackClick
Fired when the user clicks the Back button.

public event EventArgs CancelClick(EventArgs e)
Fired when the user clicks the Cancel button.

public event EventArgs UpdateClick(EventArgs e)
Fired when the user clicks the Update button. public event EventArgs HelpClick(EventArgs e)
Fired when the user clicks the Help button.

Delegates


   public delegate void WizardPageHandler(WizardPage wp, WizardControl wc)