CMFCPropertyGridProperty Class

Article
12/18/2017

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

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

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 sub-properties.
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 sub-items.
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 sub-property identified by a zero-based index.
CMFCPropertyGridProperty::GetSubItemsCount	Retrieves the number of sub-items.
`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 clicks a button that is contained in a property.
CMFCPropertyGridProperty::OnClickName	Called by a parent property list control when a user clicks the name field of a property.
CMFCPropertyGridProperty::OnClickValue	Called by a parent property list control when a user clicks 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 sub-properties.
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 clicks the right mouse button in the property name area.
CMFCPropertyGridProperty::OnRClickValue	Called by the framework when the user clicks 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 sub-item.
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 sub-item 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 sub-item, 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

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

[in] bInsertUnique
TRUE to add the list item only if it does not 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 is not added because the bInsertUnique parameter is TRUE and the list item specified by the lpszOption parameter already exists.

Remarks

CMFCPropertyGridProperty::AddSubItem

Adds a child item to a property.

BOOL AddSubItem(CMFCPropertyGridProperty* pProp);

Parameters

[in] pProp
Pointer to a property to add.

Return Value

TRUE if the specified property is successfully added as a child property. FALSE if the property is not 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 clicks 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 3 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

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

[out] rectSpin
When this method returns, a rectangle that specifies the boundaries of the spin button control for the property value. Or, if the property does not 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

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

Remarks

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

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

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

[in] strName
The name of the property.

[in] varValue
The property value.

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

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

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

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

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

Remarks

CMFCPropertyGridProperty::CreateCombo

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

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

Parameters

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

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

Return Value

Pointer to a new CComboBox object.

Remarks

CMFCPropertyGridProperty::CreateInPlaceEdit

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

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

Parameters

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

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

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

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

Remarks

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

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

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

[in] nMax
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 sub-properties.

void Expand(BOOL bExpand=TRUE);

Parameters

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

Remarks

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 sub-items.

int GetExpandedSubItems(BOOL bIncludeHidden=TRUE) const;

Parameters

Parameter	Description
[in] `bIncludeHidden`	`TRUE` to include the hidden sub-items in the count; otherwise, `FALSE`. The default value is `TRUE`.

Return Value

The number of expanded sub-items.

Remarks

CMFCPropertyGridProperty::GetHierarchyLevel

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

int GetHierarchyLevel() const;

Return Value

The property's hierarchical level.

Remarks

CMFCPropertyGridProperty::GetName

Retrieves the name of the property.

LPCTSTR GetName() const;

Return Value

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

Remarks

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.

Remarks

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.

Remarks

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.

Remarks

CMFCPropertyGridProperty::GetRect

Retrieves the bounding rectangle of a property.

CRect GetRect() const;

Return Value

A CRect object that describes the bounding rectangle.

Remarks

CMFCPropertyGridProperty::GetSubItem

Retrieves a sub-property identified by a zero-based index.

CMFCPropertyGridProperty* GetSubItem(int nIndex) const;

Parameters

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

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.

Remarks

CMFCPropertyGridProperty::GetSubItemsCount

Retrieves the number of sub-items.

int GetSubItemsCount() const;

Return Value

The number of child items.

Remarks

CMFCPropertyGridProperty::GetValue

Retrieves a property value.

virtual const _variant_t& GetValue() const;

Return Value

A variant that contains the property value.

Remarks

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.

Remarks

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.

Remarks

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

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

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

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

[in] bPropsOnly
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 sub-items if the specified point is not 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();

Remarks

CMFCPropertyGridProperty::IsAllowEdit

Indicates whether a property is editable.

BOOL IsAllowEdit() const;

Return Value

TRUE if the property is editable; otherwise FALSE.

Remarks

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.

Remarks

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.

Remarks

CMFCPropertyGridProperty::IsModified

Indicates whether the current property is modified.

BOOL IsModified() const;

Return Value

TRUE if the property is modified; otherwise, FALSE.

Remarks

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.

Remarks

CMFCPropertyGridProperty::IsSelected

Indicates whether the current property is selected.

virtual BOOL IsSelected() const;

Return Value

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

Remarks

CMFCPropertyGridProperty::IsSubItem

Indicates whether the specified property is a sub-item of the current property.

BOOL IsSubItem(CMFCPropertyGridProperty* pProp) const;

Parameters

[in] pProp
A pointer to a property.

Return Value

TRUE if the specified property is a sub-item 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.

Remarks

CMFCPropertyGridProperty::IsVisible

Indicates whether the current property is visible.

BOOL IsVisible() const;

Return Value

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

Remarks

CMFCPropertyGridProperty::m_strFormatDouble

Holds a format string for a value of type double.

static CString m_strFormatDouble;

Remarks

CMFCPropertyGridProperty::m_strFormatFloat

Holds a format string for a value of type float.

static CString m_strFormatFloat;

Remarks

CMFCPropertyGridProperty::m_strFormatLong

Holds a format string for a value of type long.

static CString m_strFormatLong;

Remarks

CMFCPropertyGridProperty::m_strFormatShort

Holds a format string for a value of type short.

static CString m_strFormatShort;

Remarks

CMFCPropertyGridProperty::OnClickButton

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

virtual void OnClickButton(CPoint point);

Parameters

[in] point
A point, in client coordinates.

Remarks

By default, this method does nothing.

CMFCPropertyGridProperty::OnClickName

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

virtual void OnClickName(CPoint C);

Parameters

Parameter	Description
[in] `C`	A point, in client coordinates.

Remarks

By default, this method does nothing.

CMFCPropertyGridProperty::OnClickValue

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

virtual BOOL OnClickValue(
    UINT uiMsg,  
    CPoint point);

Parameters

[in] uiMsg
A mouse message.

[in] point
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 is not 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();

Remarks

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

[in] pDC
Pointer to a device context.

[in] nCtlColor
(This parameter is not used.)

Return Value

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

Remarks

CMFCPropertyGridProperty::OnDblClk

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

virtual BOOL OnDblClk(CPoint point);

Parameters

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

Remarks

CMFCPropertyGridProperty::OnDrawButton

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

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

Parameters

[in] pDC
A pointer to a device context.

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

Remarks

CMFCPropertyGridProperty::OnDrawDescription

Called by the framework to draw the property description.

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

Parameters

[in] pDC
A pointer to a device context.

[in] rect
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 sub-properties.

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

Parameters

[in] pDC
A pointer to a device context.

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

Remarks

Click the expand box control to expand or collapse a list of sub-properties. 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 sub-properties. 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

[in] pDC
A pointer to a device context.

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

Remarks

CMFCPropertyGridProperty::OnDrawValue

Called by the framework to display the property value.

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

Parameters

[in] pDC
A pointer to a device context.

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

Remarks

CMFCPropertyGridProperty::OnEdit

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

virtual BOOL OnEdit(LPPOINT lptClick);

Parameters

[in] lptClick
(This parameter is not 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

Parameter	Description
[in] `CWnd`	(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

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

virtual void OnKillSelection(CMFCPropertyGridProperty*);

Parameters

[in] CMFCPropertyGridProperty*

Remarks

By default, this method does nothing.

CMFCPropertyGridProperty::OnPosSizeChanged

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

virtual void OnPosSizeChanged(CRect);

Parameters

[in] CRect

Remarks

By default, this method does nothing.

CMFCPropertyGridProperty::OnRClickName

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

virtual void OnRClickName(CPoint C);

Parameters

Parameter	Description
[in] `C`	A point, in client coordinates.

Remarks

By default, this method does nothing.

CMFCPropertyGridProperty::OnRClickValue

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

virtual void OnRClickValue(
    CPoint C,  
    BOOL B);

Parameters

Parameter	Description
[in] `C`	A point, in client coordinates.
[in] `B`	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

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

virtual 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.

Remarks

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

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

Remarks

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 sub-item.

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

Parameters

[in] pProp
Pointer to a property sub-item.

[in] bDelete
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 sub-item; that is, remove the sub-item and then add it elsewhere.

CMFCPropertyGridProperty::ResetOriginalValue

Restores the original value of an edited property.

virtual void ResetOriginalValue();

Remarks

CMFCPropertyGridProperty::SetData

Associates a DWORD value with a property.

void SetData(DWORD_PTR dwData);

Parameters

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

[in] strDescr
Text that describes the current property.

Remarks

CMFCPropertyGridProperty::SetName

Sets the name of a property.

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

Parameters

[in] lpszName
The property name.

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

Remarks

CMFCPropertyGridProperty::SetOriginalValue

Sets the original value of an editable property.

virtual void SetOriginalValue(const COleVariant& varValue);

Parameters

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

[in] varValue
A reference to a value.

Remarks

CMFCPropertyGridProperty::Show

Shows or hides a property.

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

Parameters

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

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

Share via

CMFCPropertyGridProperty Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Data Members

Remarks

Example

Inheritance Hierarchy

Requirements

CMFCPropertyGridProperty::AddOption

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::AddSubItem

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::AdjustButtonRect

Remarks

CMFCPropertyGridProperty::AdjustInPlaceEditRect

Parameters

Remarks

CMFCPropertyGridProperty::AllowEdit

Parameters

Remarks

CMFCPropertyGridProperty::CMFCPropertyGridProperty

Parameters

Remarks

CMFCPropertyGridProperty::CreateCombo

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::CreateInPlaceEdit

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::CreateSpinControl

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::Enable

Parameters

Remarks

CMFCPropertyGridProperty::EnableSpinControl

Parameters

Remarks

CMFCPropertyGridProperty::Expand

Parameters

Remarks

CMFCPropertyGridProperty::FormatProperty

Return Value

Remarks

CMFCPropertyGridProperty::GetData

Return Value

Remarks

CMFCPropertyGridProperty::GetDescription

Return Value

Remarks

CMFCPropertyGridProperty::GetExpandedSubItems

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::GetHierarchyLevel

Return Value

Remarks

CMFCPropertyGridProperty::GetName

Return Value

Remarks

CMFCPropertyGridProperty::GetNameTooltip

Return Value

Remarks

CMFCPropertyGridProperty::GetOption

Parameters

Return Value

Remarks

CMFCPropertyGridProperty::GetOptionCount

Return Value