CMFCPropertyGridCtrl Class

Artikkeli
02/15/2022

For more detail see the source code located in the mfc folder of your Visual Studio installation. For example, %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc.

Supports an editable property grid control that can display properties in alphabetical or hierarchical order.

Syntax

class CMFCPropertyGridCtrl : public CWnd

Members

Public Constructors

Name	Description
`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`	Constructs a `CMFCPropertyGridCtrl` object.
`CMFCPropertyGridCtrl::~CMFCPropertyGridCtrl`	Destructor.

Public Methods

Name	Description
`CMFCPropertyGridCtrl::accHitTest`	Called by the framework to retrieve the child element or child object at a given point on the screen. (Overrides `CWnd::accHitTest`.)
`CMFCPropertyGridCtrl::accLocation`	Called by the framework to retrieve the specified object's current screen location. (Overrides `CWnd::accLocation`.)
`CMFCPropertyGridCtrl::accSelect`	Called by the framework to modify the selection or move the keyboard focus of the specified object. (Overrides `CWnd::accSelect`.)
`CMFCPropertyGridCtrl::AddProperty`	Adds a new property to a property grid control.
`CMFCPropertyGridCtrl::AlwaysShowUserToolTip`
`CMFCPropertyGridCtrl::CloseColorPopup`	Closes the color selection dialog box.
`CMFCPropertyGridCtrl::Create`	Creates a property grid control and attaches it to the property grid control object.
`CMFCPropertyGridCtrl::DeleteProperty`	Deletes the specified property from the property grid control.
`CMFCPropertyGridCtrl::DrawControlBarColors`
`CMFCPropertyGridCtrl::EnableDescriptionArea`	Enables or disables the description area that is displayed underneath the list of properties.
`CMFCPropertyGridCtrl::EnableHeaderCtrl`	Enables or disables the header control at the top of the property grid control.
`CMFCPropertyGridCtrl::EnsureVisible`	Scrolls a property grid control and expands property items until the specified property is visible.
`CMFCPropertyGridCtrl::ExpandAll`	Expands or collapses all property grid control nodes.
`CMFCPropertyGridCtrl::FindItemByData`	Retrieves the property that is associated with a user-defined `DWORD` value.
`CMFCPropertyGridCtrl::get_accChild`	Called by the framework to retrieve the address of an `IDispatch` interface for the specified child. (Overrides `CWnd::get_accChild`.)
`CMFCPropertyGridCtrl::get_accChildCount`	Called by the framework to retrieve the number of children belonging to this object. (Overrides `CWnd::get_accChildCount`.)
`CMFCPropertyGridCtrl::get_accDefaultAction`	Called by the framework to retrieve a string that describes the object's default action. (Overrides `CWnd::get_accDefaultAction`.)
`CMFCPropertyGridCtrl::get_accDescription`	Called by framework to retrieve a string that describes the visual appearance of the specified object. (Overrides `CWnd::get_accDescription`.)
`CMFCPropertyGridCtrl::get_accFocus`	Called by the framework to retrieve the object that has the keyboard focus. (Overrides `CWnd::get_accFocus`.)
`CMFCPropertyGridCtrl::get_accHelp`	Called by the framework to retrieve an object's `Help` property string. (Overrides `CWnd::get_accHelp`.)
`CMFCPropertyGridCtrl::get_accHelpTopic`	Called by the framework to retrieve the full path of the `WinHelp` file associated with the specified object and the identifier of the appropriate topic within that file. (Overrides `CWnd::get_accHelpTopic`.)
`CMFCPropertyGridCtrl::get_accKeyboardShortcut`	Called by the framework to retrieve the specified object's shortcut key or access key. (Overrides `CWnd::get_accKeyboardShortcut`.)
`CMFCPropertyGridCtrl::get_accName`	Called by the framework to retrieve the name of the specified object. (Overrides `CWnd::get_accName`.)
`CMFCPropertyGridCtrl::get_accRole`	Called by the framework to retrieve information that describes the role of the specified object. (Overrides `CWnd::get_accRole`.)
`CMFCPropertyGridCtrl::get_accSelection`	Called by the framework to retrieve the selected children of this object. (Overrides `CWnd::get_accSelection`.)
`CMFCPropertyGridCtrl::get_accState`	Called by the framework to retrieve the current state of the specified object. (Overrides `CWnd::get_accState`.)
`CMFCPropertyGridCtrl::get_accValue`	Called by the framework to retrieve the value of the specified object. (Overrides `CWnd::get_accValue`.)
`CMFCPropertyGridCtrl::GetBkColor`	Retrieves the background color of the current property grid control.
`CMFCPropertyGridCtrl::GetBoldFont`	Retrieves the Windows font that of text in the current property grid control in bold style.
`CMFCPropertyGridCtrl::GetCurSel`	Retrieves the currently selected property.
`CMFCPropertyGridCtrl::GetCustomColors`	Retrieves the custom colors that are currently defined for property grid control elements.
`CMFCPropertyGridCtrl::GetDescriptionHeight`	Retrieves the height of the description area located at the bottom of the property grid control.
`CMFCPropertyGridCtrl::GetDescriptionRows`	Retrieves the number of rows in the description area of the current property grid control.
`CMFCPropertyGridCtrl::GetHeaderCtrl`	Retrieves the internal `CMFCHeaderCtrl` object that the framework uses to display the current property grid control.
`CMFCPropertyGridCtrl::GetHeaderHeight`	Retrieves the height of the property grid control header.
`CMFCPropertyGridCtrl::GetLeftColumnWidth`	Retrieves the width of the left column of the current property grid control, which contains the name of each property.
`CMFCPropertyGridCtrl::GetListRect`	Retrieves the bounding rectangle of the property grid control.
`CMFCPropertyGridCtrl::GetProperty`	Retrieves a pointer to the property object that corresponds to the specified index of a property grid control item.
`CMFCPropertyGridCtrl::GetPropertyColumnWidth`	Retrieves the current width of the column that contains property values.
`CMFCPropertyGridCtrl::GetPropertyCount`	Retrieves the number of properties in a property grid control.
`CMFCPropertyGridCtrl::GetRowHeight`	Retrieves the height of a row in the property grid control.
`CMFCPropertyGridCtrl::GetScrollBarCtrl`	Retrieves a pointer to the scroll bar control in the property grid control. (Overrides `CWnd::GetScrollBarCtrl`.)
`CMFCPropertyGridCtrl::GetTextColor`	Retrieves the color of the text of property items in the current property grid control.
`CMFCPropertyGridCtrl::GetThisClass`	Used by the framework to obtain a pointer to the `CRuntimeClass` object that is associated with this class type.
`CMFCPropertyGridCtrl::HitTest`	Retrieves a pointer to the property object that corresponds to a property grid control item if a specified point is in the item. This method also indicates the area in the property grid control that contains the point.
`CMFCPropertyGridCtrl::InitHeader`	Initializes the internal `CMFCHeaderCtrl` object that the framework uses to display the current property grid control.
`CMFCPropertyGridCtrl::IsAlphabeticMode`	Indicates whether a property grid control is in alphabetic mode.
`CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip`
`CMFCPropertyGridCtrl::IsDescriptionArea`	Indicates whether the description area of the property grid control is displayed.
`CMFCPropertyGridCtrl::IsGroupNameFullWidth`	Indicates whether each property group name is displayed across the width of the current property grid control.
`CMFCPropertyGridCtrl::IsHeaderCtrl`	Indicates whether the header control is displayed.
`CMFCPropertyGridCtrl::IsMarkModifiedProperties`	Indicates how the property grid control displays modified properties.
`CMFCPropertyGridCtrl::IsShowDragContext`	Indicates whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.
`CMFCPropertyGridCtrl::IsVSDotNetLook`	Indicates whether the appearance of the property grid control is in the style that is used by VS .NET.
`CMFCPropertyGridCtrl::MarkModifiedProperties`	Specifies how to display modified properties.
`CMFCPropertyGridCtrl::PreTranslateMessage`	Used by class `CWinApp` to translate window messages before they are dispatched to the `TranslateMessage` and `DispatchMessage` Windows functions. (Overrides `CWnd::PreTranslateMessage`.)
`CMFCPropertyGridCtrl::RemoveAll`	Removes all property objects from a property grid control.
`CMFCPropertyGridCtrl::ResetOriginalValues`	Restores the original value of all properties.
`CMFCPropertyGridCtrl::SetAlphabeticMode`	Sets or resets alphabetical mode.
`CMFCPropertyGridCtrl::SetBoolLabels`	Specifies the text of Boolean labels.
`CMFCPropertyGridCtrl::SetCurSel`	Selects a property in a property grid control.
`CMFCPropertyGridCtrl::SetCustomColors`	Specifies custom colors for various property grid control elements.
`CMFCPropertyGridCtrl::SetDescriptionRows`	Specifies the number of rows to display in the description section of the current property grid control.
`CMFCPropertyGridCtrl::SetGroupNameFullWidth`	Specifies whether to display the full width of the category name for a group of properties in the current property grid control.
`CMFCPropertyGridCtrl::SetListDelimiter`	Defines a character that will be used as a delimiter in a list of property values.
`CMFCPropertyGridCtrl::SetShowDragContext`	Specifies whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.
`CMFCPropertyGridCtrl::SetVSDotNetLook`	Sets the appearance of the property grid control to the style that is used in VS .NET.
`CMFCPropertyGridCtrl::UpdateColor`	Sets the color value of the currently selected color property.

