# 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:
|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:
|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.