`CPropertySheet` 类

项目
06/16/2023

表示属性表，也称为选项卡对话框。

语法

class CPropertySheet : public CWnd

成员

公共构造函数

名称	描述
`CPropertySheet::CPropertySheet`	构造 `CPropertySheet` 对象。

公共方法

名称	描述
`CPropertySheet::AddPage`	向属性表添加页面。
`CPropertySheet::Construct`	构造 `CPropertySheet` 对象。
`CPropertySheet::Create`	显示无模式属性表。
`CPropertySheet::DoModal`	显示模式属性表。
`CPropertySheet::EnableStackedTabs`	指示属性表是使用堆叠选项卡还是滚动选项卡。
`CPropertySheet::EndDialog`	终止属性表。
`CPropertySheet::GetActiveIndex`	检索属性表的活动页的索引。
`CPropertySheet::GetActivePage`	返回活动页对象。
`CPropertySheet::GetPage`	检索指向指定页面的指针。
`CPropertySheet::GetPageCount`	检索属性表中的页数。
`CPropertySheet::GetPageIndex`	检索属性表的指定页面的索引。
`CPropertySheet::GetTabControl`	检索指向选项卡控件的指针。
`CPropertySheet::MapDialogRect`	将矩形的对话框单位转换为屏幕单位。
`CPropertySheet::OnInitDialog`	重写以增强属性表初始化。
`CPropertySheet::PressButton`	模拟在属性工作表中对指定按钮的选择。
`CPropertySheet::RemovePage`	从属性表中删除某页。
`CPropertySheet::SetActivePage`	以编程方式设置活动页对象。
`CPropertySheet::SetFinishText`	设置“完成”按钮的文本。
`CPropertySheet::SetTitle`	设置属性表的标题。
`CPropertySheet::SetWizardButtons`	启用向导按钮。
`CPropertySheet::SetWizardMode`	启用向导模式。

公共数据成员

“属性”	描述
`CPropertySheet::m_psh`	Windows `PROPSHEETHEADER` 结构。提供对基本属性表参数的访问权限。

注解

属性表由一个 CPropertySheet 对象以及一个或多个 CPropertyPage 对象组成。框架将属性表显示为窗口，其中包含一组选项卡索引和一个包含当前选定页面的区域。用户使用适当的选项卡导航到特定页面。

CPropertySheet 为 Windows 98 和 Windows NT 2000 中引入的扩展 PROPSHEETHEADER 结构提供支持。该结构包含支持使用“水印”背景位图的附加标志和成员。

要在属性表对象中自动显示这些新图像，请在对 CPropertySheet::Construct 或 CPropertySheet::CPropertySheet 的调用中传递位图和调色板图像的有效值。

即使 CPropertySheet 不是从 CDialog 派生的，但管理 CPropertySheet 对象就像管理 CDialog 对象一样。例如，创建属性表需要两部分构造：调用构造函数，然后为模式属性表调用 DoModal 或为无模式属性表调用 Create。 CPropertySheet 具有两种类型的构造函数：CPropertySheet::Construct 和 CPropertySheet::CPropertySheet。

当构造 CPropertySheet 对象时，某些窗口样式可能会导致第一次机会异常。这是由于系统在创建表之前尝试更改属性表的样式而导致的。为避免此异常，请确保在创建 CPropertySheet 时设置以下样式：

DS_3DLOOK
DS_CONTROL
WS_CHILD
WS_TABSTOP

以下样式是可选的，并不会导致第一次机会异常：

DS_SHELLFONT
DS_LOCALEDIT
WS_CLIPCHILDREN

禁止使用任何其他 Window Styles，不应启用它们。

在 CPropertySheet 对象和外部对象之间交换数据类似于与 CDialog 对象交换数据。重要的区别在于，属性表的设置通常是 CPropertyPage 对象的成员变量，而不是 CPropertySheet 对象本身的成员变量。

可以创建一种称为向导的选项卡对话框，它由一个带有一系列属性页的属性表组成，这些属性页引导用户完成操作步骤，例如设置设备或创建新闻稿。在向导类型选项卡对话框中，属性页没有选项卡，一次只能看到一个属性页。此外，向导类型的选项卡对话框没有“确定”和“立即应用”按钮，而是有“后退”按钮、“下一步”（或“完成”）按钮、“取消”按钮以及“帮助”按钮。

