CMFCPropertyGridCtrl 类

项目
10/12/2023

有关更多详细信息，请参阅 Visual Studio 安装的 mfc 文件夹中的源代码。例如 %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc。

支持可以按字母或分层顺序显示属性的可编辑属性网格控件。

语法

class CMFCPropertyGridCtrl : public CWnd

成员

公共构造函数

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

公共方法

名称	描述
`CMFCPropertyGridCtrl::accHitTest`	由框架调用以检索屏幕上给定点处的子元素或子对象。（替代 `CWnd::accHitTest`。）
`CMFCPropertyGridCtrl::accLocation`	由框架调用以检索指定对象的当前屏幕位置。（替代 `CWnd::accLocation`。）
`CMFCPropertyGridCtrl::accSelect`	由框架调用以修改选定内容或移动指定对象的键盘焦点。（替代 `CWnd::accSelect`。）
`CMFCPropertyGridCtrl::AddProperty`	向属性网格控件添加新属性。
`CMFCPropertyGridCtrl::AlwaysShowUserToolTip`
`CMFCPropertyGridCtrl::CloseColorPopup`	关闭颜色选择对话框。
`CMFCPropertyGridCtrl::Create`	创建属性网格控件并将其附加到属性网格控件对象。
`CMFCPropertyGridCtrl::DeleteProperty`	从属性网格控件中删除指定的属性。
`CMFCPropertyGridCtrl::DrawControlBarColors`
`CMFCPropertyGridCtrl::EnableDescriptionArea`	启用或禁用属性列表下显示的说明区域。
`CMFCPropertyGridCtrl::EnableHeaderCtrl`	启用或禁用属性网格控件顶部的标题控件。
`CMFCPropertyGridCtrl::EnsureVisible`	滚动属性网格控件并展开属性项，直到指定属性可见。
`CMFCPropertyGridCtrl::ExpandAll`	展开或折叠所有属性网格控件节点。
`CMFCPropertyGridCtrl::FindItemByData`	检索与用户定义的 `DWORD` 值关联的属性。
`CMFCPropertyGridCtrl::get_accChild`	由框架调用以检索指定子级的 `IDispatch` 接口地址。（替代 `CWnd::get_accChild`。）
`CMFCPropertyGridCtrl::get_accChildCount`	由框架调用调用以检索属于该对象的子级的个数。（替代 `CWnd::get_accChildCount`。）
`CMFCPropertyGridCtrl::get_accDefaultAction`	由框架调用以检索描述对象默认操作的字符串。（替代 `CWnd::get_accDefaultAction`。）
`CMFCPropertyGridCtrl::get_accDescription`	由框架调用以检索描述指定对象的可视外观的字符串。（替代 `CWnd::get_accDescription`。）
`CMFCPropertyGridCtrl::get_accFocus`	由框架调用以检索具有键盘焦点的对象。（替代 `CWnd::get_accFocus`。）
`CMFCPropertyGridCtrl::get_accHelp`	由框架调用以检索对象的 `Help` 属性字符串。（替代 `CWnd::get_accHelp`。）
`CMFCPropertyGridCtrl::get_accHelpTopic`	由框架调用以检索与指定对象关联的 `WinHelp` 文件的完整路径以及该文件内相应主题的标识符。（替代 `CWnd::get_accHelpTopic`。）
`CMFCPropertyGridCtrl::get_accKeyboardShortcut`	由框架调用以检索指定对象的快捷键或访问键。（替代 `CWnd::get_accKeyboardShortcut`。）
`CMFCPropertyGridCtrl::get_accName`	由框架调用以检索指定对象的名称。（替代 `CWnd::get_accName`。）
`CMFCPropertyGridCtrl::get_accRole`	由框架调用以检索描述指定对象的角色的信息。（替代 `CWnd::get_accRole`。）
`CMFCPropertyGridCtrl::get_accSelection`	由框架调用以检索该对象的选定子级。（替代 `CWnd::get_accSelection`。）
`CMFCPropertyGridCtrl::get_accState`	由框架调用以检索指定对象的当前状态。（替代 `CWnd::get_accState`。）
`CMFCPropertyGridCtrl::get_accValue`	由框架调用以检索指定对象的值。（替代 `CWnd::get_accValue`。）
`CMFCPropertyGridCtrl::GetBkColor`	检索当前属性网格控件的背景色。
`CMFCPropertyGridCtrl::GetBoldFont`	检索当前属性网格控件中粗体样式的文本的 Windows 字体。
`CMFCPropertyGridCtrl::GetCurSel`	检索当前选定的属性。
`CMFCPropertyGridCtrl::GetCustomColors`	检索当前为属性网格控件元素定义的自定义颜色。
`CMFCPropertyGridCtrl::GetDescriptionHeight`	检索位于属性网格控件底部的说明区域的高度。
`CMFCPropertyGridCtrl::GetDescriptionRows`	检索当前属性网格控件的说明区域中的行数。
`CMFCPropertyGridCtrl::GetHeaderCtrl`	检索框架用于显示当前属性网格控件的内部 `CMFCHeaderCtrl` 对象。
`CMFCPropertyGridCtrl::GetHeaderHeight`	检索属性网格控件标题的高度。
`CMFCPropertyGridCtrl::GetLeftColumnWidth`	检索包含每个属性名称的当前属性网格控件左列的宽度。
`CMFCPropertyGridCtrl::GetListRect`	检索属性网格控件的边框。
`CMFCPropertyGridCtrl::GetProperty`	检索指向与属性网格控件项的指定索引对应的属性对象的指针。
`CMFCPropertyGridCtrl::GetPropertyColumnWidth`	检索包含属性值的列的当前宽度。
`CMFCPropertyGridCtrl::GetPropertyCount`	检索属性网格控件中的属性数。
`CMFCPropertyGridCtrl::GetRowHeight`	检索属性网格控件中行的高度。
`CMFCPropertyGridCtrl::GetScrollBarCtrl`	检索指向属性网格控件中的滚动条控件的指针。（替代 `CWnd::GetScrollBarCtrl`。）
`CMFCPropertyGridCtrl::GetTextColor`	检索当前属性网格控件中属性项的文本的颜色。
`CMFCPropertyGridCtrl::GetThisClass`	由框架用于获取指向与此类类型关联的 `CRuntimeClass` 对象的指针。
`CMFCPropertyGridCtrl::HitTest`	如果指定点位于该项中，则检索指向与属性网格控件项对应的属性对象的指针。此方法还指示包含该点的属性网格控件中的区域。
`CMFCPropertyGridCtrl::InitHeader`	初始化框架用于显示当前属性网格控件的内部 `CMFCHeaderCtrl` 对象。
`CMFCPropertyGridCtrl::IsAlphabeticMode`	指示属性网格控件是否处于字母模式。
`CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip`
`CMFCPropertyGridCtrl::IsDescriptionArea`	指示是否显示属性网格控件的说明区域。
`CMFCPropertyGridCtrl::IsGroupNameFullWidth`	指示是否跨当前属性网格控件的宽度显示每个属性组名称。
`CMFCPropertyGridCtrl::IsHeaderCtrl`	指示是否显示标题控件。
`CMFCPropertyGridCtrl::IsMarkModifiedProperties`	指示属性网格控件如何显示修改的属性。
`CMFCPropertyGridCtrl::IsShowDragContext`	指示当用户调整列大小时框架是否重新绘制当前属性网格控件的名称和值列。
`CMFCPropertyGridCtrl::IsVSDotNetLook`	指示属性网格控件的外观是否采用 VS .NET 使用的样式。
`CMFCPropertyGridCtrl::MarkModifiedProperties`	指定如何显示修改的属性。
`CMFCPropertyGridCtrl::PreTranslateMessage`	由类 `CWinApp` 用于在将窗口消息调度到 `TranslateMessage` 和 `DispatchMessage` Windows 函数之前对其进行转换。（替代 `CWnd::PreTranslateMessage`。）
`CMFCPropertyGridCtrl::RemoveAll`	从属性网格控件中删除所有属性对象。
`CMFCPropertyGridCtrl::ResetOriginalValues`	还原所有属性的原始值。
`CMFCPropertyGridCtrl::SetAlphabeticMode`	设置或重置字母模式。
`CMFCPropertyGridCtrl::SetBoolLabels`	指定布尔标签的文本。
`CMFCPropertyGridCtrl::SetCurSel`	选择属性网格控件中的属性。
`CMFCPropertyGridCtrl::SetCustomColors`	指定各种属性网格控件元素的自定义颜色。
`CMFCPropertyGridCtrl::SetDescriptionRows`	指定要在当前属性网格控件的说明部分中显示的行数。
`CMFCPropertyGridCtrl::SetGroupNameFullWidth`	指定是否在当前属性网格控件中显示一组属性的类别名称的完整宽度。
`CMFCPropertyGridCtrl::SetListDelimiter`	定义将用作属性值列表中的分隔符的字符。
`CMFCPropertyGridCtrl::SetShowDragContext`	指定当用户调整列大小时框架是否重新绘制当前属性网格控件的名称和值列。
`CMFCPropertyGridCtrl::SetVSDotNetLook`	将属性网格控件的外观设置为 VS .NET 中使用的样式。
`CMFCPropertyGridCtrl::UpdateColor`	设置当前所选颜色属性的颜色值。