Protected Methods

Name	Description
`CMFCPropertyGridCtrl::AdjustLayout`	Redraws the property grid control and its properties.
`CMFCPropertyGridCtrl::CompareProps`	Called by the property grid control to sort properties.
`CMFCPropertyGridCtrl::EditItem`	Called by the framework when the user starts to modify a property.
`CMFCPropertyGridCtrl::EndEditItem`	Called by the framework when the user stops modifying a property.
`CMFCPropertyGridCtrl::Init`	Called by the framework to initialize a property grid control.
`CMFCPropertyGridCtrl::OnChangeSelection`	Called by the framework when the current selection is changed.
`CMFCPropertyGridCtrl::OnClickButton`	Called by the framework when a property button is clicked.
`CMFCPropertyGridCtrl::OnDrawBorder`	Called by the framework to draw a border around a property grid control.
`CMFCPropertyGridCtrl::OnDrawDescription`	Called by the framework to draw the description area and display the description text.
`CMFCPropertyGridCtrl::OnDrawList`	Called by the framework to display the list of properties in the property grid control.
`CMFCPropertyGridCtrl::OnDrawProperty`	Called by the framework to display a property.
`CMFCPropertyGridCtrl::OnPropertyChanged`	Called by the framework when the value of a property is changed.
`CMFCPropertyGridCtrl::OnSelectCombo`	Called by the framework when a property that contains a combo box control is selected.
`CMFCPropertyGridCtrl::ValidateItemData`	Called by the framework to validate property data.

