CMFCPropertyGridCtrl Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CMFCPropertyGridCtrl Class.

INCLUDEcpp_fp_under_construction]

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

class CMFCPropertyGridCtrl : public CWnd  

Public Constructors

NameDescription
CMFCPropertyGridCtrl::CMFCPropertyGridCtrlConstructs a CMFCPropertyGridCtrl object.
CMFCPropertyGridCtrl::~CMFCPropertyGridCtrlDestructor.

Public Methods

NameDescription
CMFCPropertyGridCtrl::accHitTestCalled by the framework to retrieve the child element or child object at a given point on the screen. (Overrides CWnd::accHitTest.)
CMFCPropertyGridCtrl::accLocationCalled by the framework to retrieve the specified object's current screen location. (Overrides CWnd::accLocation.)
CMFCPropertyGridCtrl::accSelectCalled by the framework to modify the selection or move the keyboard focus of the specified object. (Overrides CWnd::accSelect.)
CMFCPropertyGridCtrl::AddPropertyAdds a new property to a property grid control.
CMFCPropertyGridCtrl::AlwaysShowUserToolTip
CMFCPropertyGridCtrl::CloseColorPopupCloses the color selection dialog box.
CMFCPropertyGridCtrl::CreateCreates a property grid control and attaches it to the property grid control object.
CMFCPropertyGridCtrl::DeletePropertyDeletes the specified property from the property grid control.
CMFCPropertyGridCtrl::DrawControlBarColors
CMFCPropertyGridCtrl::EnableDescriptionAreaEnables or disables the description area that is displayed underneath the list of properties.
CMFCPropertyGridCtrl::EnableHeaderCtrlEnables or disables the header control at the top of the property grid control.
CMFCPropertyGridCtrl::EnsureVisibleScrolls a property grid control and expands property items until the specified property is visible.
CMFCPropertyGridCtrl::ExpandAllExpands or collapses all property grid control nodes.
CMFCPropertyGridCtrl::FindItemByDataRetrieves the property that is associated with a user-defined DWORD value.
CMFCPropertyGridCtrl::get_accChildCalled by the framework to retrieve the address of an IDispatch interface for the specified child. (Overrides CWnd::get_accChild.)
CMFCPropertyGridCtrl::get_accChildCountCalled by the framework to retrieve the number of children belonging to this object. (Overrides CWnd::get_accChildCount.)
CMFCPropertyGridCtrl::get_accDefaultActionCalled by the framework to retrieve a string that describes the object's default action. (Overrides CWnd::get_accDefaultAction.)
CMFCPropertyGridCtrl::get_accDescriptionCalled by framework to retrieve a string that describes the visual appearance of the specified object. (Overrides CWnd::get_accDescription.)
CMFCPropertyGridCtrl::get_accFocusCalled by the framework to retrieve the object that has the keyboard focus. (Overrides CWnd::get_accFocus.)
CMFCPropertyGridCtrl::get_accHelpCalled by the framework to retrieve an object's Help property string. (Overrides CWnd::get_accHelp.)
CMFCPropertyGridCtrl::get_accHelpTopicCalled by the framework to retrieve the full path of the WinHelpfile associated with the specified object and the identifier of the appropriate topic within that file. (Overrides CWnd::get_accHelpTopic.)
CMFCPropertyGridCtrl::get_accKeyboardShortcutCalled by the framework to retrieve the specified object's shortcut key or access key. (Overrides CWnd::get_accKeyboardShortcut.)
CMFCPropertyGridCtrl::get_accNameCalled by the framework to retrieve the name of the specified object. (Overrides CWnd::get_accName.)
CMFCPropertyGridCtrl::get_accRoleCalled by the framework to retrieve information that describes the role of the specified object. (Overrides CWnd::get_accRole.)
CMFCPropertyGridCtrl::get_accSelectionCalled by the framework to retrieve the selected children of this object. (Overrides CWnd::get_accSelection.)
CMFCPropertyGridCtrl::get_accStateCalled by the framework to retrieve the current state of the specified object. (Overrides CWnd::get_accState.)
CMFCPropertyGridCtrl::get_accValueCalled by the framework to retrieve the value of the specified object. (Overrides CWnd::get_accValue.)
CMFCPropertyGridCtrl::GetBkColorRetrieves the background color of the current property grid control.
CMFCPropertyGridCtrl::GetBoldFontRetrieves the Windows font that of text in the current property grid control in bold style.
CMFCPropertyGridCtrl::GetCurSelRetrieves the currently selected property.
CMFCPropertyGridCtrl::GetCustomColorsRetrieves the custom colors that are currently defined for property grid control elements.
CMFCPropertyGridCtrl::GetDescriptionHeightRetrieves the height of the description area located at the bottom of the property grid control.
CMFCPropertyGridCtrl::GetDescriptionRowsRetrieves the number of rows in the description area of the current property grid control.
CMFCPropertyGridCtrl::GetHeaderCtrlRetrieves the internal CMFCHeaderCtrl object that the framework uses to display the current property grid control.
CMFCPropertyGridCtrl::GetHeaderHeightRetrieves the height of the property grid control header.
CMFCPropertyGridCtrl::GetLeftColumnWidthRetrieves the width of the left column of the current property grid control, which contains the name of each property.
CMFCPropertyGridCtrl::GetListRectRetrieves the bounding rectangle of the property grid control.
CMFCPropertyGridCtrl::GetPropertyRetrieves a pointer to the property object that corresponds to the specified index of a property grid control item.
CMFCPropertyGridCtrl::GetPropertyColumnWidthRetrieves the current width of the column that contains property values.
CMFCPropertyGridCtrl::GetPropertyCountRetrieves the number of properties in a property grid control.
CMFCPropertyGridCtrl::GetRowHeightRetrieves the height of a row in the property grid control.
CMFCPropertyGridCtrl::GetScrollBarCtrlRetrieves a pointer to the scroll bar control in the property grid control. (Overrides CWnd::GetScrollBarCtrl.)
CMFCPropertyGridCtrl::GetTextColorRetrieves the color of the text of property items in the current property grid control.
CMFCPropertyGridCtrl::GetThisClassUsed by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type.
CMFCPropertyGridCtrl::HitTestRetrieves 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::InitHeaderInitializes the internal CMFCHeaderCtrl object that the framework uses to display the current property grid control.
CMFCPropertyGridCtrl::IsAlphabeticModeIndicates whether a property grid control is in alphabetic mode.
CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip
CMFCPropertyGridCtrl::IsDescriptionAreaIndicates whether the description area of the property grid control is displayed.
CMFCPropertyGridCtrl::IsGroupNameFullWidthIndicates whether each property group name is displayed across the width of the current property grid control.
CMFCPropertyGridCtrl::IsHeaderCtrlIndicates whether the header control is displayed.
CMFCPropertyGridCtrl::IsMarkModifiedPropertiesIndicates how the property grid control displays modified properties.
CMFCPropertyGridCtrl::IsShowDragContextIndicates whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.
CMFCPropertyGridCtrl::IsVSDotNetLookIndicates whether the appearance of the property grid control is in the style that is used by VS .NET.
CMFCPropertyGridCtrl::MarkModifiedPropertiesSpecifies how to display modified properties.
CMFCPropertyGridCtrl::PreTranslateMessageUsed by class CWinApp to translate window messages before they are dispatched to the TranslateMessage and DispatchMessage Windows functions. (Overrides CWnd::PreTranslateMessage.)
CMFCPropertyGridCtrl::RemoveAllRemoves all property objects from a property grid control.
CMFCPropertyGridCtrl::ResetOriginalValuesRestores the original value of all properties.
CMFCPropertyGridCtrl::SetAlphabeticModeSets or resets alphabetical mode.
CMFCPropertyGridCtrl::SetBoolLabelsSpecifies the text of Boolean labels.
CMFCPropertyGridCtrl::SetCurSelSelects a property in a property grid control.
CMFCPropertyGridCtrl::SetCustomColorsSpecifies custom colors for various property grid control elements.
CMFCPropertyGridCtrl::SetDescriptionRowsSpecifies the number of rows to display in the description section of the current property grid control.
CMFCPropertyGridCtrl::SetGroupNameFullWidthSpecifies whether to display the full width of the category name for a group of properties in the current property grid control.
CMFCPropertyGridCtrl::SetListDelimiterDefines a character that will be used as a delimiter in a list of property values.
CMFCPropertyGridCtrl::SetShowDragContextSpecifies whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.
CMFCPropertyGridCtrl::SetVSDotNetLookSets the appearance of the property grid control to the style that is used in VS .NET.
CMFCPropertyGridCtrl::UpdateColorSets the color value of the currently selected color property.