要创建向导类型的对话框，请按照与创建标准属性表相同的步骤进行操作，但在调用 DoModal 之前需调用 SetWizardMode。要启用向导按钮，请调用 SetWizardButtons，并使用标志自定义其功能和外观。要启用“完成”按钮，请在用户对向导的最后一页执行操作后调用 SetFinishText。

若要详细了解如何使用 CPropertySheet 对象，请参阅属性表和属性页一文。

继承层次结构

CObject

CCmdTarget

CWnd

CPropertySheet

要求

标头afxdlgs.h：

`CPropertySheet::AddPage`

在属性工作表中使用最右边的选项卡添加所提供的页。

void AddPage(CPropertyPage* pPage);

参数

pPage
指向要添加到属性表的页。不能为 NULL。

注解

按照希望它们出现的顺序（从左到右）将页添加到属性表。

AddPage 会将 CPropertyPage 对象添加到 CPropertySheet 对象的页列表中，但不会实际为该页创建窗口。框架会推迟创建页面的窗口，直到用户选择该页面为止。

当使用 AddPage 添加属性页时，CPropertySheet 是 CPropertyPage 的父级。要从属性页访问属性表，请调用 CWnd::GetParent。

不必等到创建属性表窗口后才调用 AddPage。通常，将在调用 DoModal 或 Create 之前调用 AddPage。

如果在显示属性页后调用 AddPage，则选项卡行将反映新添加的页面。

示例

// 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`

构造 CPropertySheet 对象。

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);

参数

nIDCaption
用于属性表的标题的 ID。

pParentWnd
指向属性表的父窗口的指针。如果该参数为 NULL，则父窗口将是应用程序的主窗口。

iSelectPage
最初将出现在顶部的页面的索引。默认值为添加到工作表的第一页。

pszCaption
一个指针，指向包含要用于属性表的标题的字符串。不能为 NULL。

hbmWatermark
属性页水印位图的句柄。

hpalWatermark
水印位图和/或标题位图的调色板句柄。

hbmHeader
属性页标题位图的句柄。

备注

如果尚未调用其中一个类构造函数，则调用此成员函数。例如，在声明或分配 CPropertySheet 对象的数组时，调用 Construct。对于数组，必须为数组中的每个成员调用 Construct。

要显示属性表，请调用 DoModal 或 Create。第一个参数中包含的字符串将置于属性表的标题栏中。

如果使用上面列出的 Construct 的第三个或第四个原型，并为 hbmWatermark、hpalWatermark 和/或 hbmHeader 参数传递有效值，则可以自动显示水印和/或标题图像。

示例

以下示例演示在什么情况下调用 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`

构造 CPropertySheet 对象。

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);

参数

nIDCaption
用于属性表的标题的 ID。

pParentWnd
指向属性表的父窗口。如果该参数为 NULL，则父窗口将是应用程序的主窗口。

iSelectPage
最初将出现在顶部的页面的索引。默认值为添加到工作表的第一页。

pszCaption
指向包含要用于属性表的标题的字符串。不能为 NULL。

hbmWatermark
属性表的背景位图的句柄。

hpalWatermark
水印位图和/或标题位图的调色板句柄。

hbmHeader
属性页标题位图的句柄。

注解

要显示属性表，请调用 DoModal 或 Create。第一个参数中包含的字符串将置于属性表的标题栏中。

如果有多个参数（例如，如果使用数组），请使用 Construct 而不是 CPropertySheet。

如果使用上面的 CPropertySheet 的第三个或第四个原型，并为 hbmWatermark、hpalWatermark 和/或 hbmHeader 参数传递有效值，则可以自动显示水印和/或标题图像。

示例

// 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`

显示无模式属性表。

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

参数

pParentWnd
指向父窗口。如果该参数为 NULL，则父级是桌面。

dwStyle
属性表的窗口样式。有关可用样式的完整列表，请参阅窗口样式。

dwExStyle
属性表的扩展窗口样式。有关可用样式的完整列表，请参阅扩展窗口样式

返回值

如果属性表创建成功，则为非零值；否则为 0。

备注

可以在构造函数内部对 Create 进行调用，也可以在调用构造函数之后再调用它。

