Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Expand]Controls and Libraries
 [Collapse]Common Features
  [Expand]Data Binding Common Concepts
  [Expand]Data Source Wizard
  [Expand]Expressions
  [Expand]Behaviors
  [Collapse]Application Appearance
    Default Application Font
    Appearances
   [Expand]Look And Feel
    Glyph Skinning
  [Expand]Filtering UI Context
  [Expand]High DPI Support
  [Expand]Scaffolding Wizard
  [Expand]Formatting Values
   HTML Text Formatting
  [Expand]Menus
  [Expand]Tooltip Management
  [Expand]Saving and Restoring Layouts
   Clipboard - Copy Data and Formatting
   Version Compatibility: Default Property Values
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Appearances

All DevExpress .NET Windows Forms controls (the XtraGrid, XtraBars, XtraTreeList, etc.) provide design-time and runtime facilities for customizing the appearance of their visual elements. This includes such modifying attributes as the background and foreground colors, background images, font settings, etc., which are the subject of this document.

This document provides an overview of the appearance mechanism. Part of this mechanism is the appearance customization for a group of controls in a centralized way. You can customize the appearances in a centralized way for the editors derived from the BaseControl class. See Style Controller to learn more.

Expanded Appearances and Appearance Settings

Appearance settings are encapsulated by the AppearanceObject and AppearanceObjectEx classes. Their properties specify the background and foreground colors, gradient background, font, pen, brush and other style characteristics used to paint a particular element. The table below lists the settings provided by the appearance objects (the AppearanceObject object's properties).

Property Description
AppearanceObject.BackColor Specifies the element's background color if the AppearanceObject.BackColor2 property's value is Color.Empty. Otherwise, it specifies the gradient's starting color.
AppearanceObject.BackColor2 Specifies the background gradient's ending color.
AppearanceObject.BorderColor Specifies the element's border color.
AppearanceObject.GradientMode Specifies the background gradient's direction.
AppearanceObject.ForeColor Specifies the element's foreground color (the text color).
AppearanceObject.Font Specifies the font used to paint the element's text.
AppearanceObject.Image Specifies the element's background image.
AppearanceObject.Options Provides access to the appearance object's options. These options specify which appearance settings should be inherited.
AppearanceObject.TextOptions Provides access to the appearance object's options that specify the appearance object's text settings (horizontal and vertical alignment, trimming, etc.).

The image below illustrates these settings for a card in the Grid Control. A card consists of multiple visual elements (card caption, field caption, field value, etc.) and each can be customized via its own AppearanceObject object.

Expanded Appearance Options

The AppearanceObject class exposes the AppearanceObject.Options property, which provides access to the Boolean options that determine which appearance settings should be used to paint an element. The following table lists available appearance options.

Option Description
AppearanceOptions.UseBackColor Gets or sets whether the AppearanceObject.BackColor property's value should be used.
AppearanceOptions.UseBorderColor Gets or sets whether the AppearanceObject.BorderColor property's value should be used.
AppearanceOptions.UseFont Gets or sets whether the AppearanceObject.Font property's value should be used.
AppearanceOptions.UseForeColor Gets or sets whether the AppearanceObject.ForeColor property's value should be used.
AppearanceOptions.UseImage Gets or sets whether the AppearanceObject.Image property's value should be used.

If an option is disabled, its corresponding property isn't available. For example, if the AppearanceOptions.UseBackColor option is set to false, the AppearanceObject.BackColor property isn't used. In this case, the element's background color is specified by the control's look and feel settings. To obtain the appearance settings that are actually used to paint the control's elements, use the control's PaintAppearance property.

Once a control has been dropped onto a form, its appearance properties are set to their default values and their corresponding appearance options are disabled. The control is painted based upon its look and feel and default appearance settings. After the appearance property's default value has been changed, its corresponding option is automatically enabled. Alternatively, setting the property to its default value disables the option.

For example, by default, the BackColor property is set to the Color.Empty value. Its UseBackColor option is set to false. Once the BackColor property's value has been changed, the UseBackColor option is automatically set to true. Setting the BackColor property back to the Color.Empty value sets the option to false. This is illustrated below:

In some instances, some of the appearance settings (background color) used to paint such visual elements such as column headers, expand buttons, etc., are ignored regardless of the state of the corresponding options. This occurs when the control is painted in Office2003 or WindowsXP style.

Note

When an AppearanceObject's style setting (e.g., BackColor, ForeColor, Font and TextOptions.HAlignment) is set to a non-default value, the corresponding Use... option (e.g., Options.UseBackColor, Options.UseForeColor, Options.UseFont and Options.UseTextOptions) is automatically set to true. This happens only in the following cases:

  • The AppearanceObject belongs to a control/component (or its element), and this control/component has been completely loaded (see the control's IsLoading property to check the load status).
  • The AppearanceObject belongs to a grid column/band or tree list column/band, and the column/band belongs to a grid/tree list control.
  • The AppearanceObject is standalone, i.e., it does not belong to any control or component.

Expanded Using Appearances

Each control usually has multiple visual elements. Appearance objects for these elements are usually combined into a single object (the BaseAppearanceCollection descendant). For example, each view in Grid Control has a BaseView.Appearance property that combines the Appearance objects for all the view's elements, such as column headers, buttons, cells, footers, etc. The image below shows the Properties window displaying Appearance objects for a grid view.

Appearance objects provided by the control specify how the control's elements should be painted, by default. These settings, however, can be overridden by individual elements, since they take priority over the control's elements.

For instance, by default, all the column headers in Grid Control are painted using the appearance settings provided by the GridViewAppearances.HeaderPanel property. However, by using a column's GridColumn.AppearanceHeader property, it is possible to override these settings and provide a new appearance for the column's header, while the other column headers will be painted using default settings. So, the GridColumn.AppearanceHeader's settings take priority over the GridViewAppearances.HeaderPanel's settings.

The image below shows Grid Control with the Contact Name column's header painted using the column's appearance settings, while the other column headers use the default appearance settings.

It is also possible to customize the column header's appearance settings via the GridView.CustomDrawColumnHeader event. The Appearance object supplied via this event will have the highest priority.

Expanded Appearance Priority

The appearance of a single element in a control can be specified using multiple appearance objects which have different priorities. The appearance settings of an object with a lower priority are used to paint an element only if the appearance settings of objects with a higher priority aren't used (their corresponding appearance options, e.g. UseBackColor, UseForeColor, disabled).

For instance, by default, the hierarchy of appearances used to paint a cell in the Tree List is shown in the image below.

 

Specific appearance objects (AppearanceObjectEx instances) provide the AppearanceOptionsEx.HighPriority option, which allows a higher priority to be specified for their appearance settings. Currently, only the appearance settings provided by the columns (in XtraTreeList, XtraGrid, XtraVerticalGrid) and style conditions (in XtraGrid) are represented by AppearanceObjectEx objects.

The image below shows the hierarchy of appearances in XtraTreeList, which determine a node cell's look and feel when the HighPriority option is enabled for a column. As you can see from the image, the column's appearance settings used to paint its cells take priority over the appearances used to paint the focused node and focused cell.

Expanded Printing Appearances

DevExpress .NET controls such as Grid Control and Tree List support the printing functionality. These controls expose the AppearancePrint property, which provides the appearance settings that can be used to paint the control when it's printed. To use these settings, the option that determines whether or not the control can be painted using the print appearances used when printing must be enabled. For example, to use the print appearances to paint the grid view in Grid Control when printing, set the GridOptionsPrint.UsePrintStyles property to true. Otherwise, if this property is set to false, the grid view will be printed as it is displayed on the form.

Expanded Saving and Restoring Appearances

The appearance settings used to paint DevExpress .NET controls can be saved to the system registry, an XML file or written to a stream using the methods listed in the table below.

Method Description
BaseAppearanceCollection.SaveLayoutToRegistry Saves the appearance settings to a system registry path.
BaseAppearanceCollection.SaveLayoutToStream Saves the appearance settings to a specific stream.
BaseAppearanceCollection.SaveLayoutToXml Saves the appearance settings to a specific XML file.

Once saved, the appearance settings can be applied to any other control. This allows you to customize the control's appearance only once, and then apply the saved settings to other controls in other applications. The following table lists the methods used to restore the saved appearance settings:

Method Description
BaseAppearanceCollection.RestoreLayoutFromRegistry Restores the appearance settings stored at the specified system registry path.
BaseAppearanceCollection.RestoreLayoutFromStream Restores the appearance settings from the specified stream.
BaseAppearanceCollection.RestoreLayoutFromXml Restores the appearance settings stored in the specified XML file.

The following example code shows how to write and read the appearance settings used to paint Grid Control elements to/from an XML file.

How would you rate this topic?​​​​​​​