Protected Methods

NameDescription
CMFCPropertyGridCtrl::AdjustLayoutRedraws the property grid control and its properties.
CMFCPropertyGridCtrl::ComparePropsCalled by the property grid control to sort properties.
CMFCPropertyGridCtrl::EditItemCalled by the framework when the user starts to modify a property.
CMFCPropertyGridCtrl::EndEditItemCalled by the framework when the user stops modifying a property.
CMFCPropertyGridCtrl::InitCalled by the framework to initialize a property grid control.
CMFCPropertyGridCtrl::OnChangeSelectionCalled by the framework when the current selection is changed.
CMFCPropertyGridCtrl::OnClickButtonCalled by the framework when a property button is clicked.
CMFCPropertyGridCtrl::OnDrawBorderCalled by the framework to draw a border around a property grid control.
CMFCPropertyGridCtrl::OnDrawDescriptionCalled by the framework to draw the description area and display the description text.
CMFCPropertyGridCtrl::OnDrawListCalled by the framework to display the list of properties in the property grid control.
CMFCPropertyGridCtrl::OnDrawPropertyCalled by the framework to display a property.
CMFCPropertyGridCtrl::OnPropertyChangedCalled by the framework when the value of a property is changed.
CMFCPropertyGridCtrl::OnSelectComboCalled by the framework when a property that contains a combo box control is selected.
CMFCPropertyGridCtrl::ValidateItemDataCalled by the framework to validate property data.

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.

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:

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

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

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