Create 成员函数在创建属性表后会立即返回。要销毁属性表，请调用 CWnd::DestroyWindow。

通过调用 Create 显示的无模式属性表不像模式属性表那样具有“确定”、“取消”、“立即应用”和“帮助”按钮。所需的按钮必须由用户创建。

要显示模式属性表，请改为调用 DoModal。

示例

// 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`

显示模式属性表。

virtual INT_PTR DoModal();

返回值

如果函数成功，则为 IDOK 或 IDCANCEL；否则为 0 或 -1。如果已将属性表设置为向导（请参阅 SetWizardMode），则 DoModal 返回 ID_WIZFINISH 或 IDCANCEL。

备注

返回值对应于关闭属性表的控件 ID。此函数返回后，属性表对应的窗口和所有页面都将被销毁。对象本身仍然存在。通常，将在 DoModal 返回 IDOK 后从 CPropertyPage 对象中检索数据。

要显示无模式属性表，请改为调用 Create。

从其相应的对话框资源创建属性页时，可能会导致第一次机会异常。这是由于属性页在创建页面之前将对话框资源的样式更改为所需样式而导致的。由于资源通常是只读的，因此这将导致异常。系统会处理异常，然后复制修改后的资源。因此可以忽略第一次机会异常。

注意

如果要使用异步异常处理模型进行编译，则该异常必须由操作系统进行处理。有关异常处理模型的详细信息，请参阅 /EH（异常处理模型）。在这种情况下，不要使用 C++ try-catch 块包装对 CPropertySheet::DoModal 的调用，其中 catch 处理所有异常（例如 catch (...)）。该块将处理针对操作系统的异常，并导致不可预知的行为。但是，可以安全地使用具有特定异常类型的 C++ 异常处理或结构化异常处理，其中将访问冲突异常传递给操作系统。

为避免生成此类第一次机会异常，可以手动保证属性表具有正确的窗口样式。需要为属性表设置以下样式：

DS_3DLOOK
DS_CONTROL
WS_CHILD
WS_TABSTOP

可使用以下可选样式，而不会导致第一次机会异常：

DS_SHELLFONT
DS_LOCALEDIT
WS_CLIPCHILDREN

禁用所有其他 Windows 样式，因为它们与属性表不兼容。此建议不适用于扩展样式。通过适当地设置这些标准样式，可保证不必修改属性表，并避免生成第一次机会异常。

示例

请参阅 CPropertySheet::AddPage 的示例。

`CPropertySheet::EnableStackedTabs`

指示是否在属性表中堆叠选项卡行。

void EnableStackedTabs(BOOL bStacked);

参数

bStacked
指示是否在属性表中启用堆叠选项卡。通过将 bStacked 设置为 FALSE 来禁用堆叠的选项卡行。

注解

默认情况下，如果属性表具有的选项卡在属性表宽度的单个行中放不下，这些选项卡则会堆叠在多个行中。要使用滚动选项卡而不是堆叠选项卡，请在调用 DoModal 或 Create 之前调用 EnableStackedTabs 并将 bStacked 设置为 FALSE。

当创建模式或无模式属性表时，必须调用 EnableStackedTabs。要将此样式合并到 CPropertySheet 派生的类中，请为 WM_CREATE 编写消息处理程序。在 CWnd::OnCreate 的重写版本中，请在调用基类实现之前调用 EnableStackedTabs( FALSE )。

示例

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`

终止属性表。

void EndDialog(int nEndID);

参数

nEndID
用作属性表返回值的标识符。

备注

当按下确定、“取消”或“关闭”按钮时，框架将调用此成员函数。如果发生应关闭属性表的事件，则调用此成员函数。

此成员函数仅用于模式对话框。

示例

请参阅 CPropertySheet::PressButton 的示例。

`CPropertySheet::GetActiveIndex`

获取属性表窗口的活动页的索引号，然后将返回的索引号用作 GetPage 的参数。

int GetActiveIndex() const;

返回值

活动页的索引号。

示例

请参阅 CPropertySheet::GetActivePage 的示例。

`CPropertySheet::GetActivePage`

检索属性表窗口的活动页。

CPropertyPage* GetActivePage() const;

返回值

指向活动页的指针。

备注

使用此成员函数在活动页上执行一些操作。

示例

// 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`

