New to Telerik UI for WinForms? Download free 30-day trial

Data Binding

Data binding is a mechanism for the automatic population of the RadHeatMap with items, based on the provided data structure.

Setting up the Model and the Sample Data

In order to demonstrate how to populate a RadHeatMap with data, we will create a sample object that will hold temperature information and create a collection of those objects.

Example 1: Setting up the model

public class TempInfo
{
    public DateTime Year { get; set; }
    public string Month { get; set; }
    public double Temperature { get; set; }
}        



Public Class TempInfo
    Public Property Year As DateTime
    Public Property Month As String
    Public Property Temperature As Double
End Class


Example 2: Creating Sample Data

private BindingList<TempInfo> PrepareData()
{
    DateTime date = DateTime.Today;
    var infos = new BindingList<TempInfo>()
    {
        new TempInfo() { Year = date, Month = "Jan", Temperature = 17},
        new TempInfo() { Year = date, Month = "Feb", Temperature = 8},
        new TempInfo() { Year = date, Month = "Mar", Temperature = 20},
        new TempInfo() { Year = date.AddYears(1), Month = "Jan", Temperature = 5},
        new TempInfo() { Year = date.AddYears(1), Month = "Feb", Temperature = 13},
        new TempInfo() { Year = date.AddYears(1), Month = "Mar", Temperature = 21},
        new TempInfo() { Year = date.AddYears(2), Month = "Jan", Temperature = 14},
        new TempInfo() { Year = date.AddYears(2), Month = "Feb", Temperature = 19},
        new TempInfo() { Year = date.AddYears(2), Month = "Mar", Temperature = 17},
    };
    return infos;
}     



Private Function PrepareData() As BindingList(Of TempInfo)
    Dim _date As DateTime = DateTime.Today
    Dim infos = New BindingList(Of TempInfo)() From {
        New TempInfo() With {
            .Year = _date,
            .Month = "Jan",
            .Temperature = 17
        },
        New TempInfo() With {
            .Year = _date,
            .Month = "Feb",
            .Temperature = 8
        },
        New TempInfo() With {
            .Year = _date,
            .Month = "Mar",
            .Temperature = 20
        },
        New TempInfo() With {
            .Year = _date.AddYears(1),
            .Month = "Jan",
            .Temperature = 5
        },
        New TempInfo() With {
            .Year = _date.AddYears(1),
            .Month = "Feb",
            .Temperature = 13
        },
        New TempInfo() With {
            .Year = _date.AddYears(1),
            .Month = "Mar",
            .Temperature = 21
        },
        New TempInfo() With {
            .Year = _date.AddYears(2),
            .Month = "Jan",
            .Temperature = 14
        },
        New TempInfo() With {
            .Year = _date.AddYears(2),
            .Month = "Feb",
            .Temperature = 19
        },
        New TempInfo() With {
            .Year = _date.AddYears(2),
            .Month = "Mar",
            .Temperature = 17
        }
    }
    Return infos
End Function



Definitions

In order to visualize our data we need to set the Definition property of the control. The control works with few different definitions that describe how to data will be shown: CategoricalDefinition, VerticalDefinition, HorizontalDefinition. We will populate the control using each of the definitions.

Categorical Definition

The definition provides few properties to define what data should be used.

  • RowGroupMember: Contains the name of the property in the custom model that will be used to generate the rows.
  • ColumnGroupMember: Contains the name of the property in the custom model that will be used to generate the columns.
  • ValueMember: Contains the name of the property in the custom model that will be used to generate the cells. Based on that value the cell will be colored differently.

The RowGroupMember in our example, will point to a DateTime type property. To format the DateTime value, we can use the RowHeaderTextFormat property of the control. The ColumnGroupMember will represent the Month property. What's left is to set our value for the cell through the ValueMember, which in our case will be the Temperature property value.

Example 3: Categorical Definition


CategoricalDefinition categoricalDefinition = new CategoricalDefinition();
categoricalDefinition.RowGroupMember = "Year";
categoricalDefinition.ColumnGroupMember = "Month";
categoricalDefinition.ValueMember = "Temperature";
categoricalDefinition.DataSource = PrepareData();
this.radHeatMap1.Definition = categoricalDefinition;
this.radHeatMap1.RowHeaderWidth = 40;
this.radHeatMap1.RowHeaderTextFormat = "yyyy";
this.radHeatMap1.HeaderCellTextAlignment = ContentAlignment.MiddleCenter;   