受保护方法

名称	描述
`CMFCPropertyGridCtrl::AdjustLayout`	重新绘制属性网格控件及其属性。
`CMFCPropertyGridCtrl::CompareProps`	由属性网格控件调用以对属性进行排序。
`CMFCPropertyGridCtrl::EditItem`	当用户开始修改属性时由框架调用。
`CMFCPropertyGridCtrl::EndEditItem`	当用户停止修改属性时由框架调用。
`CMFCPropertyGridCtrl::Init`	由框架调用以初始化属性网格控件。
`CMFCPropertyGridCtrl::OnChangeSelection`	更改当前所选内容时由框架调用。
`CMFCPropertyGridCtrl::OnClickButton`	单击属性按钮时由框架调用。
`CMFCPropertyGridCtrl::OnDrawBorder`	由框架调用以围绕属性网格控件绘制边框。
`CMFCPropertyGridCtrl::OnDrawDescription`	由框架调用以绘制说明区域并显示说明文本。
`CMFCPropertyGridCtrl::OnDrawList`	由框架调用以显示属性网格控件中的属性列表。
`CMFCPropertyGridCtrl::OnDrawProperty`	由框架调用以显示属性。
`CMFCPropertyGridCtrl::OnPropertyChanged`	当属性的值更改时由框架调用。
`CMFCPropertyGridCtrl::OnSelectCombo`	选择包含组合框控件的属性时由框架调用。
`CMFCPropertyGridCtrl::ValidateItemData`	由框架调用以验证属性数据。

备注

CMFCPropertyGridCtrl 类显示一个属性网格控件，该控件包含派生自 CMFCPropertyGridProperty 类的可编辑属性。每个属性都可以表示一个类型，并且可以包含子项。属性网格控件支持底部可调整大小的区域，该区域可以显示所选属性的说明。

