ContextQMD
Back to Devexpress

HeatmapControl.DataAdapter Property

windowsforms-devexpress-dot-xtracharts-dot-heatmap-dot-heatmapcontrol.md

latest23.0 KB
Original Source

HeatmapControl.DataAdapter Property

Gets or sets an adapter that is used to load data to the heatmap.

Namespace : DevExpress.XtraCharts.Heatmap

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

NuGet Package : DevExpress.Win.Charts

Declaration

csharp
public HeatmapDataAdapterBase DataAdapter { get; set; }
vb
Public Property DataAdapter As HeatmapDataAdapterBase

Property Value

TypeDescription
HeatmapDataAdapterBase

A HeatmapDataAdapterBase descendant.

|

Remarks

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.

Examples

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.

  • Add the HeatmapControl to the Form.

  • Create a HeatmapDataSourceAdapter object and assign it to the HeatmapControl.DataAdapter property.

  • Define the adapter’s DataSource property.

  • Use the ColorDataMember property to define a data member that is used to determine cell colors.

  • Specify the following adapter properties to define data members that store heatmap arguments:

  • Create a HeatmapRangeColorProvider object and assign it to the heatmap’s ColorProvider property. The HeatmapRangeColorProvider 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.

  • Set the HeatmapControl.ToolTipEnabled property to true to enable tooltips. Specify the HeatmapControl.ToolTipTextPattern property to define tooltip text display format.

View Example

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

namespace BindHeatmapToDataSource {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
            DataTable data = CreateDataSet("BalanceOfTrade.xml");

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

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

            HeatmapRangeColorProvider colorProvider = new HeatmapRangeColorProvider() {
                Palette = palette,
                ApproximateColors = true,
                LegendItemPattern = "{V1} .. {V2}"
            };

            heatmap.ColorProvider = colorProvider;

            colorProvider.RangeStops.Add(new HeatmapRangeStop(0, HeatmapRangeStopType.Percentage));
            colorProvider.RangeStops.Add(new HeatmapRangeStop(-10));
            colorProvider.RangeStops.Add(new HeatmapRangeStop(-2.5));
            colorProvider.RangeStops.Add(new HeatmapRangeStop(0));
            colorProvider.RangeStops.Add(new HeatmapRangeStop(2.5));
            colorProvider.RangeStops.Add(new HeatmapRangeStop(10));
            colorProvider.RangeStops.Add(new HeatmapRangeStop(1, HeatmapRangeStopType.Percentage));

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

            heatmap.Legend.Visibility = DevExpress.Utils.DefaultBoolean.True;

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

            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>";

            heatmap.EnableAxisXScrolling = true;
            heatmap.EnableAxisYScrolling = true;
            heatmap.EnableAxisXZooming = true;
            heatmap.EnableAxisYZooming = true;

            heatmap.AxisX.Title.Text = "Region";
            heatmap.AxisX.Title.Visibility = DevExpress.Utils.DefaultBoolean.True;
            heatmap.AxisX.Label.Staggered = false;
            heatmap.AxisX.Label.ResolveOverlappingOptions.AllowStagger = false;
            heatmap.AxisX.Label.ResolveOverlappingOptions.AllowRotate = false;
            heatmap.AxisX.Label.ResolveOverlappingOptions.AllowHide = false;
            heatmap.AxisY.Title.Text = "Product Category";
            heatmap.AxisY.Title.Visibility = DevExpress.Utils.DefaultBoolean.True;
        }

        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;
        }
    }
}
vb
Imports System.Data
Imports DevExpress.Drawing
Imports DevExpress.XtraCharts
Imports DevExpress.XtraCharts.Heatmap

