CMFCPropertyGridProperty Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

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

class CMFCPropertyGridProperty : public CObject  

Public Constructors

NameDescription
CMFCPropertyGridProperty::CMFCPropertyGridPropertyConstructs a CMFCPropertyGridProperty object.
CMFCPropertyGridProperty::~CMFCPropertyGridPropertyDestructor.

Public Methods

NameDescription
CMFCPropertyGridProperty::AddOptionAdds a new list item to a property list control.
CMFCPropertyGridProperty::AddSubItemAdds a child item to a property.
CMFCPropertyGridProperty::AdjustButtonRectCalled by the parent property list control to tell a property to resize the bounding rectangle of an embedded button.
CMFCPropertyGridProperty::AdjustInPlaceEditRectRetrieves the boundaries of the text box and optional spin button control that are used to set a property value.
CMFCPropertyGridProperty::AllowEditMakes a property either editable or read-only.
CMFCPropertyGridProperty::CreateInPlaceEditCalled by the framework to create an editable control for a property.
CMFCPropertyGridProperty::CreateSpinControlCalled by the framework to create an editable spin button control.
CMFCPropertyGridProperty::EnableEnables or disables a property.
CMFCPropertyGridProperty::EnableSpinControlEnables or disables a spin button control that is used to modify a property value.
CMFCPropertyGridProperty::ExpandExpands or collapses a property that contains sub-properties.
CMFCPropertyGridProperty::FormatPropertyFormats the text representation of a property value.
CMFCPropertyGridProperty::GetDataRetrieves a DWORD value that is associated with a property.
CMFCPropertyGridProperty::GetDescriptionRetrieves a property description.
CMFCPropertyGridProperty::GetExpandedSubItemsRetrieves the number of expanded sub-items.
CMFCPropertyGridProperty::GetHierarchyLevelRetrieves the zero-based index of the property's hierarchy level.
CMFCPropertyGridProperty::GetNameRetrieves the name of the property.
CMFCPropertyGridProperty::GetNameTooltipCalled by the framework to display the name of the property in a tooltip.
CMFCPropertyGridProperty::GetOptionRetrieves the text of the option that is specified by an index.
CMFCPropertyGridProperty::GetOptionCountRetrieves the number of options that belong to a property.
CMFCPropertyGridProperty::GetOriginalValueRetrieves the initial value of the current property.
CMFCPropertyGridProperty::GetParentRetrieves a pointer to a parent property.
CMFCPropertyGridProperty::GetRectRetrieves the bounding rectangle of a property.
CMFCPropertyGridProperty::GetSubItemRetrieves a sub-property identified by a zero-based index.
CMFCPropertyGridProperty::GetSubItemsCountRetrieves the number of sub-items.
CMFCPropertyGridProperty::GetThisClassUsed by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type.
CMFCPropertyGridProperty::GetValueRetrieves a property value.
CMFCPropertyGridProperty::GetValueTooltipCalled by the framework to retrieve the text representation of the property value that is then displayed in a tooltip.
CMFCPropertyGridProperty::HitTestPoints to the property object that corresponds to the property list item that corresponds to a point.
CMFCPropertyGridProperty::IsAllowEditIndicates whether a property is editable.
CMFCPropertyGridProperty::IsEnabledIndicates whether a property is enabled or disabled.
CMFCPropertyGridProperty::IsExpandedIndicates whether a property is expanded or collapsed.
CMFCPropertyGridProperty::IsGroupIndicates whether the current property represents a group.
CMFCPropertyGridProperty::IsInPlaceEditingIndicates whether the current property is editable.
CMFCPropertyGridProperty::IsModifiedIndicates whether the current property is modified.
CMFCPropertyGridProperty::IsParentExpandedIndicates whether the parents of the current property are expanded.
CMFCPropertyGridProperty::IsSelectedIndicates whether the current property is selected.
CMFCPropertyGridProperty::IsVisibleIndicates whether the current property is visible.
CMFCPropertyGridProperty::OnClickButtonCalled by the framework when the user clicks a button that is contained in a property.
CMFCPropertyGridProperty::OnClickNameCalled by a parent property list control when a user clicks the name field of a property.
CMFCPropertyGridProperty::OnClickValueCalled by a parent property list control when a user clicks the value field of a property.
CMFCPropertyGridProperty::OnCloseComboCalled by the framework when a combo box that is contained in a property is closed.
CMFCPropertyGridProperty::OnDblClkCalled by the framework when the user double clicks a property.
CMFCPropertyGridProperty::OnDrawButtonCalled by the framework to draw a button that is contained in a property.
CMFCPropertyGridProperty::OnDrawDescriptionCalled by the framework to display the property description.
CMFCPropertyGridProperty::OnDrawExpandBoxCalled by the framework to draw an expand box control near a property that contains sub-properties.
CMFCPropertyGridProperty::OnDrawNameCalled by the framework to display the property name.
CMFCPropertyGridProperty::OnDrawValueCalled by the framework to display the property value.
CMFCPropertyGridProperty::OnEditCalled by the framework when the user is about to modify a property value.
CMFCPropertyGridProperty::OnEndEditCalled by the framework when the user is finished modifying a property value.
CMFCPropertyGridProperty::OnKillSelection
CMFCPropertyGridProperty::OnPosSizeChanged
CMFCPropertyGridProperty::OnRClickNameCalled by the framework when the user clicks the right mouse button in the property name area.
CMFCPropertyGridProperty::OnRClickValueCalled by the framework when the user clicks the right mouse button in the property value area.
CMFCPropertyGridProperty::OnSelectComboCalled by the framework when the user selects an item from the editable combo box.
CMFCPropertyGridProperty::OnSetCursorCalled by the framework when the mouse pointer moves to a property item.
CMFCPropertyGridProperty::OnSetSelection
CMFCPropertyGridProperty::OnUpdateValueCalled by the framework when the value of an editable property has changed.
CMFCPropertyGridProperty::PushCharCalled from the property list control when the property is selected and the user enters a new character.
CMFCPropertyGridProperty::RedrawRedraws the property.
CMFCPropertyGridProperty::RemoveAllOptionsRemoves all options (items) from a property.
CMFCPropertyGridProperty::RemoveSubItemRemoves the specified sub-item.
CMFCPropertyGridProperty::ResetOriginalValueRestores the original value of an edited property.
CMFCPropertyGridProperty::SetDataAssociates a DWORD value with a property.
CMFCPropertyGridProperty::SetDescriptionSpecifies the text that describes the current property.
CMFCPropertyGridProperty::SetNameSets the name of a property.
CMFCPropertyGridProperty::SetOriginalValueSets the original value of an editable property.
CMFCPropertyGridProperty::SetValueSets the value of a property grid property.
CMFCPropertyGridProperty::ShowShows or hides a property.