Remarks

The CMFCPropertyGridCtrl class displays a property grid control that contains editable properties derived from the CMFCPropertyGridProperty class. Each property can represent a type and it can contain subitems. The property grid control supports a resizable area at the bottom that can display the description of a selected property.

To use a property grid control, construct a CMFCPropertyGridCtrl object and then call the CMFCPropertyGridCtrl::Create method. Use the CMFCPropertyGridCtrl::AddProperty method to add properties to the list.

Selection Properties

Instead of representing a value, a property item can start a dialog box that enables the user to select a color, file, or font.

The following table lists four selection property types:

Class	Description
`CMFCPropertyGridProperty` Class	A general purpose property that is used to specify the value of strings, Booleans, dates and so on.
`CMFCPropertyGridColorProperty` Class	A property that is used to select a color value.
`CMFCPropertyGridFileProperty` Class	A property that is used to select a file.
`CMFCPropertyGridFontProperty` Class	A property that is used to select a font.

Illustrations

The following illustrations depict a property grid control that displays properties in two ways. The first illustration displays properties hierarchically and the second displays properties alphabetically.

Property List PropertySheet.

Example

The following example demonstrates how to configure a property grid control object by using various methods in the CMFCPropertyGridCtrl class. The example demonstrates how to enable the header control, enable the description area, and set the appearance of the property grid control. The example also shows how to set the alphabetic mode for the control whereby the control sorts all the properties it contains by their property name, and how to set the custom colors for various elements of the property grid control. This example is part of the New Controls sample.

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

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CMFCPropertyGridCtrl

Requirements

Header: afxpropertygridctrl.h

`CMFCPropertyGridCtrl::accSelect`

virtual HRESULT accSelect(
    long flagsSelect,
    VARIANT varChild);

Parameters

[in] flagsSelect
[in] varChild\

Return Value

Remarks

`CMFCPropertyGridCtrl::AddProperty`

Adds a new property to a property grid control.

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

Parameters

pProp
[in] Pointer to a property.

bRedraw
[in] TRUE to redraw the property immediately; otherwise, FALSE. The default value is TRUE.

bAdjustLayout
[in] TRUE to recalculate how to draw the text and value of the property, and then draw the property; FALSE to use existing calculations to draw the property. The default value is TRUE.

Return Value

If this method succeeds, the zero-based index of the position in the property grid control where the property is added; otherwise, -1.

Remarks

This method adds a pointer to the specified property to the end of the list of properties in the property grid control. Don't destroy the properties or allow them to go out of scope before the grid control is destroyed. When you're done with the property grid control, call CMFCPropertyGridCtrl::RemoveAll to delete all the added properties. The AddProperty method fails if the specified property has already been added to the list.

`CMFCPropertyGridCtrl::AdjustLayout`

Redraws the property grid control and its properties.

virtual void AdjustLayout();

Remarks

This method recalculates how to draw the entire property grid control and its properties, including images, fonts, and controls.

`CMFCPropertyGridCtrl::AlwaysShowUserToolTip`

void AlwaysShowUserToolTip(BOOL bShow = TRUE);

Parameters

[in] bShow\

Remarks

`CMFCPropertyGridCtrl::CloseColorPopup`

Closes the color selection dialog box.

virtual void CloseColorPopup();

Remarks

For more information about the color selection dialog box, see CMFCPropertyGridColorProperty Class.

`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`

Constructs a CMFCPropertyGridCtrl object.

CMFCPropertyGridCtrl();

Return Value

Remarks

`CMFCPropertyGridCtrl::CompareProps`

Called by the property grid control to sort properties.

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

Parameters

pProp1
A pointer to a property.

pProp2
A pointer to a property.

Return Value

Return Value	Description
< 0	The name of the `pProp1` parameter is less than the name of the `pProp2` parameter.
0	The name of the `pProp1` parameter is equal to the name of the `pProp2` parameter.
> 0	The name of the `pProp1` object is greater than the name of the `pProp2` parameter.

Remarks

By default, this method uses the CString::Compare method to compare the CMFCPropertyGridProperty::m_strName members of the specified parameters.

`CMFCPropertyGridCtrl::Create`

Creates a property grid control and attaches it to the property grid control object.

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

Parameters

dwStyle
[in] A bitwise combination "or" (|) of window styles.

rect
[in] A bounding rectangle that specifies the size and position of the window, in client coordinates of pParentWnd.

pParentWnd
[in] Pointer to the parent window. Must not be NULL.

nID
[in] The ID of the child window.

Return Value

TRUE if the window was created successfully; otherwise, FALSE.

Remarks

To create a property grid control, first call CMFCPropertyGridCtrl::CMFCPropertyGridCtrl to construct a property grid object. Then call CMFCPropertyGridCtrl::Create.

Example

The following example demonstrates how to use the Create method in CMFCPropertyGridCtrl class. This example is part of the New Controls sample.

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

Deletes the specified property from the property grid control.

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

Parameters