CObject

CCmdTarget

CWnd

CMFCPropertyGridCtrl

Header: afxpropertygridctrl.h

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual HRESULT accSelect(
    long flagsSelect,  
    VARIANT varChild);

Parameters

[in] flagsSelect
[in] varChild

Return Value

Remarks

Adds a new property to a property grid control.

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

Parameters

[in] pProp
Pointer to a property.

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

[in] bAdjustLayout
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. Do not destroy the properties or allow them to go out of scope before the grid control is destroyed. When you are 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.

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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

void AlwaysShowUserToolTip(BOOL bShow = TRUE);

Parameters

[in] bShow

Remarks

Closes the color selection dialog box.

virtual void CloseColorPopup();

Remarks

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

Constructs a CMFCPropertyGridCtrl object.

CMFCPropertyGridCtrl();

Return Value

Remarks

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 ValueDescription
< 0The name of the pProp1 parameter is less than the name of the pProp2 parameter.
0The name of the pProp1 parameter is equal to the name of the pProp2 parameter.
> 0The 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.

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

[in] dwStyle
A bitwise combination (OR) of window styles.

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

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

[in] nID
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);

Deletes the specified property from the property grid control.

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

Parameters

[in] pProp
Pointer to a property.

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

[in] bAdjustLayout
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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

BOOL DrawControlBarColors() const;  

Return Value

Remarks

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

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

Parameters

[in] pProp
Pointer to a property.

[in] lptClick
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

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

[in] bEnable
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.

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

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

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

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

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

virtual BOOL EndEditItem(BOOL bUpdateData=TRUE);

Parameters

[in] bUpdateData
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 is not valid or if the editing operation should continue.

Remarks

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

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

Parameters

[in] pProp
Pointer to a property.

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

Remarks

Expands or collapses all property grid control nodes.

void ExpandAll(BOOL bExpand=TRUE);

Parameters

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

Remarks

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

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

Parameters

[in] dwData
A DWORD value.

[in] bSearchSubItems
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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual HRESULT get_accChildCount(long* pcountChildren);

Parameters

[in] pcountChildren

Return Value

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual HRESULT get_accFocus(VARIANT* pvarChild);

Parameters

[in] pvarChild

Return Value

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

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

Parameters

[in] varChild
[in] pszHelp

Return Value

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

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

Parameters

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

Return Value

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

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

Parameters

[in] varChild
[in] pszKeyboardShortcut

Return Value

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual HRESULT get_accSelection(VARIANT* pvarChildren);

Parameters

[in] pvarChildren

Return Value

Remarks

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.

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.

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

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

[out] clrBackground
The background color of property values.

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

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

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

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

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

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

Remarks

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

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.

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.

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.

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

int GetHeaderHeight() const;  

Return Value