若要使用属性网格控件，请构造 CMFCPropertyGridCtrl 对象，然后调用 CMFCPropertyGridCtrl::Create 方法。使用 CMFCPropertyGridCtrl::AddProperty 方法将属性添加到列表中。

选择属性

属性项可以启动一个对话框，而不是表示一个值，该对话框使用户能够选择颜色、文件或字体。

下表列出了四种选择属性类型：

类	说明
`CMFCPropertyGridProperty` 类	一个常规用途属性，用于指定字符串、布尔、日期等的值。
`CMFCPropertyGridColorProperty` 类	用于选择颜色值的属性。
`CMFCPropertyGridFileProperty` 类	用于选择文件的属性。
`CMFCPropertyGridFontProperty` 类	用于选择字体的属性。

图示

下图描绘了一个属性网格控件，该控件以两种方式显示属性。第一个图以分层方式显示属性，第二个图按字母顺序显示属性。

Property List PropertySheet.

示例

以下示例演示如何使用 CMFCPropertyGridCtrl 类中的各种方法配置属性网格控件对象。该示例演示如何启用标题控件、启用说明区域和设置属性网格控件的外观。该示例还演示如何为控件设置字母模式，从而控件按其属性名称对其包含的所有属性进行排序，以及如何为属性网格控件的各种元素设置自定义颜色。本示例是新控件示例的一部分。

CMFCPropertyGridCtrl m_wndPropList;

m_wndPropList.EnableHeaderCtrl();
m_wndPropList.EnableDescriptionArea();
m_wndPropList.SetVSDotNetLook(m_bDotNetLook);
// BOOL m_bMarkChanged
m_wndPropList.MarkModifiedProperties(m_bMarkChanged);
// BOOL m_bPropListCategorized
m_wndPropList.SetAlphabeticMode(!m_bPropListCategorized);
// BOOL m_bShowDragContext
m_wndPropList.SetShowDragContext(m_bShowDragContext);

// BOOL m_bMarkSortedColumn
m_wndList.EnableMarkSortedColumn(m_bMarkSortedColumn);

// BOOL m_bPropListCustomColors
// set custom colors for various elements of the property grid control
if (m_bPropListCustomColors)
{
   m_wndPropList.SetCustomColors(RGB(228, 243, 254), RGB(46, 70, 165), RGB(200, 236, 209), RGB(33, 102, 49), RGB(255, 229, 216), RGB(128, 0, 0), RGB(159, 159, 255));
}
else
{
   COLORREF c = (COLORREF)-1;
   m_wndPropList.SetCustomColors(c, c, c, c, c, c, c);
}

m_wndPropList.RedrawWindow();

// restore original values of the properties
m_wndPropList.ResetOriginalValues();

继承层次结构

CObject

CCmdTarget

CWnd

CMFCPropertyGridCtrl

要求

标头afxpropertygridctrl.h：

`CMFCPropertyGridCtrl::accSelect`

virtual HRESULT accSelect(
    long flagsSelect,
    VARIANT varChild);

参数

[in] flagsSelect
[in] varChild\

返回值

备注

`CMFCPropertyGridCtrl::AddProperty`

向属性网格控件添加新属性。

int AddProperty(
    CMFCPropertyGridProperty* pProp,
    BOOL bRedraw=TRUE,
    BOOL bAdjustLayout=TRUE);

参数

pProp
[in] 指向属性的指针。

bRedraw
[in] 如果值为 TRUE，则立即重新绘制属性；否则，值为 FALSE。默认值为 TRUE。

bAdjustLayout
[in] 如果值为 TRUE，则重新计算如何绘制属性的文本和值，然后绘制属性；如果值为 FALSE，则使用现有计算来绘制属性。默认值是 TRUE。

返回值

如果此方法成功，则为属性网格控件中添加属性的位置的从零开始的索引；否则，为 -1。

注解

此方法将指向指定属性的指针添加到属性网格控件中属性列表的末尾。在网格控件被销毁之前，不要销毁属性或允许它们超出范围。完成属性网格控件后，调用 CMFCPropertyGridCtrl::RemoveAll 以删除所有添加的属性。如果已将指定的属性添加到列表中，AddProperty 方法将失败。

`CMFCPropertyGridCtrl::AdjustLayout`

重新绘制属性网格控件及其属性。

virtual void AdjustLayout();

备注

此方法重新计算如何绘制整个属性网格控件及其属性，包括图像、字体和控件。

`CMFCPropertyGridCtrl::AlwaysShowUserToolTip`

void AlwaysShowUserToolTip(BOOL bShow = TRUE);

参数

[in] bShow\

备注

`CMFCPropertyGridCtrl::CloseColorPopup`

关闭颜色选择对话框。

virtual void CloseColorPopup();

注解

有关颜色选择对话框的详细信息，请参阅 CMFCPropertyGridColorProperty 类。

`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`

构造 CMFCPropertyGridCtrl 对象。

CMFCPropertyGridCtrl();

返回值

备注

`CMFCPropertyGridCtrl::CompareProps`

由属性网格控件调用以对属性进行排序。

virtual int CompareProps(
    const CMFCPropertyGridProperty* pProp1,
    const CMFCPropertyGridProperty* pProp2) const;

参数

pProp1
指向属性的指针。

pProp2
指向属性的指针。

返回值

返回值	说明
< 0	`pProp1` 参数的名称小于 `pProp2` 参数的名称。
0	`pProp1` 参数的名称等于 `pProp2` 参数的名称。
> 0	`pProp1` 对象的名称大于 `pProp2` 参数的名称。