返回指向此属性表中指定页面的指针。

CPropertyPage* GetPage(int nPage) const;

参数

nPage
所需页面的索引，从 0 开始。必须比属性表中的页数少，范围介于 0（含）到 1（含）之间。

返回值

指向与 nPage 参数对应的页面的指针。

示例

请参阅 CPropertyPage::OnWizardFinish 的示例。

`CPropertySheet::GetPageCount`

确定属性表中当前的页数。

int GetPageCount() const;

返回值

属性表中的页数。

示例

请参阅 CPropertyPage::OnWizardFinish 的示例。

`CPropertySheet::GetPageIndex`

检索属性表中指定页面的索引号。

int GetPageIndex(CPropertyPage* pPage);

参数

pPage
指向包含要查找的索引的页面。不能为 NULL。

返回值

页面的索引号。

注解

例如，你将使用 GetPageIndex 来获取页面索引，以便使用 SetActivePage 或 GetPage。

示例

请参阅 CPropertySheet::GetActivePage 的示例。

`CPropertySheet::GetTabControl`

检索指向选项卡控件的指针以执行特定于选项卡控件的操作（即使用 CTabCtrl 中的任何 API）。

CTabCtrl* GetTabControl() const;

返回值

指向选项卡控件的指针。

备注

例如，在初始化过程中，如果要为每个选项卡添加位图，请调用此成员函数。

示例

// 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`

一种结构，其成员存储 PROPSHEETHEADER 的特征。

备注

在使用 DoModal 成员函数构造属性表之后但在显示该表之前，使用此结构初始化属性表的外观。例如，将 m_psh 的 dwSize 成员设置为希望属性表具有的大小。

有关此结构的详细信息（包括其成员列表），请参阅 Windows SDK 中的 PROPSHEETHEADER。

示例

// 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`

将矩形的对话框单位转换为屏幕单位。

void MapDialogRect(LPRECT lpRect) const;

参数

lpRect
指向包含要转换的对话框坐标的 RECT 结构或 CRect 对象。

备注

对话框单位是以当前的对话框基础单位来表示的，基础单位来自对话框文本所用字体的字符平均宽度和高度。一个水平单位是对话框基础宽度单位的四分之一，一个垂直单位是对话框基础高度单位的八分之一。

GetDialogBaseUnits Windows 函数返回系统字体的大小信息，但如果你在资源定义文件中使用 DS_SETFONT 样式，可以为每个属性表指定不同的字体。 Windows SDK 中介绍的 MapDialogRect Windows 函数为此对话框使用相应的字体。

MapDialogRect 成员函数将 lpRect 中的对话框单位替换为屏幕单位（像素），这样就可以使用矩形来创建对话框或将控件置于对话框内。

`CPropertySheet::OnInitDialog`

重写以增强属性表初始化。

virtual BOOL OnInitDialog();

返回值

指定应用程序是否已将输入焦点设置为属性表中的一个控件。如果 OnInitDialog 返回非零值，则 Windows 会将输入焦点设置为属性表中的第一个控件。只有在应用程序已将输入焦点显式设置为属性表中的一个控件时，应用程序才能返回 0。

备注

将调用此成员函数以响应 WM_INITDIALOG 消息。在 Create 或 DoModal 调用期间，此消息发送到属性表，这发生在显示属性表之前。

如果需要在初始化属性表时进行特殊处理，请重写此成员函数。在替代后的版本中，首先调用基类 OnInitDialog，但忽略其返回值。通常会从重写的成员函数中返回 TRUE。

此成员函数不需要消息映射条目。

`CPropertySheet::PressButton`

模拟在属性工作表中对指定按钮的选择。

void PressButton(int nButton);

参数

nButton
nButton：用于标识要按下的按钮。此参数可能是以下值之一：

PSBTN_BACK：用于选择“后退”按钮。
PSBTN_NEXT：用于选择“下一步”按钮。
PSBTN_FINISH：用于选择“完成”按钮。
PSBTN_OK：用于选择“确定”按钮。
PSBTN_APPLYNOW：用于选择“立即应用”按钮。
PSBTN_CANCEL：用于选择“取消”按钮。
PSBTN_HELP：用于选择“帮助”按钮。

注解

