Appearance Properties

• Aug 31, 2020
• 4 minutes to read

This document describes the purpose and implementation of the appearance properties - a special set of properties that allow you to customize the appearance of a report or any of its elements.

Appearance Properties Overview

Every report element (control or band), and a report itself, has a set of properties that specify its appearance. They are listed in the following table.

Property name	Description
XRControl.BackColor	Gets or sets a background color to a report element and its child controls.
XRControl.BorderColor	Gets or sets a border color to a report element and its child controls.
XRControl.BorderDashStyle	Gets or sets a border dash style to a report element and its child controls.
XRControl.Borders	Gets or sets borders (top, right, bottom,left), which should be visible for a report element and its child controls.
XRControl.BorderWidth	Gets or sets a border width to a report element and its child controls.
XRControl.Font	Gets or sets the font options (its name, size, etc.) to a report element and its child controls.
XRControl.ForeColor	Gets or sets the foreground color to a report element and its child controls.
XRControl.Padding	Gets or sets the indent values which are used to render the contents of a report element and its child controls.
XRControl.TextAlignment	Gets or sets the text alignment to a report element and its child controls.

Despite the fact that the properties listed in the above table are exposed by the XRControl class, the same properties are available for a report and its bands, because they are inherited from the XRControl class. For more information on this, refer to Report Class Hierarchy.

By default, these properties for every control or a band are set to empty values, which means that their real values are obtained from a control’s parent, or a parent of its parent and so on.

Note

The appearance properties may not be used by all descendants of the current report element for which they are defined. For example, the XRPageBreak class ignores the XRControl.BackColor property.

To reset values of these properties, right-click the required property in the Property Grid, and in the invoked menu, click Reset. Then, the control’s actual appearance will be determined by the appropriate properties settings of its parent.

If a report element has a style assigned to it, the priority of the properties defined by this style is determined by the XRControl.StylePriority property. Note that when a conditional formatting is involved, the appearance it defines is of greater priority than the properties described above.

Reset a Control’s Appearance at Runtime

This example demonstrates how to assign custom appearance settings (e.g., XRControl.BackColor, XRControl.ForeColor, XRControl.Borders, XRControl.Font, etc.) to report elements and reset them to their default values, as well as how to make a control ignore its personal appearance settings in favor of the settings of its parent control.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/Reporting_how-to-use-the-appearance-settings-of-report-elements-e933.

XtraReport1.vb

Imports System.Drawing
Imports System.Drawing.Printing
Imports DevExpress.XtraPrinting
Imports DevExpress.XtraReports.UI
' ...
Private Sub xrLabel2_BeforePrint(ByVal sender As Object, _ 
ByVal e As PrintEventArgs) Handles xrLabel2.BeforePrint
    SetCustomStyle(CType(sender, XRLabel))
End Sub

Private Sub xrLabel3_BeforePrint(ByVal sender As Object, _ 
ByVal e As PrintEventArgs) Handles xrLabel3.BeforePrint
    SetCustomStyle(CType(sender, XRLabel))
    ResetStyle(CType(sender, XRLabel))
End Sub

' Assign custom appearance settings to a control.
Private Sub SetCustomStyle(ByVal label As XRLabel)
    label.BackColor = Color.Gray
    label.BorderColor = Color.DarkGray
    label.Borders = BorderSide.All
    label.BorderWidth = 0.5f

    label.Font = New Font(label.Parent.Font, FontStyle.Bold)
    label.ForeColor = Color.White
    label.TextAlignment = TextAlignment.MiddleRight
End Sub

' Restore the appearance settings to their default values.
Private Sub ResetStyle(ByVal label As XRLabel)
    label.ResetBackColor()
    label.ResetBorderColor()
    label.ResetBorders()
    label.ResetBorderWidth()
    label.ResetFont()
    label.ResetForeColor()
    label.ResetPadding()
    label.ResetTextAlignment()
End Sub

XtraReport1.cs

using System.Drawing;
using System.Drawing.Printing;
using DevExpress.XtraPrinting;
using DevExpress.XtraReports.UI;
// ...
private void xrLabel2_BeforePrint(object sender, PrintEventArgs e) {
    SetCustomStyle((XRLabel)sender);
}

private void xrLabel3_BeforePrint(object sender, PrintEventArgs e) {
    SetCustomStyle((XRLabel)sender);
    ResetStyle((XRLabel)sender);
}

// Assign custom appearance settings to a control.
private void SetCustomStyle(XRLabel label) {
    label.BackColor = Color.Gray;
    label.BorderColor = Color.DarkGray;
    label.Borders = BorderSide.All;
    label.BorderWidth = 0.5f;

    label.Font = new Font(label.Parent.Font, FontStyle.Bold);
    label.ForeColor = Color.White;
    label.TextAlignment = TextAlignment.MiddleRight;
}

// Restore the appearance settings to their default values.
private void ResetStyle(XRLabel label) {
    label.ResetBackColor();
    label.ResetBorderColor();
    label.ResetBorders();
    label.ResetBorderWidth();
    label.ResetFont();
    label.ResetForeColor();
    label.ResetPadding();
    label.ResetTextAlignment();
}