`CPropertySheet` Class

Article
12/01/2022

Represents property sheets, also known as tab dialog boxes.

Syntax

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.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CPropertySheet

Requirements

Header: afxdlgs.h

`CPropertySheet::AddPage`

Adds the supplied page with the rightmost tab in the property sheet.

void AddPage(CPropertyPage* pPage);

Parameters

pPage
Points to the page to be added to the property sheet. Cannot be NULL.

Remarks

Add pages to the property sheet in the left-to-right order you want them to appear.

AddPage adds the CPropertyPage object to the CPropertySheet object's list of pages but does not actually create the window for the page. The framework postpones creation of the window for the page until the user selects that page.

When you add a property page using AddPage, the CPropertySheet is the parent of the CPropertyPage. To gain access to the property sheet from the property page, call CWnd::GetParent.

It is not necessary to wait until creation of the property sheet window to call AddPage. Typically, you will call AddPage before calling DoModal or Create.

If you call AddPage after displaying the property page, the tab row will reflect the newly added page.

Example

// Add three pages to a CPropertySheet object, then show the 
// CPropertySheet object as a modal dialog.  CStylePage, CShapePage,  
// and CColorPage are CPropertyPage-derived classes created 
// by the Add Class wizard.  

CPropertySheet dlgPropertySheet(_T("Simple PropertySheet"));

CStylePage     stylePage;
CColorPage     colorPage;
CShapePage     shapePage;
dlgPropertySheet.AddPage(&stylePage);
dlgPropertySheet.AddPage(&colorPage);
dlgPropertySheet.AddPage(&shapePage);

dlgPropertySheet.DoModal();

`CPropertySheet::Construct`

Constructs a CPropertySheet object.

void Construct(
    UINT nIDCaption,
    CWnd* pParentWnd = NULL,
    UINT iSelectPage = 0);

void Construct(
    LPCTSTR pszCaption,
    CWnd* pParentWnd = NULL,
    UINT iSelectPage = 0);

void Construct(
    UINT nIDCaption,
    CWnd* pParentWnd,
    UINT iSelectPage,
    HBITMAP hbmWatermark,
    HPALETTE hpalWatermark = NULL,
    HBITMAP hbmHeader = NULL);

void Construct(
    LPCTSTR pszCaption,
    CWnd* pParentWnd,
    UINT iSelectPage,
    HBITMAP hbmWatermark,
    HPALETTE hpalWatermark = NULL,
    HBITMAP hbmHeader = NULL);

Parameters

nIDCaption
ID of the caption to be used for the property sheet.

pParentWnd
Pointer to the parent window of the property sheet. If NULL, the parent window will be the main window of the application.

iSelectPage
The index of the page that will initially be on top. Default is the first page added to the sheet.

pszCaption
Pointer to a string containing the caption to be used for the property sheet. Cannot be NULL.

hbmWatermark
Handle to the watermark bitmap of the property page.

hpalWatermark
Handle to the palette of the watermark bitmap and/or header bitmap.

hbmHeader
Handle to the header bitmap of the property page.

Remarks

Call this member function if one of the class constructors has not already been called. For example, call Construct when you declare or allocate arrays of CPropertySheet objects. In the case of arrays, you must call Construct for each member in the array.

To display the property sheet, call DoModal or Create. The string contained in the first parameter will be placed in the caption bar for the property sheet.

You can display watermark and/or header images automatically if you use the third or fourth prototypes of Construct, listed above, and you pass valid values for the hbmWatermark, hpalWatermark, and/or hbmHeader parameters.

Example

The following example demonstrates under what circumstances you would call Construct.

const int c_cSheets = 3;
CPropertySheet   grpropsheet[c_cSheets];
// no need to call Construct for this next one
CPropertySheet   someSheet(_T("Some sheet"));

LPTSTR rgszSheets[c_cSheets] = {
   _T("Sheet 1"),
   _T("Sheet 2"),
   _T("Sheet 3")
};