Protected Methods

NameDescription
CMFCPropertyGridProperty::CreateComboCalled by the framework to add a combo box to a property.
CMFCPropertyGridProperty::HasButtonIndicates whether a property contains a button.
CMFCPropertyGridProperty::InitCalled by the framework to initialize a property object.
CMFCPropertyGridProperty::IsSubItemIndicates whether the specified property is a sub-item of the current property.
CMFCPropertyGridProperty::IsValueChangedIndicates whether the value of the current property has changed.
CMFCPropertyGridProperty::OnCtlColorCalled by the framework when it must retrieve a brush to fill the background color of a property.
CMFCPropertyGridProperty::OnDestroyWindowCalled by the framework when a property is destroyed or when editing is finished.
CMFCPropertyGridProperty::OnKillFocusCalled by the framework when the property loses the input focus.

Data Members

NameDescription
CMFCPropertyGridProperty::m_strFormatDoubleFormat string for a value of type double.
CMFCPropertyGridProperty::m_strFormatFloatFormat string for a value of type float.
CMFCPropertyGridProperty::m_strFormatLongFormat string for a value of type long.
CMFCPropertyGridProperty::m_strFormatShortFormat string for a value of type short.

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.

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();

CObject

CMFCPropertyGridProperty

Header: afxpropertygridctrl.h

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

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.

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.

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.

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

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

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

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.

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.

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

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.

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

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.

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.

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.

