HeatmapAxis Class

Contains settings for heatmap axes.

Namespace: DevExpress.Xpf.Charts.Heatmap

Assembly: DevExpress.Xpf.Charts.v24.2.dll

NuGet Package: DevExpress.Wpf.Charts

Declaration

C#

public class HeatmapAxis :
    Freezable

VB.NET

Public Class HeatmapAxis
    Inherits Freezable

Related API Members

The following members return HeatmapAxis objects:

• HeatmapControl.AxisX
• HeatmapControl.AxisY
• HeatmapHitInfo.Axis

Remarks

The HeatmapAxis class contains options that allow you to configure appearance, access label and tickmark settings, and add titles to heatmap x- and y-axes.

Use the HeatmapControl.AxisX and HeatmapControl.AxisY properties to customize heatmap axis settings.

XAML

<Window xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"  
        xmlns:dxc="http://schemas.devexpress.com/winfx/2008/xaml/charts"
        xmlns:dxh="http://schemas.devexpress.com/winfx/2008/xaml/heatmap">
    <Grid>
        <dxh:HeatmapControl>
            <!--...-->
            <dxh:HeatmapControl.AxisX>
                <dxh:HeatmapAxis/>
            </dxh:HeatmapControl.AxisX>
            <dxh:HeatmapControl.AxisY>
                <dxh:HeatmapAxis/>
            </dxh:HeatmapControl.AxisY>
        </dxh:HeatmapControl>
        <!--...-->
    </Grid>
</Window>

If you want to hide an axis, set its Visible property to False.

Enable the axis Reverse property to show axis labels and position cells in reversed order.

If a heatmap is bound to data, you can place labels in custom order. To do so, specify the HeatmapDataSourceAdapter.XArgumentComparer and/or HeatmapDataSourceAdapter.YArgumentComparer property.

Configure Axis Labels

Use an axis’s Label property to customize heatmap axis label settings. The example below configures label alignment, rotation, format pattern, and border settings of x-axis labels:

XAML

<dxh:HeatmapControl.AxisX>
    <dxh:HeatmapAxis>
        <dxh:HeatmapAxis.Label>
            <dxc:AxisLabel Background="LightGray" 
                        BorderBrush="Gray" 
                        BorderThickness="1"
                        Foreground="Black"
                        TextPattern="Division: {X}" 
                        Angle="30"/>
        </dxh:HeatmapAxis.Label>
    </dxh:HeatmapAxis>
</dxh:HeatmapControl.AxisX>

You can also use templates to customize label content and appearance: assign a DataTemplate object to the label ElementTemplate property:

XAML

<Window.Resources>
    <DataTemplate x:Key="labelTemplate">
        <Label Content="{Binding Value}" 
               Background="LightGray"/>
    </DataTemplate>
</Window.Resources>
<!--...-->
    <dxh:HeatmapControl.AxisX>
        <dxh:HeatmapAxis>
            <dxh:HeatmapAxis.Label>
                <dxc:AxisLabel ElementTemplate="{StaticResource ResourceKey=labelTemplate}"/>
            </dxh:HeatmapAxis.Label>
        </dxh:HeatmapAxis>
    </dxh:HeatmapControl.AxisX>

Add Custom Axis Labels

You can display custom labels with default labels or in place of default labels. The adapter creates default labels based on cell arguments. Use the axis’ CustomLabels property to access the custom axis label collection.

For each custom label, you need to specify the CustomAxisLabel.Value and CustomAxisLabel.Content properties.

Set the HeatmapAxis.LabelVisibilityMode property to AutoGeneratedAndCustom to show custom labels with default labels. Otherwise, only custom labels will be visible.

The following example displays a custom label on an x-axis:

XAML

<dxh:HeatmapControl.AxisX>
    <dxh:HeatmapAxis LabelVisibilityMode="AutoGeneratedAndCustom">
        <dxh:HeatmapAxis.CustomLabels>
            <dxc:CustomAxisLabel Value="West" 
                                 Content="Division: West"/>
        </dxh:HeatmapAxis.CustomLabels>
    </dxh:HeatmapAxis>
</dxh:HeatmapControl.AxisX>

Generate Custom Labels in MVVM Style

Bind the HeatmapAxis.CustomLabelItemsSource property to a collection of objects that contain label parameters to generate custom axis labels from a ViewModel. Use the HeatmapAxis.CustomLabelItemTemplate or HeatmapAxis.CustomLabelItemTemplateSelector property to specify how to convert a view model object to a custom label.

The following example generates custom labels for an x-axis:

XAML

<dxh:HeatmapControl>
    <dxh:HeatmapControl.DataContext>
        <local:MatrixHeatmapViewModel/>
    </dxh:HeatmapControl.DataContext>
    <!--...-->
    <dxh:HeatmapControl.AxisX>
        <dxh:HeatmapAxis LabelVisibilityMode="AutoGeneratedAndCustom" 
                         CustomLabelItemsSource="{Binding CustomLabels}">
            <dxh:HeatmapAxis.CustomLabelItemTemplate>
                <DataTemplate>
                    <dxc:CustomAxisLabel Value="{Binding AxisValue}" 
                                         Content="{Binding Text}"/>
                </DataTemplate>
            </dxh:HeatmapAxis.CustomLabelItemTemplate>
        </dxh:HeatmapAxis>
    </dxh:HeatmapControl.AxisX>