for (int i = 0; i < c_cSheets; i++)
   grpropsheet[i].Construct(rgszSheets[i]);

`CPropertySheet::CPropertySheet`

Constructs a CPropertySheet object.

CPropertySheet();

explicit CPropertySheet(
    UINT nIDCaption,
    CWnd* pParentWnd = NULL,
    UINT iSelectPage = 0);

explicit CPropertySheet(
    LPCTSTR pszCaption,
    CWnd* pParentWnd = NULL,
    UINT iSelectPage = 0);

CPropertySheet(
    UINT nIDCaption,
    CWnd* pParentWnd,
    UINT iSelectPage,
    HBITMAP hbmWatermark,
    HPALETTE hpalWatermark = NULL,
    HBITMAP hbmHeader = NULL);

CPropertySheet(
    LPCTSTR pszCaption,
    CWnd* pParentWnd,
    UINT iSelectPage,
    HBITMAP hbmWatermark,
    HPALETTE hpalWatermark = NULL,
    HBITMAP hbmHeader = NULL);

Parameters

nIDCaption
ID of the caption to be used for the property sheet.

pParentWnd
Points to the parent window of the property sheet. If NULL, the parent window will be the main window of the application.

iSelectPage
The index of the page that will initially be on top. Default is the first page added to the sheet.

pszCaption
Points to a string containing the caption to be used for the property sheet. Cannot be NULL.

hbmWatermark
A handle to the background bitmap of the property sheet.

hpalWatermark
A handle to the palette of the watermark bitmap and/or header bitmap.

hbmHeader
A handle to the header bitmap of the property page.

Remarks

To display the property sheet, call DoModal or Create. The string contained in the first parameter will be placed in the caption bar for the property sheet.

If you have multiple parameters (for example, if you are using an array), use Construct instead of CPropertySheet.

You can display watermark and/or header images automatically if you use the third or fourth prototypes of CPropertySheet, above, and you pass valid values for the hbmWatermark, hpalWatermark, and/or hbmHeader parameters.

Example

// Declare a CPropertySheet object titled "Simple PropertySheet".
CPropertySheet dlgPropertySheet1(_T("Simple PropertySheet"));

// Declare a CPropertySheet object whose title is specified in the
// IDS_PROPERTYSHEET_TITLE string resource, and the second page is
// initially on top.  
CPropertySheet dlgPropertySheet2(IDS_PROPERTYSHEET_TITLE, this, 1);

`CPropertySheet::Create`

Displays a modeless property sheet.

virtual BOOL Create(CWnd* pParentWnd = NULL,
    DWORD dwStyle = (DWORD)-1,
    DWORD dwExStyle = 0);

Parameters

pParentWnd
Points to parent window. If NULL, parent is the desktop.

dwStyle
Window styles for property sheet. For a complete list of available styles, see Window Styles.

dwExStyle
Extended window styles for property sheet. For a complete list of available styles, see Extended Window Styles

Return Value

Nonzero if the property sheet is created successfully; otherwise 0.

Remarks

The call to Create can be inside the constructor, or you can call it after the constructor is invoked.

The default style, expressed by passing -1 as dwStyle, is actually WS_SYSMENU|WS_POPUP|WS_CAPTION|DS_MODALFRAME|DS_CONTEXTHELP|WS_VISIBLE. The default extended window style, expressed by passing 0 as dwExStyle, is actually WS_EX_DLGMODALFRAME.

The Create member function returns immediately after creating the property sheet. To destroy the property sheet, call CWnd::DestroyWindow.

Modeless property sheets displayed with a call to Create do not have OK, Cancel, Apply Now, and Help buttons as modal property sheets do. Desired buttons must be created by the user.

To display a modal property sheet, call DoModal instead.

Example

