CMFCPropertyGridCtrl Class

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.

Supports an editable property grid control that can display properties in alphabetical or hierarchical order.

class CMFCPropertyGridCtrl : public CWnd

Members

Public Constructors

Name

Description

CMFCPropertyGridCtrl::CMFCPropertyGridCtrl

Constructs a CMFCPropertyGridCtrl object.

CMFCPropertyGridCtrl::~CMFCPropertyGridCtrl

Destructor.

Public Methods

Name

Description

CMFCPropertyGridCtrl::accHitTest

Called by the framework to retrieve the child element or child object at a given point on the screen. (Overrides CWnd::accHitTest.)

CMFCPropertyGridCtrl::accLocation

Called by the framework to retrieve the specified object's current screen location. (Overrides CWnd::accLocation.)

CMFCPropertyGridCtrl::accSelect

Called by the framework to modify the selection or move the keyboard focus of the specified object. (Overrides CWnd::accSelect.)

CMFCPropertyGridCtrl::AddProperty

Adds a new property to a property grid control.

CMFCPropertyGridCtrl::AlwaysShowUserToolTip

 

CMFCPropertyGridCtrl::CloseColorPopup

Closes the color selection dialog box.

CMFCPropertyGridCtrl::Create

Creates a property grid control and attaches it to the property grid control object.

CMFCPropertyGridCtrl::DeleteProperty

Deletes the specified property from the property grid control.

CMFCPropertyGridCtrl::DrawControlBarColors

 

CMFCPropertyGridCtrl::EnableDescriptionArea

Enables or disables the description area that is displayed underneath the list of properties.

CMFCPropertyGridCtrl::EnableHeaderCtrl

Enables or disables the header control at the top of the property grid control.

CMFCPropertyGridCtrl::EnsureVisible

Scrolls a property grid control and expands property items until the specified property is visible.

CMFCPropertyGridCtrl::ExpandAll

Expands or collapses all property grid control nodes.

CMFCPropertyGridCtrl::FindItemByData

Retrieves the property that is associated with a user-defined DWORD value.

CMFCPropertyGridCtrl::get_accChild

Called by the framework to retrieve the address of an IDispatch interface for the specified child. (Overrides CWnd::get_accChild.)

CMFCPropertyGridCtrl::get_accChildCount

Called by the framework to retrieve the number of children belonging to this object. (Overrides CWnd::get_accChildCount.)

CMFCPropertyGridCtrl::get_accDefaultAction

Called by the framework to retrieve a string that describes the object's default action. (Overrides CWnd::get_accDefaultAction.)

CMFCPropertyGridCtrl::get_accDescription

Called by framework to retrieve a string that describes the visual appearance of the specified object. (Overrides CWnd::get_accDescription.)

CMFCPropertyGridCtrl::get_accFocus

Called by the framework to retrieve the object that has the keyboard focus. (Overrides CWnd::get_accFocus.)

CMFCPropertyGridCtrl::get_accHelp

Called by the framework to retrieve an object's Help property string. (Overrides CWnd::get_accHelp.)

CMFCPropertyGridCtrl::get_accHelpTopic

Called by the framework to retrieve the full path of the WinHelp file associated with the specified object and the identifier of the appropriate topic within that file. (Overrides CWnd::get_accHelpTopic.)

CMFCPropertyGridCtrl::get_accKeyboardShortcut

Called by the framework to retrieve the specified object's shortcut key or access key. (Overrides CWnd::get_accKeyboardShortcut.)

CMFCPropertyGridCtrl::get_accName

Called by the framework to retrieve the name of the specified object. (Overrides CWnd::get_accName.)

CMFCPropertyGridCtrl::get_accRole

Called by the framework to retrieve information that describes the role of the specified object. (Overrides CWnd::get_accRole.)

CMFCPropertyGridCtrl::get_accSelection

Called by the framework to retrieve the selected children of this object. (Overrides CWnd::get_accSelection.)

CMFCPropertyGridCtrl::get_accState

Called by the framework to retrieve the current state of the specified object. (Overrides CWnd::get_accState.)

CMFCPropertyGridCtrl::get_accValue

Called by the framework to retrieve the value of the specified object. (Overrides CWnd::get_accValue.)

CMFCPropertyGridCtrl::GetBkColor

Retrieves the background color of the current property grid control.

CMFCPropertyGridCtrl::GetBoldFont

Retrieves the Windows font that of text in the current property grid control in bold style.

CMFCPropertyGridCtrl::GetCurSel

Retrieves the currently selected property.

