CPropertySheet Class

Represents property sheets, also known as tab dialog boxes.

class CPropertySheet : public CWnd

Members

Public Constructors

Name

Description

CPropertySheet::CPropertySheet

Constructs a CPropertySheet object.

Public Methods

Name

Description

CPropertySheet::AddPage

Adds a page to the property sheet.

CPropertySheet::Construct

Constructs a CPropertySheet object.

CPropertySheet::Create

Displays a modeless property sheet.

CPropertySheet::DoModal

Displays a modal property sheet.

CPropertySheet::EnableStackedTabs

Indicates whether the property sheet uses stacked or scrolling tabs.

CPropertySheet::EndDialog

Terminates the property sheet.

CPropertySheet::GetActiveIndex

Retrieves the index of the active page of the property sheet.

CPropertySheet::GetActivePage

Returns the active page object.

CPropertySheet::GetPage

Retrieves a pointer to the specified page.

CPropertySheet::GetPageCount

Retrieves the number of pages in the property sheet.

CPropertySheet::GetPageIndex

Retrieves the index of the specified page of the property sheet.

CPropertySheet::GetTabControl

Retrieves a pointer to a tab control.

CPropertySheet::MapDialogRect

Converts the dialog-box units of a rectangle to screen units.

CPropertySheet::OnInitDialog

Override to augment property sheet initialization.

CPropertySheet::PressButton

Simulates the choice of the specified button in a property sheet.

CPropertySheet::RemovePage

Removes a page from the property sheet.

CPropertySheet::SetActivePage

Programmatically sets the active page object.

CPropertySheet::SetFinishText

Sets the text for the Finish button.

CPropertySheet::SetTitle

Sets the caption of the property sheet.

CPropertySheet::SetWizardButtons

Enables the wizard buttons.

CPropertySheet::SetWizardMode

Enables the wizard mode.

Public Data Members

Name

Description

CPropertySheet::m_psh

The Windows PROPSHEETHEADER structure. Provides access to basic property sheet parameters.

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.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CPropertySheet

Requirements

Header: afxdlgs.h

See Also

Reference

CWnd Class

Hierarchy Chart

Concepts

MFC Sample CMNCTRL1

MFC Sample CMNCTRL2

MFC Sample PROPDLG

MFC Sample SNAPVW