pProp
[in] Pointer to a property.

bRedraw
[in] TRUE to redraw the property grid control; otherwise, FALSE. The default value is TRUE.

bAdjustLayout
[in] TRUE to recalculate how to draw all the text, images, and items in the property grid control, and then draw the control; otherwise, FALSE. The default value is TRUE.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method to delete a property, and any sub-items, from the property grid control.

`CMFCPropertyGridCtrl::DrawControlBarColors`

BOOL DrawControlBarColors() const;

Return Value

Remarks

`CMFCPropertyGridCtrl::EditItem`

Called by the framework when the user starts to modify a property.

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

Parameters

pProp
[in] Pointer to a property.

lptClick
[in] The point on the property grid control that the user clicked to begin the edit operation. The point is in the client coordinates of the control. The default value is NULL.

Return Value

TRUE if method is successful; otherwise, FALSE.

Remarks

`CMFCPropertyGridCtrl::EnableDescriptionArea`

Enables or disables the description area that is displayed underneath the list of properties in the property grid control.

void EnableDescriptionArea(BOOL bEnable=TRUE);

Parameters

bEnable
[in] TRUE to enable the description area; FALSE to disable the description area. The default value is TRUE.

Remarks

The description area is displayed at the bottom of the property grid control. By default, the description area is disabled and not visible.

`CMFCPropertyGridCtrl::EnableHeaderCtrl`

Enables or disables the header control at the top of the property grid control.

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

Parameters

bEnable
[in] TRUE to enable the header control; FALSE to disable the header control. The default value is TRUE.

lpszLeftColumn
[in] The title of the left column of the header control. The default value is Property.

lpszRightColumn
[in] The title of the right column of the header control. The default value is Value.

`CMFCPropertyGridCtrl::EndEditItem`

Called by the framework when the user finishes modifying a property.

virtual BOOL EndEditItem(BOOL bUpdateData=TRUE);

Parameters

bUpdateData
[in] TRUE to specify that the modified property data must be validated when the edit operation is complete; otherwise, FALSE. The default value is TRUE.

Return Value

TRUE if the edit operation ends successfully; FALSE if the modified property data isn't valid or if the editing operation should continue.

Remarks

`CMFCPropertyGridCtrl::EnsureVisible`

Scrolls a property grid control and expands property items until the specified property is visible.

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

Parameters

pProp
[in] Pointer to a property.

bExpandParents
[in] TRUE to expand parent items to make the specified property visible; otherwise, FALSE. The default is FALSE.

Remarks

`CMFCPropertyGridCtrl::ExpandAll`

Expands or collapses all property grid control nodes.

void ExpandAll(BOOL bExpand=TRUE);

Parameters

bExpand
[in] TRUE to expand all nodes; FALSE to collapse all nodes. The default value is TRUE.

Remarks

`CMFCPropertyGridCtrl::FindItemByData`

Retrieves the property that is associated with a user-defined DWORD value.

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

Parameters

dwData
[in] A DWORD value.

bSearchSubItems
[in] TRUE to search property sub-items; otherwise, FALSE. The default value is TRUE.

Return Value

A pointer to the associated property object if this method succeeds; otherwise, NULL.

Remarks

Use the CMFCPropertyGridCtrl::CMFCPropertyGridCtrl constructor or CMFCPropertyGridProperty::SetData method to associate a DWORD with a property.

`CMFCPropertyGridCtrl::get_accChildCount`

virtual HRESULT get_accChildCount(long* pcountChildren);

Parameters

[in] pcountChildren\

Return Value

Remarks

`CMFCPropertyGridCtrl::get_accFocus`

virtual HRESULT get_accFocus(VARIANT* pvarChild);

Parameters

[in] pvarChild\

Return Value

Remarks

`CMFCPropertyGridCtrl::get_accHelp`

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

Parameters

[in] varChild
[in] pszHelp\

Return Value

Remarks

`CMFCPropertyGridCtrl::get_accHelpTopic`

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

Parameters

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

Return Value

Remarks

`CMFCPropertyGridCtrl::get_accKeyboardShortcut`

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

Parameters

[in] varChild
[in] pszKeyboardShortcut\

Return Value

Remarks

`CMFCPropertyGridCtrl::get_accSelection`

virtual HRESULT get_accSelection(VARIANT* pvarChildren);

Parameters

[in] pvarChildren\

Return Value

Remarks

`CMFCPropertyGridCtrl::GetBkColor`

Retrieves the background color of the current property grid control.

COLORREF GetBkColor() const;

Return Value

An RGB color value.

Remarks

This method retrieves the color that the framework uses to draw the background of the current property grid control. The CMFCPropertyGridCtrl::GetTextColor method retrieves the foreground color.

`CMFCPropertyGridCtrl::GetBoldFont`

Retrieves the Windows font that is used to draw text in the current property grid control in bold style.

CFont& GetBoldFont();

Return Value

A reference to a CFont object that describes the characteristics of a bold font.

`CMFCPropertyGridCtrl::GetCurSel`

Retrieves the currently selected property.

CMFCPropertyGridProperty* GetCurSel() const;

Return Value

A pointer to the property object that corresponds to the selected item in the property grid control.

Remarks

`CMFCPropertyGridCtrl::GetCustomColors`

Retrieves the custom colors that are currently defined for property grid control elements.

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

Parameters

