通过

CMFCPropertySheet 类

  • 项目

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

  1. 从 CMFCPropertySheet 类派生一个类，并对其命名，例如，CMyPropertySheet。

  2. 为每个属性页构造一个 CMFCPropertyPage 对象。

  3. 调用 CMyPropertySheet 构造函数中的 CMFCPropertySheet::SetLook 方法。 该方法的参数指定属性页的显示方式：属性表顶部或左侧的选项卡；Microsoft OneNote 属性表样式的选项卡；Microsoft Outlook 工具栏控件上的按钮；树控件上的节点；或属性表左侧的项列表。

  4. 如果创建 Microsoft Outlook 工具栏样式的属性表，则调用 CMFCPropertySheet::SetIconsList 方法将一个图像列表与属性页关联。

  5. 为每个属性页调用 CMFCPropertySheet::AddPage 方法。

  6. 创建 CMFCPropertySheet 控件并调用其 DoModal 方法。

图示

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

CMFCPropertySheet 颜色控件。

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

CMFCPropertySheet 列表和属性控件。

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

属性树。

继承层次结构

CObject

CCmdTarget

CWnd

CPropertySheet

CMFCPropertySheet

要求

标头：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 类