`CMFCPropertyGridProperty` class

Article
10/17/2022

A CMFCPropertyGridProperty object represents a list item in a property list control.

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.

Syntax

class CMFCPropertyGridProperty : public CObject

Members

Public Constructors

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

Public Methods

Name	Description
`CMFCPropertyGridProperty::AddOption`	Adds a new list item to a property list control.
`CMFCPropertyGridProperty::AddSubItem`	Adds a child item to a property.
`CMFCPropertyGridProperty::AdjustButtonRect`	Called by the parent property list control to tell a property to resize the bounding rectangle of an embedded button.
`CMFCPropertyGridProperty::AdjustInPlaceEditRect`	Retrieves the boundaries of the text box and optional spin button control that are used to set a property value.
`CMFCPropertyGridProperty::AllowEdit`	Makes a property either editable or read-only.
`CMFCPropertyGridProperty::CreateInPlaceEdit`	Called by the framework to create an editable control for a property.
`CMFCPropertyGridProperty::CreateSpinControl`	Called by the framework to create an editable spin button control.
`CMFCPropertyGridProperty::Enable`	Enables or disables a property.
`CMFCPropertyGridProperty::EnableSpinControl`	Enables or disables a spin button control that is used to modify a property value.
`CMFCPropertyGridProperty::Expand`	Expands or collapses a property that contains subproperties.
`CMFCPropertyGridProperty::FormatProperty`	Formats the text representation of a property value.
`CMFCPropertyGridProperty::GetData`	Retrieves a DWORD value that is associated with a property.
`CMFCPropertyGridProperty::GetDescription`	Retrieves a property description.
`CMFCPropertyGridProperty::GetExpandedSubItems`	Retrieves the number of expanded subitems.
`CMFCPropertyGridProperty::GetHierarchyLevel`	Retrieves the zero-based index of the property's hierarchy level.
`CMFCPropertyGridProperty::GetName`	Retrieves the name of the property.
`CMFCPropertyGridProperty::GetNameTooltip`	Called by the framework to display the name of the property in a tooltip.
`CMFCPropertyGridProperty::GetOption`	Retrieves the text of the option that is specified by an index.
`CMFCPropertyGridProperty::GetOptionCount`	Retrieves the number of options that belong to a property.
`CMFCPropertyGridProperty::GetOriginalValue`	Retrieves the initial value of the current property.
`CMFCPropertyGridProperty::GetParent`	Retrieves a pointer to a parent property.
`CMFCPropertyGridProperty::GetRect`	Retrieves the bounding rectangle of a property.
`CMFCPropertyGridProperty::GetSubItem`	Retrieves a subproperty identified by a zero-based index.
`CMFCPropertyGridProperty::GetSubItemsCount`	Retrieves the number of subitems.
`CMFCPropertyGridProperty::GetThisClass`	Used by the framework to obtain a pointer to the `CRuntimeClass` object that is associated with this class type.
`CMFCPropertyGridProperty::GetValue`	Retrieves a property value.
`CMFCPropertyGridProperty::GetValueTooltip`	Called by the framework to retrieve the text representation of the property value that is then displayed in a tooltip.
`CMFCPropertyGridProperty::HitTest`	Points to the property object that corresponds to the property list item that corresponds to a point.
`CMFCPropertyGridProperty::IsAllowEdit`	Indicates whether a property is editable.
`CMFCPropertyGridProperty::IsEnabled`	Indicates whether a property is enabled or disabled.
`CMFCPropertyGridProperty::IsExpanded`	Indicates whether a property is expanded or collapsed.
`CMFCPropertyGridProperty::IsGroup`	Indicates whether the current property represents a group.
`CMFCPropertyGridProperty::IsInPlaceEditing`	Indicates whether the current property is editable.
`CMFCPropertyGridProperty::IsModified`	Indicates whether the current property is modified.
`CMFCPropertyGridProperty::IsParentExpanded`	Indicates whether the parents of the current property are expanded.
`CMFCPropertyGridProperty::IsSelected`	Indicates whether the current property is selected.
`CMFCPropertyGridProperty::IsVisible`	Indicates whether the current property is visible.
`CMFCPropertyGridProperty::OnClickButton`	Called by the framework when the user selects a button that is contained in a property.
`CMFCPropertyGridProperty::OnClickName`	Called by a parent property list control when a user selects the name field of a property.
`CMFCPropertyGridProperty::OnClickValue`	Called by a parent property list control when a user selects the value field of a property.
`CMFCPropertyGridProperty::OnCloseCombo`	Called by the framework when a combo box that is contained in a property is closed.
`CMFCPropertyGridProperty::OnDblClk`	Called by the framework when the user double clicks a property.
`CMFCPropertyGridProperty::OnDrawButton`	Called by the framework to draw a button that is contained in a property.
`CMFCPropertyGridProperty::OnDrawDescription`	Called by the framework to display the property description.
`CMFCPropertyGridProperty::OnDrawExpandBox`	Called by the framework to draw an expand box control near a property that contains subproperties.
`CMFCPropertyGridProperty::OnDrawName`	Called by the framework to display the property name.
`CMFCPropertyGridProperty::OnDrawValue`	Called by the framework to display the property value.
`CMFCPropertyGridProperty::OnEdit`	Called by the framework when the user is about to modify a property value.
`CMFCPropertyGridProperty::OnEndEdit`	Called by the framework when the user is finished modifying a property value.
`CMFCPropertyGridProperty::OnKillSelection`
`CMFCPropertyGridProperty::OnPosSizeChanged`
`CMFCPropertyGridProperty::OnRClickName`	Called by the framework when the user selects the right mouse button in the property name area.
`CMFCPropertyGridProperty::OnRClickValue`	Called by the framework when the user selects the right mouse button in the property value area.
`CMFCPropertyGridProperty::OnSelectCombo`	Called by the framework when the user selects an item from the editable combo box.
`CMFCPropertyGridProperty::OnSetCursor`	Called by the framework when the mouse pointer moves to a property item.
`CMFCPropertyGridProperty::OnSetSelection`
`CMFCPropertyGridProperty::OnUpdateValue`	Called by the framework when the value of an editable property has changed.
`CMFCPropertyGridProperty::PushChar`	Called from the property list control when the property is selected and the user enters a new character.
`CMFCPropertyGridProperty::Redraw`	Redraws the property.
`CMFCPropertyGridProperty::RemoveAllOptions`	Removes all options (items) from a property.
`CMFCPropertyGridProperty::RemoveSubItem`	Removes the specified subitem.
`CMFCPropertyGridProperty::ResetOriginalValue`	Restores the original value of an edited property.
`CMFCPropertyGridProperty::SetData`	Associates a DWORD value with a property.
`CMFCPropertyGridProperty::SetDescription`	Specifies the text that describes the current property.
`CMFCPropertyGridProperty::SetName`	Sets the name of a property.
`CMFCPropertyGridProperty::SetOriginalValue`	Sets the original value of an editable property.
`CMFCPropertyGridProperty::SetValue`	Sets the value of a property grid property.
`CMFCPropertyGridProperty::Show`	Shows or hides a property.

