CMFCPropertyGridCtrl Class

Article
01/30/2013

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