# 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.
Last Updated: 5/25/2022, 1:18:09 PM