The height of the header, in pixels.

Remarks

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.

Retrieves the bounding rectangle of the property grid control.

CRect GetListRect() const;  

Return Value

The bounding rectangle of the property grid control. This rectange does not include the description area and header.

Remarks

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

[in] nIndex
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

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.

Retrieves the number of properties in a property grid control.

int GetPropertyCount() const;  

Return Value

The number of properties.

Remarks

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.

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

virtual CScrollBar* GetScrollBarCtrl(int nBar) const;  

Parameters

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

Return Value

A pointer to a scroll bar object, or NULL if there is 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.

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.

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

[in] pt
A point, in client coordinates.

[in, out] pnArea
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.

[in] bPropsOnly
TRUE to test only the property area; FALSE to test the description area if the specified point is not 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 is not 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 click 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.

ValueArea
ClickArea::ClickExpandBoxProperty expand box control.
ClickArea::ClickNameProperty name.
ClickArea::ClickValueProperty value.
CMFCPropertyGridProperty::ClickDescriptionProperty grid control description area.

Called by the framework to initialize a property grid control.

virtual void Init();

Remarks

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

virtual void InitHeader();

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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

BOOL IsAlwaysShowUserToolTip() const;  

Return Value

Remarks

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.

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.

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.

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

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 are not redrawn until the drag operation is completed.

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

BOOL IsVSDotNetLook() const;  

Return Value

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

Remarks

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

Specifies how to display modified properties.

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

Parameters

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

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

Remarks

Called by the framework when the current selection is changed.

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

Parameters

ParameterDescription
[in] pNewSelPointer to the newly selected property.
[in] pOldSelPointer to the previously selected property.

Remarks

The default implementation of this method does nothing.

Called by the framework when a property button is clicked.

virtual void OnClickButton(CPoint point);

Parameters

[in] point
A point, in client coordinates.

Remarks

By default, this method updates the current property value.

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

virtual void OnDrawBorder(CDC* pDC);

Parameters

[in] pDC
A pointer to a device context.

Remarks

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

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

Parameters

[in] pDC
A pointer to a device context.

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

Remarks

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

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

virtual void OnDrawList(CDC* pDC);

Parameters

[in] pDC
A pointer to a device context.

Remarks

Called by the framework to display a property.

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

Parameters

[in] pDC
A pointer to a device context.

[in] pProp
A pointer to a property object.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

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

virtual void OnPropertyChanged(CMFCPropertyGridProperty* pProp) const;  

Parameters

[in] pProp
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.

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

void OnSelectCombo();

Remarks

Removes all property objects from a property grid control.

void RemoveAll();

Remarks

Restores the original values of all properties.

void ResetOriginalValues(BOOL bRedraw=TRUE);

Parameters

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

Remarks

Sets or resets alphabetic mode.

void SetAlphabeticMode(BOOL bSet=TRUE);

Parameters

[in] bSet
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.

Specifies the text of Boolean labels.

void SetBoolLabels(
    LPCTSTR lpszTrue,  
    LPCTSTR lpszFalse);

Parameters

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

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

Remarks

Selects a property in a property grid control.

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

Parameters

[in] pProp
A pointer to a property object.

[in] bRedraw
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.

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

[in] clrBackground
The background color of property values.

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

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

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

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

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

[in] clrLine
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.

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

void SetDescriptionRows(int nDescRows);

Parameters

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

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

[in] bGroupNameFullWidth
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.

[in] bRedraw
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.

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

void SetListDelimiter(TCHAR c);

Parameters

[in] c
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 (',').

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

[in] bShowDragContext
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 are not redrawn until the drag operation is completed.

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

void SetVSDotNetLook(BOOL bSet=TRUE);

Parameters

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

Remarks

Sets the color value of the currently selected color property.

virtual void UpdateColor(COLORREF color);

Parameters

[in] color
An RGB color value.

Remarks

This method asserts in debug mode if the currently selected property of the property grid control is not a color property.

Called by the framework to validate property data.

virtual BOOL ValidateItemData(CMFCPropertyGridProperty* pProp);

Parameters

ParameterDescription
[in] pPropPointer to a property. This parameter is not used.

Return Value

Always TRUE.

Remarks

The CMFCPropertyGridCtrl::EndEditItem method calls this method to validate data. By default, this method does not 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 does not update the property.

Hierarchy Chart
Classes

Show: