Selection Changes

The selected page in the Wizard can be changed programmatically and numerous cancelable selection changed events fire whenever a page change occurs.

Programmatically Getting or Setting the Selected Page

Wizard has several members that are essential for getting or setting the currently selected page programmatically:

Page Change Event Sequence

Whenever a selected page change occurs, regardless of what caused it, numerous events fire. The event sequence is designed so that you can process the selection change events at either the wizard or page-specific levels.

All of the events receive an informative event argument of type WizardSelectedPageChangeEventArgs that has these important members:

The first events that fire upon a page change request are page changing events. These are cancellable events and if the Cancel property is set in these, then the page change will be cancelled and no new selected page will be set.

Page changing events fire in this order:

• Wizard.PreviewSelectedPageChanging

• WizardPage.Unselecting on the old selected page

• WizardPage.Selecting on the new selected page

• Wizard.SelectedPageChanging

If the page change is not cancelled, then the actual page change will occur and a series of page changed events fire.

Page changed events fire in this order:

• Wizard.PreviewSelectedPageChanged

• WizardPage.Unselected on the old selected page

• WizardPage.Selected on the new selected page

• Wizard.SelectedPageChanged

Page changed events are a great place to add code to initialize a page that is about to be displayed.

Page Selection Flags

The WizardSelectedPageChangeEventArgs.SelectionFlags property of the event arguments gives you a lot of information about why the selected page change occurred. This lets you better determine whether you may want to take some sort of programmatic action to override or cancel a page change.

The WizardPageSelectionFlags flags enumeration has these values:

Forward and Backward Progress

Wizard tracks a notion of forward and backward progress. This is used in several internal areas such as stack-based page sequencing and for transition effects.

When moving "forward" through pages, it is assumed you are doing things like clicking the Next button. When moving "backward" through pages, it is assumed you are doing things like clicking the Back button.

Transitions use this information so that they can be set to perform their effects in one direction when moving forward, or in another direction when moving backward.

Overriding Selected Page Changes to a Select a Different Page

Sometimes you may wish to abort default page sequencing and provide your own decision-based sequencing instead.

This code shows how to alter the page that will be selected next when a specific page is set and a CheckBox is checked. The new selected page will be programmatically set in this scenario. Note that if the CheckBox is not checked, the default page sequencing will be used.

private void wizard_SelectedPageChanging(object sender, WizardSelectedPageChangeEventArgs e) {
	if (e.OldSelectedPage == decisionBasedPage) {
		if (alternatePathCheckBox.IsChecked == true) {
			e.NewSelectedPage = alternatePage;
		}
	}
}

Canceling Selected Page Changes / Validation

As mentioned above, selected page changes may be canceled in any of the page changing events. Functionality of cancelling and not moving to a new page is generally used for data validation purposes.

This code shows how to cancel a page change at the wizard level when a specific page is set and a name TextBox is empty.

private void wizard_SelectedPageChanging(object sender, WizardSelectedPageChangeEventArgs e) {
	if (e.OldSelectedPage == dataEntryPage) {
		if (nameTextBox.Text.Length == 0) {
			MessageBox.Show("Please enter a name.");
			e.Cancel = true;
		}
	}
}