Protected Methods

Name	Description
`CMFCPropertyGridProperty::CreateCombo`	Called by the framework to add a combo box to a property.
`CMFCPropertyGridProperty::HasButton`	Indicates whether a property contains a button.
`CMFCPropertyGridProperty::Init`	Called by the framework to initialize a property object.
`CMFCPropertyGridProperty::IsSubItem`	Indicates whether the specified property is a subitem of the current property.
`CMFCPropertyGridProperty::IsValueChanged`	Indicates whether the value of the current property has changed.
`CMFCPropertyGridProperty::OnCtlColor`	Called by the framework when it must retrieve a brush to fill the background color of a property.
`CMFCPropertyGridProperty::OnDestroyWindow`	Called by the framework when a property is destroyed or when editing is finished.
`CMFCPropertyGridProperty::OnKillFocus`	Called by the framework when the property loses the input focus.

Data Members

Name	Description
`CMFCPropertyGridProperty::m_strFormatDouble`	Format string for a value of type double.
`CMFCPropertyGridProperty::m_strFormatFloat`	Format string for a value of type float.
`CMFCPropertyGridProperty::m_strFormatLong`	Format string for a value of type long.
`CMFCPropertyGridProperty::m_strFormatShort`	Format string for a value of type short.

Remarks

Use a CMFCPropertyGridProperty object to represent a property, which you then add to a property list control. For more information, see CMFCPropertyGridCtrl Class.

A property object can represent data types such as strings, dates, and Boolean or integer values. It can contain child properties, or it can contain a control such as a combo box or a button control.

Example

The following example demonstrates how to construct a CMFCPropertyGridProperty object. The example also demonstrates how to use various methods in the CMFCPropertyGridProperty class to add an option, add a subitem, enable a property, and show a property. This example is part of the New Controls sample.

CMFCPropertyGridProperty *pGroup1 = new CMFCPropertyGridProperty(_T("Appearance"));

// construct a COleVariant object.
COleVariant var3DLook((short)VARIANT_FALSE, VT_BOOL);

pGroup1->AddSubItem(new CMFCPropertyGridProperty(_T("3D Look"), var3DLook,
                                                 _T("Specifies the dialog's font will be nonbold and controls will have a 3D border")));

CMFCPropertyGridProperty *pProp = new CMFCPropertyGridProperty(_T("Border"),
                                                               _T("Dialog Frame"), _T("One of: None, Thin, Resizable, or Dialog Frame"));
pProp->AddOption(_T("None"));
pProp->AddOption(_T("Thin"));
pProp->AddOption(_T("Resizable"));
pProp->AddOption(_T("Dialog Frame"));
pProp->AllowEdit(FALSE);

pGroup1->AddSubItem(pProp);
pGroup1->AddSubItem(new CMFCPropertyGridProperty(_T("Caption"), (COleVariant) _T("About NewControlsDemo"), _T("Specifies the text that will be displayed in the dialog's title bar")));
pGroup1->AdjustButtonRect();
pGroup1->AllowEdit();
pGroup1->Enable();
pGroup1->Show();
pGroup1->Redraw();

Inheritance Hierarchy

CObject

CMFCPropertyGridProperty

Requirements

Header: afxpropertygridctrl.h

`CMFCPropertyGridProperty::AddOption`

Adds a new list item to a property list control.

BOOL AddOption(
    LPCTSTR lpszOption,
    BOOL bInsertUnique=TRUE);

