Using Property Sheets

Before creating a property sheet, you must define one or more pages.

    To define a property sheet page

1. Create a PROPSHEETPAGE structure which contains information about a property sheet's icon, label, dialog box template, dialog box procedure, and other attributes.
2. Call the CreatePropertySheet function and pass it a pointer to the PROPSHEETPAGE structure. The function returns a HPROPSHEETPAGE handle to the property page.

Once 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 allows you to initialize and cleanup 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 of the pages that have been added to it. 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.