</dxh:HeatmapControl>

C#

using System.Collections.Generic;
using System.Windows;
namespace HeatmapChart {
    public class MatrixHeatmapViewModel {
        public string[] XArguments { get; set; }
        public string[] YArguments { get; set; }
        public double[,] Values { get; set; }
        public List<CustomLabel> CustomLabels { get; set; }
        public MatrixHeatmapViewModel() {
            XArguments = new string[] { "March", "April", "May", "June", "July" };
            YArguments = new string[] { "Accessories", "Bikes", "Clothing", "Components" };
            Values = new double[,] {
               { 214.3, 530.1, 630.2, 854.4, 313.4 },
               { 321.3, 514.4, 281.3, 533.4, 541.9 },
               { 604.3, 429.1, 632.6, 438.4, 265.4 },
               { 485.3, 544.7, 740.3, 661.4, 516.6 }
            };
            CustomLabels = new List<CustomLabel> {
                new CustomLabel{ AxisValue = "April", Text = "April (04/30)" },
                new CustomLabel{ AxisValue = "May", Text = "May (05/31)" },
            };
        }
    }
    public class CustomLabel {
        public string AxisValue { get; set; }
        public string Text { get; set; }
    }
}

VB.NET

Imports System.Collections.Generic

Namespace HeatmapChart
    Public Class MatrixHeatmapViewModel
        Public Property XArguments As String()
        Public Property YArguments As String()
        Public Property Values As Double(,)
        Public Property CustomLabels As List(Of CustomLabel)

        Public Sub New()
            XArguments = New String() {"March", "April", "May", "June", "July"}
            YArguments = New String() {"Accessories", "Bikes", "Clothing", "Components"}
            Values = New Double(,) {
            {214.3, 530.1, 630.2, 854.4, 313.4},
            {321.3, 514.4, 281.3, 533.4, 541.9},
            {604.3, 429.1, 632.6, 438.4, 265.4},
            {485.3, 544.7, 740.3, 661.4, 516.6}}
            CustomLabels = New List(Of CustomLabel) From {
                New CustomLabel With {
                    .AxisValue = "April",
                    .Text = "April (04/30)"
                },
                New CustomLabel With {
                    .AxisValue = "May",
                    .Text = "May (05/31)"
                }
            }
        End Sub
    End Class

    Public Class CustomLabel
        Public Property AxisValue As String
        Public Property Text As String
    End Class
End Namespace

Specify Grid Step

Use the GridSpacing property to specify how frequently the Heatmap Control should plot its tickmarks and labels. The GridSpacing value is automatically calculated until the AutoGrid property is enabled.

Customize Axis Tickmarks

Use the following properties to customize axis tickmarks:

• TickmarksCrossAxis
• TickmarksLength
• TickmarksThickness
• TickmarksVisible

Note that tickmarks are painted the same color as the axis to which they belong. The tickmark frequency depends on the axis GridSpacing property value.

The following example configures tickmark settings such as color, length, and thickness, and specifies tickmark frequency:

XAML

<dxh:HeatmapControl.AxisX>
    <dxh:HeatmapAxis Brush="LightGray" GridSpacing="1" AutoGrid="False"
                     TickmarksCrossAxis="True" TickmarksLength="8"
                     TickmarksThickness="2" TickmarksVisible="True"/>
</dxh:HeatmapControl.AxisX>

Add Axis Title

You can accompany an axis with a single title that can be aligned along the axis. To show the title, assign an AxisTitle object to the Title property. Then, specify the title Content property.

The following example shows how to add a title for a y-axis:

XAML

<dxh:HeatmapControl.AxisY>
    <dxh:HeatmapAxis>
        <dxh:HeatmapAxis.Title>
            <dxc:AxisTitle Content="Product Category"/>
        </dxh:HeatmapAxis.Title>
    </dxh:HeatmapAxis>
</dxh:HeatmapControl.AxisY>

Specify Axis Position

Define the Alignment property to specify axis position. The following values are available:

Near

The x-axis is positioned at the bottom of the chart, the y-axis – at the left.

Far

The x-axis is positioned at the top of the chart, the y-axis – at the right.

XAML

<dxh:HeatmapControl.AxisX>
    <dxh:HeatmapAxis Alignment="Far"/>
</dxh:HeatmapControl.AxisX>
<dxh:HeatmapControl.AxisY>
    <dxh:HeatmapAxis Alignment="Far"/>
</dxh:HeatmapControl.AxisY>

Customize Axis Appearance

You can specify the axis color and thickness: define the Brush and Thickness properties:

XAML

<dxh:HeatmapControl.AxisX>
    <dxh:HeatmapAxis Brush="Gray" Thickness="3"/>
</dxh:HeatmapControl.AxisX>

Inheritance

Object

DispatcherObject

DependencyObject

Freezable

HeatmapAxis