备注

默认情况下，此方法使用 CString::Compare 方法比较指定参数的 CMFCPropertyGridProperty::m_strName 成员。

`CMFCPropertyGridCtrl::Create`

创建属性网格控件并将其附加到属性网格控件对象。

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

参数

dwStyle
[in] 窗口样式的按位组合“或”(|)。

rect
[in] 一个边框，指定窗口的大小和位置，以 pParentWnd 的客户端坐标表示。

pParentWnd
[in] 指向父窗口的指针。不得为 NULL。

nID
[in] 子窗口的 ID。

返回值

如果成功创建窗口，值为 TRUE；否则，值为 FALSE。

备注

若要创建属性网格控件，请先调用 CMFCPropertyGridCtrl::CMFCPropertyGridCtrl 来构造属性网格对象。然后调用 CMFCPropertyGridCtrl::Create。

示例

以下示例演示了如何在 CMFCPropertyGridCtrl 类中使用 Create 方法。本示例是新控件示例的一部分。

// CRect rectPropList
// CMFCPropertyGridCtrl m_wndPropList
// The this pointer points to a CPage5 class which extends the CMFCPropertyPage class.
m_wndPropList.Create(WS_CHILD | WS_VISIBLE | WS_TABSTOP | WS_BORDER, rectPropList, this, (UINT)-1);

`CMFCPropertyGridCtrl::DeleteProperty`

从属性网格控件中删除指定的属性。

BOOL DeleteProperty(
    CMFCPropertyGridProperty*& pProp,
    BOOL bRedraw=TRUE,
    BOOL bAdjustLayout=TRUE);

参数

pProp
[in] 指向属性的指针。

bRedraw
[in] 如果值为 TRUE，则重绘属性网格控件；否则，值为 FALSE。默认值是 TRUE。

bAdjustLayout
[in] 如果值为 TRUE，则重新计算如何绘制属性网格控件中的所有文本、图像和项，然后绘制控件；否则，值为 FALSE。默认值是 TRUE。

返回值

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

备注

使用此方法从属性网格控件中删除属性和任何子项。

`CMFCPropertyGridCtrl::DrawControlBarColors`

BOOL DrawControlBarColors() const;

返回值

注解

`CMFCPropertyGridCtrl::EditItem`

当用户开始修改属性时由框架调用。

virtual BOOL EditItem(
    CMFCPropertyGridProperty* pProp,
    LPPOINT lptClick=NULL);

参数

pProp
[in] 指向属性的指针。

lptClick
[in] 用户单击以开始编辑操作的属性网格控件上的点。该点以控件的客户端坐标表示。默认值为 NULL。

返回值

如果此方法成功，值为 TRUE；否则，值为 FALSE。

备注

`CMFCPropertyGridCtrl::EnableDescriptionArea`

启用或禁用显示在属性网格控件的属性列表下方的说明区域。

void EnableDescriptionArea(BOOL bEnable=TRUE);

参数

bEnable
[in] 如果值为 TRUE，则启用说明区域；如果值为 FALSE，则禁用说明区域。默认值为 TRUE。

备注

说明区域显示在属性网格控件底部。默认情况下，说明区域处于禁用状态且不可见。

`CMFCPropertyGridCtrl::EnableHeaderCtrl`

启用或禁用属性网格控件顶部的标题控件。

void EnableHeaderCtrl(
    BOOL bEnable=TRUE,
    LPCTSTR lpszLeftColumn=_T("Property"),
    LPCTSTR lpszRightColumn=_T("Value"));

参数

bEnable
[in] 如果值为 TRUE，则启用标题控件；如果值为 FALSE，则禁用标题控件。默认值为 TRUE。

lpszLeftColumn
[in] 标题控件左列的标题。默认值为 Property。

lpszRightColumn
[in] 标题控件右列的标题。默认值是 Value。

`CMFCPropertyGridCtrl::EndEditItem`

当用户完成修改属性时由框架调用。

virtual BOOL EndEditItem(BOOL bUpdateData=TRUE);

参数

bUpdateData
[in] 如果值为 TRUE，则指定编辑操作完成后必须验证修改后的属性数据；否则，值为 FALSE. 默认值为 TRUE。

返回值

如果编辑操作成功完成，值为 TRUE；如果修改后的属性数据无效，或者编辑操作应继续，值为 FALSE。

备注

`CMFCPropertyGridCtrl::EnsureVisible`

滚动属性网格控件并展开属性项，直到指定属性可见。

void EnsureVisible(
    CMFCPropertyGridProperty* pProp,
    BOOL bExpandParents=FALSE);

参数

pProp
[in] 指向属性的指针。

bExpandParents
[in] 如果值为 TRUE，则展开父项以使指定的属性可见；否则，值为 FALSE。默认值为 FALSE。

注解

`CMFCPropertyGridCtrl::ExpandAll`

展开或折叠所有属性网格控件节点。

void ExpandAll(BOOL bExpand=TRUE);

参数

bExpand
[in] 如果值为 TRUE，则展开所有节点；如果值为 FALSE，则折叠所有节点。默认值为 TRUE。

备注

`CMFCPropertyGridCtrl::FindItemByData`

检索与用户定义的 DWORD 值关联的属性。

CMFCPropertyGridProperty* FindItemByData(
    DWORD_PTR dwData,
    BOOL bSearchSubItems=TRUE) const;

参数

dwData
[in] DWORD 值。

bSearchSubItems
[in] 如果值为 TRUE，则搜索属性子项；否则，值为 FALSE。默认值为 TRUE。

