A property sheet is a system-defined dialog box that you use to view or modify object attributes or properties. A property sheet includes a frame, a title bar, and three buttons: OK, Cancel (X), and Help (?), located atop the window. To use property sheets, you must include the Prsht.h header file in your application.
A property sheet contains and manages one or more related dialog boxes, called property pages. Each page in a property sheet is an application-defined modeless dialog box that manages the controls that enable a user to view and edit the properties of an object. A property sheet must contain at least one property page, but cannot contain more than the value of MAXPROPPAGES as defined in the header files.
Users access property sheets by using an ALT+Tap action. A property sheet sends a notification message to the dialog box procedure for a page when the page becomes active or inactive and when a user taps the OK, Cancel (X), or Help (?) button. The notifications are sent in the form of WM_NOTIFY messages. The lParam parameter of the WM_NOTIFY messages points to an NMHDR structure, which includes the window handle to the property sheet dialog box. Some notification messages require that a property sheet page return either TRUE or FALSE in response to the WM_NOTIFY message. To respond, the page must use the SetWindowLong function to set the DWL_MSGRESULT value for the page dialog box to either TRUE or FALSE.
Each page has a corresponding label, which the property sheet displays in the tab that it creates for the page. Because all property sheet pages expect you to use a roman font, and not bold, you must ensure that the font is not bold by specifying the DS_3DLOOK style in the dialog box template. The following screen shot shows a Windows CE property sheet.
Before creating a property sheet, you must define one or more pages.
To define a property sheet pageOnce you have defined one or more property sheet pages, you can create a property sheet. One way to create a property sheet is to specify the address of a PROPSHEETHEADER structure in a call to the PropertySheet function. The structure defines the icon and title for the property sheet and also includes a pointer to an array of HPROPSHEETPAGE handles. When PropertySheet creates the property sheet, it includes the pages identified in the array. The order of the array determines the order of the pages in the property sheet.
Another method to create a property sheet is to specify an array of PROPSHEETHEADER structures instead of an array of HPROPSHEETPAGE handles. In this case, PropertySheet creates handles for the pages before adding them to the property sheet.
The PropertySheet function automatically sets the size and initial position of a property sheet. The position is based on the position of the owner window, and the size is based on the largest page specified in the array of pages when the property sheet is created.
After creating a property sheet, you can add and remove pages by using the PSM_ADDPAGE message. Note that the size of the property sheet cannot change after it has been created, so the new page must be no larger than the largest page currently in the property sheet. To remove a page, use the PSM_REMOVEPAGE message. When you define a page, you can specify the address of the PropSheetPageProc callback function that the property sheet calls when it creates or removes the page. Using PropSheetPageProc enables you to initialize individual property sheet pages.
To destroy a page that was created by the CreatePropertySheetPage function, but was not added to the property sheet, use the DestroyPropertySheetPage function. Destroying a property sheet automatically destroys all pages that have been added. The system destroys the pages in reverse order from that specified in the array used to create the pages.
You specify the title of a property sheet in the PROPSHEETHEADER structure that you used to create the property sheet. If the dwFlags member includes the PSH_PROPTITLE value, the property sheet adds the prefix "Properties" to the specified title string. Use the PSM_SETTITLE message to change the title after a property sheet has been created.
By default, a property sheet uses the name string specified in the dialog box template as the label for the property page sheet page. You can override the name string by including the PSP_USETITLE value as the dwFlags member of the PROPSHEETPAGE structure that defines the page. When PSP_USETITLE is specified, the pszTitle member must contain the address of the label string for the page.