Skip to main content
All docs
V24.1

Conditional Formatting

  • 6 minutes to read

You can apply conditional formatting to a Card dashboard item’s visual elements (like Title, Subtitle, different values) and change the card’s background.

Note

Cards that use a legacy layout do not support conditional formatting.

Supported Format Rules

You can use measure or dimension values to calculate a format rule. You can also use delta values to calculate a Card dashboard item’s format rules.

Format rules that can be applied to different data item types are as follows:

Data Type

Supported Format Conditions

numeric

Value

Top-Bottom

Average

Expression

Icon Ranges

Color Ranges

Gradient Ranges

string

Value with the condition type set to Equal To, Not Equal To or Text that Contains

Expression

date-time

Value

A Date Occurring for dimensions with the continuous date-time group interval

Expression

Icon Ranges

Color Ranges

Gradient Ranges

Refer to the Conditional Formatting Basics topic for more information about format rule types.

Create and Edit a Format Rule

You can create and edit format rules in the following ways:

  • Click the Edit Rules button on the Home ribbon tab.

    EditRules_Ribbon

    The invoked dialog contains the calculated by combo box where you can select the item whose values are used to calculate the format rule.

    • To apply a format rule to a specific card, calculate a format rule by delta values. The expression format condition is an exception to this rule and applies to all cards.
    • To apply a format rule to all cards in a Card item, use hidden measures and series dimensions to calculate a rule.

    For a Card item, the Edit Rules dialog has the using combo box. If you use a delta calculation, specify the delta type in this box. Click the Add button, select the format rule from the pop-up menu, and specify the rule’s condition:

  • Click the series dimension/hidden measure menu button and select Add Format Rule/Edit Rules.

Refer to the following topic for information on how to create and edit format rules: Conditional Formatting in Windows Designer.

Card-Specific Format Condition Settings

Specify appearance settings and set the condition’s value for the format rule. Available settings depend on the selected format rule.

The appearance settings dialog contains the Apply to drop-down list. Select a layout element to which you want to apply a format rule. Select All elements to apply the format rule to all card elements.

You can add an icon to the custom layout element or configure the style of its display text. The image below displays the value format rule that colors the display text of the State dimension layout element green:

Note

The background color is applied to the entire card, regardless of the selection in the Apply to drop-down.

Some predefined background styles contain a font color. This font color applies to all the card elements regardless of the drop-down list settings (all/particular element).

Create a Format Rule for a Data Item in Code

View Example: How to Apply Conditional Formatting to the Card Dashboard Item

Create a CardItemFormatRule object and specify its settings to add a format rule:

The following code snippet creates a format rule for cards whose actual value is between Value1 and Value2:

using System.Windows.Forms;
using DevExpress.DashboardCommon;
using System.Drawing;

CardDashboardItem card = (CardDashboardItem)dashboardDesigner1.Dashboard.Items["cardDashboardItem1"];

CardItemFormatRule rule = new CardItemFormatRule();
rule.DataItem = card.Cards[0].ActualValue;
rule.ApplyToLayoutElement = CardFormatRuleLayoutElement.ActualValue;
FormatConditionValue value = new FormatConditionValue();
value.StyleSettings = new AppearanceSettings(Color.LightCoral, Color.DarkBlue);
value.Value1 = 50000;
value.Value2 = 70000;
value.Condition = DashboardFormatCondition.Between;
rule.Condition = value;
card.FormatRules.Add(rule);

Create a Format Rule for Delta in Code

Create a CardItemDeltaFormatRule object and specify its settings to add a delta format rule:

The following code snippet illustrates the delta rule that is calculated from the delta’s absolute variation value:

using System.Windows.Forms;
using DevExpress.DashboardCommon;

CardDashboardItem card = (CardDashboardItem)dashboardDesigner1.Dashboard.Items["cardDashboardItem1"];

CardItemDeltaFormatRule rule = new CardItemDeltaFormatRule();
rule.DeltaValueType = DeltaValueType.AbsoluteVariation;
rule.Card = card.Cards[0];
var condition = new FormatConditionRangeGradient(FormatConditionRangeGradientPredefinedType.BlueGreen);
rule.Condition = condition;
card.FormatRules.Add(rule);

Use the following API to create a format rule for a Card dashboard item:

API Description
CardItemDeltaFormatRule A format rule that is calculated by delta and used to apply conditional formatting to the Card dashboard item.
CardItemFormatRule A format rule that is calculated by data items and used to apply conditional formatting to the Card dashboard item.
CardItemFormatRuleBase Serves as the base class for classes that are format rules for the Card item.
CardItemFormatRuleCollection A collection of CardItemFormatRuleBase descendants that are format rules for the Card item.
CardFormatRuleLayoutElement Lists values that specify the card’s layout elements to which the format rule applies.
CardFormatRuleTextLayoutElement A card’s dimension layout element to which a format rule applies.
CardFormatRuleDimensionLayoutElement A card’s text layout element to which a format rule applies.
CardDashboardItem.FormatRules Provides access to format rules of the Card dashboard item.
CardItemDeltaFormatRule.DeltaValueType Gets or sets the delta type according to which a condition is calculated.
CardItemFormatRule.DataItem Gets or sets the data item by whose values a format rule is calculated.
CardItemFormatRuleBase.ApplyToLayoutElement Gets or sets the Card dashboard item’s layout element to apply conditional formatting.
DashboardItemFormatRule.Condition Gets or sets a condition used to apply formatting to a dashboard item.
CardItemDeltaFormatRule.Card Gets or sets a card that is used to calculate a delta format rule.
CardFormatRuleLayoutElement.CreateDimensionElement(String) Creates a dimension layout element to which a format rule applies.
CardFormatRuleLayoutElement.CreateTextElement(String) Creates a text layout element to which a format rule applies.