Namespace BindHeatmapToDataSource

    Public Partial Class Form1
        Inherits System.Windows.Forms.Form

        Public Sub New()
            Me.InitializeComponent()
            Dim data As System.Data.DataTable = BindHeatmapToDataSource.Form1.CreateDataSet("BalanceOfTrade.xml")
            Me.heatmap.DataAdapter = New HeatmapDataSourceAdapter() With {.XArgumentDataMember = "Country", .YArgumentDataMember = "Product", .ColorDataMember = "Value", .DataSource = data}
            Dim palette As Palette = New Palette("Custom") From {System.Drawing.Color.Red, System.Drawing.Color.White, System.Drawing.Color.Green}
            Dim colorProvider As HeatmapRangeColorProvider = New HeatmapRangeColorProvider() With {.Palette = palette, .ApproximateColors = True, .LegendItemPattern = "{V1} .. {V2}"}
            Me.heatmap.ColorProvider = colorProvider
            colorProvider.RangeStops.Add(New HeatmapRangeStop(0, HeatmapRangeStopType.Percentage))
            colorProvider.RangeStops.Add(New HeatmapRangeStop(-10))
            colorProvider.RangeStops.Add(New HeatmapRangeStop(-2.5))
            colorProvider.RangeStops.Add(New HeatmapRangeStop(0))
            colorProvider.RangeStops.Add(New HeatmapRangeStop(2.5))
            colorProvider.RangeStops.Add(New HeatmapRangeStop(10))
            colorProvider.RangeStops.Add(New HeatmapRangeStop(1, HeatmapRangeStopType.Percentage))
            Me.heatmap.Titles.Add(New HeatmapTitle With {.Text = "Balance of Trade"})
            Me.heatmap.Legend.Visibility = DevExpress.Utils.DefaultBoolean.[True]
            Me.heatmap.Label.Visible = True
            Me.heatmap.Label.DXFont = New DXFont("SegoeUI", 6)
            Me.heatmap.Label.Pattern = "{V}"
            Me.heatmap.Label.Color = System.Drawing.Color.Black
            Me.heatmap.ToolTipEnabled = True
            Me.heatmap.ToolTipController = New DevExpress.Utils.ToolTipController With {.AllowHtmlText = True, .ToolTipLocation = DevExpress.Utils.ToolTipLocation.RightTop, .ShowBeak = True}
            Me.heatmap.ToolTipTextPattern = "X: <b>{X}</b>" & Global.Microsoft.VisualBasic.Constants.vbLf & "Y: <b>{Y}</b>"
            Me.heatmap.EnableAxisXScrolling = True
            Me.heatmap.EnableAxisYScrolling = True
            Me.heatmap.EnableAxisXZooming = True
            Me.heatmap.EnableAxisYZooming = True
            Me.heatmap.AxisX.Title.Text = "Region"
            Me.heatmap.AxisX.Title.Visibility = DevExpress.Utils.DefaultBoolean.[True]
            Me.heatmap.AxisX.Label.Staggered = False
            Me.heatmap.AxisX.Label.ResolveOverlappingOptions.AllowStagger = False
            Me.heatmap.AxisX.Label.ResolveOverlappingOptions.AllowRotate = False
            Me.heatmap.AxisX.Label.ResolveOverlappingOptions.AllowHide = False
            Me.heatmap.AxisY.Title.Text = "Product Category"
            Me.heatmap.AxisY.Title.Visibility = DevExpress.Utils.DefaultBoolean.[True]
        End Sub

        Public Shared Function CreateDataSet(ByVal xmlFileName As String) As DataTable
            Dim filePath As String = BindHeatmapToDataSource.Form1.GetRelativePath(xmlFileName)
            If Not String.IsNullOrWhiteSpace(filePath) Then
                Dim dataSet As System.Data.DataSet = New System.Data.DataSet()
                dataSet.ReadXml(filePath)
                If dataSet.Tables.Count > 0 Then Return dataSet.Tables(0)
            End If

            Return Nothing
        End Function

        Public Shared Function GetRelativePath(ByVal name As String) As String
            name = "Data\" & name
            Dim dir As System.IO.DirectoryInfo = New System.IO.DirectoryInfo(System.Windows.Forms.Application.StartupPath)
            For i As Integer = 0 To 10
                Dim filePath As String = System.IO.Path.Combine(dir.FullName, name)
                If System.IO.File.Exists(filePath) Then Return filePath
                dir = System.IO.Directory.GetParent(dir.FullName)
            Next

            Return String.Empty
        End Function
    End Class
End Namespace

The XML file structure looks as follows:

Show XML

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>

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.

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 HeatmapRangeColorProvider object and assign it to the heatmap’s ColorProvider property. The HeatmapRangeColorProvider 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.

View Example

csharp
using DevExpress.XtraCharts;
using DevExpress.XtraCharts.Heatmap;
using System.Drawing;
using System.Windows.Forms;

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

            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
            };

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

            heatmap.ColorProvider = colorProvider;

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

            heatmap.Label.Visible = true;
            heatmap.Label.Pattern = "{V}";
        }
    }
}
vb
Imports DevExpress.XtraCharts
Imports DevExpress.XtraCharts.Heatmap
Imports System.Drawing
Imports System.Windows.Forms

