CMFCPropertySheet 类

项目
06/16/2023

CMFCPropertySheet 类支持每个属性页由页选项卡、工具栏按钮、树控件节点或列表项表示的属性表。

语法

class CMFCPropertySheet : public CPropertySheet

成员

公共构造函数

名称	描述
CMFCPropertySheet::CMFCPropertySheet	构造 `CMFCPropertySheet` 对象。
`CMFCPropertySheet::~CMFCPropertySheet`	析构函数。

公共方法

名称	描述
CMFCPropertySheet::AddPage	向属性表添加页面。
CMFCPropertySheet::AddPageToTree	向树控件添加新的属性页。
CMFCPropertySheet::AddTreeCategory	向树控件添加新节点。
CMFCPropertySheet::EnablePageHeader	在每个页面顶部保留一定空间，用于绘制自定义页眉。
CMFCPropertySheet::GetHeaderHeight	检索当前页眉的高度。
CMFCPropertySheet::GetLook	检索一个枚举值，该值指定当前属性表的外观。
CMFCPropertySheet::GetNavBarWidth	检索导航栏的宽度（以像素为单位）。
CMFCPropertySheet::GetTab	检索支持当前属性表控件的内部选项卡控件对象。
`CMFCPropertySheet::GetThisClass`	由框架用于获取指向与此类类型关联的 CRuntimeClass 对象的指针。
CMFCPropertySheet::InitNavigationControl	初始化当前属性表控件的外观。
CMFCPropertySheet::OnActivatePage	当属性页处于启用状态时由框架调用。
CMFCPropertySheet::OnDrawPageHeader	由框架调用，用于绘制自定义属性页页眉。
`CMFCPropertySheet::OnInitDialog`	处理 WM_INITDIALOG 消息。（替代 CPropertySheet::OnInitDialog。）
CMFCPropertySheet::OnRemoveTreePage	由框架调用，用于从树控件中删除属性页。
`CMFCPropertySheet::PreTranslateMessage`	在将窗口消息发送到 TranslateMessage 和 DispatchMessage Windows 函数之前，对此消息进行转换。（替代 `CPropertySheet::PreTranslateMessage`。）
CMFCPropertySheet::RemoveCategory	从树控件中删除节点。
CMFCPropertySheet::RemovePage	从属性表中删除属性页。
CMFCPropertySheet::SetIconsList	指定用于 Outlook 窗格的导航控件的图像列表。
CMFCPropertySheet::SetLook	指定属性表的外观。

备注

CMFCPropertySheet 类表示属性表，也称为选项卡对话框。 CMFCPropertySheet 类可以用多种方式显示属性页。

执行以下步骤，以便在应用程序中使用 CMFCPropertySheet 类：

从 CMFCPropertySheet 类派生一个类，并对其命名，例如，CMyPropertySheet。
为每个属性页构造一个 CMFCPropertyPage 对象。
调用 CMyPropertySheet 构造函数中的 CMFCPropertySheet::SetLook 方法。该方法的参数指定属性页的显示方式：属性表顶部或左侧的选项卡；Microsoft OneNote 属性表样式的选项卡；Microsoft Outlook 工具栏控件上的按钮；树控件上的节点；或属性表左侧的项列表。
如果创建 Microsoft Outlook 工具栏样式的属性表，则调用 CMFCPropertySheet::SetIconsList 方法将一个图像列表与属性页关联。
为每个属性页调用 CMFCPropertySheet::AddPage 方法。
创建 CMFCPropertySheet 控件并调用其 DoModal 方法。

图示

下图描绘了一个采用嵌入式 Microsoft Outlook 工具栏样式的属性表。该 Outlook 工具栏显示在属性表左侧。

CMFCPropertySheet color controls.

下图描绘了一个包含 CMFCPropertyGridCtrl Class 对象的属性表。该对象是一个采用标准常用控件属性表样式的属性表。

CMFCPropertySheet list and property controls.

下图描绘了一个采用树控件样式的属性表。

Property Tree.

继承层次结构

要求

标头：afxpropertysheet.h

CMFCPropertySheet::AddPage

向属性表添加页面。

void AddPage(CPropertyPage* pPage);

参数

pPage
[in] 指向页面对象的指针。此参数不能为 NULL。

注解

此方法将指定的属性页添加为属性表中最右边的选项卡。因此，使用此方法可以按从左到右的顺序添加页面。

如果属性表采用 Microsoft Outlook 样式，框架将在属性表左侧显示导航按钮的列表。此方法添加属性页后，会向列表添加相应的按钮。若要显示属性页，请单击其相应的按钮。有关属性表样式的详细信息，请参阅 CMFCPropertySheet::SetLook。

CMFCPropertySheet::AddPageToTree

向树控件添加新的属性页。

void AddPageToTree(
    CMFCPropertySheetCategoryInfo* pCategory,
    CMFCPropertyPage* pPage,
    int nIconNum=-1,
    int nSelIconNum=-1);

参数

pCategory
[in] 指向父树节点的指针，如果要将指定页与顶级节点相关联，则为 NULL。调用 CMFCPropertySheet::AddTreeCategory 方法可以获取此指针。

