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 and Paste Operations. Data 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]ASP.NET Core 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]CodeRush Classic
[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 their visual elements' appearance. This includes modifying attributes such as the background and foreground colors, background images, font settings, etc.

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

The AppearanceObject and AppearanceObjectEx classes encapsulate appearance settings. 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 the appearance objects (the AppearanceObject object's properties) provide.

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 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 to use the AppearanceObject.BackColor property's value.
AppearanceOptions.UseBorderColor Gets or sets whether to use the AppearanceObject.BorderColor property's value.
AppearanceOptions.UseFont Gets or sets whether to use the AppearanceObject.Font property's value.
AppearanceOptions.UseForeColor Gets or sets whether to use the AppearanceObject.ForeColor property's value.
AppearanceOptions.UseImage Gets or sets whether to use the AppearanceObject.Image property's value.

If an option is disabled, its corresponding property is not available. For example, if the AppearanceOptions.UseBackColor option is set to false, the AppearanceObject.BackColor property is not 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 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 on its look and feel and default appearance settings. After the appearance property's default value changes, 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 certain cases, some appearance settings (background color) used to paint such visual elements such as column headers, expand buttons, etc., are ignored regardless of the corresponding options' state. This occurs when a 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. These elements' appearance objects 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 a grid view's appearance objects.

Appearance objects the control provides specify how the control's elements should be painted (by defauly). These settings, however, can be overridden using individual elements, since they take priority over the control's elements.

For instance, all the column headers in Grid Control are painted using the appearance settings the GridViewAppearances.HeaderPanel property provide, by default. However, 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 are painted using the 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 has the highest priority.

Expanded Appearance Editor

The Appearance Editor allows you to re-apply multiple objects' appearance settings. Customize the first element as usual, then click the ellipsis button next to the "Appearance" property to invoke the dialog.

In the Appearance Editor dialog, click "Save As..." to save the source element's appearance as a template.

When the template is saved, close the Editor and re-invoke it for other elements you need to customize. Use the selector at the editor's top to choose a template, then click "Apply" and proceed to the next element. You can also rename and delete appearance templates before applying them.

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 are not used (their corresponding appearance options, for example, UseBackColor, UseForeColor, disabled).

For instance, the default appearance hierarchy 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 specifying a higher priority for their appearance settings. Currently, AppearanceObjectEx objects represent only the appearance settings the columns (in XtraTreeList, XtraGrid, XtraVerticalGrid) and style conditions (in XtraGrid) provide.

The image below shows the appearance hierarchy in XtraTreeList, which determine a node cell's look and feel when a column's HighPriority option is enabled. 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 is 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 it is printed, set the GridOptionsPrint.UsePrintStyles property to true. Otherwise, if this property is set to false, the grid view is printed as it is displayed on the form.

Expanded Save and Restore 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 stream.
BaseAppearanceCollection.SaveLayoutToXml Saves the appearance settings to a 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?​​​​​​​