// This code fragment shows how to create a modeless property sheet 
// dialog in a command message handler (OnModelessPropertySheet()) 
// of a CView-derived class.
void CPSheetView::OnModelessPropertySheet()
{
   // Declare a CPropertySheet object.  m_pdlgPropertySheet is a data
   // member of type CPropertySheet in CView-derived class.
   m_pdlgPropertySheet = new CPropertySheet(_T("Simple PropertySheet"));
   ASSERT(m_pdlgPropertySheet);

   // Add three pages to the CPropertySheet object.  Both m_pstylePage, 
   // m_pcolorPage, and m_pshapePage are data members of type 
   // CPropertyPage-derived classes in CView-derived class.
   m_pstylePage = new CStylePage;
   m_pcolorPage = new CColorPage;
   m_pshapePage = new CShapePage;
   m_pdlgPropertySheet->AddPage(m_pstylePage);
   m_pdlgPropertySheet->AddPage(m_pcolorPage);
   m_pdlgPropertySheet->AddPage(m_pshapePage);

   // Create a modeless CPropertySheet dialog.
   m_pdlgPropertySheet->Create();
}

// The code fragment below shows how to destroy the C++ objects for
// propertysheet and propertypage in the destructor of CView-derived
// class.
// NOTE:  DestroyWindow() is called in CPropertySheet::OnClose() so
// you do not need to call it here.  Property pages are children
// of the CPropertySheet, they will be destroyed by their parents.
CPSheetView::~CPSheetView()
{
   delete m_pshapePage;
   delete m_pstylePage;
   delete m_pcolorPage;
   delete m_pdlgPropertySheet;
}

`CPropertySheet::DoModal`

Displays a modal property sheet.

virtual INT_PTR DoModal();

Return Value

IDOK or IDCANCEL if the function was successful; otherwise 0 or -1. If the property sheet has been established as a wizard (see SetWizardMode), DoModal returns either ID_WIZFINISH or IDCANCEL.

Remarks

The return value corresponds to the ID of the control that closed the property sheet. After this function returns, the windows corresponding to the property sheet and all the pages will have been destroyed. The objects themselves will still exist. Typically, you will retrieve data from the CPropertyPage objects after DoModal returns IDOK.

To display a modeless property sheet, call Create instead.

When a property page is created from its corresponding dialog resource, it can cause a first-chance exception. This results from the property page changing the style of the dialog resource to the required style before the page is created. Because resources are generally read-only, this causes an exception. The system handles the exception, and makes a copy of the modified resource. The first-chance exception can therefore be ignored.

Note

This exception must be handled by the operating system if you are compiling with the asynchronous exception handling model. For more information about exception handling models, see /EH (Exception Handling Model). In this case, do not wrap calls to CPropertySheet::DoModal with a C++ try-catch block in which the catch handles all exceptions, for example, catch (...). This block would handle the exception intended for the operating system, and cause unpredictable behavior. However, you can safely use C++ exception handling with specific exception types or structured exception handling where the Access Violation exception is passed through to the operating system.

To avoid generating this first-chance exception, you can manually guarantee that the property sheet has the correct Window Styles. You need to set the following styles for a property sheet:

DS_3DLOOK
DS_CONTROL
WS_CHILD
WS_TABSTOP

You can use the following optional styles without causing a first-chance exception:

DS_SHELLFONT
DS_LOCALEDIT
WS_CLIPCHILDREN

Disable all other Windows styles because they are not compatible with property sheets. This advice does not apply to extended styles. Setting these standard styles appropriately will guarantee that the property sheet does not have to be modified and will avoid generating the first-chance exception.

Example

See the example for CPropertySheet::AddPage.

`CPropertySheet::EnableStackedTabs`

Indicates whether to stack rows of tabs in a property sheet.

void EnableStackedTabs(BOOL bStacked);

Parameters

bStacked
Indicates whether stacked tabs are enabled in the property sheet. Disable stacked rows of tags by setting bStacked to FALSE.

Remarks

By default, if a property sheet has more tabs than will fit in a single row in the width of the property sheet, the tabs will stack in multiple rows. To use scrolling tabs instead of stacking tabs, call EnableStackedTabs with bStacked set to FALSE before calling DoModal or Create.

