Skip to main content

Dashboard.ColorScheme Property

Provides access to a dashboard color scheme.

Namespace: DevExpress.DashboardCommon

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

NuGet Package: DevExpress.Dashboard.Core

Declaration

public ColorScheme ColorScheme { get; }

Property Value

Type Description
ColorScheme

A ColorScheme object that is the color scheme used to color dashboard item elements.

Remarks

The dashboard provides two ways for coloring dashboard item elements.

  • Using a global color scheme that provides consistent colors for identical values across the dashboard. To access the dashboard color scheme, use the ColorScheme property.
  • Using a local color scheme that provides an individual set of colors for each dashboard item. For instance, the Chart and Pie dashboard items provide the ChartDashboardItemBase.ColorScheme property to access a local color scheme.

The Chart and Pie dashboard items expose the ChartDashboardItemBase.ColoringOptions property that allows you to access coloring options. The DashboardItemColoringOptions object returned by this property exposes the DashboardItemColoringOptions.UseGlobalColors property, allowing you to specify whether the dashboard item uses a global or local color scheme.

Dashboard items allow you to color specific dimension values/measures or their combinations using specified colors.

To color required dimension values/measures, specify the coloring mode using the following properties.

The ColorScheme class provides access to a collection of ColorSchemeEntry objects that allow you to map the required dimension values/measures and the specified color. To do this, use the following members.

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:

View Example: How to Customize a Dashboard Color Scheme

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

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);
            entry.ColorDefinition = new ColorDefinition((Color)colorSchemeRecord["color"]);
            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.Rows.Add("Beverages", "UK", "Extended Price", Color.Red);
            colorTable.Rows.Add("Beverages", "USA", "Extended Price", Color.Green);
            return colorTable;
        }
    }
}
See Also