pPage
[in] 指向属性页对象的指针。

nIconNum
[in] 图标的从零开始的索引；如果未使用图标，则为 -1。未选择页面时，图标将显示在树控件属性页旁边。默认值为 -1。

nSelIconNum
[in] 图标的从零开始的索引；如果未使用图标，则为 -1。选择页面时，图标将显示在树控件属性页旁边。默认值为 -1。

备注

此方法将属性页添加为树控件的叶。若要添加属性页，请创建 CMFCPropertySheet 对象，调用 CMFCPropertySheet::SetLook 方法并将 look 参数设置为 CMFCPropertySheet::PropSheetLook_Tree，然后使用此方法添加属性页。

CMFCPropertySheet::AddTreeCategory

向树控件添加新节点。

CMFCPropertySheetCategoryInfo* AddTreeCategory(
    LPCTSTR lpszLabel,
    int nIconNum=-1,
    int nSelectedIconNum=-1,
    const CMFCPropertySheetCategoryInfo* pParentCategory=NULL);

参数

lpszLabel
[in] 节点的名称。

nIconNum
[in] 图标的从零开始的索引；如果未使用图标，则为 -1。未选择页面时，图标将显示在树控件属性页旁边。默认值为 -1。

nSelectedIconNum
[in] 图标的从零开始的索引；如果未使用图标，则为 -1。选择页面时，图标将显示在树控件属性页旁边。默认值为 -1。

pParentCategory
[in] 指向父树节点的指针，如果要将指定页与顶级节点相关联，则为 NULL。使用 CMFCPropertySheet::AddTreeCategory 方法设置此参数。

返回值

指向树控件中新节点的指针。

备注

使用此方法向树控件添加新节点（也称为类别）。若要添加节点，请创建 CMFCPropertySheet 对象，调用 CMFCPropertySheet::SetLook 方法并将 look 参数设置为 CMFCPropertySheet::PropSheetLook_Tree，然后使用此方法添加节点。

在对 CMFCPropertySheet::AddPageToTree 和 CMFCPropertySheet::AddTreeCategory 的后续调用中使用此方法的返回值。

CMFCPropertySheet::CMFCPropertySheet

构造 CMFCPropertySheet 对象。

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

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

参数

pszCaption
[in] 包含属性表标题的字符串。不能为 NULL。

nIDCaption
[in] 包含属性表标题的资源 ID。

pParentWnd
[in] 指向属性表的父窗口的指针，如果父窗口是应用程序的主窗口，则为 NULL。默认值为 NULL。

iSelectPage
[in] 顶部属性页的从零开始的索引。默认值为 0。

备注

有关详细信息，请参阅 CPropertySheet::CPropertySheet 构造函数的参数。

CMFCPropertySheet::EnablePageHeader

在每个页面顶部保留一定空间，用于绘制自定义页眉。

void EnablePageHeader(int nHeaderHeight);

参数

nHeaderHeight
[in] 标题的高度（以像素为单位）。

备注

若要使用 nHeaderHeight 参数的值绘制自定义标题，请重写 CMFCPropertySheet::OnDrawPageHeader 方法。

CMFCPropertySheet::GetHeaderHeight

检索当前页眉的高度。

int GetHeaderHeight() const;

返回值

标题的高度（以像素为单位）。

注解

在调用此方法之前，先调用 CMFCPropertySheet::EnablePageHeader 方法。

CMFCPropertySheet::GetLook

检索一个枚举值，该值指定当前属性表的外观。

PropSheetLook GetLook() const;

返回值

用于指定属性表外观的枚举值之一。有关可能值的列表，请参阅 CMFCPropertySheet::SetLook 的“注解”部分中的枚举表。

CMFCPropertySheet::GetNavBarWidth

获取导航栏的宽度。

int GetNavBarWidth() const;

返回值

导航栏的宽度（以像素为单位）。

CMFCPropertySheet::GetTab

检索支持当前属性表控件的内部选项卡控件对象。

CMFCTabCtrl& GetTab() const;

返回值

内部选项卡控件对象。

注解

可以设置属性表，使其以不同的样式显示，例如树控件、导航按钮列表或一组选项卡式页面。

在调用此方法之前，请调用 CMFCPropertySheet::SetLook 方法以设置属性表控件的外观。然后调用 CMFCPropertySheet::InitNavigationControl 方法以初始化内部选项卡控件对象。使用此方法检索选项卡控件对象，然后使用该对象处理属性表上的选项卡。

如果不将属性表控件设置为以 Microsoft OneNote 样式显示，则此方法在调试模式下断言。

CMFCPropertySheet::InitNavigationControl

初始化当前属性表控件的外观。

virtual CWnd* InitNavigationControl();

返回值

指向属性表控件的窗口的指针。

备注

一个属性表控件可以以几种不同的形式出现，例如一组选项卡式页面、树控件或一个导航按钮列表。使用 CMFCPropertySheet::SetLook 方法指定属性表控件的外观。

CMFCPropertySheet::OnActivatePage

当属性页处于启用状态时由框架调用。