clrBackground
[out] The background color of property values.

clrText
[out] The color of property names and property value text.

clrGroupBackground
[out] The background color of a property group.

clrGroupText
[out] The color of text in the property group.

clrDescriptionBackground
[out] The background color of the description area.

clrDescriptionText
[out] The color of text in the description area.

clrLine
[out] The color of lines that are drawn between properties.

Remarks

Use the CMFCPropertyGridCtrl::SetCustomColors method to set custom colors.

`CMFCPropertyGridCtrl::GetDescriptionHeight`

Retrieves the height of the description area, which is located at the bottom of the property grid control.

int GetDescriptionHeight() const;

Return Value

The height of the description area, in pixels.

Remarks

The height of the description area is calculated automatically and is set to 1/4 the height of the property grid control.

Use the CMFCPropertyGridCtrl::EnableDescriptionArea method to display or hide the description area. Use the CMFCPropertyGridCtrl::IsDescriptionArea method to determine whether the description area is displayed or hidden.

`CMFCPropertyGridCtrl::GetDescriptionRows`

Retrieves the number of rows in the description area of the current property grid control.

int GetDescriptionRows() const;

Return Value

The number of rows in the description area of the current property grid control.

Remarks

The CMFCPropertyGridCtrl::CMFCPropertyGridCtrl constructor initializes the description area to 3 rows.

`CMFCPropertyGridCtrl::GetHeaderCtrl`

Retrieves the internal CMFCHeaderCtrl object that the framework uses to display the current property grid control.

virtual CMFCHeaderCtrl& GetHeaderCtrl();

Return Value

A reference to a CMFCHeaderCtrl object.

`CMFCPropertyGridCtrl::GetHeaderHeight`

Retrieves the height of the header of a property grid control.

int GetHeaderHeight() const;

Return Value

The height of the header, in pixels.

Remarks

`CMFCPropertyGridCtrl::GetLeftColumnWidth`

Retrieves of the width of the left column of the current property grid control, which contains the name of each property.

int GetLeftColumnWidth() const;

Return Value

The width of the name column.

Remarks

The right column of a property grid control contains the value of each property.

`CMFCPropertyGridCtrl::GetListRect`

Retrieves the bounding rectangle of the property grid control.

CRect GetListRect() const;

Return Value

The bounding rectangle of the property grid control. This rectange doesn't include the description area and header.

Remarks

`CMFCPropertyGridCtrl::GetProperty`

Retrieves a pointer to the property object that corresponds to the specified index of an item in a property grid control.

CMFCPropertyGridProperty* GetProperty(int nIndex) const;

Parameters

nIndex
[in] The zero-based index of a property grid control item.

This method asserts if the nIndex parameter is less than zero or greater than or equal to the number of properties.

Return Value

A pointer to the property object that corresponds to the specified index if this method is successful; otherwise, NULL.

Remarks

`CMFCPropertyGridCtrl::GetPropertyColumnWidth`

Retrieves the current width of the column that contains property values.

int GetPropertyColumnWidth() const;

Return Value

The current width of the column that contains property values.

Remarks

The column on the right in the property grid control contains the property values. A customer can use the split box of the property grid control to change the width of the values column.

`CMFCPropertyGridCtrl::GetPropertyCount`

Retrieves the number of properties in a property grid control.

int GetPropertyCount() const;

Return Value

The number of properties.

Remarks

`CMFCPropertyGridCtrl::GetRowHeight`

Retrieves the height of a row in the property grid control.

int GetRowHeight() const;

Return Value

The height of a row.

Remarks

The height of a row is equal to the current font height plus 4 pixels.

`CMFCPropertyGridCtrl::GetScrollBarCtrl`

Retrieves a pointer to the scroll bar control in the property grid control.

virtual CScrollBar* GetScrollBarCtrl(int nBar) const;

Parameters

nBar
[in] The orientation of the scroll bar, which must be SB_VERT.

Return Value

A pointer to a scroll bar object, or NULL if there's no scroll bar or the scroll bar orientation is SB_HORZ.

Remarks

Use this method to gain direct access to the vertical scroll bar control.

`CMFCPropertyGridCtrl::GetTextColor`

Retrieves the color that is used to draw the text of property items in the current property grid control.

COLORREF GetTextColor() const;

Return Value

An RGB color value.

Remarks

This method retrieves the color that the framework uses to draw the foreground of the current property grid control. The CMFCPropertyGridCtrl::GetBkColor method retrieves the background color.

`CMFCPropertyGridCtrl::HitTest`

Retrieves a pointer to the property object that corresponds to a property grid control item if a specified point is in the item. This method also indicates the area in the property grid control that contains the point.

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

Parameters

pt
[in] A point, in client coordinates.

pnArea
[in, out] A pointer to a ClickArea variable. When this method returns, the variable indicates the property area that contains the specified point. For more information about a property area, see Remarks.

bPropsOnly
[in] TRUE to test only the property area; FALSE to test the description area if the specified point isn't in the property area. The default value is FALSE. For more information about the description area, see Remarks.

Return Value

If the bPropsOnly parameter is TRUE and the specified point is in a property area, the return value is a pointer to the corresponding property object. In addition, the pnArea parameter is set to the particular area that contains the specified point. Otherwise, the return value is NULL and the pnArea parameter isn't modified.