返回值

如果此方法成功，则值为指向关联属性对象的指针；否则，值为 NULL。

注解

使用 CMFCPropertyGridCtrl::CMFCPropertyGridCtrl 构造函数或 CMFCPropertyGridProperty::SetData 方法将 DWORD 与属性相关联。

`CMFCPropertyGridCtrl::get_accChildCount`

virtual HRESULT get_accChildCount(long* pcountChildren);

参数

[in] pcountChildren\

返回值

备注

`CMFCPropertyGridCtrl::get_accFocus`

virtual HRESULT get_accFocus(VARIANT* pvarChild);

参数

[in] pvarChild\

返回值

注解

`CMFCPropertyGridCtrl::get_accHelp`

virtual HRESULT get_accHelp(
    VARIANT varChild,
    BSTR* pszHelp);

参数

[in] varChild
[in] pszHelp\

返回值

备注

`CMFCPropertyGridCtrl::get_accHelpTopic`

virtual HRESULT get_accHelpTopic(
    BSTR* pszHelpFile,
    VARIANT varChild,
    long* pidTopic);

参数

[in] pszHelpFile
[in] varChild
[in] pidTopic\

返回值

备注

`CMFCPropertyGridCtrl::get_accKeyboardShortcut`

virtual HRESULT get_accKeyboardShortcut(
    VARIANT varChild,
    BSTR* pszKeyboardShortcut);

参数

[in] varChild
[in] pszKeyboardShortcut\

返回值

备注

`CMFCPropertyGridCtrl::get_accSelection`

virtual HRESULT get_accSelection(VARIANT* pvarChildren);

参数

[in] pvarChildren\

返回值

注解

`CMFCPropertyGridCtrl::GetBkColor`

检索当前属性网格控件的背景色。

COLORREF GetBkColor() const;

返回值

RGB 颜色值。

备注

此方法检索框架用于绘制当前属性网格控件背景的颜色。 CMFCPropertyGridCtrl::GetTextColor 方法检索前景色。

`CMFCPropertyGridCtrl::GetBoldFont`

检索用于在当前属性网格控件中以粗体样式绘制文本的 Windows 字体。

CFont& GetBoldFont();

返回值

对描述粗体字体特征的 CFont 对象的引用。

`CMFCPropertyGridCtrl::GetCurSel`

检索当前选定的属性。

CMFCPropertyGridProperty* GetCurSel() const;

返回值

指向与属性网格控件中所选项对应的属性对象的指针。

备注

`CMFCPropertyGridCtrl::GetCustomColors`

检索当前为属性网格控件元素定义的自定义颜色。

void GetCustomColors(
    COLORREF& clrBackground,
    COLORREF& clrText,
    COLORREF& clrGroupBackground,
    COLORREF& clrGroupText,
    COLORREF& clrDescriptionBackground,
    COLORREF& clrDescriptionText,
    COLORREF& clrLine);

参数

clrBackground
[out] 属性值的背景色。

clrText
[out] 属性名称和属性值文本的颜色。

clrGroupBackground
[out] 属性组的背景色。

clrGroupText
[out] 属性组中文本的颜色。

clrDescriptionBackground
[out] 说明区域的背景色。

clrDescriptionText
[out] 说明区域中的文本颜色。

clrLine
[out] 在属性之间绘制的线条的颜色。

注解

使用 CMFCPropertyGridCtrl::SetCustomColors 方法设置自定义颜色。

`CMFCPropertyGridCtrl::GetDescriptionHeight`

检索位于属性网格控件底部的说明区域的高度。

int GetDescriptionHeight() const;

返回值

说明区域的高度（以像素为单位）。

备注

说明区域的高度是自动计算的，设置为属性网格控件高度的 1/4。

使用 CMFCPropertyGridCtrl::EnableDescriptionArea 方法显示或隐藏说明区域。使用 CMFCPropertyGridCtrl::IsDescriptionArea 方法确定说明区域是显示还是隐藏。

`CMFCPropertyGridCtrl::GetDescriptionRows`

检索当前属性网格控件的说明区域中的行数。

int GetDescriptionRows() const;

返回值

当前属性网格控件的说明区域中的行数。

注解

CMFCPropertyGridCtrl::CMFCPropertyGridCtrl 构造函数将说明区域初始化为 3 行。

`CMFCPropertyGridCtrl::GetHeaderCtrl`

检索框架用于显示当前属性网格控件的内部 CMFCHeaderCtrl 对象。

virtual CMFCHeaderCtrl& GetHeaderCtrl();

返回值

对 CMFCHeaderCtrl 对象的引用。

`CMFCPropertyGridCtrl::GetHeaderHeight`

检索属性网格控件标题的高度。

int GetHeaderHeight() const;

返回值

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

备注

`CMFCPropertyGridCtrl::GetLeftColumnWidth`

检索包含每个属性名称的当前属性网格控件左列的宽度。

int GetLeftColumnWidth() const;

返回值

名称列的宽度。

备注

属性网格控件的右列包含每个属性的值。

`CMFCPropertyGridCtrl::GetListRect`

检索属性网格控件的边框。

CRect GetListRect() const;

返回值

属性网格控件的边框。此矩形不包括说明区域和标题。

注解

`CMFCPropertyGridCtrl::GetProperty`

检索指向与属性网格控件中的项的指定索引对应的属性对象的指针。

CMFCPropertyGridProperty* GetProperty(int nIndex) const;

参数

nIndex
[in] 属性网格控件项的从零开始的索引。