Dim categoricalDefinition As CategoricalDefinition = New CategoricalDefinition()
categoricalDefinition.RowGroupMember = "Year"
categoricalDefinition.ColumnGroupMember = "Month"
categoricalDefinition.ValueMember = "Temperature"
categoricalDefinition.DataSource = PrepareData()
Me.radHeatMap1.Definition = categoricalDefinition
Me.radHeatMap1.RowHeaderWidth = 40
Me.radHeatMap1.RowHeaderTextFormat = "yyyy"
Me.radHeatMap1.HeaderCellTextAlignment = ContentAlignment.MiddleCenter



WinForms RadHeatMapMap Data Binding Categorical Definition

Vertical Definition

Alternatively, we can also use a VerticalDefinition. We'll set the months as HeaderPath of our HeatMap. Thus the months supplied by the Month property of our underlying source will be visualized as column headers. For each row, we'll display the Temperature and Rain values of the corresponding month. However, this setup may not clearly indicate which month belongs to which year. To address this, we can customize the column headers by subscribing to the HeaderCellPainting event of the control. Within the event handler, we can specifically target the column header row and retrieve information about the associated data item from the first data cell in the column.

Example 4: Vertical Definition


private void Bind_VerticalDefinition()
{
    HeatMapGradientColorizer heatMapGradientColorizer = new HeatMapGradientColorizer();
    ColorConverter colorConverter = new ColorConverter();
    heatMapGradientColorizer.GradientStops = new List<GradientStop>()
    {
    new GradientStop() { Color=(Color)new ColorConverter().ConvertFromString("#D9E7F1"), Position=0 },
    new GradientStop() { Color=(Color)new ColorConverter().ConvertFromString("#01518C"), Position=1 }
    };
    VerticalDefinition verticalDefinition = new VerticalDefinition();
    verticalDefinition.DataSource = PrepareData();
    verticalDefinition.HeaderMember = "Month";
    verticalDefinition.MemberMappings = new MemberMappingsCollection() {
    new MemberMapping() { Header = "Temperature in Celsius", ValueMember = "Temperature",},
    new MemberMapping() { Header = "Rain in Centimeters", ValueMember = "Rain", Colorizer = heatMapGradientColorizer }
    };
    this.radHeatMap1.HeatMapElement.RowHeaderWidth = 130;
    this.radHeatMap1.HeaderCellPainting += RadHeatMap1_HeaderCellPainting;
    this.radHeatMap1.Definition = verticalDefinition;
}

private void RadHeatMap1_HeaderCellPainting(object sender, HeatMapHeaderCellPaintingEventArgs e)
{
    if (e.Index.ColumnIndex > -1 && e.Index.RowIndex == -1)
    {
        var heatMapItem = this.radHeatMap1.Definition.GetDataItem(new CellIndex(0,e.Index.ColumnIndex));
        var dataBoundItem = heatMapItem.DataBoundItem as TempInfo;
        e.Text = dataBoundItem.Year.ToString("yyyy") +"  "+ dataBoundItem.Month;
    }
}



Private Sub Bind_VerticalDefinition()
    Dim heatMapGradientColorizer As HeatMapGradientColorizer = New HeatMapGradientColorizer()
    Dim colorConverter As ColorConverter = New ColorConverter()
    heatMapGradientColorizer.GradientStops = New List(Of GradientStop)() From {
        New GradientStop() With {
            .Color = CType(New ColorConverter().ConvertFromString("#D9E7F1"), Color),
            .Position = 0
        },
        New GradientStop() With {
            .Color = CType(New ColorConverter().ConvertFromString("#01518C"), Color),
            .Position = 1
        }
    }
    Dim verticalDefinition As VerticalDefinition = New VerticalDefinition()
    verticalDefinition.DataSource = PrepareData()
    verticalDefinition.HeaderMember = "Month"
    verticalDefinition.MemberMappings = New MemberMappingsCollection() From {
        New MemberMapping() With {
            .Header = "Temperature in Celsius",
            .ValueMember = "Temperature"
        },
        New MemberMapping() With {
            .Header = "Rain in Centimeters",
            .ValueMember = "Rain",
            .Colorizer = heatMapGradientColorizer
        }
    }
    Me.radHeatMap1.HeatMapElement.RowHeaderWidth = 130
    AddHandler Me.radHeatMap1.HeaderCellPainting, AddressOf RadHeatMap1_HeaderCellPainting
    Me.radHeatMap1.Definition = verticalDefinition
End Sub

Private Sub RadHeatMap1_HeaderCellPainting(ByVal sender As Object, ByVal e As HeatMapHeaderCellPaintingEventArgs)
    If e.Index.ColumnIndex > -1 AndAlso e.Index.RowIndex = -1 Then
        Dim heatMapItem = Me.radHeatMap1.Definition.GetDataItem(New CellIndex(0, e.Index.ColumnIndex))
        Dim dataBoundItem = TryCast(heatMapItem.DataBoundItem, TempInfo)
        e.Text = dataBoundItem.Year.ToString("yyyy") & "  " + dataBoundItem.Month
    End If