CMFCPropertyGridCtrl::GetCustomColors

Retrieves the custom colors that are currently defined for property grid control elements.

CMFCPropertyGridCtrl::GetDescriptionHeight

Retrieves the height of the description area located at the bottom of the property grid control.

CMFCPropertyGridCtrl::GetDescriptionRows

Retrieves the number of rows in the description area of the current property grid control.

CMFCPropertyGridCtrl::GetHeaderCtrl

Retrieves the internal CMFCHeaderCtrl object that the framework uses to display the current property grid control.

CMFCPropertyGridCtrl::GetHeaderHeight

Retrieves the height of the property grid control header.

CMFCPropertyGridCtrl::GetLeftColumnWidth

Retrieves the width of the left column of the current property grid control, which contains the name of each property.

CMFCPropertyGridCtrl::GetListRect

Retrieves the bounding rectangle of the property grid control.

CMFCPropertyGridCtrl::GetProperty

Retrieves a pointer to the property object that corresponds to the specified index of a property grid control item.

CMFCPropertyGridCtrl::GetPropertyColumnWidth

Retrieves the current width of the column that contains property values.

CMFCPropertyGridCtrl::GetPropertyCount

Retrieves the number of properties in a property grid control.

CMFCPropertyGridCtrl::GetRowHeight

Retrieves the height of a row in the property grid control.

CMFCPropertyGridCtrl::GetScrollBarCtrl

Retrieves a pointer to the scroll bar control in the property grid control. (Overrides CWnd::GetScrollBarCtrl.)

CMFCPropertyGridCtrl::GetTextColor

Retrieves the color of the text of property items in the current property grid control.

CMFCPropertyGridCtrl::GetThisClass

Used by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type.

CMFCPropertyGridCtrl::HitTest

Retrieves a pointer to the property object that corresponds to a property grid control item if a specified point is in the item. This method also indicates the area in the property grid control that contains the point.

CMFCPropertyGridCtrl::InitHeader

Initializes the internal CMFCHeaderCtrl object that the framework uses to display the current property grid control.

CMFCPropertyGridCtrl::IsAlphabeticMode

Indicates whether a property grid control is in alphabetic mode.

CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip

 

CMFCPropertyGridCtrl::IsDescriptionArea

Indicates whether the description area of the property grid control is displayed.

CMFCPropertyGridCtrl::IsGroupNameFullWidth

Indicates whether each property group name is displayed across the width of the current property grid control.

CMFCPropertyGridCtrl::IsHeaderCtrl

Indicates whether the header control is displayed.

CMFCPropertyGridCtrl::IsMarkModifiedProperties

Indicates how the property grid control displays modified properties.

CMFCPropertyGridCtrl::IsShowDragContext

Indicates whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.

CMFCPropertyGridCtrl::IsVSDotNetLook

Indicates whether the appearance of the property grid control is in the style that is used by VS .NET.

CMFCPropertyGridCtrl::MarkModifiedProperties

Specifies how to display modified properties.

CMFCPropertyGridCtrl::PreTranslateMessage

Used by class CWinApp to translate window messages before they are dispatched to the TranslateMessage and DispatchMessage Windows functions. (Overrides CWnd::PreTranslateMessage.)

CMFCPropertyGridCtrl::RemoveAll

Removes all property objects from a property grid control.

CMFCPropertyGridCtrl::ResetOriginalValues

Restores the original value of all properties.

CMFCPropertyGridCtrl::SetAlphabeticMode

Sets or resets alphabetical mode.

CMFCPropertyGridCtrl::SetBoolLabels

Specifies the text of Boolean labels.

CMFCPropertyGridCtrl::SetCurSel

Selects a property in a property grid control.

CMFCPropertyGridCtrl::SetCustomColors

Specifies custom colors for various property grid control elements.

CMFCPropertyGridCtrl::SetDescriptionRows

Specifies the number of rows to display in the description section of the current property grid control.

CMFCPropertyGridCtrl::SetGroupNameFullWidth

Specifies whether to display the full width of the category name for a group of properties in the current property grid control.

CMFCPropertyGridCtrl::SetListDelimiter

Defines a character that will be used as a delimiter in a list of property values.

CMFCPropertyGridCtrl::SetShowDragContext

Specifies whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.

CMFCPropertyGridCtrl::SetVSDotNetLook

Sets the appearance of the property grid control to the style that is used in VS .NET.

CMFCPropertyGridCtrl::UpdateColor

Sets the color value of the currently selected color property.

Protected Methods

Name

Description

CMFCPropertyGridCtrl::AdjustLayout