Parameters

lpszOption
[in] The list item (option) to add.

bInsertUnique
[in] TRUE to add the list item only if it doesn't already exist; otherwise, FALSE. The default value is TRUE.

Return Value

TRUE, which means that the list item is added. Otherwise, FALSE, which means that the list item isn't added because the bInsertUnique parameter is TRUE and the list item specified by the lpszOption parameter already exists.

`CMFCPropertyGridProperty::AddSubItem`

Adds a child item to a property.

BOOL AddSubItem(CMFCPropertyGridProperty* pProp);

Parameters

pProp
[in] Pointer to a property to add.

Return Value

TRUE if the specified property is successfully added as a child property. FALSE if the property isn't added because it already occurs in the parent property.

Remarks

Use this method to create a hierarchical list of parent and child properties. After a child property is added, the parent property automatically displays an expand box control that is designated by a plus sign (+). When the user selects the plus sign, the parent property expands and displays any child property items.

`CMFCPropertyGridProperty::AdjustButtonRect`

Called by the parent property list control to tell a property to resize the bounding rectangle of an embedded button.

virtual void AdjustButtonRect();

Remarks

By default, this method:

Adjusts the width of the button equal to the height of the button plus three pixels.
Moves the bounding rectangle of the button to the right edge of the property.
Shifts the button 1 pixel below the top edge of the property.

`CMFCPropertyGridProperty::AdjustInPlaceEditRect`

Retrieves the boundaries of the text box and optional spin button control that are used to set a property value.

virtual void AdjustInPlaceEditRect(
    CRect& rectEdit,
    CRect& rectSpin);

Parameters

rectEdit
[out] When this method returns, a rectangle that specifies the boundaries of the text box for the property value.

rectSpin
[out] When this method returns, a rectangle that specifies the boundaries of the spin button control for the property value. Or, if the property doesn't support a spin button, an empty rectangle.

Remarks

The value area of a property consists of a text box and possibly an option button, such as a spin button control. This method calculates the dimensions of the text box and option button and then returns those values in the specified parameters.

`CMFCPropertyGridProperty::AllowEdit`

Makes a property either editable or read-only.

void AllowEdit(BOOL bAllow=TRUE);

Parameters

bAllow
[in] TRUE to make the property editable; FALSE to make the property read-only. The default value is TRUE.

`CMFCPropertyGridProperty::CMFCPropertyGridProperty`

Constructs a CMFCPropertyGridProperty object.

CMFCPropertyGridProperty(
    const CString& strGroupName,
    DWORD_PTR dwData=0,
    BOOL bIsValueList=FALSE);

CMFCPropertyGridProperty(
    const CString& strName,
    const _variant_t& varValue,
    LPCTSTR lpszDescr=NULL,
    DWORD_PTR dwData=0,
    LPCTSTR lpszEditMask=NULL,
    LPCTSTR lpszEditTemplate=NULL,
    LPCTSTR lpszValidChars=NULL);

Parameters

strGroupName
[in] The group name. 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.

dwData
[in] Application-specific data, such as an integer or a pointer to other data that is associated with the property. The default value is 0.

strName
[in] The name of the property.

varValue
[in] The property value.

lpszDescr
[in] The property description. The default value is NULL.

lpszEditMask
[in] The edit mask, if the property is a masked edit control. The default value is NULL.

lpszEditTemplate
[in] The edit template, if the property is a masked edit control. The default value is NULL.

lpszValidChars
[in] A list of valid characters, if the property is a masked edit control. The default value is NULL.

bIsValueList
[in] TRUE if the property represents a list of values; FALSE if the property represents a single value. The default value is FALSE.

`CMFCPropertyGridProperty::CreateCombo`

Called by the framework to add a combo box to a property.

virtual CComboBox* CreateCombo(
    CWnd* pWndParent,
    CRect rect);

Parameters

pWndParent
[in] Pointer to the parent window of the combo box.

rect
[in] The bounding rectangle of the combo box.

Return Value

Pointer to a new CComboBox object.

`CMFCPropertyGridProperty::CreateInPlaceEdit`

Called by the framework to create an editable control for a property.

virtual CWnd* CreateInPlaceEdit(
    CRect rectEdit,
    BOOL& bDefaultFormat);

Parameters

rectEdit
[in] The bounding rectangle of the editable control.

bDefaultFormat
[in] TRUE to use the default property format to set the text of the editable control; otherwise, FALSE.

Return Value

A pointer to the editable control if this method succeeds; otherwise, NULL.

Remarks

This method uses the values of the varValue, lpszEditMask, lpszEditTemplate, and lpszValidChars parameters that are specified in the CMFCPropertyGridProperty class constructor. By default, this method supports the varValue variant types. This includes VT_BSTR, VT_R4, VT_R8, VT_UI1, VT_I2, VT_INT, VT_UINT, VT_I4, VT_UI2, VT_UI4, and VT_BOOL.

This method creates a CMFCMaskedEdit control if one or more of the lpszEditMask, lpszEditTemplate, or lpszValidChars parameters are specified; otherwise, it creates a CEdit control.

`CMFCPropertyGridProperty::CreateSpinControl`

Called by the framework to create an editable spin button control.

virtual CSpinButtonCtrl* CreateSpinControl(CRect rectSpin);