End Sub


WinForms RadHeatMapMap Data Binding Vertical Definition

Horizontal Definition

This definition closely resembles the VerticalDefinition, with the distinction that the property value of our underlying source, specifically the HeaderMember property, will be represented as row headers. To accommodate this, we must make adjustments to the HeaderCellPainting event handler to correctly handle the row headers instead of the column headers.

Example 5: Horizontal Definition


private void Bind_HorizontalDefinition()
{
    HeatMapGradientColorizer heatMapGradientColorizer = new HeatMapGradientColorizer();
    ColorConverter colorConverter = new ColorConverter();
    heatMapGradientColorizer.GradientStops = new List<GradientStop>()
    {
    new GradientStop() { Color=(Color)new ColorConverter().ConvertFromString("#D9E7F1"), Position=0 },
    new GradientStop() { Color=(Color)new ColorConverter().ConvertFromString("#01518C"), Position=1 }
    };
    HorizontalDefinition horizontalDefinition = new HorizontalDefinition();
    horizontalDefinition.DataSource = PrepareData();
    horizontalDefinition.HeaderMember = "Month";
    horizontalDefinition.MemberMappings = new MemberMappingsCollection()
    {
    new MemberMapping() { Header = "Temperature in Celsius", ValueMember = "Temperature",},
    new MemberMapping() { Header = "Rain in Centimeters", ValueMember = "Rain", Colorizer = heatMapGradientColorizer }
    };
    this.radHeatMap1.HeatMapElement.RowHeaderWidth = 80;
    this.radHeatMap1.HeaderCellPainting += RadHeatMap1_HeaderCellPainting1;
    this.radHeatMap1.Definition = horizontalDefinition;
}

private void RadHeatMap1_HeaderCellPainting1(object sender, HeatMapHeaderCellPaintingEventArgs e)
{
    if (e.Index.ColumnIndex == -1 && e.Index.RowIndex > -1)
    {
        var heatMapItem = this.radHeatMap1.Definition.GetDataItem(new CellIndex(e.Index.RowIndex, 0));
        var dataBoundItem = heatMapItem.DataBoundItem as TempInfo;
        e.Text = dataBoundItem.Year.ToString("yyyy") + "  " + dataBoundItem.Month;
    }
}




Private Sub Bind_HorizontalDefinition()
    Dim heatMapGradientColorizer As HeatMapGradientColorizer = New HeatMapGradientColorizer()
    Dim colorConverter As ColorConverter = New ColorConverter()
    heatMapGradientColorizer.GradientStops = New List(Of GradientStop)() From {
        New GradientStop() With {
            .Color = CType(New ColorConverter().ConvertFromString("#D9E7F1"), Color),
            .Position = 0
        },
        New GradientStop() With {
            .Color = CType(New ColorConverter().ConvertFromString("#01518C"), Color),
            .Position = 1
        }
    }
    Dim horizontalDefinition As HorizontalDefinition = New HorizontalDefinition()
    horizontalDefinition.DataSource = PrepareData()
    horizontalDefinition.HeaderMember = "Month"
    horizontalDefinition.MemberMappings = New MemberMappingsCollection() From {
        New MemberMapping() With {
            .Header = "Temperature in Celsius",
            .ValueMember = "Temperature"
        },
        New MemberMapping() With {
            .Header = "Rain in Centimeters",
            .ValueMember = "Rain",
            .Colorizer = heatMapGradientColorizer
        }
    }
    Me.radHeatMap1.HeatMapElement.RowHeaderWidth = 80
    AddHandler Me.radHeatMap1.HeaderCellPainting, AddressOf RadHeatMap1_HeaderCellPainting1
    Me.radHeatMap1.Definition = horizontalDefinition
End Sub

Private Sub RadHeatMap1_HeaderCellPainting1(ByVal sender As Object, ByVal e As HeatMapHeaderCellPaintingEventArgs)
    If e.Index.ColumnIndex = -1 AndAlso e.Index.RowIndex > -1 Then
        Dim heatMapItem = Me.radHeatMap1.Definition.GetDataItem(New CellIndex(e.Index.RowIndex, 0))
        Dim dataBoundItem = TryCast(heatMapItem.DataBoundItem, TempInfo)
        e.Text = dataBoundItem.Year.ToString("yyyy") & "  " + dataBoundItem.Month
    End If
End Sub


WinForms RadHeatMapMap Data Binding Horizontal Definition

Design Time

It is possible to specify the data member properties via the Smart Tag. The following tutorial demonstrates how to bind the heat map control to a BindingSource object in the current form.

WinForms RadHeatMapMap Data Binding Design Time

See Also

In this article