Wizard Framework for Windows Forms User Guide

Getting Started

Back to Table of Contents

Creating a Wizard

All wizards start with the Wizard class itself. This class, like all parent controls, has a Controls property to which you add WizardPage controls. No other type of child control can be added. When you create a wizard by dropping an instance of the Wizard class on your form from the toolbox, three pages are automatically added to it by the designer. Also, the wizard's Dock property is automatically set to Fill, so it will fill the container you drag it to. In most situations your form will contain the wizard as its only child. The first thing you might do with a new wizard is to set the MarginImage and BannerImage properties to tailor the wizard to your liking.

You will notice that at design time you use the Back and Next buttons to move through your wizard, just like you would at runtime. An additional feature of the designer is a hyperlink "Choose Page" which, when clicked, shows a list of all pages in the wizard so that you can quickly jump to the one you need. Note that no matter which page is selected at design time, at runtime the wizard will start with the first page.

A dotted outline on each page indicates the designable area in which you can add child controls. We use the snaplines feature of the designer to suggest layout characteristics for laying out these child controls. For instance, although a page is quite wide, best practices suggest leaving a standard margin at the side, and snaplines help with that. To set the title of a page, use its Text property.

To add pages, right-click on an existing page and select either Add Page Before or Add Page After. In this way you can populate your wizard with as many pages as you need and fill them all with child controls. For simple linear wizards this is all you'll need to do to configure the wizard.

There are two important time-saving properties on all pages: IntroductionText and ProceedText. If you specify either of these, the wizard includes the text at the start or finish of the page, respectively. Having text at the top or bottom of a page is so common that saving the developer from having to add and configure a label each time is a good boost of productivity. 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 standard Form class, resize it to about 550 by 400 pixels and drop a Wizard into it from the toolbox, which will take up all available space automatically.

Unless your application consists of only a wizard, you will normally show your wizard windows modally. When the AutoCloseModalForm property of your wizard is set to true (the default) the wizard will automatically set the DialogResult of the form to OK or Cancel when the wizard is finished or cancelled. If you are not showing the form modally, or you do not wish this to happen, you'll need to respond to the Cancel and Finish events of the wizard instead.

Controlling Page Order and Navigation

The order of paging within a wizard is determined by the NextPage and PreviousPage properties of each page. When you create a wizard, three pages are automatically added to it: a start page, a standard page and a finish page. These all have their NextPage and PreviousPage properties set appropriately to one another. As you use the designer to add pages, the designer also looks after these properties to ensure they are updated correctly.

A slightly more advanced wizard might have three pages where if you press the Back button from the last page, you go straight to the first page. An example of this is a wizard on which the middle page the user does nothing; a progress bar is shown instead as an operation completes. This is very easy to achieve: just navigate to the last page and set its PreviousPage property to the first page. The designer makes this quite easy by showing a dropdown of all pages in the propertygrid; all you need to do is name all your pages appropriately and it becomes very straightforward.

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 at design time 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.
BeforeMoveBack 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 Application, Error, Information, Question and Warning.

Next: Further Integration