Parameters

rectSpin
[in] A rectangle that defines where the editable spin button control is created.

Return Value

A pointer to a new CMFCSpinButtonCtrl object that is cast as a pointer to a CSpinButtonCtrl object.

Remarks

Call the CMFCPropertyGridProperty::EnableSpinControl method to display an editable spin button control at the right edge of the property.

`CMFCPropertyGridProperty::Enable`

Enables or disables a property.

void Enable(BOOL bEnable=TRUE);

Parameters

bEnable
[in] TRUE to enable the property; FALSE to disable the property. Disabled properties don't respond to mouse or keyboard input. The default value is TRUE.

`CMFCPropertyGridProperty::EnableSpinControl`

Enables or disables a spin button control that is used to modify a property value.

void EnableSpinControl(
    BOOL bEnable=TRUE,
    int nMin=0,
    int nMax=0);

Parameters

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

nMin
[in] The minimum value of the spin button control. The default value is 0.

nMax
[in] The maximum value of the spin button control. The default value is 0.

Remarks

The framework automatically creates a spin button control when a property is about to be edited.

The property type, which is specified by the varValue parameter of the CMFCPropertyGridProperty::CMFCPropertyGridProperty constructor, must be a supported variant type. Otherwise, this method asserts in debug mode. The supported types include VT_INT, VT_UINT, VT_I2, VT_I4, VT_UI2, and VT_UI4.

`CMFCPropertyGridProperty::Expand`

Expands or collapses a property that contains subproperties.

void Expand(BOOL bExpand=TRUE);

Parameters

bExpand
[in] TRUE to expand the property; FALSE to collapse the property. The default value is TRUE.

`CMFCPropertyGridProperty::FormatProperty`

Formats the text representation of a property value.

virtual CString FormatProperty();

Return Value

The text representation of the property value.

Remarks

This method is called by the framework before the property value is displayed.

`CMFCPropertyGridProperty::GetData`

Retrieves a DWORD value that is associated with a property.

DWORD_PTR GetData() const;

Return Value

A DWORD value.

Remarks

The data that is returned is an application-specific value, such as a number or a pointer to other data. Specify the data value when you construct the property or when you call the CMFCPropertyGridProperty::SetData method.

`CMFCPropertyGridProperty::GetDescription`

Retrieves a property description.

const CString& GetDescription() const;

Return Value

A text string that contains the property description.

Remarks

Property list control also uses this method to display the description of the property.

`CMFCPropertyGridProperty::GetExpandedSubItems`

Retrieves the number of expanded subitems.

int GetExpandedSubItems(BOOL bIncludeHidden=TRUE) const;

Parameters

bIncludeHidden
[in] TRUE to include the hidden subitems in the count; otherwise, FALSE. The default value is TRUE.

Return Value

The number of expanded subitems.

`CMFCPropertyGridProperty::GetHierarchyLevel`

Retrieves the zero-based index of the property's hierarchy level.

int GetHierarchyLevel() const;

Return Value

The property's hierarchical level.

`CMFCPropertyGridProperty::GetName`

Retrieves the name of the property.

LPCTSTR GetName() const;

Return Value

Pointer to a string that contains the name of the property.

`CMFCPropertyGridProperty::GetNameTooltip`

Called by the framework to display the name of the property in a tooltip.

virtual CString GetNameTooltip();

Return Value

A string that contains the property name. By default, the return value is the empty string.

`CMFCPropertyGridProperty::GetOption`

Retrieves the text of the option that is specified by an index.

LPCTSTR GetOption(int nIndex) const;

Parameters

nIndex
The zero-based index of the property list item (option) to retrieve.

Return Value

Pointer to a string that contains the option text.

`CMFCPropertyGridProperty::GetOptionCount`

Retrieves the number of options that belong to a property.

int GetOptionCount() const;

Return Value

The number of property list items (options) that are contained in the property control.

Remarks

Call the CMFCPropertyGridProperty::AddOption method to add items to the property list. Call the CMFCPropertyGridProperty::RemoveAllOptions method to remove all items.

`CMFCPropertyGridProperty::GetOriginalValue`

Retrieves the initial value of the current property.

const COleVariant& GetOriginalValue() const;

Return Value

The original value of the current property.

Remarks

Use this method to undo the effect of an edit operation that changes the value of the current property.

The original value of the current property is set by the CMFCPropertyGridProperty::CMFCPropertyGridProperty constructor, modified by the CMFCPropertyGridProperty::SetOriginalValue method, and reset by the CMFCPropertyGridProperty::ResetOriginalValue method.

`CMFCPropertyGridProperty::GetParent`

Retrieves a pointer to a parent property.

CMFCPropertyGridProperty* GetParent() const;

Return Value

A pointer to a parent property object, or NULL for the top-level property.

`CMFCPropertyGridProperty::GetRect`

Retrieves the bounding rectangle of a property.

CRect GetRect() const;

Return Value

A CRect object that describes the bounding rectangle.

`CMFCPropertyGridProperty::GetSubItem`

Retrieves a subproperty identified by a zero-based index.

CMFCPropertyGridProperty* GetSubItem(int nIndex) const;

Parameters

nIndex
[in] The zero-based index of the property to retrieve. This parameter is invalid if it's less than zero or greater than or equal to the number of subproperties.

