All docs
V21.2
21.2 (EAP/Beta)
21.1
The page you are viewing does not exist in version 21.1. This link will take you to the root page.
20.2
The page you are viewing does not exist in version 20.2. This link will take you to the root page.
20.1
The page you are viewing does not exist in version 20.1. This link will take you to the root page.
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.
You are viewing help content for pre-release software. This document and the features it describes are subject to change.

HeatmapControl Class

Displays a customizable and interactive heatmap chart.

Namespace: DevExpress.XtraCharts.Heatmap

Assembly: DevExpress.XtraCharts.v21.2.UI.dll

Declaration

public class HeatmapControl :
    Control,
    IChartContainer,
    IChartRenderProvider,
    IHeatmapInteractionContainer,
    IToolTipControlClient,
    ICursorHolder,
    ISupportLookAndFeel

Remarks

A heatmap is a data analysis tool that uses colors and color intensity to visualize a change in magnitude. Each heatmap cell is defined by three values: X-argument, Y-argument, and Value (Color Value). The arguments are displayed along corresponding axes. The value is used to determine the cell color.

The following image depicts the main elements of a heatmap:

Heatmap elements

Demos

The Heatmap Control ships with a set of demo applications that you can explore in the DevExpress Demo Center:

Run Demo: Color Providers

Run Demo: Large Data

Run Demo: Labels

Run Demo: Tooltip

Add a Heatmap Control to the Project

Drag and drop the HeatmapControl component from the Toolbox to the form to add a heatmap chart control to the project.

HeatmapControl in Toolbox

This adds references to the following assemblies in the project:

  • DevExpress.Charts.v21.2.Core.dll
  • DevExpress.Data.Desktop.v21.2.dll
  • DevExpress.Data.v21.2.dll
  • DevExpress.Printing.v21.2.Core.dll
  • DevExpress.XtraPrinting.v21.2.dll
  • DevExpress.Utils.v21.2.dll
  • DevExpress.Utils.v21.2.UI.dll
  • DevExpress.XtraBars.v21.2.dll
  • DevExpress.XtraCharts.v21.2.dll
  • DevExpress.XtraCharts.v21.2.UI.dll
  • DevExpress.XtraCharts.v21.2.Wizard.dll
  • DevExpress.XtraEditors.v21.2.dll

Load Data to a Heatmap

The Heatmap Control uses data adapters to load data. Heatmap data adapters are derived from the HeatmapDataAdapterBase class. Use the Heatmap Control’s DataAdapter property to assign an adapter to a heatmap. The following adapters are available:

  • HeatmapDataSourceAdapter – Allows you to bind the Heatmap Control to a data source.
  • HeatmapMatrixAdapter – Allows you to use collections of values to specify x-arguments and y-arguments, and pass a matrix of numeric values to define heatmap cell values.

Paint a Heatmap

The Heatmap Control ships with multiple color providers that implement different coloring algorithms:

  • KeyColorProvider – Applies colors to heatmap cells based on color values that are used as key values (keys). Cells with equal keys have the same color.
  • RangeColorProvider – Applies colors based on ranges to which cell values belong.
  • ObjectColorProvider – Applies a color to a cell that is stored in the Color Data Member. This color provider can be used only with the Data Source Adapter.

To assign a color provider object to a heatmap, use the HeatmapDataAdapterBase.ColorProvider property.

Add Titles

You can add multiple titles to a heatmap. To do this, add HeatmapTitle objects to the Heatmap Control’s Titles collection.

Configure Cell Labels

Use the HeatmapControl.Label property to access heatmap cell label settings. Enable the HeatmapLabel.Visible property to display labels. Specify the HeatmapLabel.Pattern property to format labels.

Zoom and Scroll Heatmap

Enable the following properties to allow users to scroll and zoom a heatmap:

You can use the HeatmapControl.Scroll, HeatmapControl.ZoomIn and HeatmapControl.ZoomOut methods to scroll and zoom a heatmap programmatically.

Enable and Customize Tooltips

Set the HeatmapControl.ToolTipEnabled property to true to display tooltips when a user hovers over a heatmap cell.

Use the HeatmapControl.ToolTipController property to access tooltip settings.

Specify the HeatmapControl.ToolTipTextPattern property to format tooltip text. For advanced tooltip text customization, handle the HeatmapControl.CustomizeHeatmapToolTip event.

Highlight Heatmap Cells

A user can hover over a heatmap cell with the mouse cursor to highlight this cell. Specify the HeatmapControl.HighlightMode property to select an appropriate highlight mode.

If you want to perform custom actions when a user highlights a heatmap cell, handle the HeatmapControl.HighlightedItemChanged event.

Examples

How to Create a Heatmap Based on a Matrix of Numeric Values

This example shows how to use arrays of string and numeric values to create a heatmap.

A heatmap that uses a Matrix Adapter

Follow the steps below to create a heatmap:

  • Add the HeatmapControl to the Form.
  • Create a HeatmapMatrixAdapter object and assign it to the HeatmapControl.DataAdapter property.
  • Use the adapter’s XArguments and YArguments properties to populate the heatmap with x- and y-arguments that are displayed along x- and y-axes.
  • Assign a two-dimensional array of double values to the adapter’s Values property.
  • Create a RangeColorProvider object and assign it to the adapter’s ColorProvider property. The RangeColorProvider paints cells based on a value range to which the cell value belongs.
  • Add a HeatmapTitle to the heatmap’s Titles collection. Specify the title’s Text property.
  • Use the heatmap’s Label property to configure cell label options. This example shows how to configure label text format.
using DevExpress.XtraCharts;
using DevExpress.XtraCharts.Heatmap;
using System;
using System.Drawing;
using System.Windows.Forms;

