Share via


CPropertySheet Class

Represents property sheets, also known as tab dialog boxes.

class CPropertySheet : public CWnd

Remarks

A property sheet consists of a CPropertySheet object and one or more CPropertyPage objects. The framework displays a property sheet as a window with a set of tab indices and an area that contains the currently selected page. The user navigates to a specific page by using the appropriate tab.

CPropertySheet provides support for the expanded PROPSHEETHEADER structure introduced in Windows 98 and Windows NT 2000. The structure contains additional flags and members that support using a "watermark" background bitmap.

To display these new images automatically in your property sheet object, pass valid values for the bitmap and palette images in the call to CPropertySheet::Construct or CPropertySheet::CPropertySheet.

Even though CPropertySheet is not derived from CDialog, managing a CPropertySheet object is like managing a CDialog object. For example, creation of a property sheet requires two-part construction: call the constructor, and then call DoModal for a modal property sheet or Create for a modeless property sheet. CPropertySheet has two types of constructors: CPropertySheet::Construct and CPropertySheet::CPropertySheet.

When you construct a CPropertySheet object, some Window Styles can cause a first-chance exception to occur. This results from the system trying to change the style of the property sheet before the sheet is created. To avoid this exception, make sure that you set the following styles when you create your CPropertySheet:

  • DS_3DLOOK

  • DS_CONTROL

  • WS_CHILD

  • WS_TABSTOP

The following styles are optional, and will not cause the first-chance exception:

  • DS_SHELLFONT

  • DS_LOCALEDIT

  • WS_CLIPCHILDREN

Any other Window Styles are forbidden and you should not enable them.

Exchanging data between a CPropertySheet object and an external object is similar to exchanging data with a CDialog object. The important difference is that the settings of a property sheet are typically member variables of the CPropertyPage objects rather than of the CPropertySheet object itself.

You can create a type of tab dialog box called a wizard, which consists of a property sheet with a sequence of property pages that guide the user through the steps of an operation, such as setting up a device or creating a newsletter. In a wizard-type tab dialog box, the property pages do not have tabs, and only one property page is visible at a time. Also, instead of having OK and Apply Now buttons, a wizard-type tab dialog box has a Back button, a Next or Finish button, a Cancel button, and a Help button.

To create a wizard-type dialog box, follow the same steps that you would follow to create a standard property sheet, but call SetWizardMode before you call DoModal. To enable the wizard buttons, call SetWizardButtons, using flags to customize their function and appearance. To enable the Finish button, call SetFinishText after the user has taken action on the last page of the wizard.

For more information about how to use CPropertySheet objects, see the article Property Sheets and Property Pages. Also, see Knowledge Base article Q146916 : HOWTO: Create a Modeless CPropertySheet with Standard Buttons and article Q300606 : HOWTO: Design a Resizable MFC Property Sheet.

Requirements

Header: afxdlgs.h

Smart Device Developer Notes

Not supported for Smartphone projects.

See Also

Tasks

CMNCTRL1 Sample: Demonstrates Common Control MFC Classes, Part 1

CMNCTRL2 Sample: Demonstrates Common Control MFC Classes, Part 2

PROPDLG Sample: Demonstrates Property Sheet Support

SNAPVW Sample: Uses Property Pages in a Form View Application

Reference

CWnd Class

Hierarchy Chart

Other Resources

CPropertySheet Members