此方法断言 nIndex 参数是小于零还是大于或等于属性数。

返回值

如果此方法成功，则值为指向与指定索引相对应的属性对象的指针；否则，值为 NULL。

备注

`CMFCPropertyGridCtrl::GetPropertyColumnWidth`

检索包含属性值的列的当前宽度。

int GetPropertyColumnWidth() const;

返回值

包含属性值的列的当前宽度。

备注

属性网格控件右侧的列包含属性值。客户可以使用属性网格控件的拆分框更改值列的宽度。

`CMFCPropertyGridCtrl::GetPropertyCount`

检索属性网格控件中的属性数。

int GetPropertyCount() const;

返回值

属性数。

注解

`CMFCPropertyGridCtrl::GetRowHeight`

检索属性网格控件中行的高度。

int GetRowHeight() const;

返回值

行的高度。

备注

行的高度等于当前字体高度加上 4 个像素。

`CMFCPropertyGridCtrl::GetScrollBarCtrl`

检索指向属性网格控件中的滚动条控件的指针。

virtual CScrollBar* GetScrollBarCtrl(int nBar) const;

参数

nBar
[in] 滚动条的方向，必须是 SB_VERT。

返回值

指向滚动条对象的指针，如果没有滚动条或滚动条方向为 SB_HORZ，则为 NULL。

备注

使用此方法可直接访问垂直滚动条控件。

`CMFCPropertyGridCtrl::GetTextColor`

检索用于在当前属性网格控件中绘制属性项文本的颜色。

COLORREF GetTextColor() const;

返回值

RGB 颜色值。

备注

此方法检索框架用于绘制当前属性网格控件前景的颜色。 CMFCPropertyGridCtrl::GetBkColor 方法检索背景色。

`CMFCPropertyGridCtrl::HitTest`

如果指定点位于该项中，则检索指向与属性网格控件项对应的属性对象的指针。此方法还指示包含该点的属性网格控件中的区域。

CMFCPropertyGridProperty* HitTest(
    CPoint pt,
    CMFCPropertyGridProperty::ClickArea* pnArea=NULL,
    BOOL bPropsOnly=FALSE) const;

参数

pt
[in] 一个点，以客户端坐标表示。

pnArea
[in, out] 指向 ClickArea 变量的指针。当此方法返回时，变量指示包含指定点的属性区域。有关属性区域的详细信息，请参阅“注解”。

bPropsOnly
[in] 如果值为 TRUE，则仅测试属性区域；如果值为 FALSE，则测试说明区域，如果指定点不在属性区域中。默认值是 FALSE。有关说明区域的详细信息，请参阅“注解”。

返回值

如果 bPropsOnly 参数为 TRUE 且指定点在属性区域中，则返回值是指向相应属性对象的指针。此外，pnArea 参数设置为包含指定点的特定区域。否则，返回值为 NULL 且 pnArea 参数不会被修改。

如果 bPropsOnly 参数为 FALSE，则返回值始终为 NULL。但是，如果指定点在说明区域中，则 pnArea 参数设置为 CMFCPropertyGridProperty::ClickDescription。

注解

术语“属性区域”是指属性网格控件项的名称、值或扩展框区域中的任何一个。说明区域是属性网格控件底部的区域。选择属性网格控件项时，说明区域会显示相应属性的说明。

此方法设置 pnArea 参数指向的变量的值。下表列出了可能的值和对应的区域。

值	区域
`ClickArea::ClickExpandBox`	属性展开框控件。
`ClickArea::ClickName`	属性名称。
`ClickArea::ClickValue`	属性值。
`CMFCPropertyGridProperty::ClickDescription`	属性网格控件说明区域。

`CMFCPropertyGridCtrl::Init`

由框架调用以初始化属性网格控件。

virtual void Init();

备注

`CMFCPropertyGridCtrl::InitHeader`

初始化框架用于显示当前属性网格控件的内部 CMFCHeaderCtrl 对象。

virtual void InitHeader();

`CMFCPropertyGridCtrl::IsAlphabeticMode`

指示属性网格控件是否处于字母模式。

BOOL IsAlphabeticMode() const;

返回值

如果属性网格控件处于字母模式，值为 TRUE；否则，值为 FALSE。

备注

当属性网格控件处于字母模式时，所有属性都按其名称的字母顺序排序。否则，属性将分组在其父节点下。

使用 CMFCPropertyGridCtrl::SetAlphabeticMode 方法启用或禁用字母模式。

`CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip`

BOOL IsAlwaysShowUserToolTip() const;

返回值

备注

`CMFCPropertyGridCtrl::IsDescriptionArea`

指示是否显示属性网格控件的说明区域。

BOOL IsDescriptionArea() const;

返回值

如果显示说明区域，值为 TRUE；否则，值为 FALSE。

备注

使用 CMFCPropertyGridCtrl::EnableDescriptionArea 方法隐藏或显示说明区域。

`CMFCPropertyGridCtrl::IsGroupNameFullWidth`

指示是否跨当前属性网格控件的宽度显示每个属性组名称。

BOOL IsGroupNameFullWidth() const;

返回值

如果组名称跨属性网格控件的宽度显示，值为 TRUE；如果组名称被控件的右（值）列截断，值为 FALSE。

注解

组是属性网格控件中相关属性的集合。如果控件以分层方式显示，则组名称显示为组上方行中的类别标题。

`CMFCPropertyGridCtrl::IsHeaderCtrl`

指示是否显示标题控件。

BOOL IsHeaderCtrl() const;

返回值

如果显示标题控件，值为 TRUE；否则，值为 FALSE。