Namespace HeatmapMatrixData

    Public Partial Class Form1
        Inherits System.Windows.Forms.Form

        Public Sub New()
            Me.InitializeComponent()
            Dim dataAdapter As DevExpress.XtraCharts.Heatmap.HeatmapMatrixAdapter = New DevExpress.XtraCharts.Heatmap.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}}
            Me.heatmap.DataAdapter = dataAdapter
            Dim palette As DevExpress.XtraCharts.Palette = New DevExpress.XtraCharts.Palette("Custom") From {System.Drawing.Color.White, System.Drawing.Color.SkyBlue, System.Drawing.Color.DarkBlue}
            Dim colorProvider As DevExpress.XtraCharts.Heatmap.HeatmapRangeColorProvider = New DevExpress.XtraCharts.Heatmap.HeatmapRangeColorProvider() With {.Palette = palette, .ApproximateColors = True}
            colorProvider.RangeStops.Add(New DevExpress.XtraCharts.Heatmap.HeatmapRangeStop(0, DevExpress.XtraCharts.Heatmap.HeatmapRangeStopType.Percentage))
            colorProvider.RangeStops.Add(New DevExpress.XtraCharts.Heatmap.HeatmapRangeStop(20, DevExpress.XtraCharts.Heatmap.HeatmapRangeStopType.Absolute))
            colorProvider.RangeStops.Add(New DevExpress.XtraCharts.Heatmap.HeatmapRangeStop(40, DevExpress.XtraCharts.Heatmap.HeatmapRangeStopType.Absolute))
            colorProvider.RangeStops.Add(New DevExpress.XtraCharts.Heatmap.HeatmapRangeStop(60, DevExpress.XtraCharts.Heatmap.HeatmapRangeStopType.Absolute))
            colorProvider.RangeStops.Add(New DevExpress.XtraCharts.Heatmap.HeatmapRangeStop(90, DevExpress.XtraCharts.Heatmap.HeatmapRangeStopType.Absolute))
            colorProvider.RangeStops.Add(New DevExpress.XtraCharts.Heatmap.HeatmapRangeStop(1, DevExpress.XtraCharts.Heatmap.HeatmapRangeStopType.Percentage))
            Me.heatmap.ColorProvider = colorProvider
            Me.heatmap.Titles.Add(New DevExpress.XtraCharts.Heatmap.HeatmapTitle With {.Text = "Sales by Categories"})
            Me.heatmap.Label.Visible = True
            Me.heatmap.Label.Pattern = "{V}"
        End Sub
    End Class
End Namespace

The following code snippets (auto-collected from DevExpress Examples) contain references to the DataAdapter property.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

winforms-dashboard-custom-items-extension/CS/CustomItemExtension/CustomItems/Heatmap/HeatmapItemControlProvider.cs#L54

csharp
void ClearDataBindings() {
    heatmap.DataAdapter = null;
    dataAdapter.DataSource = dataAdapter.ColorDataMember = dataAdapter.XArgumentDataMember = dataAdapter.YArgumentDataMember = null;

winforms-heatmap-matrix-data/CS/Form1.cs#L20

csharp
};
heatmap.DataAdapter = dataAdapter;

winforms-heatmap-bind-to-data-source/CS/Form1.cs#L15

csharp
heatmap.DataAdapter = new HeatmapDataSourceAdapter() {
    XArgumentDataMember = "Country",

winforms-dashboard-custom-items-extension/VB/CustomItemExtension/CustomItems/Heatmap/HeatmapItemControlProvider.vb#L62

vb
Private Sub ClearDataBindings()
    heatmap.DataAdapter = Nothing
    dataAdapter.YArgumentDataMember = Nothing

winforms-heatmap-matrix-data/VB/Form1.vb#L17

vb
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}}
Me.heatmap.DataAdapter = dataAdapter
Dim palette As DevExpress.XtraCharts.Palette = New DevExpress.XtraCharts.Palette("Custom") From {System.Drawing.Color.White, System.Drawing.Color.SkyBlue, System.Drawing.Color.DarkBlue}

winforms-heatmap-bind-to-data-source/VB/Form1.vb#L17

vb
Dim data As System.Data.DataTable = BindHeatmapToDataSource.Form1.CreateDataSet("BalanceOfTrade.xml")
Me.heatmap.DataAdapter = New DevExpress.XtraCharts.Heatmap.HeatmapDataSourceAdapter() With {.XArgumentDataMember = "Country", .YArgumentDataMember = "Product", .ColorDataMember = "Value", .DataSource = data}
Dim palette As DevExpress.XtraCharts.Palette = New DevExpress.XtraCharts.Palette("Custom") From {System.Drawing.Color.Red, System.Drawing.Color.White, System.Drawing.Color.Green}

See Also

HeatmapControl Class

HeatmapControl Members

DevExpress.XtraCharts.Heatmap Namespace