If the bPropsOnly parameter is FALSE, the return value is always NULL. However, if the specified point is in the description area, the pnArea parameter is set to CMFCPropertyGridProperty::ClickDescription.

Remarks

The term property area refers to any one of the name, value, or expand box areas of a property grid control item. The description area is the zone at the bottom of a property grid control. When you select a property grid control item, the description area displays a description of the corresponding property.

This method sets the value of the variable that the pnArea parameter points to. The following table lists the possible values and corresponding areas.

Value	Area
`ClickArea::ClickExpandBox`	Property expand box control.
`ClickArea::ClickName`	Property name.
`ClickArea::ClickValue`	Property value.
`CMFCPropertyGridProperty::ClickDescription`	Property grid control description area.

`CMFCPropertyGridCtrl::Init`

Called by the framework to initialize a property grid control.

virtual void Init();

Remarks

`CMFCPropertyGridCtrl::InitHeader`

Initializes the internal CMFCHeaderCtrl object that the framework uses to display the current property grid control.

virtual void InitHeader();

`CMFCPropertyGridCtrl::IsAlphabeticMode`

Indicates whether a property grid control is in alphabetic mode.

BOOL IsAlphabeticMode() const;

Return Value

TRUE if the property grid control is in alphabetic mode; otherwise FALSE.

Remarks

When the property grid control is in alphabetic mode, all properties are sorted alphabetically by their names. Otherwise, properties are grouped under their parent nodes.

Use the CMFCPropertyGridCtrl::SetAlphabeticMode method to enable or disable alphabetic mode.

`CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip`

BOOL IsAlwaysShowUserToolTip() const;

Return Value

Remarks

`CMFCPropertyGridCtrl::IsDescriptionArea`

Indicates whether the description area of the property grid control is displayed.

BOOL IsDescriptionArea() const;

Return Value

TRUE if the description area is displayed; otherwise, FALSE.

Remarks

Use the CMFCPropertyGridCtrl::EnableDescriptionArea method to hide or display the description area.

`CMFCPropertyGridCtrl::IsGroupNameFullWidth`

Indicates whether each property group name is displayed across the width of the current property grid control.

BOOL IsGroupNameFullWidth() const;

Return Value

TRUE if group names are displayed across the width of the property grid control; FALSE if group names are truncated by the right (value) column of the control.

Remarks

A group is a collection of related properties in a property grid control. If the control is displayed hierarchically, the group name is displayed as a category title in the row above the group.

`CMFCPropertyGridCtrl::IsHeaderCtrl`

Indicates whether the header control is displayed.

BOOL IsHeaderCtrl() const;

Return Value

TRUE if the header control is displayed; otherwise FALSE.

Remarks

Use the CMFCPropertyGridCtrl::EnableHeaderCtrl method to hide or display the header control.

`CMFCPropertyGridCtrl::IsMarkModifiedProperties`

Indicates how the property grid control displays modified properties.

BOOL IsMarkModifiedProperties() const;

Return Value

TRUE if bold style is used to display modified properties; FALSE if regular style is used to display modified properties.

Remarks

`CMFCPropertyGridCtrl::IsShowDragContext`

Indicates whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.

BOOL IsShowDragContext() const;

Return Value

TRUE if the framework redraws the name and value columns during a resize operation; FALSE if the framework redraws the columns after the drag operation is completed.

Remarks

The user can resize the name and value columns of a property grid control by dragging the split bar that is between the columns. If the drag context is displayed, the name and value columns are resized as long as the user drags the split bar. Otherwise, the split bar moves but the columns aren't redrawn until the drag operation is completed.

`CMFCPropertyGridCtrl::IsVSDotNetLook`

Indicates whether the appearance of the property grid control is in the style of Visual Studio .NET.

BOOL IsVSDotNetLook() const;

Return Value

TRUE if the property grid control is in the style of Visual Studio .NET; otherwise, FALSE.

Remarks

Use the CMFCPropertyGridCtrl::SetVSDotNetLook method to set the property grid control to the style of Visual Studio .NET.

`CMFCPropertyGridCtrl::MarkModifiedProperties`

Specifies how to display modified properties.

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

Parameters

bMark
[in] TRUE to display modified properties in bold style; FALSE to display modified properties in regular style. The default value is TRUE.

bRedraw
[in] TRUE to redraw the property grid control immediately; otherwise, FALSE. The default value is TRUE.

Remarks

`CMFCPropertyGridCtrl::OnChangeSelection`

Called by the framework when the current selection is changed.

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

Parameters

pNewSel
[in] Pointer to the newly selected property.

pOldSel
[in] Pointer to the previously selected property.

Remarks

The default implementation of this method does nothing.

`CMFCPropertyGridCtrl::OnClickButton`

Called by the framework when a property button is clicked.

virtual void OnClickButton(CPoint point);

Parameters

point
[in] A point, in client coordinates.

Remarks

By default, this method updates the current property value.

`CMFCPropertyGridCtrl::OnDrawBorder`

Called by the framework to draw a border around a property grid control.

virtual void OnDrawBorder(CDC* pDC);

Parameters

pDC
[in] A pointer to a device context.

Remarks

`CMFCPropertyGridCtrl::OnDrawDescription`

Called by the framework to draw the description area and display the description text.

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

Parameters

pDC
[in] A pointer to a device context.

rect
[in] A rectangle that specifies where to draw the description area.

Remarks