You must call EnableStackedTabs when you create a modal or a modeless property sheet. To incorporate this style in a CPropertySheet-derived class, write a message handler for WM_CREATE. In the overridden version of CWnd::OnCreate, call EnableStackedTabs( FALSE ) before calling the base class implementation.

Example

int CMyPropertySheet::OnCreate(LPCREATESTRUCT lpCreateStruct)
{
   // Set for Scrolling Tabs style
   EnableStackedTabs(FALSE);
   // Call the base class
   if (CPropertySheet::OnCreate(lpCreateStruct) == -1)
      return -1;

   return 0;
}

`CPropertySheet::EndDialog`

Terminates the property sheet.

void EndDialog(int nEndID);

Parameters

nEndID
Identifier to be used as return value of the property sheet.

Remarks

This member function is called by the framework when the OK, Cancel, or Close button is pressed. Call this member function if an event occurs that should close the property sheet.

This member function is only used with a modal dialog box.

Example

See the example for CPropertySheet::PressButton.

`CPropertySheet::GetActiveIndex`

Gets the index number of the property sheet window's active page and then uses the returned index number as the parameter for GetPage.

int GetActiveIndex() const;

Return Value

The index number of the active page.

Example

See the example for CPropertySheet::GetActivePage.

`CPropertySheet::GetActivePage`

Retrieves the property sheet window's active page.

CPropertyPage* GetActivePage() const;

Return Value

The pointer to the active page.

Remarks

Use this member function to perform some action on the active page.

Example

// The code fragment below sets the last active page (i.e. the 
// active page when the propertysheet was closed) to be the first 
// visible page when the propertysheet is shown. The last active 
// page was saved in m_LastActivePage, (a member variable of 
// CDocument-derived class) when OK was selected from the 
// propertysheet. CMyPropertySheet is a CPropertySheet-derived class.
BOOL CMyPropertySheet::OnInitDialog()
{
   BOOL bResult = CPropertySheet::OnInitDialog();

   CMDIFrameWnd* pframe = (CMDIFrameWnd*)AfxGetMainWnd();
   CMDIChildWnd* pchild = pframe->MDIGetActive();
   CPSheetDoc* doc = (CPSheetDoc*)pchild->GetActiveDocument();
   SetActivePage(doc->m_LastActivePage);

   return bResult;
}

BOOL CMyPropertySheet::OnCommand(WPARAM wParam, LPARAM lParam)
{
   if (LOWORD(wParam) == IDOK)
   {
      CMDIFrameWnd* pframe = (CMDIFrameWnd*)AfxGetMainWnd();
      CMDIChildWnd* pchild = pframe->MDIGetActive();
      CPSheetDoc* doc = (CPSheetDoc*)pchild->GetActiveDocument();
      doc->m_LastActivePage = GetPageIndex(GetActivePage()); // or GetActiveIndex()
   }

   return CPropertySheet::OnCommand(wParam, lParam);
}

`CPropertySheet::GetPage`

Returns a pointer to the specified page in this property sheet.

CPropertyPage* GetPage(int nPage) const;

Parameters

nPage
Index of the desired page, starting at 0. Must be between 0 and one less than the number of pages in the property sheet, inclusive.

Return Value

The pointer to the page corresponding to the nPage parameter.

Example

See the example for CPropertyPage::OnWizardFinish.

`CPropertySheet::GetPageCount`

Determines the number of pages currently in the property sheet.

int GetPageCount() const;

Return Value

The number of pages in the property sheet.

Example

See the example for CPropertyPage::OnWizardFinish.

`CPropertySheet::GetPageIndex`

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

int GetPageIndex(CPropertyPage* pPage);

Parameters

pPage
Points to the page with the index to be found. Cannot be NULL.

Return Value

The index number of a page.

Remarks

For example, you would use GetPageIndex to get the page index in order to use SetActivePage or GetPage.

Example

See the example for CPropertySheet::GetActivePage.

`CPropertySheet::GetTabControl`

