HeatmapControl.Legend Property

Returns heatmap legend options.

Namespace: DevExpress.XtraCharts.Heatmap

Assembly: DevExpress.XtraCharts.v24.1.UI.dll

NuGet Package: DevExpress.Win.Charts

Declaration

C#

public HeatmapLegend Legend { get; }

VB.NET

Public ReadOnly Property Legend As HeatmapLegend

Property Value

Type	Description
HeatmapLegend	Contains options for the heatmap legend.

Example

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:

  • XArgumentDataMember
  • YArgumentDataMember

• 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

C#

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.NET

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>