Use the CMFCPropertyGridCtrl::EnableDescriptionArea method to display the description area.

`CMFCPropertyGridCtrl::OnDrawList`

Called by the framework to display the list of properties in the property grid control.

virtual void OnDrawList(CDC* pDC);

Parameters

pDC
[in] A pointer to a device context.

Remarks

`CMFCPropertyGridCtrl::OnDrawProperty`

Called by the framework to display a property.

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

Parameters

pDC
[in] A pointer to a device context.

pProp
[in] A pointer to a property object.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

`CMFCPropertyGridCtrl::OnPropertyChanged`

Called by the framework when the value of a property is changed.

virtual void OnPropertyChanged(CMFCPropertyGridProperty* pProp) const;

Parameters

pProp
[in] A pointer to a property object whose value has changed.

Remarks

By default, this method sends the AFX_WM_PROPERTY_CHANGED message to the owner of the property grid control.

`CMFCPropertyGridCtrl::OnSelectCombo`

Called by the framework when a property that contains a combo box control is selected.

void OnSelectCombo();

Remarks

`CMFCPropertyGridCtrl::RemoveAll`

Removes all property objects from a property grid control.

void RemoveAll();

Remarks

`CMFCPropertyGridCtrl::ResetOriginalValues`

Restores the original values of all properties.

void ResetOriginalValues(BOOL bRedraw=TRUE);

Parameters

bRedraw
[in] TRUE to redraw the property list; otherwise, FALSE. The default value is TRUE.

Remarks

`CMFCPropertyGridCtrl::SetAlphabeticMode`

Sets or resets alphabetic mode.

void SetAlphabeticMode(BOOL bSet=TRUE);

Parameters

bSet
[in] TRUE to set alphabetic mode; FALSE reset alphabetic mode. The default value is TRUE.

Remarks

When the property grid control is in alphabetic mode, the control sorts all the properties it contains by their property name.

`CMFCPropertyGridCtrl::SetBoolLabels`

Specifies the text of Boolean labels.

void SetBoolLabels(
    LPCTSTR lpszTrue,
    LPCTSTR lpszFalse);

Parameters

lpszTrue
[in] The text string to display for the Boolean value of true.

lpszFalse
[in] The text string to display for the Boolean value of false.

Remarks

`CMFCPropertyGridCtrl::SetCurSel`

Selects a property in a property grid control.

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

Parameters

pProp
[in] A pointer to a property object.

bRedraw
[in] TRUE to redraw the property grid control immediately; otherwise, FALSE. The default value is TRUE.

Remarks

Use this method to cancel the selection of the current item in the property grid control and then select the item that corresponds to the specified property.

`CMFCPropertyGridCtrl::SetCustomColors`

Specifies custom colors for various elements of the property grid control.

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

Parameters

clrBackground
[in] The background color of property values.

clrText
[in] The color of property names and property value text.

clrGroupBackground
[in] The background color of a property group.

clrGroupText
[in] The new text color of property group.

clrDescriptionBackground
[in] The background color of the description area.

clrDescriptionText
[in] The color of text in the description area.

clrLine
[in] The color of lines that are drawn between properties.

Remarks

For any parameter, specify the ((COLORREF)-1) color value to use the default color for that element of the property grid control.

To customize the appearance of a specific property, derive a class from the CMFCPropertyGridProperty class and then override the CMFCPropertyGridProperty::OnDrawName, CMFCPropertyGridProperty::OnDrawValue, CMFCPropertyGridProperty::OnDrawExpandBox, and CMFCPropertyGridProperty::OnDrawButton methods.

`CMFCPropertyGridCtrl::SetDescriptionRows`

Specifies the number of rows to display in the description section of the current property grid control.

void SetDescriptionRows(int nDescRows);

Parameters

nDescRows
[in] The number of rows to display in the property description.

`CMFCPropertyGridCtrl::SetGroupNameFullWidth`

Specifies whether to display the full width of the category name for a group of properties in the current property grid control.

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

Parameters

bGroupNameFullWidth
[in] TRUE to display the complete width of the category name regardless of the width of the property name column. FALSE to limit the width of the category name to the width of the property name column. The default value is TRUE.

bRedraw
[in] TRUE to update the property grid control immediately; FALSE to update the control when the next redraw event occurs. The default value is TRUE.

Remarks

The property grid control consists of a resizable property name column and a property value column. The end of the name column is also the start of the value column. To resize the columns, drag the border between the columns.

The terms group name and category name are used interchangeably in this method. The category name is displayed on a row that heads a set of related properties and values. This method specifies whether the width of the property name column also specifies the width of the displayed category name.

`CMFCPropertyGridCtrl::SetListDelimiter`

Defines a character that is used as a delimiter in a list of property values.

void SetListDelimiter(TCHAR c);

Parameters

c
[in] A character to serve as a delimiter.

Remarks

Use this method to define a delimiter character in a list of property values that are used in the CMFCPropertyGridProperty::CMFCPropertyGridProperty constructor. In that constructor, set the bIsValueList parameter to TRUE.

By default, the CMFCPropertyGridCtrl::CMFCPropertyGridCtrl constructor sets the delimiter character to comma (',').

`CMFCPropertyGridCtrl::SetShowDragContext`

Specifies whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.

void SetShowDragContext(BOOL bShowDragContext = TRUE);

Parameters