Retrieves a pointer to a tab control to do something specific to the tab control (that is, to use any of the APIs in CTabCtrl).

CTabCtrl* GetTabControl() const;

Return Value

A pointer to a tab control.

Remarks

For example, call this member function if you want to add bitmaps to each of the tabs during initialization.

Example

// Create and associate a tooltip control to the tab control of 
// CMyTTPropertySheet.  CMyTTPropertySheet is a CPropertySheet-derived
// class.
BOOL CMyTTPropertySheet::OnInitDialog()
{
   BOOL bResult = CPropertySheet::OnInitDialog();

   // Create a tooltip control.  m_pToolTipCtrl is a member variable
   // of type CToolTipCtrl* in CMyTTPropertySheet class.  It is 
   // initialized to NULL in the constructor, and destroyed in the 
   // destructor of CMyTTPropertySheet class.
   m_pToolTipCtrl = new CToolTipCtrl;
   if (!m_pToolTipCtrl->Create(this))
   {
      TRACE(_T("Unable To create ToolTip\n"));
      return bResult;
   }

   // Associate the tooltip control to the tab control
   // of CMyPropertySheet.
   CTabCtrl* ptab = GetTabControl();
   ptab->SetToolTips(m_pToolTipCtrl);

   // Get the bounding rectangle of each tab in the tab control of the
   // property sheet. Use this rectangle when registering a tool with 
   // the tool tip control.  IDS_FIRST_TOOLTIP is the first ID string 
   // resource that contains the text for the tool.
   int count = ptab->GetItemCount();
   int id = IDS_FIRST_TOOLTIP;
   for (int i = 0; i < count; i++)
   {
      CRect r;
      ptab->GetItemRect(i, &r);
      VERIFY(m_pToolTipCtrl->AddTool(ptab, id, &r, id));
      id++;
   }

   // Activate the tooltip control.
   m_pToolTipCtrl->Activate(TRUE);

   return bResult;
}

// Override PreTranslateMessage() so RelayEvent() can be 
// called to pass a mouse message to CMyTTPropertySheet's 
// tooltip control for processing.
BOOL CMyTTPropertySheet::PreTranslateMessage(MSG* pMsg)
{
   if (NULL != m_pToolTipCtrl)
      m_pToolTipCtrl->RelayEvent(pMsg);

   return CPropertySheet::PreTranslateMessage(pMsg);
}

`CPropertySheet::m_psh`

A structure whose members store the characteristics of PROPSHEETHEADER.

Remarks

Use this structure to initialize the appearance of the property sheet after it is constructed but before it is displayed with the DoModal member function. For example, set the dwSize member of m_psh to the size you want the property sheet to have.

For more information on this structure, including a listing of its members, see PROPSHEETHEADER in the Windows SDK.

Example

// This code fragment shows how to change CPropertySheet's settings 
// before it is shown.  After the changes, CPropertySheet has the 
// caption "Simple Properties", no "Apply" button, and the 
// second page (CColorPage) initially on top.  

CPropertySheet dlgPropertySheet(_T("Simple PropertySheet"));

CStylePage stylePage;
CColorPage colorPage;
CShapePage shapePage;
dlgPropertySheet.AddPage(&stylePage);
dlgPropertySheet.AddPage(&colorPage);
dlgPropertySheet.AddPage(&shapePage);

dlgPropertySheet.m_psh.dwFlags |= PSH_NOAPPLYNOW | PSH_PROPTITLE;
dlgPropertySheet.m_psh.pszCaption = _T("Simple");
dlgPropertySheet.m_psh.nStartPage = 1;

dlgPropertySheet.DoModal();

`CPropertySheet::MapDialogRect`

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

void MapDialogRect(LPRECT lpRect) const;

Parameters

lpRect
Points to a RECT structure or CRect object that contains the dialog-box coordinates to be converted.

Remarks

Dialog-box units are stated in terms of the current dialog-box base unit derived from the average width and height of characters in the font used for dialog-box text. One horizontal unit is one-fourth of the dialog-box base-width unit, and one vertical unit is one-eighth of the dialog-box base height unit.

