Edit

Share via


CMFCPropertyGridProperty class

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.

See also

Hierarchy Chart
Classes
CMFCPropertyGridCtrl class