bShowDragContext
[in] TRUE to redraw the name and value columns during a resize operation; FALSE to redraw the columns after the drag operation is completed. The default value is TRUE.

Remarks

`CMFCPropertyGridCtrl::SetVSDotNetLook`

Sets the appearance of the property grid control to the style that is used in Visual Studio .NET.

void SetVSDotNetLook(BOOL bSet=TRUE);

Parameters

bSet
[in] TRUE to set the property grid control to the style that is used in Visual Studio .NET; otherwise, FALSE. The default value is TRUE.

Remarks

`CMFCPropertyGridCtrl::UpdateColor`

Sets the color value of the currently selected color property.

virtual void UpdateColor(COLORREF color);

Parameters

color
[in] An RGB color value.

Remarks

This method asserts in debug mode if the currently selected property of the property grid control isn't a color property.

`CMFCPropertyGridCtrl::ValidateItemData`

Called by the framework to validate property data.

virtual BOOL ValidateItemData(CMFCPropertyGridProperty* pProp);

Parameters

pProp
[in] Pointer to a property. This parameter isn't used.

Return Value

Always TRUE.

Remarks

The CMFCPropertyGridCtrl::EndEditItem method calls this method to validate data. By default, this method doesn't use its pProp parameter and its return value is always TRUE.

If you override this method, return TRUE if the specified property data is valid. Otherwise, return FALSE, in which case the framework doesn't update the property.

Jaa

CMFCPropertyGridCtrl Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Remarks

Selection Properties

Illustrations

Example

Inheritance Hierarchy

Requirements

CMFCPropertyGridCtrl::accSelect

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::AddProperty

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::AdjustLayout

Remarks

CMFCPropertyGridCtrl::AlwaysShowUserToolTip

Parameters

Remarks

CMFCPropertyGridCtrl::CloseColorPopup

Remarks

CMFCPropertyGridCtrl::CMFCPropertyGridCtrl

Return Value

Remarks

CMFCPropertyGridCtrl::CompareProps

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::Create

Parameters

Return Value

Remarks

Example

CMFCPropertyGridCtrl::DeleteProperty

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::DrawControlBarColors

Return Value

Remarks

CMFCPropertyGridCtrl::EditItem

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::EnableDescriptionArea

Parameters

Remarks

CMFCPropertyGridCtrl::EnableHeaderCtrl

Parameters

CMFCPropertyGridCtrl::EndEditItem

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::EnsureVisible

Parameters

Remarks

CMFCPropertyGridCtrl::ExpandAll

Parameters

Remarks

CMFCPropertyGridCtrl::FindItemByData

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::get_accChildCount

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::get_accFocus

Parameters

Return Value

Remarks

CMFCPropertyGridCtrl::get_accHelp

Parameters

`CMFCPropertyGridCtrl::accSelect`

`CMFCPropertyGridCtrl::AddProperty`

`CMFCPropertyGridCtrl::AdjustLayout`

`CMFCPropertyGridCtrl::AlwaysShowUserToolTip`

`CMFCPropertyGridCtrl::CloseColorPopup`

`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`

`CMFCPropertyGridCtrl::CompareProps`

`CMFCPropertyGridCtrl::Create`

`CMFCPropertyGridCtrl::DeleteProperty`

`CMFCPropertyGridCtrl::DrawControlBarColors`

`CMFCPropertyGridCtrl::EditItem`

`CMFCPropertyGridCtrl::EnableDescriptionArea`

`CMFCPropertyGridCtrl::EnableHeaderCtrl`

`CMFCPropertyGridCtrl::EndEditItem`

`CMFCPropertyGridCtrl::EnsureVisible`

`CMFCPropertyGridCtrl::ExpandAll`

`CMFCPropertyGridCtrl::FindItemByData`

`CMFCPropertyGridCtrl::get_accChildCount`

`CMFCPropertyGridCtrl::get_accFocus`

`CMFCPropertyGridCtrl::get_accHelp`

`CMFCPropertyGridCtrl::get_accHelpTopic`

`CMFCPropertyGridCtrl::get_accKeyboardShortcut`

`CMFCPropertyGridCtrl::get_accSelection`

`CMFCPropertyGridCtrl::GetBkColor`

`CMFCPropertyGridCtrl::GetBoldFont`

`CMFCPropertyGridCtrl::GetCurSel`

`CMFCPropertyGridCtrl::GetCustomColors`

`CMFCPropertyGridCtrl::GetDescriptionHeight`

`CMFCPropertyGridCtrl::GetDescriptionRows`

`CMFCPropertyGridCtrl::GetHeaderCtrl`

`CMFCPropertyGridCtrl::GetHeaderHeight`

`CMFCPropertyGridCtrl::GetLeftColumnWidth`

`CMFCPropertyGridCtrl::GetListRect`

`CMFCPropertyGridCtrl::GetProperty`

`CMFCPropertyGridCtrl::GetPropertyColumnWidth`

`CMFCPropertyGridCtrl::GetPropertyCount`

`CMFCPropertyGridCtrl::GetRowHeight`

`CMFCPropertyGridCtrl::GetScrollBarCtrl`

`CMFCPropertyGridCtrl::GetTextColor`

`CMFCPropertyGridCtrl::HitTest`

`CMFCPropertyGridCtrl::Init`

`CMFCPropertyGridCtrl::InitHeader`