Wizard Framework for WPF User Guide

Getting Started

Back to Table of Contents

Creating a Wizard

All wizards start with the Wizard class itself. This class has a Pages property which exposes a collection of WizardPage objects that are the children of the wizard. This documentation will assume you are using XAML to configure a wizard but of course it can easily be done in code too. Wizard Framework is geared towards XAML configuration, and the first thing you need to do is to ensure you have declared an XML namespace to represent the Wizard Framework classes:

<Window ... xmlns:wz="http://schemas.divelements.co.uk/wpf/wizardframework">

You can thereafter use the wz: prefix to instantiate Wizard Framework classes. To create a very simple wizard with a few pages, all of which have titles, use the following XAML:

<wz:Wizard>
	<wz:WizardPage Title="Page One" />
	<wz:WizardPage Title="Page Two" />
	<wz:WizardPage Title="Page Three" />
</wz:Wizard>

If you run your project at this point the wizard would appear at the first page and would allow you to navigate through the pages using the Next and Previous buttons.

The WizardPage objects are controls that accept a single child. This means that you will typically use a container such as the Grid class as the child of your WizardPage, then further populate that with more children. For example, to create a page hosting a couple of list boxes and some descriptive text you might use the following:

<wz:WizardPage Description="Use the lists to choose the hardware you have attached." Title="Select Hardware">
	<Grid Margin="21,0">
		<Grid.ColumnDefinitions>
			<ColumnDefinition Width="*" />
			<ColumnDefinition Width="*" />
		</Grid.ColumnDefinitions>
		<ListBox Margin="0,20,10,80">
			<ListBoxItem Content="Item 1" />
			<ListBoxItem Content="Item 2" />
			<ListBoxItem Content="Item 3" />
			<ListBoxItem Content="Item 4" />
		</ListBox>
		<ListBox Margin="10,20,0,80" Grid.Column="1">
			<ListBoxItem Content="Item 1" />
			<ListBoxItem Content="Item 2" />
			<ListBoxItem Content="Item 3" />
			<ListBoxItem Content="Item 4" />
		</ListBox>
		<TextBlock Margin="0,0,0,25" VerticalAlignment="Bottom" TextWrapping="Wrap"
			Text="You cannot move beyond this page until certain validation
			criteria are met: an item must be selected in both listboxes."
			Grid.ColumnSpan="2" />
	</Grid>
</wz:WizardPage>

There are two important time-saving properties on all pages: LeadingText and TrailingText. If you specify either of these, the wizard includes the text at the start or finish of the page, respectively, and adjusts the content accordingly. This saves the developer from having to include a TextBlock and configure it on the design surface. Pages also have a Description property, which includes a piece of text under the header when using the Wizard 97 style. The Aero Wizard style has no concept of descriptive text per page, so under that style the Description property is simply ignored.

Once you have your wizard populated with pages with which to collect information, you simply need to handle the Cancel and Finish events of the wizard to complete its integration. The Finish event is triggered when the user presses the Next button (which will be labeled Finish) on the last page.

Hosting the Wizard

Typically, a wizard is the only object in a window. We suggest you use the WizardWindow class to host wizards in your application. WizardWindow is part of the Wizard Framework package. It derives from Window and adds automatic support for Aero Glass in Windows Vista. It also responds automatically to the Cancel and Finish events of a wizard hosted within. To use WizardWindow as your top-level window object, you would use the following:

<wz:WizardWindow x:Class="..."
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:wz="http://schemas.divelements.co.uk/wpf/wizardframework"
    Title="Demonstration Wizard" Width="503" Height="388">
	<wz:Wizard>
		<wz:WizardPage Title="Page One" />
	</wz:Wizard>
</wz:WizardWindow>

Unless your application consists of only a wizard, you will normally show your wizard windows modally. When you use the WizardWindow class and it is shown modally you do not have to handle the Cancel and Finish events of your wizard control. Instead, Wizard Framework will automatically set the DialogResult of your window, causing it to close and return the wizard result to the code that showed it. If you need to prevent this from happening you can set the SetWindowDialogResult property of the wizard to false.

Controlling Page Order and Navigation

When you configure a wizard using either XAML or pure code, you add the pages to the wizard in a certain order. This order becomes the default order of the pages within the wizard. You have already seen that simply adding a bunch of pages then running your application will cause the wizard to step through those pages in the order they appear in XAML.

Each wizard page has a PreviousPage and NextPage property. It is these properties that are automatically set to the neighbouring pages, but they can be explicitly set too. For instance, to create a wizard with three pages which navigates forward normally but goes straight from the third page to the first page when navigating backward, you would use the following:

<wz:Wizard>
	<wz:WizardPage Name="firstPage" Title="Page One" />
	<wz:WizardPage Name="secondPage" Title="Page Two" />
	<wz:WizardPage Name="thirdPage" Title="Third Page" PreviousPage="{Binding ElementName=firstPage}">
		<TextBlock Text="Pressing the Back button will take you back to the first page!" />
	</wz:WizardPage>
</wz:Wizard>

Note that we have had to start naming the pages so they can be referred to by other parts of the XAML.

The AllowCancel, AllowMoveNext and AllowMovePrevious properties of each page determine whether the user is allowed to cancel the wizard and navigate from that page. For instance, during a certain operation you may wish to disallow the cancellation of the wizard for a period of time. The most commonly-used of these properties is AllowMoveNext. It is common to set this property to false until certain input criteria on a page are met. You would set AllowMoveNext to false in your XAML then, in code, respond to validation events of the controls within the page and set the property to true when needed.

Wizard Page Events

We have already discussed events of the wizard itself (Cancel and Finish), but each page also has events and it is these you will need to use to enable fine-grained control over the user's progress through your wizard. These events are set forth in the table below.

BeforeDisplay Occurs when a page is about to be displayed, during navigation. This event should be used to populate any data in the page that is about to be displayed, especially data that needs to be calculated or retrieved based upon choices made earlier in the wizard. To maintain best UI practices, no long-running code should be present in the handler for this event.
AfterDisplay Occurs when a page has just been displayed after the user has moved forwards to it. Also occurs for the first page shown in the wizard. This event is used for triggering code that should run as soon as a page is displayed, such as on a progress page.
BeforeMoveNext Occurs as the user is about to move forwards from the page raising the event. This event is normally used either to perform validation for the page, where the handler sets e.Cancel to false to cancel the forward navigation, or to determine what the next page should be, where the page is being used as a decision page as to which pages should follow. More on this kind of decision-based navigation later.
BeforeMovePrevious Occurs as the user is about to move backwards from the page raising the event.

The InformationBox Control

This control is included with Wizard Framework as a handy way of expressing a piece of text next to a standard Windows image. The text is automatically justified appropriately and the images change depending on what version of Windows your application is running on. Supported images are Information, Warning, Error and UserAccountControl (Vista only).

Next: Further Integration