QA: How can I use a property sheet to implement a Wizard?

By Joao Paulo Figueira, August 11, 2003.
Print version

Question

How can I use a property sheet to implement a wizard-like dialog?

Answer

Although the documentation says that the PSH_WIZARD flag is supported for property sheets, it does not seem to work as it should. So, you are a bit left on your own if you want to implement a wizard-like dialog. There is already a solution published on this site - see QA: How can I create a wizard style dialog? (http://www.pocketpcdn.com/articles/wizarddlg.html). The approach presented in that article uses a dialog as the container for property pages, and explicitly implements all the navigation and containment. Fortunately, there is a simpler approach that uses property sheets but, before we get to it, let us look into what Pocket PC property sheets have to offer us.

Pocket PC Property Sheets

Figure 1

In an article published elsewhere - see Property sheet callbacks in the Pocket PC 2002 (http://www.codeproject.com/useritems/cepropertysheet.asp) - the property sheet callback mechanism is introduced and made compatible with MFC, through the CCePropertySheet class. By using a customized callback function, one can add the header and footer found in most Settings property sheets (see Figure 1). The header and footer are set up by handling the PSCB_GETTITLE and PSCB_GETLINKTEXT callback messages:

What this article does not tell you is how the property sheet is assembled by the system, and how you can use this information for your own purposes. The property sheet is a dialog that contains the following items:

• The property page dialog
• The header. This is an optional static child control whose ID is 0x3028.
• The tab control. It is a child control whose ID 0x3020. MFC identifies it as AFX_IDC_TAB_CONTROL
• The footer. This is an optional rich ink control whose text - set by PSCB_GETLINKTEXT - is interpreted as the parameter of a EM_INSERTLINKS message (see richink.h for more information).

The main idea of this article is that the tab control can be hidden and that wizard-like navigation can be implemented using SetActivePage(), GetActiveIndex() and GetPageCount().

Implementation

We are now prepared to implement a wizard-like dialog using a property sheet (CCeWizard). This class derives from CCePropertySheet, thereby allowing the user to insert headers and footers. The first thing we need to do is to set-up the dialog:

We will get to the PopulateToolBar and UpdateControls() methods a bit later. Now, you may notice that after hiding the tab control, the line that separates the header from the dialog is gone too. Apparently, this line is a part of the tab control, and thus it is hidden. To circumvent this problem, we have to draw it ourselves, in the OnPaint method:

Note that the line is drawn only if there is a title (m_strTitle belongs to the CCePropertySheet class).

Navigation

Now, we have to worry about navigating through the wizard: after hiding the tab control, we must provide a means for the user to flip through the several pages (property pages). The best place to put the control buttons is on the command bar. The CCeWizard class provides two options for placing controls on the command bar (although you can certainly override this functionality): graphic buttons or text buttons. If you want to provide graphic buttons (Figure 2), create a toolbar on the resource editor with at least four buttons: ID_BAR_OK, ID_BAR_CANCEL, ID_BAR_BACK and ID_BAR_NEXT. When you create your CCeWizard object, pass the toolbar id as the second parameter to the constructor. To show text buttons (Figure 3), use 0 as the second parameter on the class constructor, and define the following string resources: IDS_BAR_OK, IDS_BAR_CANCEL, IDS_BAR_BACK and IDS_BAR_NEXT.

Figure 2

Figure 3

Handling the navigation commands is a simple matter. Here is the ID_BAR_BACK handler:

And now, the ID_BAR_NEXT handler:

Updating Controls

Now, let's see how to update the wizard's controls. This task is necessary in order to let the application's user know where in the wizard he or she is. This is done in two ways: updating the navigation buttons and reporting the progress in the wizard's header. All of this is achieved in just one method:

Note that the navigation button's state is updated in the same way whether they are graphic or text.

Inserting the Toolbar

Both the graphics and the text toolbar are inserted using just one method:

And that's it.

Easter Egg

During the writing of this QA, an interesting behaviour of the Pocket PC property sheet was found: when you create CCePropertySheet object with a title and, before calling DoModal() you change its style with:

you get an interesting result (Figure 4): here are the next and back buttons! But where are your property pages?

Figure 4

Sample Code

All the code above is available for download in a test application. This applications shows how to use the several options of the property sheet and the wizard, as well as the Easter Egg. PropSheetLnk.zip - 160K.

Related resources:

• QA: How can I create a wizard style dialog?

Discuss