ColorScheme Class

A color scheme used to color dashboard item elements.

Namespace: DevExpress.DashboardCommon

Assembly: DevExpress.Dashboard.v26.1.Core.dll

Declaration

C#

public class ColorScheme :
    NotifyingCollection<ColorSchemeEntry>

VB.NET

Public Class ColorScheme
    Inherits NotifyingCollection(Of ColorSchemeEntry)

Related API Members

The following members return ColorScheme objects:

• ChartDashboardItemBase.ColorScheme
• CustomDashboardItem.ColorScheme
• Dashboard.ColorScheme
• PieMapDashboardItem.ColorScheme
• RangeFilterDashboardItem.ColorScheme
• ScatterChartDashboardItem.ColorScheme
• TreemapDashboardItem.ColorScheme

Remarks

You can color dashboard item elements in two ways:

Global Color Scheme

Provides consistent colors for identical values across the dashboard. To access the dashboard color scheme, use the Dashboard.ColorScheme property.

Local Color Scheme

Provides an independent set of colors for each dashboard item. The Chart and Pie items expose the ColorScheme property to access it.

Dashboard items that support color variation expose the ColoringOptions property. This property returns a DashboardItemColoringOptions object. Set its DashboardItemColoringOptions.UseGlobalColors property to choose between a global and local color scheme.

You can apply specific colors to dimension values/measures or their combinations.

Specify the color mode with the following properties:

• The Dimension.ColoringMode property specifies the dimension’s color mode.
• The DashboardItemColoringOptions.MeasuresColoringMode property specifies the color mode for dashboard item measures.

The ColorScheme class is a collection of ColorSchemeEntry objects that map dimension values/measures to colors and styles. Use the following members:

• The ColorSchemeEntry.DimensionKeys collection contains ColorSchemeDimensionKey objects that allow you to specify the dimension and corresponding dimension value. Use the Dimension.GetDimensionDefinition method to obtain the dimension definition and pass the returned object to the ColorSchemeDimensionKey constructor.
• The ColorSchemeEntry.MeasureKey property returns the ColorSchemeMeasureKey object that allows you to specify measures to be colored. Use the Measure.GetMeasureDefinition method to obtain the measure definition and pass the returned object to the ColorSchemeMeasureKey constructor.
• The ColorSchemeEntry.DataSource property specifies the data source that contains the required dimensions and measures.
• The ColorSchemeEntry.ColorDefinition property specifies the color, hatch style, and line style used to paint the specified dimension values/measures. You can select the color from a built-in palette or specify a custom color.

Tip

Documentation:
Coloring

Example

The following example demonstrates how to customize a dashboard color scheme to color specified dimension values using predefined colors.

In this example, the dashboard contains Pie and Chart dashboard items, whose dimension values are colored by hue. Dimension values and corresponding colors are stored in a data table.

To add custom colors to the dashboard color scheme (the Dashboard.ColorScheme property), create the ColorSchemeEntry objects.

The ColorSchemeEntry class has the following properties:

• The ColorSchemeEntry.DataSource property specifies a data source containing dimension values.
• The ColorSchemeEntry.DimensionKeys property allows you to specify the dimension values.
• The ColorSchemeEntry.ColorDefinition property sets the color, fill style, and line style (through a DashboardPaletteItem) used to paint the dimension values.

View Example: How to Customize a Dashboard Color Scheme

Form1.cs

using DevExpress.DashboardCommon;
using DevExpress.Drawing;
using DevExpress.XtraBars.Ribbon;
using System.Data;
using System.Drawing;

namespace Dashboard_Coloring {
    public partial class Form1 : RibbonForm {
        public Form1() {
            InitializeComponent();
            dashboardDesigner1.CreateRibbon();

            // Create a color table that contains dimension values, measures and colors.
            DataTable colorTable = CreateColorTable();
            // Load a dashboard from the XML file.
            Dashboard dashboard = new Dashboard(); dashboard.LoadFromXml(@"..\..\Data\Dashboard.xml");
            IDashboardDataSource dataSource = dashboard.DataSources["dataSource1"];

            // Specify the coloring mode for the pie series, pie measures and chart argument.
            PieDashboardItem pie1 = (PieDashboardItem)dashboard.Items["pieDashboardItem1"];
            ChartDashboardItem chart1 = (ChartDashboardItem)dashboard.Items["chartDashboardItem1"];
            pie1.SeriesDimensions[0].ColoringMode = ColoringMode.Hue;
            pie1.ColoringOptions.MeasuresColoringMode = ColoringMode.Hue;
            chart1.Arguments[0].ColoringMode = ColoringMode.Hue;

            foreach (DataRow row in colorTable.Rows) {
                dashboard.ColorScheme.Add(CreateColorSchemeEntry(row, dataSource, false));
                dashboard.ColorScheme.Add(CreateColorSchemeEntry(row, dataSource, true));
            }
            dashboardDesigner1.Dashboard = dashboard;
        }