The GetDialogBaseUnits Windows function returns size information for the system font, but you can specify a different font for each property sheet if you use the DS_SETFONT style in the resource-definition file. The MapDialogRect Windows function, described in the Windows SDK, uses the appropriate font for this dialog box.

The MapDialogRect member function replaces the dialog-box units in lpRect with screen units (pixels) so that the rectangle can be used to create a dialog box or position a control within a box.

`CPropertySheet::OnInitDialog`

Overrides to augment property sheet initialization.

virtual BOOL OnInitDialog();

Return Value

Specifies whether the application has set the input focus to one of the controls in the property sheet. If OnInitDialog returns nonzero, Windows sets the input focus to the first control in the property sheet. The application can return 0 only if it has explicitly set the input focus to one of the controls in the property sheet.

Remarks

This member function is called in response to the WM_INITDIALOG message. This message is sent to the property sheet during the Create or DoModal calls, which occur immediately before the property sheet is displayed.

Override this member function if you need to perform special processing when the property sheet is initialized. In the overridden version, first call the base class OnInitDialog but disregard its return value. You will normally return TRUE from your overridden member function.

You do not need a message-map entry for this member function.

`CPropertySheet::PressButton`

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

void PressButton(int nButton);

Parameters

nButton
nButton : Identifies the button to be pressed. This parameter can be one of the following values:

PSBTN_BACK Chooses the Back button.
PSBTN_NEXT Chooses the Next button.
PSBTN_FINISH Chooses the Finish button.
PSBTN_OK Chooses the OK button.
PSBTN_APPLYNOW Chooses the Apply Now button.
PSBTN_CANCEL Chooses the Cancel button.
PSBTN_HELP Chooses the Help button.

Remarks

See PSM_PRESSBUTTON for more information about the Windows SDK Pressbutton message.

A call to PressButton will not send the PSN_APPLY notification from a property page to the framework. To send this notification, call CPropertyPage::OnOK.

Example

// Simulate the selection of OK and Cancel buttons when Alt+K and
// Alt+C are pressed.  CMyPropertySheet is a CPropertySheet-derived 
// class.
BOOL CMyPropertySheet::PreTranslateMessage(MSG* pMsg)
{
   if (pMsg->message >= WM_KEYFIRST && pMsg->message <= WM_KEYLAST)
   {
      BOOL altkey = GetKeyState(VK_MENU) < 0;
      if (altkey)
      {
         BOOL handled = TRUE;
         switch (toupper((int)pMsg->wParam))
         {
         case 'C':                     // for Alt+C - Cancel button
            PressButton(PSBTN_CANCEL);   // or EndDialog(IDCANCEL);
            break;

         case 'K':                     // for Alt+K - OK button
            PressButton(PSBTN_OK);      // or EndDialog(IDOK);
            break;

         default:
            handled = FALSE;
         }

         if (handled)
            return TRUE;
      }
   }

   return CPropertySheet::PreTranslateMessage(pMsg);
}

`CPropertySheet::RemovePage`

Removes a page from the property sheet and destroys the associated window.

void RemovePage(CPropertyPage* pPage);
void RemovePage(int nPage);

Parameters

pPage
Points to the page to be removed from the property sheet. Cannot be NULL.

nPage
Index of the page to be removed. Must be between 0 and one less than the number of pages in the property sheet, inclusive.

Remarks

The CPropertyPage object itself is not destroyed until the owner of the CPropertySheet window is closed.

`CPropertySheet::SetActivePage`

Changes the active page.

BOOL SetActivePage(int nPage);
BOOL SetActivePage(CPropertyPage* pPage);

Parameters

nPage
Index of the page to set. It must be between 0 and one less than the number of pages in the property sheet, inclusive.

pPage
Points to the page to set in the property sheet. It cannot be NULL.

Return Value

Nonzero if the property sheet is activated successfully; otherwise 0.

