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.
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 WinHelpfile 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.
.jpeg "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
Requirements
Header: afxpropertygridctrl.h
CMFCPropertyGridCtrl::accSelect
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
CMFCPropertyGridCtrl::AddProperty
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.
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
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
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
[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);
CMFCPropertyGridCtrl::DeleteProperty
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.
CMFCPropertyGridCtrl::DrawControlBarColors
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
CMFCPropertyGridCtrl::EditItem
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
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
[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.
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
[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.
CMFCPropertyGridCtrl::EndEditItem
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
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
[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
CMFCPropertyGridCtrl::ExpandAll
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
CMFCPropertyGridCtrl::FindItemByData
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.
CMFCPropertyGridCtrl::get_accChildCount
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
CMFCPropertyGridCtrl::get_accFocus
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
CMFCPropertyGridCtrl::get_accHelp
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
CMFCPropertyGridCtrl::get_accHelpTopic
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
CMFCPropertyGridCtrl::get_accKeyboardShortcut
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
CMFCPropertyGridCtrl::get_accSelection
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
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
[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.
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 does not 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
[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
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
[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.
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
[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.
| 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
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
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 are not 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 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.
CMFCPropertyGridCtrl::MarkModifiedProperties
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
CMFCPropertyGridCtrl::OnChangeSelection
Called by the framework when the current selection is changed.
virtual void OnChangeSelection(
CMFCPropertyGridProperty* pNewSel,
CMFCPropertyGridProperty* pOldSel);
Parameters
| Parameter | Description |
|---|---|
[in] pNewSel |
Pointer to the newly selected property. |
[in] pOldSel |
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
[in] point
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
[in] pDC
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
[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.
CMFCPropertyGridCtrl::OnDrawList
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
CMFCPropertyGridCtrl::OnDrawProperty
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
CMFCPropertyGridCtrl::OnPropertyChanged
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.
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
[in] bRedraw
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
[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.
CMFCPropertyGridCtrl::SetBoolLabels
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
CMFCPropertyGridCtrl::SetCurSel
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.
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
[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.
CMFCPropertyGridCtrl::SetDescriptionRows
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.
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
[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.
CMFCPropertyGridCtrl::SetListDelimiter
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 (',').
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
[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.
CMFCPropertyGridCtrl::SetVSDotNetLook
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
CMFCPropertyGridCtrl::UpdateColor
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.
CMFCPropertyGridCtrl::ValidateItemData
Called by the framework to validate property data.
virtual BOOL ValidateItemData(CMFCPropertyGridProperty* pProp);
Parameters
| Parameter | Description |
|---|---|
[in] pProp |
Pointer 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.