        // Create color scheme entries to map dimension values, measures and colors.
        private ColorSchemeEntry CreateColorSchemeEntry(DataRow colorSchemeRecord,
                                                        IDashboardDataSource dataSource,
                                                        bool includeMeasures) {
            DimensionDefinition categoryDefinition = new DimensionDefinition("CategoryName");
            DimensionDefinition countryDefinition = new DimensionDefinition("Country");
            MeasureDefinition priceDefinition = new MeasureDefinition("Extended Price");

            ColorSchemeEntry entry = new ColorSchemeEntry();
            entry.DimensionKeys.Add(new ColorSchemeDimensionKey(categoryDefinition,
                colorSchemeRecord["CategoryName"]));
            entry.DimensionKeys.Add(new ColorSchemeDimensionKey(countryDefinition,
                colorSchemeRecord["Country"]));
            if (includeMeasures)
                entry.MeasureKey = new ColorSchemeMeasureKey(priceDefinition);
            // Use a DashboardPaletteItem to define the color, a fill style (hatch), and line style.
            entry.ColorDefinition = new ColorDefinition(new DashboardPaletteItem(
                (Color)colorSchemeRecord["color"],
                (DXHatchStyle)colorSchemeRecord["hatch"],
                (DXDashStyle)colorSchemeRecord["line"]));
            entry.DataSource = dataSource;
            return entry;
        }

        private DataTable CreateColorTable() {
            DataTable colorTable = new DataTable();
            colorTable.Columns.Add("CategoryName", typeof(string));
            colorTable.Columns.Add("Country", typeof(string));
            colorTable.Columns.Add("measure", typeof(string));
            colorTable.Columns.Add("color", typeof(Color));
            colorTable.Columns.Add("hatch", typeof(DXHatchStyle));
            colorTable.Columns.Add("line", typeof(DXDashStyle));
            colorTable.Rows.Add("Beverages", "UK", "Extended Price", Color.Red, DXHatchStyle.DiagonalCross, DXDashStyle.Dash);
            colorTable.Rows.Add("Beverages", "USA", "Extended Price", Color.Green, DXHatchStyle.Sphere, DXDashStyle.Dot);
            return colorTable;
        }
    }
}

Form1.vb

Imports System.Data
Imports System.Drawing
Imports DevExpress.DashboardCommon
Imports DevExpress.Drawing
Imports DevExpress.XtraBars.Ribbon

Namespace Dashboard_Coloring
    Partial Public Class Form1
        Inherits RibbonForm

        Public Sub New()
            InitializeComponent()
            dashboardDesigner1.CreateRibbon()
            ' Create a color table that contains dimension values, measures and colors.
            Dim colorTable As DataTable = CreateColorTable()
            ' Load a dashboard from the XML file.
            Dim dashboard As New Dashboard()
            dashboard.LoadFromXml("..\..\Data\Dashboard.xml")
            Dim dataSource As IDashboardDataSource = dashboard.DataSources("dataSource1")

            ' Specify the coloring mode for the pie series, pie measures and chart argument.
            Dim pie1 As PieDashboardItem = CType(dashboard.Items("pieDashboardItem1"), PieDashboardItem)
            Dim chart1 As ChartDashboardItem = CType(dashboard.Items("chartDashboardItem1"), ChartDashboardItem)
            pie1.SeriesDimensions(0).ColoringMode = ColoringMode.Hue
            pie1.ColoringOptions.MeasuresColoringMode = ColoringMode.Hue
            chart1.Arguments(0).ColoringMode = ColoringMode.Hue

            For Each row As DataRow In colorTable.Rows
                dashboard.ColorScheme.Add(CreateColorSchemeEntry(row, dataSource, False))
                dashboard.ColorScheme.Add(CreateColorSchemeEntry(row, dataSource, True))
            Next row
            dashboardDesigner1.Dashboard = dashboard
        End Sub

        ' Create color scheme entries to map dimension values, measures and colors.
        Private Function CreateColorSchemeEntry(ByVal colorSchemeRecord As DataRow, ByVal dataSource As IDashboardDataSource, ByVal includeMeasures As Boolean) As ColorSchemeEntry
            Dim categoryDefinition As New DimensionDefinition("CategoryName")
            Dim countryDefinition As New DimensionDefinition("Country")
            Dim priceDefinition As New MeasureDefinition("Extended Price")

            Dim entry As New ColorSchemeEntry()
            entry.DimensionKeys.Add(New ColorSchemeDimensionKey(categoryDefinition, colorSchemeRecord("CategoryName")))
            entry.DimensionKeys.Add(New ColorSchemeDimensionKey(countryDefinition, colorSchemeRecord("Country")))
            If includeMeasures Then
                entry.MeasureKey = New ColorSchemeMeasureKey(priceDefinition)
            End If
            ' Use a DashboardPaletteItem to define the color, a fill style (hatch), and line style.
            entry.ColorDefinition = New ColorDefinition(New DashboardPaletteItem(DirectCast(colorSchemeRecord("color"), Color), DirectCast(colorSchemeRecord("hatch"), DXHatchStyle), DirectCast(colorSchemeRecord("line"), DXDashStyle)))
            entry.DataSource = dataSource
            Return entry
        End Function

        Private Function CreateColorTable() As DataTable
            Dim colorTable As New DataTable()
            colorTable.Columns.Add("CategoryName", GetType(String))
            colorTable.Columns.Add("Country", GetType(String))
            colorTable.Columns.Add("measure", GetType(String))
            colorTable.Columns.Add("color", GetType(Color))
            colorTable.Columns.Add("hatch", GetType(DXHatchStyle))
            colorTable.Columns.Add("line", GetType(DXDashStyle))
            colorTable.Rows.Add("Beverages", "UK", "Extended Price", Color.Red, DXHatchStyle.DiagonalCross, DXDashStyle.Dash)
            colorTable.Rows.Add("Beverages", "USA", "Extended Price", Color.Green, DXHatchStyle.Sphere, DXDashStyle.Dot)
            Return colorTable
        End Function
    End Class
End Namespace

The image below shows the resulting dashboard with the customized color scheme:

Inheritance

Object

Collection<ColorSchemeEntry>

NotifyingCollection<ColorSchemeEntry>

ColorScheme