MFC Programmer WTL Guide (9) Property pages and wizards

Introduced

Even before you become a common control for Windows 95, using a property sheet to represent some options has become a popular way. Wizard-mode property sheets are often used to direct users to install software or perform other complex tasks. WTL provides good support for the property sheets in both ways, using the dialog-related features described earlier, such as DDX and DDV. In this chapter I will show how to create a basic property sheet and wizard, and how to handle the notification messages and events that the property pages send.

WTL property sheet Class

Implementing a property sheet requires a combination of Cpropertysheetwindow and Cpropertysheetimpl two classes, both of which are defined in the Atldlgs.h header file. The Cpropertysheetwindow class is a window interface class (that is, a CWindow derived class), Cpropertysheetimpl a complete implementation of the message map chain and the window, similar to the basic Windows Class of ATL, It requires joint use of CWindow and CWindowImpl two classes.

The Cpropertysheetwindow class encapsulates the processing of various psm_* messages, for example, Setactivepagebyid () encapsulates the psm_setcurselid message. The Cpropertysheetimpl class manages a propsheetheader structure and an array of hpropsheetpage types, and the Cpropertysheetimpl class also provides

Some methods are used to populate propsheetheader structures, add or remove property pages, and you can also use M_PSH member variables to manipulate propsheetheader structures directly.

Finally, the CPropertySheet class is a special case of the Cpropertysheetimpl class, which you can use directly without having to customize the entire property sheet.

The method of Cpropertysheetimpl

Here are some important methods for the Cpropertysheetimpl class. Since many methods are simply encapsulation of window messages, they are not listed here and you can view the complete list of functions in the atldlgs.h.

CPropertySheetImpl(_U_STRINGorID title = (LPCTSTR) NULL,
　　　　　　　　　 UINT uStartPage = 0, HWND hWndParent = NULL)

The constructor of the Cpropertysheetimpl class allows you to use some of the commonly used properties (the default), so you do not need to invoke other methods to set them. Title Specifies the text that appears in the title bar of the property sheet, _u_stringorid is a WTL tool class that automatically converts LPCTSTR and resource IDs, for example, the following two lines of code are correct:

CPropertySheetImpl mySheet ( IDS_SHEET_TITLE );
　 CPropertySheetImpl mySheet ( _T("My prop sheet") );

Ids_sheet_title is the ID of the string. Ustartpage is the property page that is activated when the property sheet is started, and is a 0-based index. hWndParent is the handle to the parent window of the property sheet.

BOOL addpage (Hpropsheetpage hpage)

BOOL addpage (Lpcpropsheetpage pPage)

Add a property page. If this property page has already been created, you can use the first overloaded function and use the handle of the property page (Hpropsheetpage) as an argument. Typically, using the second overloaded function, you can use this overloaded function to simply set up a PROPSHEETPAGE data structure (which, as you'll later talk, works together with Cpropertypageimpl), and Cpropertysheetimpl will create and manage this property page for you.

BOOL removepage (Hpropsheetpage hpage)

BOOL removepage (int npageindex)

To remove a property page, you can use the handle or index of the property page.

BOOL setactivepage (Hpropsheetpage hpage)

BOOL setactivepage (int npageindex)

Sets the active page for the property sheet. You can use the handle or index of the property page. You can use this method to dynamically set an active property page before the property sheet is created (displayed).

void Settitle (LPCTSTR lpsztext, UINT nstyle = 0)

Make the caption text for the property sheet window. Nstyle can be either 0 or psh_proptitle, and if it is psh_proptitle, the property sheet has a psh_proptitle style so that the system adds a string before the window caption you specify through the Lpsztext parameter "properties For ".

void SetWizardMode()

Set the Psh_wizard style to rename the property sheet to wizard mode, which must be called before the property sheet is displayed.

void Enablehelp ()