备注

使用 CMFCPropertyGridCtrl::EnableHeaderCtrl 方法隐藏或显示标题控件。

`CMFCPropertyGridCtrl::IsMarkModifiedProperties`

指示属性网格控件如何显示修改的属性。

BOOL IsMarkModifiedProperties() const;

返回值

如果使用粗体样式显示修改后的属性，值为 TRUE如果使用常规样式显示修改后的属性，值为 FALSE。

注解

`CMFCPropertyGridCtrl::IsShowDragContext`

指示当用户调整列大小时框架是否重新绘制当前属性网格控件的名称和值列。

BOOL IsShowDragContext() const;

返回值

如果框架在调整大小操作期间重绘名称和值列，值为 TRUE；如果框架在拖动操作完成后重新绘制列，值为 FALSE。

备注

用户可以通过拖动列之间的拆分栏来调整属性网格控件的名称和值列的大小。如果显示拖动上下文，只要用户拖动拆分栏，就可以调整名称和值列的大小。否则，拆分栏将移动，但在拖动操作完成之前不会重新绘制列。

`CMFCPropertyGridCtrl::IsVSDotNetLook`

指示属性网格控件的外观是否采用 Visual Studio .NET 的样式。

BOOL IsVSDotNetLook() const;

返回值

如果属性网格控件采用 Visual Studio .NET 的样式，值为 TRUE；否则，值为 FALSE。

备注

使用 CMFCPropertyGridCtrl::SetVSDotNetLook 方法将属性网格控件设置为 Visual Studio .NET 的样式。

`CMFCPropertyGridCtrl::MarkModifiedProperties`

指定如何显示修改的属性。

void MarkModifiedProperties(
    BOOL bMark=TRUE,
    BOOL bRedraw=TRUE);

参数

bMark
[in] 如果值为 TRUE，则以粗体样式显示修改后的属性；如果值为 FALSE，则以常规样式显示修改后的属性。默认值为 TRUE。

bRedraw
[in] 如果值为 TRUE，则立即重绘属性网格控件；否则，值为 FALSE。默认值为 TRUE。

备注

`CMFCPropertyGridCtrl::OnChangeSelection`

更改当前所选内容时由框架调用。

virtual void OnChangeSelection(
    CMFCPropertyGridProperty* pNewSel,
    CMFCPropertyGridProperty* pOldSel);

参数

pNewSel
[in] 指向新选定属性的指针。

pOldSel
[in] 指向以前选定属性的指针。

备注

此方法的默认实现不执行任何操作。

`CMFCPropertyGridCtrl::OnClickButton`

单击属性按钮时由框架调用。

virtual void OnClickButton(CPoint point);

参数

point
[in] 一个点，以客户端坐标表示。

备注

默认情况下，此方法会更新当前属性值。

`CMFCPropertyGridCtrl::OnDrawBorder`

由框架调用以围绕属性网格控件绘制边框。

virtual void OnDrawBorder(CDC* pDC);

参数

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

注解

`CMFCPropertyGridCtrl::OnDrawDescription`

由框架调用以绘制说明区域并显示说明文本。

virtual void OnDrawDescription(
    CDC* pDC,
    CRect rect);

参数

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

rect
[in] 一个指定在何处绘制说明区域的矩形。

备注

使用 CMFCPropertyGridCtrl::EnableDescriptionArea 方法显示说明区域。

`CMFCPropertyGridCtrl::OnDrawList`

由框架调用以显示属性网格控件中的属性列表。

virtual void OnDrawList(CDC* pDC);

参数

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

备注

`CMFCPropertyGridCtrl::OnDrawProperty`

由框架调用以显示属性。

virtual int OnDrawProperty(
    CDC* pDC,
    CMFCPropertyGridProperty* pProp) const;

参数

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

pProp
[in] 一个指向属性对象的指针。

返回值

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

备注

`CMFCPropertyGridCtrl::OnPropertyChanged`

当属性的值更改时由框架调用。

virtual void OnPropertyChanged(CMFCPropertyGridProperty* pProp) const;

参数

pProp
[in] 一个指向其值已更改的属性对象的指针。

备注

默认情况下，此方法会将 AFX_WM_PROPERTY_CHANGED 消息发送到属性网格控件的所有者。

`CMFCPropertyGridCtrl::OnSelectCombo`

选择包含组合框控件的属性时由框架调用。

void OnSelectCombo();

备注

`CMFCPropertyGridCtrl::RemoveAll`

从属性网格控件中删除所有属性对象。

void RemoveAll();

备注

`CMFCPropertyGridCtrl::ResetOriginalValues`

还原所有属性的原始值。

void ResetOriginalValues(BOOL bRedraw=TRUE);

参数

bRedraw
[in] 如果值为 TRUE，则重绘属性列表；否则，值为 FALSE。默认值为 TRUE。

备注

`CMFCPropertyGridCtrl::SetAlphabeticMode`

设置或重置字母模式。

void SetAlphabeticMode(BOOL bSet=TRUE);

参数

bSet
[in] 如果值为 TRUE，则设置为字母模式；如果值为 FALSE，则重置字母模式。默认值为 TRUE。

注解

当属性网格控件处于字母模式时，该控件按其属性名称对它包含的所有属性进行排序。

`CMFCPropertyGridCtrl::SetBoolLabels`

指定布尔标签的文本。

void SetBoolLabels(
    LPCTSTR lpszTrue,
    LPCTSTR lpszFalse);

参数

lpszTrue
[in] 要为布尔值 true 显示的文本字符串。