Retrieves the number of expanded sub-items.

int GetExpandedSubItems(BOOL bIncludeHidden=TRUE) const;

 

Parameters

ParameterDescription
[in] bIncludeHiddenTRUE 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

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

int GetHierarchyLevel() const;

 

Return Value

The property's hierarchical level.

Remarks

Retrieves the name of the property.

LPCTSTR GetName() const;

 

Return Value

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

Remarks

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

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

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.

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.

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

Retrieves the bounding rectangle of a property.

CRect GetRect() const;

 

Return Value

A CRect object that describes the bounding rectangle.

Remarks

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

Retrieves the number of sub-items.

int GetSubItemsCount() const;

 

Return Value

The number of child items.

Remarks

Retrieves a property value.

virtual const _variant_t& GetValue() const;

 

Return Value

A variant that contains the property value.

Remarks

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

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

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.

AreaDescription
ClickArea::ClickExpandBoxThe expand box control, which is designated by a plus sign (+).
ClickArea::ClickNameThe property name.
ClickArea::ClickValueThe property value.

Called by the framework to initialize a property object.

void Init();

Remarks

Indicates whether a property is editable.

BOOL IsAllowEdit() const;

 

Return Value

TRUE if the property is editable; otherwise FALSE.

Remarks

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.

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

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.

Indicates whether the current property is editable.

BOOL IsInPlaceEditing() const;

 

Return Value

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

Remarks

Indicates whether the current property is modified.

BOOL IsModified() const;

 

Return Value

TRUE if the property is modified; otherwise, FALSE.

Remarks

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

Indicates whether the current property is selected.

virtual BOOL IsSelected() const;

 

Return Value

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

Remarks

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.

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

Indicates whether the current property is visible.

BOOL IsVisible() const;

 

Return Value

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

Remarks

Holds a format string for a value of type double.

static CString m_strFormatDouble;  

Remarks

Holds a format string for a value of type float.

static CString m_strFormatFloat;  

Remarks

Holds a format string for a value of type long.

static CString m_strFormatLong;  

Remarks

Holds a format string for a value of type short.

static CString m_strFormatShort;  

Remarks

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.

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

virtual void OnClickName(CPoint C);

Parameters

ParameterDescription
[in] CA point, in client coordinates.

Remarks

By default, this method does nothing.

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.

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

virtual void OnCloseCombo();

Remarks

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

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.

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

virtual void OnDestroyWindow();

Remarks

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

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.

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.

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

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

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.

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.

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

virtual BOOL OnKillFocus(CWnd*);

Parameters

ParameterDescription
[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.

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.

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.

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

virtual void OnRClickName(CPoint C);

Parameters

ParameterDescription
[in] CA point, in client coordinates.

Remarks

By default, this method does nothing.

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

ParameterDescription
[in] CA point, in client coordinates.
[in] BA Boolean.

Remarks

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

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.

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.

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.

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

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.

Redraws the property.

void Redraw();

Remarks

Removes all options (items) from a property.

void RemoveAllOptions();

Remarks

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

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.

Restores the original value of an edited property.

virtual void ResetOriginalValue();

Remarks

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.

Specifies the text that describes the current property.

void SetDescription(const CString& strDescr);

Parameters

[in] strDescr
Text that describes the current property.

Remarks

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

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.

Sets the value of a property grid property.

virtual void SetValue(const _variant_t& varValue);

Parameters

[in] varValue
A reference to a value.

Remarks

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.

Hierarchy Chart
Classes
CMFCPropertyGridCtrl Class

Show: