CMFCPropertyGridCtrl Class

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.

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

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::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.

See also

Hierarchy Chart
Classes