Redraws the property grid control and its properties.

CMFCPropertyGridCtrl::CompareProps

Called by the property grid control to sort properties.

CMFCPropertyGridCtrl::EditItem

Called by the framework when the user starts to modify a property.

CMFCPropertyGridCtrl::EndEditItem

Called by the framework when the user stops modifying a property.

CMFCPropertyGridCtrl::Init

Called by the framework to initialize a property grid control.

CMFCPropertyGridCtrl::OnChangeSelection

Called by the framework when the current selection is changed.

CMFCPropertyGridCtrl::OnClickButton

Called by the framework when a property button is clicked.

CMFCPropertyGridCtrl::OnDrawBorder

Called by the framework to draw a border around a property grid control.

CMFCPropertyGridCtrl::OnDrawDescription

Called by the framework to draw the description area and display the description text.

CMFCPropertyGridCtrl::OnDrawList

Called by the framework to display the list of properties in the property grid control.

CMFCPropertyGridCtrl::OnDrawProperty

Called by the framework to display a property.

CMFCPropertyGridCtrl::OnPropertyChanged

Called by the framework when the value of a property is changed.

CMFCPropertyGridCtrl::OnSelectCombo

Called by the framework when a property that contains a combo box control is selected.

CMFCPropertyGridCtrl::ValidateItemData

Called by the framework to validate property data.

Remarks

The CMFCPropertyGridCtrl class displays a property grid control that contains editable properties derived from the CMFCPropertyGridProperty class. Each property can represent a type and it can contain subitems. The property grid control supports a resizable area at the bottom that can display the description of a selected property.

To use a property grid control, construct a CMFCPropertyGridCtrl object and then call the CMFCPropertyGridCtrl::Create method. Use the CMFCPropertyGridCtrl::AddProperty method to add properties to the list.

Selection Properties

Instead of representing a value, a property item can start a dialog box that enables the user to select a color, file, or font.

The following table lists four selection property types:

Class

Description

CMFCPropertyGridProperty Class

A general purpose property that is used to specify the value of strings, Booleans, dates and so on.

CMFCPropertyGridColorProperty Class

A property that is used to select a color value.

CMFCPropertyGridFileProperty Class

A property that is used to select a file.

CMFCPropertyGridFontProperty Class

A property that is used to select a font.

Illustrations

The following illustrations depict a property grid control that displays properties in two ways. The first illustration displays properties hierarchically and the second displays properties alphabetically.

Property List PropertySheet

Example

The following example demonstrates how to configure a property grid control object by using various methods in the CMFCPropertyGridCtrl class. The example demonstrates how to enable the header control, enable the description area, and set the appearance of the property grid control. The example also shows how to set the alphabetic mode for the control whereby the control sorts all the properties it contains by their property name, and how to set the custom colors for various elements of the property grid control. This example is part of the New Controls sample.

    CMFCPropertyGridCtrl m_wndPropList;


...


    m_wndPropList.EnableHeaderCtrl();
    m_wndPropList.EnableDescriptionArea();
    m_wndPropList.SetVSDotNetLook(m_bDotNetLook);
    // BOOL m_bMarkChanged
    m_wndPropList.MarkModifiedProperties(m_bMarkChanged);
    // BOOL m_bPropListCategorized
    m_wndPropList.SetAlphabeticMode(!m_bPropListCategorized);
    // BOOL m_bShowDragContext
    m_wndPropList.SetShowDragContext(m_bShowDragContext);


...


    // BOOL m_bMarkSortedColumn
    m_wndList.EnableMarkSortedColumn(m_bMarkSortedColumn);


...


    // BOOL m_bPropListCustomColors
    // set custom colors for various elements of the property grid control
    if (m_bPropListCustomColors)
    {
        m_wndPropList.SetCustomColors(RGB(228, 243, 254), RGB(46, 70, 165), RGB(200, 236, 209), RGB(33, 102, 49), RGB(255, 229, 216), RGB(128, 0, 0), RGB(159, 159, 255));
    }
    else
    {
        COLORREF c = (COLORREF)-1;
        m_wndPropList.SetCustomColors(c, c, c, c, c, c, c);
    }

    m_wndPropList.RedrawWindow();


...


    // restore original values of the properties
    m_wndPropList.ResetOriginalValues();

Inheritance Hierarchy

CObject

   CCmdTarget

      CWnd

         CMFCPropertyGridCtrl

Requirements

Header: afxpropertygridctrl.h

See Also

Reference

Hierarchy Chart

Other Resources

MFC Classes