namespace HeatmapMatrixAdapterSample {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e) {
            HeatmapControl heatmap = new HeatmapControl();
            heatmap.Dock = DockStyle.Fill;
            this.Controls.Add(heatmap);

            HeatmapMatrixAdapter dataAdapter = new HeatmapMatrixAdapter();
            dataAdapter.XArguments = new string[] { "North", "South", "West", "East", "Central" };
            dataAdapter.YArguments = new string[] { "Components", "Clothing", "Bikes", "Accessories" };
            dataAdapter.Values = new double[,] {
                { 21.3, 50.1, 63.2, 64.4, 33.4 },
                { 32.3, 54.4, 81.3, 53.4, 54.9 },
                { 60.3, 49.1, 42.6, 48.4, 65.4 },
                { 45.3, 54.7, 70.3, 66.4, 56.6 }
            };
            heatmap.DataAdapter = dataAdapter;

            Palette palette = new Palette("Custom") {
                Color.White,
                Color.SkyBlue,
                Color.DarkBlue
            };

            RangeColorProvider colorProvider = new RangeColorProvider() {
                Palette = palette,
                ApproximateColors = true
            };
            colorProvider.RangeStops.Add(new Unit(0, UnitType.Percentage));
            colorProvider.RangeStops.Add(new Unit(20, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(40, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(60, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(90, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(1, UnitType.Percentage));

            dataAdapter.ColorProvider = colorProvider;

            heatmap.Titles.Add(new HeatmapTitle { Text = "Sales by Categories" });

            heatmap.Label.Visible = true;
            heatmap.Label.Pattern = "{V}";
        }
    }
}

How to Bind a Heatmap to a Data Source (XML File)

The following example shows how to create a heatmap and bind it to a data source. In this example, the heatmap obtains data from an XML file.

A heatmap that uses a Data Source Adapter to load data.

using DevExpress.XtraCharts;
using DevExpress.XtraCharts.Heatmap;
using System;
using System.Data;
using System.Drawing;
using System.IO;
using System.Windows.Forms;

namespace HeatmapChart {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
        }
        private void Form1_Load(object sender, EventArgs e) {
            HeatmapControl heatmap = new HeatmapControl();
            heatmap.Dock = DockStyle.Fill;
            this.Controls.Add(heatmap);

            Palette palette = new Palette("Custom") {
                Color.Red,
                Color.White,
                Color.Green
            };

            RangeColorProvider colorProvider = new RangeColorProvider() {
                Palette = palette,
                ApproximateColors = true
            };

            colorProvider.RangeStops.Add(new Unit(0, UnitType.Percentage));
            colorProvider.RangeStops.Add(new Unit(-10, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(-2.5, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(0, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(2.5, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(10, UnitType.Absolute));
            colorProvider.RangeStops.Add(new Unit(1, UnitType.Percentage));

            DataTable data = CreateDataSet("BalanceOfTrade.xml");

            heatmap.DataAdapter = new HeatmapDataSourceAdapter() {
                XArgumentDataMember = "Country",
                YArgumentDataMember = "Product",
                ColorDataMember = "Value",
                DataSource = data,
                ColorProvider = colorProvider
            };

            heatmap.Titles.Add(new HeatmapTitle { Text = "Balance of Trade" });

            heatmap.Label.Visible = true;
            heatmap.Label.Font = new Font("SegoeUI", 6);
            heatmap.Label.Pattern = "{V}";

            heatmap.ToolTipEnabled = true;
            heatmap.ToolTipController = new DevExpress.Utils.ToolTipController {
                AllowHtmlText = true,
                ToolTipLocation = DevExpress.Utils.ToolTipLocation.RightTop,
                ShowBeak = true
            };
            heatmap.ToolTipTextPattern = "X: <b>{X}</b>\nY: <b>{Y}</b>";
        }
        public static DataTable CreateDataSet(string xmlFileName) {
            string filePath = GetRelativePath(xmlFileName);
            if (!string.IsNullOrWhiteSpace(filePath)) {
                DataSet dataSet = new DataSet();
                dataSet.ReadXml(filePath);
                if (dataSet.Tables.Count > 0)
                    return dataSet.Tables[0];
            }
            return null;
        }
        public static string GetRelativePath(string name) {
            name = "Data\\" + name;
            DirectoryInfo dir = new DirectoryInfo(Application.StartupPath);
            for (int i = 0; i <= 10; i++) {
                string filePath = Path.Combine(dir.FullName, name);
                if (File.Exists(filePath))
                    return filePath;
                dir = Directory.GetParent(dir.FullName);
            }
            return string.Empty;
        }
    }
}

The XML file structure looks as follows:

Show XML
<?xml version="1.0" standalone="yes"?>
<BalanceOfTrade xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="Item">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="Country" type="xs:string"/>
          <xs:element name="Product" type="xs:string"/>
          <xs:element name="Value" type="xs:double"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
  </xs:schema>
  <Item>
    <Country>China</Country>
    <Product>Computer</Product>
    <Value>-151.9</Value>
  </Item>
  <Item>
    <Country>China</Country>
    <Product>Oil, Gas, Minerals</Product>
    <Value>1.9</Value>
  </Item>
  <Item>
    <Country>China</Country>
    <Product>Transportation</Product>
    <Value>10.9</Value>
  </Item>
  <Item>
    <Country>China</Country>
    <Product>Apparel</Product>
    <Value>-56.3</Value>
  </Item>
  <!--...-->
</BalanceOfTrade>     

Implements

DevExpress.XtraCharts.Heatmap.Native.IHeatmapInteractionContainer

Inheritance

See Also