Return Value

A pointer to a property object that is a child item of this property.

-or-

In retail mode, NULL if the nIndex parameter is invalid. In debug mode, this method asserts.

`CMFCPropertyGridProperty::GetSubItemsCount`

Retrieves the number of subitems.

int GetSubItemsCount() const;

Return Value

The number of child items.

`CMFCPropertyGridProperty::GetValue`

Retrieves a property value.

virtual const _variant_t& GetValue() const;

Return Value

A variant that contains the property value.

`CMFCPropertyGridProperty::GetValueTooltip`

Called by the framework to retrieve the text representation of the property value that is then displayed in a tooltip.

virtual CString GetValueTooltip();

Return Value

A CString object containing the textual representation of the property value. By default, this value is the empty string.

`CMFCPropertyGridProperty::HasButton`

Indicates whether a property contains a button.

virtual BOOL HasButton() const;

Return Value

TRUE if a property contains a button (or property list); otherwise, FALSE.

`CMFCPropertyGridProperty::HitTest`

Points to the property object that corresponds to the property list item that corresponds to a point.

CMFCPropertyGridProperty* HitTest(
    CPoint point,
    CMFCPropertyGridProperty::ClickArea* pnArea=NULL);

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

Parameters

point
[in] The point to test, in client coordinates. This parameter is typically the current mouse pointer location.

pt
[in] The point to test, in client coordinates.

pnArea
[out] When this method returns, indicates the area that contains the specified point. For more information, see Remarks. The default value is NULL.

bPropsOnly
[in] TRUE to test any area in the property control; FALSE to test only the description area. The default value is FALSE.

Return Value

A pointer to a property object or NULL.

Remarks

By default, this method tests property subitems if the specified point isn't found within any of the property items.

The following table lists the values that can be returned to the pnArea parameter.

Area	Description
`ClickArea::ClickExpandBox`	The expand box control, which is designated by a plus sign (+).
`ClickArea::ClickName`	The property name.
`ClickArea::ClickValue`	The property value.

`CMFCPropertyGridProperty::Init`

Called by the framework to initialize a property object.

void Init();

`CMFCPropertyGridProperty::IsAllowEdit`

Indicates whether a property is editable.

BOOL IsAllowEdit() const;

Return Value

TRUE if the property is editable; otherwise FALSE.

`CMFCPropertyGridProperty::IsEnabled`

Indicates whether a property is enabled or disabled.

BOOL IsEnabled() const;

Return Value

TRUE if the property is enabled; FALSE if the property is disabled.

Remarks

Tells whether a property is enabled or disabled.

`CMFCPropertyGridProperty::IsExpanded`

Indicates whether a property is expanded or collapsed.

BOOL IsExpanded() const;

Return Value

TRUE if the property is expanded; FALSE if the property is collapsed.

`CMFCPropertyGridProperty::IsGroup`

Indicates whether the current property represents a group.

BOOL IsGroup() const;

Return Value

TRUE if the current property object represents a group; FALSE if the property represents a value.

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.

`CMFCPropertyGridProperty::IsInPlaceEditing`

Indicates whether the current property is editable.

BOOL IsInPlaceEditing() const;

Return Value

TRUE if the current property is editable; otherwise, FALSE.

`CMFCPropertyGridProperty::IsModified`

Indicates whether the current property is modified.

BOOL IsModified() const;

Return Value

TRUE if the property is modified; otherwise, FALSE.

`CMFCPropertyGridProperty::IsParentExpanded`

Indicates whether the parents of the current property are expanded.

BOOL IsParentExpanded() const;

Return Value

TRUE if all parents of the current property are expanded; FALSE if the parent properties are collapsed.

`CMFCPropertyGridProperty::IsSelected`

Indicates whether the current property is selected.

virtual BOOL IsSelected() const;

Return Value

TRUE if the current property is selected; otherwise, FALSE.

`CMFCPropertyGridProperty::IsSubItem`

Indicates whether the specified property is a subitem of the current property.

BOOL IsSubItem(CMFCPropertyGridProperty* pProp) const;

Parameters

pProp
[in] A pointer to a property.

Return Value

TRUE if the specified property is a subitem of the current property; otherwise, FALSE.

`CMFCPropertyGridProperty::IsValueChanged`

Indicates whether the value of the current property has changed.

virtual BOOL IsValueChanged() const;

Return Value

TRUE if the value of the current property has changed; otherwise, FALSE.

`CMFCPropertyGridProperty::IsVisible`

Indicates whether the current property is visible.

BOOL IsVisible() const;

Return Value

TRUE if the current property is visible; otherwise; FALSE.

`CMFCPropertyGridProperty::m_strFormatDouble`

Holds a format string for a value of type double.

static CString m_strFormatDouble;

`CMFCPropertyGridProperty::m_strFormatFloat`

Holds a format string for a value of type float.

static CString m_strFormatFloat;

`CMFCPropertyGridProperty::m_strFormatLong`

Holds a format string for a value of type long.

static CString m_strFormatLong;

`CMFCPropertyGridProperty::m_strFormatShort`

Holds a format string for a value of type short.

static CString m_strFormatShort;

`CMFCPropertyGridProperty::OnClickButton`

Called by the framework when the user selects a button that is contained in a property.

virtual void OnClickButton(CPoint point);

Parameters

point
[in] A point, in client coordinates.

Remarks

By default, this method does nothing.

`CMFCPropertyGridProperty::OnClickName`

Called by a parent property list control when a user selects the name field of a property.

virtual void OnClickName(CPoint C);

Parameters

C
[in] A point, in client coordinates.

Remarks

By default, this method does nothing.

`CMFCPropertyGridProperty::OnClickValue`

Called by a parent property list control when a user selects the value field of a property.

virtual BOOL OnClickValue(
    UINT uiMsg,
    CPoint point);

Parameters

uiMsg
[in] A mouse message.

point
[in] A point, in client coordinates.

Return Value

TRUE if the specified mouse message is processed by this method; otherwise, FALSE.

Remarks

By default, this method returns FALSE if the current property isn't editable. Otherwise, the edit or spin control that is associated with this property processes the specified mouse message, and then this method returns TRUE.

`CMFCPropertyGridProperty::OnCloseCombo`

Called by the framework when a combo box that is contained in a property is closed.

virtual void OnCloseCombo();

`CMFCPropertyGridProperty::OnCtlColor`

Called by the framework when it must retrieve a brush to fill the background color of a property.

virtual HBRUSH OnCtlColor(
    CDC* pDC,
    UINT nCtlColor);

Parameters

pDC
[in] Pointer to a device context.