有关 Windows SDK Pressbutton 消息的详细信息，请参阅 PSM_PRESSBUTTON。

对 PressButton 的调用不会从属性页将 PSN_APPLY 通知发送到框架。要发送此通知，请调用 CPropertyPage::OnOK。

示例

// 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`

从属性表中删除一个页面并销毁关联的窗口。

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

参数

pPage
指向要从属性表中删除的页面。不能为 NULL。

nPage
要删除的页面索引。必须比属性表中的页数少，范围介于 0（含）到 1（含）之间。

备注

在 CPropertySheet 窗口的所有者关闭之前，CPropertyPage 对象本身不会被销毁。

`CPropertySheet::SetActivePage`

更改活动页。

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

参数

nPage
要设置的页的索引。它必须比属性表中的页数少，范围介于 0（含）到 1（含）之间。

pPage
指向要在属性表中设置的页面。它不能为 NULL。

返回值

如果属性表成功激活，则为非零值；否则为 0。

备注

例如，如果用户在一个页面上的操作应会导致另一个页成为活动页，请使用 SetActivePage。

示例

请参阅 CPropertySheet::GetActivePage 的示例。

`CPropertySheet::SetFinishText`

设置“完成”命令按钮中的文本。

void SetFinishText(LPCTSTR lpszText);

参数

lpszText
指向要在“完成”命令按钮上显示的文本。

备注

在用户完成向导最后一页上的操作后，调用 SetFinishText 以显示“完成”命令按钮上的文本并隐藏“下一步”和“后退”按钮。

示例

// 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`

指定属性表的标题（显示在框架窗口标题栏中的文本）。

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

参数

nStyle
指定属性表标题的样式。样式必须指定为 0 或 PSH_PROPTITLE。如果样式设置为 PSH_PROPTITLE，则“属性”一词会出现在指定为标题的文本之后。例如，调用 SetTitle("Simple", PSH_PROPTITLE) 将生成属性表标题“简单属性”。

lpszText
指向在属性表的标题栏中用作标题的文本。

注解

默认情况下，属性表使用属性表构造函数中的标题参数。

示例

// 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`

启用或禁用向导属性表中的“后退”、“下一步”或“完成”按钮。

void SetWizardButtons(DWORD dwFlags);

参数

dwFlags
一组标志，用于自定义向导按钮的功能和外观。此参数可为以下值的组合：

PSWIZB_BACK：“后退”按钮
PSWIZB_NEXT：“下一步”按钮
PSWIZB_FINISH：“完成”按钮
PSWIZB_DISABLEDFINISH：“已禁用的完成”按钮

备注

只能在对话框打开后才能调用 SetWizardButtons；不能在调用 DoModal 之前调用 SetWizardButtons。通常应从 CPropertyPage::OnSetActive 调用 SetWizardButtons。

如果想在用户完成向导后更改“完成”按钮上的文本或隐藏“下一步”和“后退”按钮，请调用 SetFinishText。请注意，“完成”和“下一步”为同一按钮。可以一次显示“完成”或“下一步”按钮，但不能同时显示两者。

示例

CPropertySheet 具有三个向导属性页：CStylePage、CColorPage 和 CShapePage。下面的代码片段显示如何启用和禁用向导属性页上的“后退”和“下一步”按钮。

// 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`

将属性页建立为向导。

void SetWizardMode();

注解

向导属性页的一个关键特征是，用户使用“下一步”（或“完成”）、“后退”和“取消”按钮（而不是选项卡）进行导航。

在调用 DoModal 之前调用 SetWizardMode。在调用 SetWizardMode 后，DoModal 将返回 ID_WIZFINISH（如果用户使用“完成”按钮关闭）或 IDCANCEL。

SetWizardMode 设置 PSH_WIZARD 标志。

示例

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

CStylePage pageStyle;
CColorPage pageColor;
CShapePage pageShape;

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

sheet.SetWizardMode();

sheet.DoModal();

另请参阅

MFC 示例 CMNCTRL1
MFC 示例 CMNCTRL2
MFC 示例 PROPDLG
MFC 示例 SNAPVW
CWnd 类
 层次结构图

通过

CPropertySheet 类

语法

成员

公共构造函数

公共方法

公共数据成员

注解

继承层次结构

要求

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` 类

`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`