virtual void OnActivatePage(CPropertyPage* pPage);

参数

pPage
[in] 指向表示已启用的属性页的属性页对象的指针。

注解

默认情况下，此方法可确保已启用的属性页滚动到视图中。如果当前属性表的样式包含 Microsoft Outlook 窗格，此方法会将相应的 Outlook 按钮设置为选中状态。

CMFCPropertySheet::OnDrawPageHeader

由框架调用，用于绘制自定义属性页的标题。

virtual void OnDrawPageHeader(
    CDC* pDC,
    int nPage,
    CRect rectHeader);

参数

pDC
[in] 指向设备上下文的指针。

nPage
[in] 从零开始的属性页码。

rectHeader
[in] 指定在何处绘制标题的边框。

注解

默认情况下，此方法不执行任何操作。如果重写此方法，请在框架调用此方法之前调用 CMFCPropertySheet::EnablePageHeader 方法。

CMFCPropertySheet::OnRemoveTreePage

由框架调用，用于从树控件中删除属性页。

virtual BOOL OnRemoveTreePage(CPropertyPage* pPage);

参数

pPage
[in] 指向表示要删除的属性页的属性页对象的指针。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

CMFCPropertySheet::RemoveCategory

从树控件中删除节点。

void RemoveCategory(CMFCPropertySheetCategoryInfo* pCategory);

参数

pCategory
[in] 指向要删除的类别（节点）的指针。

备注

使用此方法从树控件中删除节点（也称为类别）。使用 CMFCPropertySheet::AddTreeCategory 方法将节点添加到树控件。

CMFCPropertySheet::RemovePage

从属性表中删除属性页。

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

参数

pPage
[in] 指向表示要删除的属性页的属性页对象的指针。不能为 NULL。

nPage
[in] 要删除的页面的从零开始的索引。

备注

此方法删除指定的属性页并销毁其关联的窗口。在 CMFCPropertySheet 窗口关闭之前，pPage 参数指定的属性页对象不会被销毁。

CMFCPropertySheet::SetIconsList

指定用于 Outlook 窗格的导航控件的图像列表。

BOOL SetIconsList(
    UINT uiImageListResID,
    int cx,
    COLORREF clrTransparent=RGB(255, 0, 255));
void SetIconsList(HIMAGELIST hIcons);

参数

uiImageListResID
[in] 图像列表的资源 ID。

cx
[in] 图像列表中的图标的宽度（以像素为单位）。

clrTransparent
[in] 透明图像颜色。此颜色的图像部分将是透明的。默认值为洋红色，RGB(255,0,255)。

hIcons
[in] 现有图像列表的句柄。

返回值

在第一个方法重载语法中，如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

如果属性表采用 Microsoft Outlook 样式，框架将在属性表左侧显示导航按钮列表（称为 Outlook 窗格控件）。使用此方法设置 Outlook 窗格控件要使用的图像列表。

有关支持此方法的方法的详细信息，请参阅 CImageList::Create 和 CImageList::Add。有关如何设置属性表样式的详细信息，请参阅 CMFCPropertySheet::SetLook。

CMFCPropertySheet::SetLook

指定属性表的外观。

void SetLook(
    PropSheetLook look,
    int nNavControlWidth=100);

参数

look
[in] 用于指定属性表外观的枚举值之一。属性表的默认样式为 CMFCPropertySheet::PropSheetLook_Tabs。有关详细信息，请参阅本主题的“注解”部分中的表。

nNavControlWidth
[in] 导航控件的宽度（以像素为单位）。默认值为 100。

备注

若要以默认样式以外的样式显示属性表，请在创建属性表窗口之前调用此方法。

下表列出了可在 look 参数中指定的枚举值。

值	说明
`CMFCPropertySheet::PropSheetLook_Tabs`	（默认）显示每个属性页的选项卡。选项卡显示在属性表的顶部，如果选项卡的数量超过了单行所能容纳的数量，则会堆叠起来。
`CMFCPropertySheet::PropSheetLook_OutlookBar`	在属性表左侧采用 Microsoft Outlook 栏样式显示导航按钮列表。列表中的每个按钮对应一个属性页。如果按钮的数量超过了列表的可见区域中所能容纳的数量，框架将显示滚动箭头。
`CMFCPropertySheet::PropSheetLook_Tree`	在属性表左侧显示树控件。树控件的每个父节点或子节点对应一个属性页。如果节点的数量超过了树控件的可见区域中所能容纳的数量，框架将显示滚动箭头。
`CMFCPropertySheet::PropSheetLook_OneNoteTabs`	采用 Microsoft OneNote 样式显示每个属性页的选项卡。框架在属性表顶部显示选项卡，如果选项卡的数量超过了单行所能容纳的数量，框架将显示滚动箭头。
`CMFCPropertySheet::PropSheetLook_List`	在属性表左侧显示列表。每个列表项对应一个属性页。如果列表项的数量超过了列表的可见区域中所能容纳的数量，框架将显示滚动箭头。

另请参阅

层次结构图
 类
 CMFCPropertyPage 类
 CMFCOutlookBar 类

通过