nCtlColor
[in] (This parameter isn't used.)

Return Value

The handle to a brush if this method is successful; otherwise, NULL.

`CMFCPropertyGridProperty::OnDblClk`

Called by the framework when the user double clicks a property.

virtual BOOL OnDblClk(CPoint point);

Parameters

point
[in] A point, in client coordinates.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

By default, this method selects the next property item in the property list control.

`CMFCPropertyGridProperty::OnDestroyWindow`

Called by the framework when a property is destroyed or when editing is finished.

virtual void OnDestroyWindow();

`CMFCPropertyGridProperty::OnDrawButton`

Called by the framework to draw a button that is contained in a property.

virtual void OnDrawButton(
    CDC* pDC,
    CRect rectButton);

Parameters

pDC
[in] A pointer to a device context.

rectButton
[in] A bounding rectangle that specifies where to draw a button.

`CMFCPropertyGridProperty::OnDrawDescription`

Called by the framework to draw the property description.

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

Parameters

pDC
[in] A pointer to a device context.

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

Remarks

By default, this method draws the property name and description in the font used by the parent property list control. The property description is drawn in regular style and the property name is drawn in bold style.

`CMFCPropertyGridProperty::OnDrawExpandBox`

Called by the framework to draw an expand box control near a property that contains subproperties.

virtual void OnDrawExpandBox(
    CDC* pDC,
    CRect rectExpand);

Parameters

pDC
[in] A pointer to a device context.

rectExpand
[in] A bounding rectangle that specifies where to draw the expand box control.

Remarks

Select the expand box control to expand or collapse a list of subproperties. The expand box control is designated by a square that contains a plus (+) or minus (-) sign. A plus sign indicates that the property can be expanded to show a list of subproperties. A minus sign indicates that the list can be collapsed to show only the property.

`CMFCPropertyGridProperty::OnDrawName`

Called by the framework to display the property name.

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

Parameters

pDC
[in] A pointer to a device context.

rect
[in] A bounding rectangle that specifies where to draw the property name.

`CMFCPropertyGridProperty::OnDrawValue`

Called by the framework to display the property value.

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

Parameters

pDC
[in] A pointer to a device context.

rect
[in] A bounding rectangle that specifies where to draw the property value.

`CMFCPropertyGridProperty::OnEdit`

Called by the framework when the user is about to modify a property value.

virtual BOOL OnEdit(LPPOINT lptClick);

Parameters

lptClick
[in] (This parameter isn't used.) A pointer to a point, in client coordinates.

Return Value

TRUE if the edit operation starts successfully; otherwise, FALSE.

Remarks

This function is called by the framework when the user is about to modify a property value. By default, this method starts the appropriate editor for a combo box control or a spin control.

`CMFCPropertyGridProperty::OnEndEdit`

Called by the framework when the user is finished modifying a property value.

virtual BOOL OnEndEdit();

Return Value

This method always returns TRUE.

Remarks

By default, this method destroys the current editing control and then returns TRUE.

`CMFCPropertyGridProperty::OnKillFocus`

Called by the framework when the property loses the input focus.

virtual BOOL OnKillFocus(CWnd*);

Parameters

CWnd
[in] (Not used.) Pointer to a window.

Return Value

This method always returns TRUE.

Remarks

By default, this method does nothing and then returns TRUE. If you override this method, return TRUE if the framework can end the edit operation when the property loses the input focus.

`CMFCPropertyGridProperty::OnKillSelection`

virtual void OnKillSelection(CMFCPropertyGridProperty*);

Parameters

[in] CMFCPropertyGridProperty*\

Remarks

By default, this method does nothing.

`CMFCPropertyGridProperty::OnPosSizeChanged`

virtual void OnPosSizeChanged(CRect);

Parameters

[in] CRect\

Remarks

By default, this method does nothing.

`CMFCPropertyGridProperty::OnRClickName`

Called by the framework when the user selects the right mouse button in the property name area.

virtual void OnRClickName(CPoint C);

Parameters

C
[in] A point, in client coordinates.

Remarks

By default, this method does nothing.

`CMFCPropertyGridProperty::OnRClickValue`

Called by the framework when the user selects the right mouse button in the property value area.

virtual void OnRClickValue(
    CPoint C,
    BOOL B);

Parameters

C
[in] A point, in client coordinates.

B
[in] A Boolean.

Remarks

By default, this method does nothing and the B parameter has no predefined purpose.

`CMFCPropertyGridProperty::OnSelectCombo`

Called by the framework when the user selects an item from the editable combo box.

virtual void OnSelectCombo();

Remarks

By default, this method uses the text of the selected item to update the property value.

`CMFCPropertyGridProperty::OnSetCursor`

Called by the framework when the mouse pointer moves to a property item.

virtual BOOL OnSetCursor() const;

Return Value

TRUE if the current property is a variant type or a list of values, and this method successfully loads the insertion point (I-beam) mouse cursor; otherwise, FALSE.

Remarks

This method supports the following variant types: VT_INT, VT_I2, VT_I4, VT_UINT, VT_UI1, VT_UI2, VT_UI4, VT_R4, VT_R8, and VT_BSTR.

`CMFCPropertyGridProperty::OnSetSelection`

virtual void OnSetSelection CMFCPropertyGridProperty*);

Parameters

[in] CMFCPropertyGridProperty*\

Remarks

By default, this method does nothing.

`CMFCPropertyGridProperty::OnUpdateValue`

Called by the framework when the value of an editable property has changed.

virtual BOOL OnUpdateValue();

Return Value

TRUE if this method is successful; otherwise, FALSE.

`CMFCPropertyGridProperty::PushChar`

Called from the property list control when the property is selected and the user enters a new character.

virtual BOOL PushChar(UINT nChar);

Parameters

nChar
[in] A character.

Return Value

TRUE if the edit operation is continuing; otherwise, FALSE.

Remarks

This method supports a property that is either a list of values or one of the following variant types: VT_INT, VT_I2, VT_I4, VT_UINT, VT_UI1, VT_UI2, VT_UI4, VT_R4, VT_R8, and VT_BSTR.

`CMFCPropertyGridProperty::Redraw`

Redraws the property.

void Redraw();

`CMFCPropertyGridProperty::RemoveAllOptions`

Removes all options (items) from a property.

void RemoveAllOptions();

Remarks

Options are also known as the list items of a property list control.

`CMFCPropertyGridProperty::RemoveSubItem`

Removes the specified subitem.

BOOL RemoveSubItem(
    CMFCPropertyGridProperty*& pProp,
    BOOL bDelete=TRUE);

Parameters

pProp
[in] Pointer to a property subitem.

bDelete
[in] TRUE to delete the property object that is specified by the pProp parameter; otherwise, FALSE. The default value is TRUE.

Return Value

Remarks

Specify FALSE for the bDelete parameter if you intend to move the specified subitem; that is, remove the subitem and then add it elsewhere.

`CMFCPropertyGridProperty::ResetOriginalValue`

Restores the original value of an edited property.

virtual void ResetOriginalValue();

`CMFCPropertyGridProperty::SetData`

Associates a DWORD value with a property.

void SetData(DWORD_PTR dwData);

Parameters

dwData
[in] An application-specific 32-bit value, such as an integer or a pointer to other data.

Remarks

Use the CMFCPropertyGridProperty::GetData method to retrieve the DWORD value. Use the CMFCPropertyGridCtrl::FindItemByData method to locate the property list item that is associated with the specified DWORD value.

`CMFCPropertyGridProperty::SetDescription`

Specifies the text that describes the current property.

void SetDescription(const CString& strDescr);

Parameters

strDescr
[in] Text that describes the current property.

`CMFCPropertyGridProperty::SetName`

Sets the name of a property.

void SetName(
    LPCTSTR lpszName,
    BOOL bRedraw=TRUE);

Parameters

lpszName
[in] The property name.

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

`CMFCPropertyGridProperty::SetOriginalValue`

Sets the original value of an editable property.

virtual void SetOriginalValue(const COleVariant& varValue);

Parameters

varValue
[in] A value.

Remarks

Use the CMFCPropertyGridProperty::ResetOriginalValue method to reset the original value of an edited property.

`CMFCPropertyGridProperty::SetValue`

Sets the value of a property grid property.

virtual void SetValue(const _variant_t& varValue);

Parameters

varValue
[in] A reference to the value to set the property to.

Example: `SetValue`

void SetPropBarValue(UINT propId, const DWORD& barPropDwordValue)
{
  auto property = propertiesGridCtrlList.FindItemByData(propId);
  if (property != nullptr)
  {
    property->SetValue(static_cast<_variant_t >(barPropDwordValue == 1)); // set value to true or false depending on dword value
  }
}

`CMFCPropertyGridProperty::Show`

Shows or hides a property.

void Show(
    BOOL bShow=TRUE,
    BOOL bAdjustLayout=TRUE);

Parameters

bShow
[in] TRUE to display the current property and its subitems; FALSE to hide the current property and its subitems. The default value is TRUE.

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

CMFCPropertyGridProperty class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Data Members

Remarks

Example

Inheritance Hierarchy

Requirements

CMFCPropertyGridProperty::AddOption

Parameters

Return Value

CMFCPropertyGridProperty::AddSubItem

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::AdjustButtonRect

Remarks

CMFCPropertyGridProperty::AdjustInPlaceEditRect

Parameters

Remarks

CMFCPropertyGridProperty::AllowEdit

Parameters

CMFCPropertyGridProperty::CMFCPropertyGridProperty

Parameters

CMFCPropertyGridProperty::CreateCombo

Parameters

Return Value

CMFCPropertyGridProperty::CreateInPlaceEdit

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::CreateSpinControl

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::Enable

Parameters

CMFCPropertyGridProperty::EnableSpinControl

Parameters

Remarks

CMFCPropertyGridProperty::Expand

Parameters

CMFCPropertyGridProperty::FormatProperty

Return Value

Remarks

CMFCPropertyGridProperty::GetData

Return Value

Remarks

CMFCPropertyGridProperty::GetDescription

Return Value

Remarks

CMFCPropertyGridProperty::GetExpandedSubItems

Parameters

Return Value

CMFCPropertyGridProperty::GetHierarchyLevel

Return Value

CMFCPropertyGridProperty::GetName

Return Value

CMFCPropertyGridProperty::GetNameTooltip

Return Value

CMFCPropertyGridProperty::GetOption

Parameters

Return Value

CMFCPropertyGridProperty::GetOptionCount

Return Value

Remarks

CMFCPropertyGridProperty::GetOriginalValue

Return Value

Remarks

CMFCPropertyGridProperty::GetParent

Return Value

CMFCPropertyGridProperty::GetRect

Return Value

CMFCPropertyGridProperty::GetSubItem

Parameters

Return Value

CMFCPropertyGridProperty::GetSubItemsCount

`CMFCPropertyGridProperty` class

`CMFCPropertyGridProperty::AddOption`

`CMFCPropertyGridProperty::AddSubItem`

`CMFCPropertyGridProperty::AdjustButtonRect`

`CMFCPropertyGridProperty::AdjustInPlaceEditRect`

`CMFCPropertyGridProperty::AllowEdit`

`CMFCPropertyGridProperty::CMFCPropertyGridProperty`

`CMFCPropertyGridProperty::CreateCombo`

`CMFCPropertyGridProperty::CreateInPlaceEdit`

`CMFCPropertyGridProperty::CreateSpinControl`

`CMFCPropertyGridProperty::Enable`

`CMFCPropertyGridProperty::EnableSpinControl`

`CMFCPropertyGridProperty::Expand`

`CMFCPropertyGridProperty::FormatProperty`

`CMFCPropertyGridProperty::GetData`

`CMFCPropertyGridProperty::GetDescription`

`CMFCPropertyGridProperty::GetExpandedSubItems`

`CMFCPropertyGridProperty::GetHierarchyLevel`

`CMFCPropertyGridProperty::GetName`

`CMFCPropertyGridProperty::GetNameTooltip`

`CMFCPropertyGridProperty::GetOption`

`CMFCPropertyGridProperty::GetOptionCount`

`CMFCPropertyGridProperty::GetOriginalValue`

`CMFCPropertyGridProperty::GetParent`

`CMFCPropertyGridProperty::GetRect`

`CMFCPropertyGridProperty::GetSubItem`

`CMFCPropertyGridProperty::GetSubItemsCount`

`CMFCPropertyGridProperty::GetValue`

`CMFCPropertyGridProperty::GetValueTooltip`

`CMFCPropertyGridProperty::HasButton`

`CMFCPropertyGridProperty::HitTest`

`CMFCPropertyGridProperty::Init`

`CMFCPropertyGridProperty::IsAllowEdit`

`CMFCPropertyGridProperty::IsEnabled`

`CMFCPropertyGridProperty::IsExpanded`

`CMFCPropertyGridProperty::IsGroup`

`CMFCPropertyGridProperty::IsInPlaceEditing`

`CMFCPropertyGridProperty::IsModified`

`CMFCPropertyGridProperty::IsParentExpanded`

`CMFCPropertyGridProperty::IsSelected`

`CMFCPropertyGridProperty::IsSubItem`

`CMFCPropertyGridProperty::IsValueChanged`

`CMFCPropertyGridProperty::IsVisible`

`CMFCPropertyGridProperty::m_strFormatDouble`

`CMFCPropertyGridProperty::m_strFormatFloat`

`CMFCPropertyGridProperty::m_strFormatLong`

`CMFCPropertyGridProperty::m_strFormatShort`

`CMFCPropertyGridProperty::OnClickButton`

`CMFCPropertyGridProperty::OnClickName`

`CMFCPropertyGridProperty::OnClickValue`

`CMFCPropertyGridProperty::OnCloseCombo`

`CMFCPropertyGridProperty::OnCtlColor`

`CMFCPropertyGridProperty::OnDblClk`

`CMFCPropertyGridProperty::OnDestroyWindow`

`CMFCPropertyGridProperty::OnDrawButton`

`CMFCPropertyGridProperty::OnDrawDescription`

`CMFCPropertyGridProperty::OnDrawExpandBox`

`CMFCPropertyGridProperty::OnDrawName`