FormatConditionColorRangeBar Class

A format condition used to visualize numeric values using bars whose colors are contained in the specified color set.

Namespace: DevExpress.DashboardCommon

Assembly: DevExpress.Dashboard.v19.2.Core.dll

Declaration

C#

public class FormatConditionColorRangeBar :
    FormatConditionRangeSet,
    IMinMaxInfo

VB.NET

Public Class FormatConditionColorRangeBar
    Inherits FormatConditionRangeSet
    Implements IMinMaxInfo

Remarks

Range conditions allow you to apply formatting using a predefined set of value ranges and corresponding style settings.

To create a format condition to display bars of different colors with lengths proportional to corresponding values, use the following approaches.

1. To use a predefined set of colors, pass the required FormatConditionRangeSetPredefinedType enumeration value to the FormatConditionColorRangeBar constructor or call the FormatConditionColorRangeBar.Generate method.

2. To use a predefined set of colors and custom range boundaries, do the following.

   • Pass the required FormatConditionRangeSetPredefinedType enumeration value to the FormatConditionColorRangeBar constructor or call the FormatConditionColorRangeBar.Generate method.
   • Specify the type of range boundaries using the FormatConditionRangeBase.ValueType property and assign the required boundary values using the FormatConditionRangeBase.SetValues property.
   • If necessary, change the comparison logic using the FormatConditionRangeBase.SetValueComparison property.

3. To use custom range boundaries and the required style specified for each range, do the following.

   • Specify whether an absolute or percent scale is used to define range boundaries using the FormatConditionRangeBase.ValueType property.
   • Create the required number of RangeInfo objects that are the ranges containing boundary values (the RangeInfo.Value property), a comparison logic (RangeInfo.ValueComparison) and style setting applied to range values (assign the BarStyleSettings object to the RangeInfo.StyleSettings property).
   • Add initialized RangeInfo objects to the FormatConditionRangeBase.RangeSet collection.

Assign the resulting FormatConditionColorRangeBar object to the DashboardItemFormatRule.Condition property.

Example

The Bar Color Ranges condition (FormatConditionColorRangeBar) allows you to visualize numeric values using bars whose colors are contained in the specified color set.

This example shows how to display colored bars within Grid cells. Click the Update Formatting button to change the number of ranges, specify new range boundaries and customize colors mapped to existing ranges.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-apply-conditional-formatting-to-grid-cells-using-the-bar-color-ranges-condition-t304349.

Form1.cs

using System;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;

namespace Grid_IconRangeCondition {
    public partial class Form1 : DevExpress.XtraEditors.XtraForm {
        public Form1() {
            InitializeComponent();
            dashboardViewer1.CustomizeDashboardTitle += DashboardViewer1_CustomizeDashboardTitle;
            Dashboard dashboard = new Dashboard(); dashboard.LoadFromXml(@"..\..\Data\Dashboard.xml");
            dashboardViewer1.Dashboard = dashboard;
            GridDashboardItem grid = (GridDashboardItem)dashboard.Items["gridDashboardItem1"];
            GridMeasureColumn extendedPrice = (GridMeasureColumn)grid.Columns[1];

            GridItemFormatRule rangeRule = new GridItemFormatRule(extendedPrice);
            FormatConditionColorRangeBar rangeBarCondition =
                new FormatConditionColorRangeBar(FormatConditionRangeSetPredefinedType.ColorsRedGreenBlue);
            rangeBarCondition.BarOptions.ShowBarOnly = true;
            rangeRule.Condition = rangeBarCondition;

            grid.FormatRules.AddRange(rangeRule);
        }

        private void DashboardViewer1_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e)
        {
            DashboardToolbarItem itemUpdate = new DashboardToolbarItem(
                (args) => UpdateFormatting())
            {
                Caption = "Update Formatting",
            };
            e.Items.Add(itemUpdate);
        }

        private void UpdateFormatting() {
            GridDashboardItem grid = 
                (GridDashboardItem)dashboardViewer1.Dashboard.Items["gridDashboardItem1"];
            GridItemFormatRule rangeRule = grid.FormatRules[0];
            FormatConditionColorRangeBar rangeBarCondition = (FormatConditionColorRangeBar)rangeRule.Condition;
            RangeInfo range3 = rangeBarCondition.RangeSet[2];
            range3.Value = 50;
            range3.StyleSettings =
                new BarStyleSettings(FormatConditionAppearanceType.GradientGreen);

            RangeInfo range4 = new RangeInfo();
            range4.Value = 75;
            range4.StyleSettings =
                new BarStyleSettings(FormatConditionAppearanceType.GradientBlue);
            rangeBarCondition.RangeSet.Add(range4);

            rangeRule.Condition = rangeBarCondition;
        }
    }
}

Form1.vb

Imports System
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin

Namespace Grid_IconRangeCondition
    Partial Public Class Form1
        Inherits DevExpress.XtraEditors.XtraForm

        Public Sub New()
            InitializeComponent()
            AddHandler dashboardViewer1.CustomizeDashboardTitle, AddressOf DashboardViewer1_CustomizeDashboardTitle
            Dim dashboard As New Dashboard()
            dashboard.LoadFromXml("..\..\Data\Dashboard.xml")
            dashboardViewer1.Dashboard = dashboard
            Dim grid As GridDashboardItem = CType(dashboard.Items("gridDashboardItem1"), GridDashboardItem)
            Dim extendedPrice As GridMeasureColumn = CType(grid.Columns(1), GridMeasureColumn)

            Dim rangeRule As New GridItemFormatRule(extendedPrice)
            Dim rangeBarCondition As New FormatConditionColorRangeBar(FormatConditionRangeSetPredefinedType.ColorsRedGreenBlue)
            rangeBarCondition.BarOptions.ShowBarOnly = True
            rangeRule.Condition = rangeBarCondition

            grid.FormatRules.AddRange(rangeRule)
        End Sub

        Private Sub DashboardViewer1_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As CustomizeDashboardTitleEventArgs)
            Dim itemUpdate As New DashboardToolbarItem(Sub(args) UpdateFormatting()) With {.Caption = "Update Formatting"}
            e.Items.Add(itemUpdate)
        End Sub

        Private Sub UpdateFormatting()
            Dim grid As GridDashboardItem = CType(dashboardViewer1.Dashboard.Items("gridDashboardItem1"), GridDashboardItem)
            Dim rangeRule As GridItemFormatRule = grid.FormatRules(0)
            Dim rangeBarCondition As FormatConditionColorRangeBar = CType(rangeRule.Condition, FormatConditionColorRangeBar)
            Dim range3 As RangeInfo = rangeBarCondition.RangeSet(2)
            range3.Value = 50
            range3.StyleSettings = New BarStyleSettings(FormatConditionAppearanceType.GradientGreen)

            Dim range4 As New RangeInfo()
            range4.Value = 75
            range4.StyleSettings = New BarStyleSettings(FormatConditionAppearanceType.GradientBlue)
            rangeBarCondition.RangeSet.Add(range4)

            rangeRule.Condition = rangeBarCondition
        End Sub
    End Class
End Namespace

Inheritance

Object

FormatConditionBase

FormatConditionRangeBase

FormatConditionRangeSet

FormatConditionColorRangeBar