Remarks

For example, use SetActivePage if a user's action on one page should cause another page to become the active page.

Example

See the example for CPropertySheet::GetActivePage.

`CPropertySheet::SetFinishText`

Sets the text in the Finish command button.

void SetFinishText(LPCTSTR lpszText);

Parameters

lpszText
Points to the text to be displayed on the Finish command button.

Remarks

Call SetFinishText to display the text on the Finish command button and hide the Next and Back buttons after the user completes action on the last page of the wizard.

Example

// CShapePage is the last wizard property page. Enable the Back 
// button and change the Next button to Finish. The "Finish" button 
// will have "Done" as its caption.
BOOL CShapePage::OnSetActive()
{
   CPropertySheet* psheet = (CPropertySheet*)GetParent();
   psheet->SetWizardButtons(PSWIZB_BACK | PSWIZB_FINISH);
   psheet->SetFinishText(_T("Done"));

   return CPropertyPage::OnSetActive();
}

`CPropertySheet::SetTitle`

Specifies the property sheet's caption (the text displayed in the title bar of a frame window).

void SetTitle(
    LPCTSTR lpszText,
    UINT nStyle = 0);

Parameters

nStyle
Specifies the style of the property sheet title. The style must be specified at 0 or as PSH_PROPTITLE. If the style is set as PSH_PROPTITLE, the word "Properties" appears after the text specified as the caption. For example, calling SetTitle("Simple", PSH_PROPTITLE) will result in a property sheet caption of "Simple Properties."

lpszText
Points to the text to be used as the caption in the title bar of the property sheet.

Remarks

By default, a property sheet uses the caption parameter in the property sheet constructor.

Example

// Declare a CPropertySheet object with a caption "Simple PropertySheet".
CPropertySheet dlgPropertySheet(_T("Simple PropertySheet"));

// Add three pages to the CPropertySheet object. CStylePage, CColorPage,
// and CShapePage are CPropertyPage-derived classes created
// by the Add Class wizard.
CStylePage     stylePage;
CColorPage     colorPage;
CShapePage     shapePage;
dlgPropertySheet.AddPage(&stylePage);
dlgPropertySheet.AddPage(&colorPage);
dlgPropertySheet.AddPage(&shapePage);

// Change the caption of the CPropertySheet object 
// from "Simple PropertySheet" to "Simple Properties".
dlgPropertySheet.SetTitle(_T("Simple"), PSH_PROPTITLE);

// Show the CPropertySheet object as MODAL.
dlgPropertySheet.DoModal();

`CPropertySheet::SetWizardButtons`

Enables or disables the Back, Next, or Finish button in a wizard property sheet.

void SetWizardButtons(DWORD dwFlags);

Parameters

dwFlags
A set of flags that customize the function and appearance of the wizard buttons. This parameter can be a combination of the following values:

PSWIZB_BACK Back button
PSWIZB_NEXT Next button
PSWIZB_FINISH Finish button
PSWIZB_DISABLEDFINISH Disabled Finish button

Remarks

Call SetWizardButtons only after the dialog is open; you can't call SetWizardButtons before you call DoModal. Typically, you should call SetWizardButtons from CPropertyPage::OnSetActive.

If you want to change the text on the Finish button or hide the Next and Back buttons once the user has completed the wizard, call SetFinishText. Note that the same button is shared for Finish and Next. You can display a Finish or a Next button at one time, but not both.

Example

A CPropertySheet has three wizard property pages: CStylePage, CColorPage, and CShapePage. The code fragment below shows how to enable and disable the Back and Next buttons on the wizard property page.

// CStylePage is the first wizard property page.  Disable the Back 
// button but enable the Next button.
BOOL CStylePage::OnSetActive() 
{
   CPropertySheet* psheet = (CPropertySheet*) GetParent();   
   psheet->SetWizardButtons(PSWIZB_NEXT);
   
   return CPropertyPage::OnSetActive();
}

