Introducing the PropertyGridControl
- 9 minutes to read
The PropertyGridControl, which is encapsulated by the PropertyGridControl class, is designed to display and edit settings of any object. Generally, the control’s functionality is similar to the functionality provided by the standard PropertyGrid control. However, it features some advanced capabilities for controlling appearance and behavior settings. These are described in this document.
Row Customization
After a Property Grid Control has been bound to an object(s), it automatically retrieves information on the available public fields from the object and creates editor rows to represent the fields. The following image shows a sample PropertyGridControl, listing the settings of a SimpleButton.
Each row in the Property Grid Control is a component. So, its settings can be accessed and customized either at design time (via the control’s Designer) or at runtime. The following image illustrates the Rows Page of the control’s Designer, showing the tree-like structure of rows that reflect the properties of the bound SimpleButton.
One of the main advantages of the Property Grid Control is the row customization feature. It allows you to change row captions, appearance settings, disable or hide rows, assign specific editors to cells, etc., by customizing row properties. Moreover, the control’s Designer enables you to easily rearrange rows as you wish, using drag and drop. For instance, you can reorder rows, move a row so it is displayed as a child of another row or move it under another category row.
To hide a row you can set its BaseRow.Visible property to false. Hidden rows are not permanently removed from the grid. They can still be accessed at runtime by end-users via the Customization Form. See the Layout Customization section below for more information on runtime customization.
Categories
In .NET an object’s properties can be related to specific categories by using the CategoryAttribute attribute. When an object is bound to a PropertyGridControl, additional category rows are created to represent categories, and all object properties are displayed under respective category rows (if a property is not related to a category it will be represented by a row under the Misc category row). The standard PropertyGrid control also supports categories in Categorized mode. However, it doesn’t allow you to access and customize category rows.
A category row in a Property Grid Control displays a name and an expand button, which can be painted using one of the two following styles: ExplorerBar and TreeView. The VGridControlBase.TreeButtonStyle property is used to specify an expand button style.
Available expand button styles are demonstrated in the following image, which displays two Property Grid Controls listing the settings of a sample bound object.
If you need to disable Categorized mode, and therefore list an object’s settings in alphabetical order, set the Property Grid Control’s BaseOptionsView.ShowRootCategories property to false. The image below demonstrates what a Property Grid Control looks like without the properties grouped by categories.
The Property Grid Control provides more control over displaying categories.
Category row customization
Like regular rows, category rows are components, and their settings can be accessed both at design time and runtime. You can change row captions, reorder, hide, remove, collapse rows, etc.
Custom categories
In specific instances, you may want to add custom categories to the PropertyGridControl. For example, you can do this if an object is implemented so its settings are not related to any categories using the CategoryAttribute attribute. You can do this at design time or runtime by creating category rows and moving regular rows under the created category rows.
Collapsing and expanding
Category rows can be collapsed or expanded via the BaseRow.Expanded property. If you collapse a specific category row at design time, it will remain collapsed when the application starts.
Appearance customization
Appearance settings of category rows can be changed via the VGridAppearanceCollection.Category property of the VGridControlBase.Appearance object. This allows you to specify the foreground and background colors, font settings, gradient mode, etc.
Data Editing
Both the VGridControl and Property Grid Control support the in-place editing feature, which allows an end-user to edit cells using various editors. By default, the in-place editor used to edit a specific cell is determined by the type of cell data. A property of any enumeration type is edited using a ComboBoxEdit control. A property of the Boolean type is also edited using a ComboBoxEdit control with the True and False options. However, if default editors don’t meet your requirements, you can assign different editors to cells (you can use any editors derived from the BaseEdit class). There are two ways to assign editors.
Assigning different default editors
As mentioned above, Boolean values are edited by default using a ComboBoxEdit control that has two options: True and False. The Property Grid Control permits you to assign different default editors to specific data types. For instance, if you want to edit Boolean values using a CheckEdit control, you need to associate the Boolean data type with a CheckEdit control. To associate editors with data types at design time, use the Default Editors Page page of the control’s Designer. To do it at runtime, use the PropertyGridControl.DefaultEditors collection. The following image shows a Property Grid Control that uses a CheckEdit control to edit Boolean values (the control is painted using the Asphalt World skin).
Assigning editors directly to rows
You can directly assign editors to rows via a row’s RowProperties.RowEdit property. The assigned editor will override the default editor.
The control’s Designer provides a handy way to assign editors to rows. See the Assigning Editors to Editor Rows topic that illustrates this task.
Please refer to the In-place Editors topic for more information on in-place editing in vertical grid controls.
Layout Customization
Like the VerticalGridControl, the Property Grid Control supports runtime layout customization. By default, an end-user can resize rows, collapse/expand category rows, or resize columns. Other customization operations are disabled and can be optionally enabled. The following table lists all the layout customization operations that are available in the PropertyGridControl, along with options that control these operations.
Operation | Control’s setting |
|---|---|
Resizing columns | VGridOptionsBehavior.ResizeHeaderPanel enables the column horizontal sizing. |
Resizing rows | The control’s VGridOptionsBehavior.ResizeRowHeaders property and the VGridOptionsRow.AllowSize options of rows. |
Drag-and-drop of rows | The control’s VGridOptionsBehavior.DragRowHeaders property and the VGridOptionsRow.AllowMove options of rows. |
Hiding/restoring rows | The Property Grid Control allows you to hide specific rows by setting their BaseRow.Visible properties to false. Hidden rows can be accessed by end-users at runtime via the Customization Form. The end-user can drag a hidden row from the Customization Form to the grid or hide currently visible rows by dragging them to the Customization Form. Drag-and-drop to/from the Customization Form is only available if the form is visible. To display the form call the VGridControlBase.RowsCustomization method. To hide the form, call the VGridControlBase.DestroyCustomization method. |
Expanding category rows | BaseOptionsView.ShowButtons displays/hides category expand buttons; VGridOptionsRow.DblClickExpanding options of rows - allow the rows to collapse/expand on a double-click event. |
Note that changes made in the layout by end-users at runtime are not automatically saved between application runs. You need to use one of the SaveLayoutTo… methods provided by the Property Grid Control to save the current layout to a data store (a stream, XML file or the system registry) and use one of the RestoreLayoutFrom… methods to restore the saved layout. See the Saving and Restoring Layout Basics topic, for more information.
In addition to the built-in layout customization support you can provide end-users with OLE drag-and-drop to and from the PropertyGridControl. See the OLE Drag and Drop Overview topic for more information.
Multi-Editor Rows
With the Property Grid Control it is possible to display multiple values within a single row. By default, when an object is bound to a control, rows are created to represent the object’s public fields, and each row contains a single value.
If you want to display multiple values that represent different fields within a row, you need to create a multi-editor row (a MultiEditorRow class object). After a multi-editor row is created, add cells that will be displayed within the row. To do this, add items to the MultiEditorRow.PropertiesCollection property. The following image illustrates a multi-editor row that displays values of the AllowDrop and AllowFocus fields.
At design time you can create a multi-editor row and add items to it using the Rows page of the control’s Designer.
For more information, see the Multi-Editor Rows document.
Appearance and Look And Feel
Like other DevExpress .NET controls, the Property Grid Control supports the Appearance and Look And Feel mechanisms.
The Look And Feel mechanism specifies the current paint scheme that determines the default color scheme and the way in which various visual elements (buttons, borders, scroll bars, etc.) are painted. There are multiple paint schemes supported by the Property Grid Control (Flat, UltraFlat, Style3D, Office2003 and WindowsXP), plus multiple skinning themes. Some of them are demonstrated below.
To specify the control’s look and feel settings, use the VGridControlBase.LookAndFeel property. For more information on the Look And Feel mechanism, please refer to the Look And Feel topic.
While the Look And Feel mechanism maintains the overall look and feel of the control, the Appearance technology allows you to customize appearance settings of the control: background and foreground colors, font settings, gradient mode, etc. Appearance settings of the Property Grid Control are grouped within the VGridControlBase.Appearance object. This provides access to multiple properties that control the appearance of the focused cell, values, category rows, lines etc.
Although you can customize appearance settings directly by changing the corresponding properties, you can also apply one of the style schemes provided by the control. Open the Style Schemes Page in the control’s Designer to see a list of available style schemes. Select the required scheme and click the Apply button. The control’s appearance settings will be immediately changed to match the selected scheme. The following images illustrate some of the available style schemes.