lpszFalse
[in] 要为布尔值 false 显示的文本字符串。

注解

`CMFCPropertyGridCtrl::SetCurSel`

选择属性网格控件中的属性。

void SetCurSel(
    CMFCPropertyGridProperty* pProp,
    BOOL bRedraw=TRUE);

参数

pProp
[in] 一个指向属性对象的指针。

bRedraw
[in] 如果值为 TRUE，则立即重绘属性网格控件；否则，值为 FALSE。默认值为 TRUE。

备注

使用此方法取消属性网格控件中当前项的选择，然后选择与指定属性对应的项。

`CMFCPropertyGridCtrl::SetCustomColors`

指定属性网格控件的各种元素的自定义颜色。

void SetCustomColors(
    COLORREF clrBackground,
    COLORREF clrText,
    COLORREF clrGroupBackground,
    COLORREF clrGroupText,
    COLORREF clrDescriptionBackground,
    COLORREF clrDescriptionText,
    COLORREF clrLine);

参数

clrBackground
[in] 属性值的背景色。

clrText
[in] 属性名称和属性值文本的颜色。

clrGroupBackground
[in] 属性组的背景色。

clrGroupText
[in] 属性组的新文本颜色。

clrDescriptionBackground
[in] 说明区域的背景色。

clrDescriptionText
[in] 说明区域中的文本颜色。

clrLine
[in] 在属性之间绘制的线条的颜色。

备注

对于任何参数，请指定 ((COLORREF)-1) 颜色值以使用属性网格控件的元素的默认颜色。

若要自定义特定属性的外观，请从 CMFCPropertyGridProperty 类派生类，然后重写 CMFCPropertyGridProperty::OnDrawName、CMFCPropertyGridProperty::OnDrawValue、CMFCPropertyGridProperty::OnDrawExpandBox 和 CMFCPropertyGridProperty::OnDrawButton 方法。

`CMFCPropertyGridCtrl::SetDescriptionRows`

指定要在当前属性网格控件的说明部分中显示的行数。

void SetDescriptionRows(int nDescRows);

参数

nDescRows
[in] 要在属性说明中显示的行数。

`CMFCPropertyGridCtrl::SetGroupNameFullWidth`

指定是否在当前属性网格控件中显示一组属性的类别名称的完整宽度。

void SetGroupNameFullWidth(
    BOOL bGroupNameFullWidth = TRUE,
    BOOL bRedraw = TRUE);

参数

bGroupNameFullWidth
[in] 如果值为 TRUE，则显示类别名称的完整宽度，而不考虑属性名称列的宽度。如果值为 FALSE，则将类别名称的宽度限制为属性名称列的宽度。默认值为 TRUE。

bRedraw
[in] 如果值为 TRUE，则立即更新属性网格控件；如果值为 FALSE，则在发生下一次重绘事件时更新控件。默认值为 TRUE。

注解

属性网格控件由可调整大小的“属性名称”列和“属性值”列组成。名称列的末尾也是值列的开头。若要调整列的大小，请拖动列之间的边框。

此方法中可互换使用术语“组名称”和“类别名称”。类别名称显示在以一组相关属性和值为标题的行上。此方法指定属性名称列的宽度是否还指定显示类别名称的宽度。

`CMFCPropertyGridCtrl::SetListDelimiter`

定义用作属性值列表中的分隔符的字符。

void SetListDelimiter(TCHAR c);

参数

c
[in] 一个用作分隔符的字符。

注解

使用此方法在 CMFCPropertyGridProperty::CMFCPropertyGridProperty 构造函数中使用的属性值列表中定义分隔符字符。在该构造函数中，将 bIsValueList 参数设置为 TRUE。

默认情况下，CMFCPropertyGridCtrl::CMFCPropertyGridCtrl 构造函数将分隔符字符设置为逗号（“,”）。

`CMFCPropertyGridCtrl::SetShowDragContext`

指定当用户调整列大小时框架是否重新绘制当前属性网格控件的名称和值列。

void SetShowDragContext(BOOL bShowDragContext = TRUE);

参数

bShowDragContext
[in] 如果值为 TRUE，则在重设大小操作期间重新绘制名称和值列；如果值为 FALSE，则在拖动操作完成后重新绘制列。默认值是 TRUE。

注解

`CMFCPropertyGridCtrl::SetVSDotNetLook`

将属性网格控件的外观设置为 Visual Studio .NET 中使用的样式。

void SetVSDotNetLook(BOOL bSet=TRUE);

参数

bSet
[in] 如果值为 TRUE，则将属性网格控件设置为 Visual Studio .NET 中使用的样式；否则，值为 FALSE。默认值为 TRUE。

注解

`CMFCPropertyGridCtrl::UpdateColor`

设置当前所选颜色属性的颜色值。

virtual void UpdateColor(COLORREF color);

参数

color
[in] RGB 颜色值。

备注

如果属性网格控件当前选定的属性不是颜色属性，则此方法在调试模式下断言。

`CMFCPropertyGridCtrl::ValidateItemData`

由框架调用以验证属性数据。

virtual BOOL ValidateItemData(CMFCPropertyGridProperty* pProp);

参数

pProp
[in] 指向属性的指针。不使用此参数。

返回值

总是为 TRUE。

注解

CMFCPropertyGridCtrl::EndEditItem 方法调用此方法来验证数据。默认情况下，此方法不使用其 pProp 参数，其返回值始终为 TRUE。

如果重写此方法，则在指定的属性数据有效时返回 TRUE。否则，返回 FALSE，在这种情况下，框架不会更新属性。

另请参阅

层次结构图
 类