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.
class CMFCPropertyGridCtrl : public CWnd
| Name | Description |
|---|---|
CMFCPropertyGridCtrl::CMFCPropertyGridCtrl |
Constructs a CMFCPropertyGridCtrl object. |
CMFCPropertyGridCtrl::~CMFCPropertyGridCtrl |
Destructor. |
| 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. |
| 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. |
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:
| 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. |
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.
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();
Header: afxpropertygridctrl.h
virtual HRESULT accSelect(
long flagsSelect,
VARIANT varChild);
[in] flagsSelect
[in] varChild\
Adds a new property to a property grid control.
int AddProperty(
CMFCPropertyGridProperty* pProp,
BOOL bRedraw=TRUE,
BOOL bAdjustLayout=TRUE);
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.
If this method succeeds, the zero-based index of the position in the property grid control where the property is added; otherwise, -1.
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.
Redraws the property grid control and its properties.
virtual void AdjustLayout();
This method recalculates how to draw the entire property grid control and its properties, including images, fonts, and controls.
void AlwaysShowUserToolTip(BOOL bShow = TRUE);
[in] bShow\
Closes the color selection dialog box.
virtual void CloseColorPopup();
For more information about the color selection dialog box, see CMFCPropertyGridColorProperty Class.
Constructs a CMFCPropertyGridCtrl object.
CMFCPropertyGridCtrl();
Called by the property grid control to sort properties.
virtual int CompareProps(
const CMFCPropertyGridProperty* pProp1,
const CMFCPropertyGridProperty* pProp2) const;
pProp1
A pointer to a property.
pProp2
A pointer to a property.
| 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. |
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);
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.
TRUE if the window was created successfully; otherwise, FALSE.
To create a property grid control, first call CMFCPropertyGridCtrl::CMFCPropertyGridCtrl to construct a property grid object. Then call CMFCPropertyGridCtrl::Create.
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);
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.
TRUE if this method is successful; otherwise, FALSE.
Use this method to delete a property, and any sub-items, from the property grid control.
BOOL DrawControlBarColors() const;
Called by the framework when the user starts to modify a property.
virtual BOOL EditItem(
CMFCPropertyGridProperty* pProp,
LPPOINT lptClick=NULL);
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.
TRUE if method is successful; otherwise, FALSE.
Enables or disables the description area that is displayed underneath the list of properties in the property grid control.
void EnableDescriptionArea(BOOL bEnable=TRUE);
bEnable
[in] TRUE to enable the description area; FALSE to disable the description area. The default value is TRUE.
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"));
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.
Called by the framework when the user finishes modifying a property.
virtual BOOL EndEditItem(BOOL bUpdateData=TRUE);
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.
TRUE if the edit operation ends successfully; FALSE if the modified property data isn't valid or if the editing operation should continue.
Scrolls a property grid control and expands property items until the specified property is visible.
void EnsureVisible(
CMFCPropertyGridProperty* pProp,
BOOL bExpandParents=FALSE);
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.
Expands or collapses all property grid control nodes.
void ExpandAll(BOOL bExpand=TRUE);
bExpand
[in] TRUE to expand all nodes; FALSE to collapse all nodes. The default value is TRUE.
Retrieves the property that is associated with a user-defined DWORD value.
CMFCPropertyGridProperty* FindItemByData(
DWORD_PTR dwData,
BOOL bSearchSubItems=TRUE) const;
dwData
[in] A DWORD value.
bSearchSubItems
[in] TRUE to search property sub-items; otherwise, FALSE. The default value is TRUE.
A pointer to the associated property object if this method succeeds; otherwise, NULL.
Use the CMFCPropertyGridCtrl::CMFCPropertyGridCtrl constructor or CMFCPropertyGridProperty::SetData method to associate a DWORD with a property.
virtual HRESULT get_accChildCount(long* pcountChildren);
[in] pcountChildren\
virtual HRESULT get_accFocus(VARIANT* pvarChild);
[in] pvarChild\
virtual HRESULT get_accHelp(
VARIANT varChild,
BSTR* pszHelp);
[in] varChild
[in] pszHelp\
virtual HRESULT get_accHelpTopic(
BSTR* pszHelpFile,
VARIANT varChild,
long* pidTopic);
[in] pszHelpFile
[in] varChild
[in] pidTopic\
virtual HRESULT get_accKeyboardShortcut(
VARIANT varChild,
BSTR* pszKeyboardShortcut);
[in] varChild
[in] pszKeyboardShortcut\
virtual HRESULT get_accSelection(VARIANT* pvarChildren);
[in] pvarChildren\
Retrieves the background color of the current property grid control.
COLORREF GetBkColor() const;
An RGB color value.
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();
A reference to a CFont object that describes the characteristics of a bold font.
Retrieves the currently selected property.
CMFCPropertyGridProperty* GetCurSel() const;
A pointer to the property object that corresponds to the selected item in the property grid control.
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);
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.
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;
The height of the description area, in pixels.
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;
The number of rows in the description area of the current property grid control.
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();
A reference to a CMFCHeaderCtrl object.
Retrieves the height of the header of a property grid control.
int GetHeaderHeight() const;
The height of the header, in pixels.
Retrieves of the width of the left column of the current property grid control, which contains the name of each property.
int GetLeftColumnWidth() const;
The width of the name column.
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;
The bounding rectangle of the property grid control. This rectange doesn't include the description area and header.
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;
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.
A pointer to the property object that corresponds to the specified index if this method is successful; otherwise, NULL.
Retrieves the current width of the column that contains property values.
int GetPropertyColumnWidth() const;
The current width of the column that contains property values.
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;
The number of properties.
Retrieves the height of a row in the property grid control.
int GetRowHeight() const;
The height of a row.
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;
nBar
[in] The orientation of the scroll bar, which must be SB_VERT.
A pointer to a scroll bar object, or NULL if there's no scroll bar or the scroll bar orientation is SB_HORZ.
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;
An RGB color value.
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;
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.
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.
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. |
Called by the framework to initialize a property grid control.
virtual void Init();
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;
TRUE if the property grid control is in alphabetic mode; otherwise FALSE.
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.
BOOL IsAlwaysShowUserToolTip() const;
Indicates whether the description area of the property grid control is displayed.
BOOL IsDescriptionArea() const;
TRUE if the description area is displayed; otherwise, FALSE.
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;
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.
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;
TRUE if the header control is displayed; otherwise FALSE.
Use the CMFCPropertyGridCtrl::EnableHeaderCtrl method to hide or display the header control.
Indicates how the property grid control displays modified properties.
BOOL IsMarkModifiedProperties() const;
TRUE if bold style is used to display modified properties; FALSE if regular style is used to display modified properties.
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;
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.
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.
Indicates whether the appearance of the property grid control is in the style of Visual Studio .NET.
BOOL IsVSDotNetLook() const;
TRUE if the property grid control is in the style of Visual Studio .NET; otherwise, FALSE.
Use the CMFCPropertyGridCtrl::SetVSDotNetLook method to set the property grid control to the style of Visual Studio .NET.
Specifies how to display modified properties.
void MarkModifiedProperties(
BOOL bMark=TRUE,
BOOL bRedraw=TRUE);
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.
Called by the framework when the current selection is changed.
virtual void OnChangeSelection(
CMFCPropertyGridProperty* pNewSel,
CMFCPropertyGridProperty* pOldSel);
pNewSel
[in] Pointer to the newly selected property.
pOldSel
[in] Pointer to the previously selected property.
The default implementation of this method does nothing.
Called by the framework when a property button is clicked.
virtual void OnClickButton(CPoint point);
point
[in] A point, in client coordinates.
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);
pDC
[in] A pointer to a device context.
Called by the framework to draw the description area and display the description text.
virtual void OnDrawDescription(
CDC* pDC,
CRect rect);
pDC
[in] A pointer to a device context.
rect
[in] A rectangle that specifies where to draw the description area.
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);
pDC
[in] A pointer to a device context.
Called by the framework to display a property.
virtual int OnDrawProperty(
CDC* pDC,
CMFCPropertyGridProperty* pProp) const;
pDC
[in] A pointer to a device context.
pProp
[in] A pointer to a property object.
TRUE if this method is successful; otherwise, FALSE.
Called by the framework when the value of a property is changed.
virtual void OnPropertyChanged(CMFCPropertyGridProperty* pProp) const;
pProp
[in] A pointer to a property object whose value has changed.
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();
Removes all property objects from a property grid control.
void RemoveAll();
Restores the original values of all properties.
void ResetOriginalValues(BOOL bRedraw=TRUE);
bRedraw
[in] TRUE to redraw the property list; otherwise, FALSE. The default value is TRUE.
Sets or resets alphabetic mode.
void SetAlphabeticMode(BOOL bSet=TRUE);
bSet
[in] TRUE to set alphabetic mode; FALSE reset alphabetic mode. The default value is TRUE.
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);
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.
Selects a property in a property grid control.
void SetCurSel(
CMFCPropertyGridProperty* pProp,
BOOL bRedraw=TRUE);
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.
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);
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.
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);
nDescRows
[in] 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);
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.
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);
c
[in] A character to serve as a delimiter.
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);
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.
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.
Sets the appearance of the property grid control to the style that is used in Visual Studio .NET.
void SetVSDotNetLook(BOOL bSet=TRUE);
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.
Sets the color value of the currently selected color property.
virtual void UpdateColor(COLORREF color);
color
[in] An RGB color value.
This method asserts in debug mode if the currently selected property of the property grid control isn't a color property.
Called by the framework to validate property data.
virtual BOOL ValidateItemData(CMFCPropertyGridProperty* pProp);
pProp
[in] Pointer to a property. This parameter isn't used.
Always TRUE.
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.