// CColorPage is the second wizard property page. Enable both the 
// Back button and the Next button.
BOOL CColorPage::OnSetActive()
{
   CPropertySheet* psheet = (CPropertySheet*)GetParent();
   psheet->SetWizardButtons(PSWIZB_BACK | PSWIZB_NEXT);

   return CPropertyPage::OnSetActive();
}

// CShapePage is the last wizard property page. Enable the Back 
// button and change the Next button to Finish. The "Finish" button 
// will have "Done" as its caption.
BOOL CShapePage::OnSetActive()
{
   CPropertySheet* psheet = (CPropertySheet*)GetParent();
   psheet->SetWizardButtons(PSWIZB_BACK | PSWIZB_FINISH);
   psheet->SetFinishText(_T("Done"));

   return CPropertyPage::OnSetActive();
}

`CPropertySheet::SetWizardMode`

Establishes a property page as a wizard.

void SetWizardMode();

Remarks

A key characteristic of a wizard property page is that the user navigates using Next or Finish, Back, and Cancel buttons instead of tabs.

Call SetWizardMode before calling DoModal. After you call SetWizardMode, DoModal will return either ID_WIZFINISH (if the user closes with the Finish button) or IDCANCEL.

SetWizardMode sets the PSH_WIZARD flag.

Example

CPropertySheet sheet(_T("Simple PropertySheet"));

CStylePage pageStyle;
CColorPage pageColor;
CShapePage pageShape;

sheet.AddPage(&pageStyle);
sheet.AddPage(&pageColor);
sheet.AddPage(&pageShape);

sheet.SetWizardMode();

sheet.DoModal();

Share via

CPropertySheet Class

Syntax

Members

Public Constructors

Public Methods

Public Data Members

Remarks

Inheritance Hierarchy

Requirements

CPropertySheet::AddPage

Parameters

Remarks

Example

CPropertySheet::Construct

Parameters

Remarks

Example

CPropertySheet::CPropertySheet

Parameters

Remarks

Example

CPropertySheet::Create

Parameters

Return Value

Remarks

Example

CPropertySheet::DoModal

Return Value

Remarks

Example

CPropertySheet::EnableStackedTabs

Parameters

Remarks

Example

CPropertySheet::EndDialog

Parameters

Remarks

Example

CPropertySheet::GetActiveIndex

Return Value

Example

CPropertySheet::GetActivePage

Return Value

Remarks

Example

CPropertySheet::GetPage

Parameters

Return Value

Example

CPropertySheet::GetPageCount

Return Value

Example

CPropertySheet::GetPageIndex

Parameters

Return Value

Remarks

Example

CPropertySheet::GetTabControl

Return Value

Remarks

Example

CPropertySheet::m_psh

Remarks

Example

CPropertySheet::MapDialogRect

Parameters

Remarks

CPropertySheet::OnInitDialog

Return Value

Remarks

CPropertySheet::PressButton

Parameters

Remarks

Example

CPropertySheet::RemovePage

Parameters

Remarks

CPropertySheet::SetActivePage

Parameters

`CPropertySheet` Class

`CPropertySheet::AddPage`

`CPropertySheet::Construct`

`CPropertySheet::CPropertySheet`

`CPropertySheet::Create`

`CPropertySheet::DoModal`

`CPropertySheet::EnableStackedTabs`

`CPropertySheet::EndDialog`

`CPropertySheet::GetActiveIndex`

`CPropertySheet::GetActivePage`

`CPropertySheet::GetPage`

`CPropertySheet::GetPageCount`

`CPropertySheet::GetPageIndex`

`CPropertySheet::GetTabControl`

`CPropertySheet::m_psh`

`CPropertySheet::MapDialogRect`

`CPropertySheet::OnInitDialog`

`CPropertySheet::PressButton`

`CPropertySheet::RemovePage`

`CPropertySheet::SetActivePage`

`CPropertySheet::SetFinishText`

`CPropertySheet::SetTitle`

`CPropertySheet::SetWizardButtons`

`CPropertySheet::SetWizardMode`