Magic Logo
top
properties
methods
Class WizardDialog
The WizardDialog should be used when you need to create a wizard that appears as a modal dialog Form. To do this yourself simply create a new Form and fill the entire client area with an instance of the WizardControl. To save you time, this has already been done and added to the library. You can use visual inheritance to derive from and customize it.

Visual Inheritance

Use the Add New Item option from your project and select the Inherited Form selection. If your project already has a reference to the Magic Library then it will present a list of the forms you can inherit from. Otherwise use the Browse button and navigate to the MagicLibrary.dll assembly. From the list of forms availble for inheritance double click WizardDialog a new Class will be added to your project.

Configuring

Double click your new source file and the designer will show your Form with the WizardControl already apparent. Click on the header portion and then navigate to the Properties window to start configuring the wizard setup. At a minimum you should examine and modify the Profile and Title.

Click the elipses button for the WizardPages property to add and configure the individual pages you need. To design each page you should modify the SelectedIndex property to the page index of interest. When a valid page index is defined you will notice a grid appear on the page portion of the control which indicates that design surface available for dragging and dropping controls from the toolbox.

Caption bar text

You can adjust the static text in the caption bar by using the Text property of your derived Form instance. You can use the TitleMode property to determine if any extra text should be appended dynamically depending on the currently selected page. By default the WizardPage.CaptionTitle property for the currently selected page is used. If you prefer to have to no extra text appended then simply set the TitleMode property to TitleModes.None. Note that this property is implemented on the WizardDialog class and so you need to select the whole Form before it will become available. You will not see it listed when the WizardControl instance inside the Form is selected in the properties window.

Wizard Events

All the WizardControl events have attached handlers that are declared as virtual so that you can override them as appropriate in your derived Form class. By default the OnCloseClick and OnFinishClick will set the dialog result code to DialogResult.OK and close the Form. The OnCancelClick handler sets the result code to DialogResult.Cancel and also closes the Form. All the other handlers have no default implementation.

An example of customization might be overriding the OnCancelClick virtual method. Your derived method could display a message box asking the user if they want to abort the wizard and exit. If they answer in the affirmative then you call the base implementation that closes down the Form. Otherwise you do not call the base method and so prevent the close operation from occuring.

Properties
public TitleModes TitleMode Has five possible values.
  • TitleModes.None Uses the Form.Text value only
  • TitleModes.WizardPageTitle Appends the WizardPage.Title value
  • TitleModes.WizardPageSubTitle Appends the WizardPage.SubTitle value
  • TitleModes.WizardPageCaptionTitle Appends the WizardPage.CaptionTitle value
  • TitleModes.Steps Appends 'Step 1 of 5' style description
Default: TitleModes.WizardPageCaptionTitle

Methods
public void ResetTitleMode() Used to redefine the TitelMode to the default value

protected virtual void ApplyTitleMode() Implements calculation of caption text to match current TitleMode setting. Override this method to implement customization of title text.

protected virtual void OnPagesCleared() Will update the caption bar text to reflect the new collection size

protected virtual void OnPagesChanged() Will update the caption bar text to reflect the new collection size

protected virtual void OnCloseClick(object sender, EventArgs e)
By default will close the Form with result of DialogResult.OK

protected virtual void OnFinishClick(object sender, EventArgs e)
By default will close the Form with result of DialogResult.OK

protected virtual void OnCancelClick(object sender, EventArgs e)
By default will close the Form with result of DialogResult.Cancel

protected virtual void OnNextClick(object sender, CancelEventArgs e)
By default does nothing, override to add your own functionality

protected virtual void OnBackClick(object sender, CancelEventArgs e)
By default does nothing, override to add your own functionality

protected virtual void OnUpdateClick(object sender, EventArgs e)
By default does nothing, override to add your own functionality

protected virtual void OnHelpClick(object sender, EventArgs e)
By default does nothing, override to add your own functionality

protected virtual void OnSelectionChanged(object sender, EventArgs e)
Will update the caption bar text to reflect the new page selection

protected virtual void OnWizardEnterPage(WizardPage wp, WizardControl wc)
By default does nothing, override to add your own functionality

protected virtual void OnWizardEnterLeave(WizardPage wp, WizardControl wc)
By default does nothing, override to add your own functionality

protected virtual void OnWizardCaptionTitleChanged(object sender, EventArgs e)
Will update the caption bar text to reflect the new value