Customizing the appearance

The appearance of the PropertyGrid can be customized in many ways, either globally to match your user interface, or on a Property-by-Property basis.

Global appearance

Properties arrangement

There are three ways to display Properties and this is controlled by the DisplayMode property which takes a DisplayModes enumeration:

DisplayMode	Sets or returns
Categorized	Properties are grouped into categories.
Flat	Properties are not grouped into categories and are displayed in the order set by a TypeDescriptor.
FlatSorted	Properties are not grouped into categories and are displayed in alphanumeric order.

In Categorized mode, another property called HideCategoriesMode allows to refine how certain categories are shown:

HideCategoriesModes	Sets or returns
None	No special treatment is done on categories.
HideTheRemainingCategory	When there is only one category in the grid, it can be nicer to remove it and see all Properties at the root level.
HideEmptyRootCategories	Hides empty categories.

Drawing manager

The drawing manager draws most of the PropertyGrid. This class, derived from CustomDrawManager, applies a unified look with a certain style. Typically, a predefined drawing manager is used. However, you can create and assign your own instance.

> To assign a predefined drawing manager

DrawingManager = DrawManagers.DotnetDrawManager;

> To assign a custom instance of the drawing manager

DrawManager = new MyCustomDrawManager();

Layout and appearance

Several properties enable you to modify the global layout of the PropertyGrid plus appearance options not handled by the drawing manager.

Property	Sets or returns
RightToLeft	When set to true, mirrors the layout to support right to left languages.
CommentsBackColor	Background color of Comments area.
CommentsForeColor	Text color of Comments area.
DisabledForeColor	Text color of disabled Properties (global). Each Property can still be individually customized.
GridBackColor	Background color of grid (the area behind the Properties). Each Property can still be individually customized.
GridForeColor	Text color of every string displayed in the grid (labels and values). Each Property can still be individually customized.
GridColor	Color of the vertical and horizontal lines making up the grid.
HighlightedTextColor	Text color for the currently selected Property.
ReadonlyForeColor	Text color of any read-only property (label and value). Each Property can still be individually customized.
SelectedNotFocusedBkgColor	Background color of the selected Property when the PropertyGrid does not have the focus.
CommentsHeight	Height, in pixels, of the comments area.
CommentsVisibility	Visibility status of the comments area (boolean).
ToolbarVisibility	Visibility status of the toolbar (boolean).
Toolbar	A reference on the toolbar for customization of its content.
ToolTipMode	Options for the display of tooltips: - None – none displayed. - ToolTipsOnLabels - on labels only. - ToolTipsOnValues - on values only. - ToolTipsOnValuesAndLabels - on both labels and values.
EllipsisMode	Options for the display of the ellipsis (…) indicating a truncated label or value string: - None - one displayed. - EllipsisOnLabels - on labels only. - EllipsisOnValues - on values only. - EllipsisOnValuesAndLabels - on both labels and values.
Font	Font used to display every string in the grid. Each Property can still be customized individually.
GlobalTextMargin	Margin in pixels, calculated based on the active global font. This harmonizes the spacing between lines, icons and text. You can use this value when developing custom drawing managers or inplace controls.
LabelColumnWidth	Returns the width, in pixels, of the column containing the labels.
LabelColumnWidthRatio	The ratio between the label and value columns (0.0 to 1.0).
LeftColumnWidth	Width, in pixels, of the first column that hosts the +/- glyphs of the root categories.
PropertyVerticalMargin	Width, in pixels, of the margin applied above and below Property label and value texts.
ReadOnlyVisual	Options for the behavior of read-only Properties: - ReadOnlyFeel: A textbox is displayed when the Property is active. Clipboard operation is enabled. - Disabled: Like disabled Properties. No inplace control is shown.
ShowDefaultValues	When set to true, the value part will be displayed in bold font when the underlying value is different from the one supplied by a DefaultValue attribute or if an existing ShouldSerialize method for this property says so.
ShowAdditionalIndentation	When set to true, displays Property indentations as MSPG does (except for the first level whose +/- glyphs won’t appear in the left most column).

> Best fitting

Two methods make some parts of the grid fit the text inside:

Method	Description
AdjustLabelColumn	Resizes the label column to adjust itself to the longest label.
AdjustComments	Resizes the comments area to adjust itself to the help text of the currently selected property. A boolean argument indicates if the selected property should be made visible (by a call to EnsureVisible).

Disabled state

SPG - unlike MSPG - has many options controlling the way the grid is disabled.

To disable the grid, use the following code:

Enabled = false;
myGrid.DisableMode = PropertyGrid.DisableModes. ...;

DisableModes are exclusive and are listed below:

Mode	Description
None	Temporarily ignores having Enabled set to False.
Simple	Default mode. The whole grid is manageable, but all the textboxes are read-only. Clipboard operation is enabled.
NoValueSelection	Like Simple, except inplace controls are never shown and Clipboard operation is disabled.
NoPropertySelection	Like NoValueSelection except that no Property can be selected. Nodes can be expanded and collapsed, and the grid scrolled.
Full	Nothing is selectable, and nothing operates. Like a disabled MSPG.

Additionally the DisableModeGrayedOut property, when set to true, ensures that all strings are grayed out. It can be paired with any of the above modes.

At last, the columns and the comments area can be locked to prevent the user to resize them:

myGrid.CommentsLock = true;
myGrid.ColumnsLock = true;

Label and value appearance

Property Class properties

Several properties of the Property class enable you to modify the appearance of individual Properties.

Property	Sets or returns
BackColor	Background color of the whole Property, label and value. (You can override this for the value by using PropertyValue.BackColor property.)
ForeColor	Text color of the whole Property, label and value. (You can override this for the value by using the PropertyValue.ForeColor property.)
DisabledForeColor	Text color of the Property when disabled, label and value. (You can override this for the value by using the PropertyValue.DisabledForeColor property.)
ReadOnlyForeColor	Text color of a readonly Property, label and value. (You can override this for the value by using the PropertyValue.ReadOnlyForeColor property.)
Font	Font for the Property's strings. (You can override this for the value by using the PropertyValue.Font property.)
DisplayName	Label for the Property.
Comment	Comment for the Property. The comment is displayed in the comment area.
ImageIndex	The index for an image from the ImageList, to be displayed to the left of a category, subcategory or property label. The ImageList is set at the PropertyGrid level, so that it can be used by any property.

PropertyValue class properties

The PropertyValue class contains additional properties for customizing its display:

Property	Sets or returns
ImageSource	Indicates where the image is taken from. It can be: - None - no image is displayed. - Value - an image is displayed and is stored in the ImageList set to this PropertyValue. - Grid - an image is displayed and is stored in the ImageList set to the PropertyGrid. - Image - an image is displayed and is specified with the Image property.
ImageList	When set and ImageSource is set to Value, an icon is automatically determined depending on the current value of the Property. Used mainly by listboxes to place an icon in front of each entry.
Image	References an image to display. ImageSource must be set to Image.
ImageIndex	The index of an image in an ImageList (set on the grid or on the value).
ImageSize	Image size in pixels. Normally, the image is drawn to fit the height of a Property. This option prevents the image from being stretched oddly if the Property height has been increased by the Font size, or by PropertyVerticalMargin.