Telerik UI for Windows Phone by Progress

Annotations are visual elements that can be used to highlight certain areas on the plot area and denote statistical significance.

The Chart provides the following types of annotations: Cartesian Grid Line, Cartesian Plot Band, Polar Axis Grid Line, Polar Axis Plot Band, Radial Axis Grid Line, Radial Axis Plot Band and custom Cartesian and Polar annotations.

Topic Contents:

Annotation Classes Hierarchy

Rad Chart View-annotations-classes

Adding Annotations to the Chart

Every chart contains an Annotations collection which holds all the annotations plotted on the chart.

Note

The chart will visualize an annotation only if it contains data.

Cartesian Chart

When adding GridLine or PlotBand annotations to RadCartesianChart, you have to bind their Axis property to either the vertical or horizontal axis. That way the annotation knows what its orientation is, and also the coordinates on which it has to be rendered.

CopyXAML
<telerik:RadCartesianChart x:Name="cartesianChart">

    <telerik:RadCartesianChart.Annotations>
        <telerik:CartesianGridLineAnnotation Axis="{Binding ElementName=verticalAxis}" 
                                                Value="6" Stroke="Red" StrokeThickness="1"/>
        <telerik:CartesianGridLineAnnotation Axis="{Binding ElementName=horizontalAxis}" 
                                                Value="2.8" Stroke="Blue" StrokeThickness="1"/>
    </telerik:RadCartesianChart.Annotations>

    <telerik:RadCartesianChart.VerticalAxis>
        <telerik:LinearAxis x:Name="verticalAxis"/>
    </telerik:RadCartesianChart.VerticalAxis>

    <telerik:RadCartesianChart.HorizontalAxis>
        <telerik:LinearAxis x:Name="horizontalAxis"/>
    </telerik:RadCartesianChart.HorizontalAxis>
</telerik:RadCartesianChart>
CopyC#
cartesianChart.Annotations.Add(
    new CartesianGridLineAnnotation 
    { 
        Axis = cartesianChart.VerticalAxis, 
        Value = 6, Stroke = new SolidColorBrush(Colors.Red), 
        StrokeThickness = 1
    });
cartesianChart.Annotations.Add(
    new CartesianGridLineAnnotation 
    { 
        Axis = cartesianChart.HorizontalAxis, 
        Value = 2.8, Stroke = new SolidColorBrush(Colors.Blue), 
        StrokeThickness = 1
    });

Here is the result

Polar Chart

Annotations derived from the PolarChartAnnotation class, on the other hand, do not require such binding.

CopyXAML
<telerik:RadPolarChart>

    <telerik:RadPolarChart.Annotations>
        <telerik:PolarAxisGridLineAnnotation Value="2" Stroke="Red"/>
        <telerik:PolarAxisGridLineAnnotation Value="7" Stroke="LightGreen"/>
        <telerik:PolarAxisGridLineAnnotation Value="8" Stroke="LightBlue"/>
    </telerik:RadPolarChart.Annotations>

    <telerik:RadPolarChart.RadialAxis>
        <telerik:NumericRadialAxis/>
    </telerik:RadPolarChart.RadialAxis>

    <telerik:RadPolarChart.PolarAxis>
        <telerik:PolarAxis/>
    </telerik:RadPolarChart.PolarAxis>

</telerik:RadPolarChart>
CopyC#
polarChart.Annotations.Add(
    new PolarAxisGridLineAnnotation { Value = 2, Stroke = new SolidColorBrush(Colors.Red) });
polarChart.Annotations.Add(
    new PolarAxisGridLineAnnotation { Value = 7, Stroke = new SolidColorBrush(Colors.LightGreen) });
polarChart.Annotations.Add(
    new PolarAxisGridLineAnnotation { Value = 8, Stroke = new SolidColorBrush(Colors.LightBlue) });

For the result check the image of the Polar Axis Grid Line Annotation

Annotation types

Conceptually there are 3 types of annotations - grid line, plot band and custom. Below is comparison for each depending on the scenario - Cartesian, Polar or Radial.

Grid Line

Cartesian / Polar / Radial Grid Line Comparison

In the case of the Cartesian chart, the grid line represents a vertical or horizontal line which crosses the entire plot area.

CartesianGridLineAnnotation
Rad Chart View-annotations-cartesian-gridline

Polar axis grid lines represent concentric circles that cross the polar axis at the corresponding Value.

PolarAxisGridLineAnnotation
Rad Chart View-annotations-polar-gridline

RadialAxisGridLineAnnotation is basically the radius of the PolarChart.

RadialAxisGridLineAnnotation
Rad Chart View-annotations-radial-gridline

Properties

Common:

  • DashArray

  • Stroke

  • StrokeThickness

Cartesian:

  • Axis

    The Cartesian GridLine needs a reference to either the Vertical or the Horizontal Axis.

  • Value (of type object)

    The place on the axis (to which annotation is bound to) where line crosses it.

    *When the axis is numeric (Linear or Logarithmic) a numeric value is expected and when it is a CategoricalAxis - a category.

  • Label

    The string, defining the label.

  • LabelDefinition

    Check the Annotation Labels section for more details.

Polar:

  • Value (of type double)

    Specifies the location on the polar axis (the radius), where the grid line will cross.

Radial:

  • Value (of type object)

    Specifies the location on the radial axis, where the grid line will cross.

    *When the radial axis is NumericRadialAxis a numeric value is expected and when it is a CategoricalRadialAxis - a category.

Plot Band

Plot Band Annotation is a stripe, crossing its corresponding axis, specified by the From and To properties

Cartesian / Polar / Radial Plot Band Comparison

The Cartesian Plot Band Annotation is either a horizontal or a vertical stripe, which crosses entirely the vertical or horizontal axis, respectively.

CopyXAML
<telerik:CartesianPlotBandAnnotation Axis="{Binding ElementName=verticalAxis}" From="4.3" To="5.5"/>
<telerik:CartesianPlotBandAnnotation Axis="{Binding ElementName=horizontalAxis}" From="0.5" To="1.5"/>
CartesianPlotBandAnnotation
Rad Chart View-annotations-cartesian-plotband

The Polar axis plot band annotation resembles a donut.

CopyXAML
<telerik:PolarAxisPlotBandAnnotation From="6" To="9"/>
PolarAxisPlotBandAnnotation
Rad Chart View-annotations-polar-plotband

RadialAxisPlotBandAnnotation represents visually a sector of the circle (pie slice).

RadialAxisPlotBandAnnotation
Rad Chart View-annotations-radial-plotband

A plotband starting from 180 degrees and ending in 270 degrees will look like this:

CopyXAML
<telerik:RadialAxisPlotBandAnnotation From="180" To="270" />
RadialAxisPlotBandAnnotation
Rad Chart View-annotations-polar-plotband-180-270

If you wonder how to annotate the bigger segment from the image above, then you should switch the From and To values. Voilà:

CopyXAML
<telerik:RadialAxisPlotBandAnnotation From="270" To="180" />
RadialAxisPlotBandAnnotation
Rad Chart View-annotations-polar-plotband-270-180

Properties

Common:

  • Fill

  • DashArray

  • Stroke

  • StrokeThickness

Cartesian:

  • Axis

    The Cartesian PlotBand needs a reference to either the Vertical or the Horizontal Axis.

  • From (of type object)

    The starting point for the plot band.

    *When the axis is numeric (Linear or Logarithmic) a numeric value is expected and when it is a CategoricalAxis - a category.

  • To (of type object)

    The ending point for the plot band.

    *When the axis is numeric (Linear or Logarithmic) a numeric value is expected and when it is a CategoricalAxis - a category.

  • Label

    The string, defining the label.

  • LabelDefinition

    Check the Annotation Labels section for more details.

Polar:

  • From (of type double)

    The starting point for the plot band.

    To (of type double)

    The ending point for the plot band.

Radial:

  • From (of type object)

    The starting point for the plot band.

    *When the radial axis is NumericRadialAxis a numeric value is expected and when it is a CategoricalRadialAxis - a category.

  • To (of type object)

    The ending point for the plot band.

    *When the radial axis is NumericRadialAxis a numeric value is expected and when it is a CategoricalRadialAxis - a category.

Custom Annotation

The CartesianCustomAnnotation and PolarCustomAnnotation classes expose the functionality of adding user defined annotations to respectively the RadCartesianChart and RadPolarChart

Cartesian and Polar examples

The Cartesian Custom Annotation, renders its Content starting at the specified position(HorizontalValue, VerticalValue).

CartesianCustomAnnotation
Rad Chart View-annotations-cartesian-custom
CopyXAML
<telerik:RadCartesianChart.Annotations>
    <telerik:CartesianCustomAnnotation HorizontalValue="2" VerticalValue="2"
                                        HorizontalAlignment="Center" VerticalAlignment="Center" VerticalOffset="-8">
        <telerik:CartesianCustomAnnotation.Content>
            <StackPanel Orientation="Vertical">
                <TextBlock Text="Singularity location"/>
                <Rectangle Width="100" Height="100">
                    <Rectangle.Fill>
                        <RadialGradientBrush Center="0.5,0.5" RadiusX="0.5" RadiusY="0.5" GradientOrigin="0.5,0.5">
                            <GradientStop Color="Purple" Offset="0.2"></GradientStop>
                            <GradientStop Color="Violet" Offset="0.6"></GradientStop>
                            <GradientStop Color="Transparent" Offset="1"></GradientStop>
                        </RadialGradientBrush>
                    </Rectangle.Fill>
                </Rectangle>
            </StackPanel>
        </telerik:CartesianCustomAnnotation.Content>
    </telerik:CartesianCustomAnnotation>
</telerik:RadCartesianChart.Annotations>

The content of the PolarCustomAnnotation is rendered at the (RadialValue, PolarValue) position.

PolarCustomAnnotation
Rad Chart View-annotations-polar-custom
CopyXAML
<telerik:RadPolarChart.Annotations>
    <telerik:PolarCustomAnnotation PolarValue="20" RadialValue="300" 
                                   HorizontalAlignment="Center" VerticalAlignment="Center">
        <telerik:PolarCustomAnnotation.Content>
                <Path Stroke="Red" StrokeThickness="2">
                    <Path.Data>
                        <PathGeometry>
                            <PathGeometry.Figures>
                                <PathFigure StartPoint="0,0">
                                    <LineSegment Point="20,30"/>
                                </PathFigure>
                                <PathFigure StartPoint="0,30">
                                    <LineSegment Point="20,0"/>
                                </PathFigure>
                            </PathGeometry.Figures>
                        </PathGeometry>
                    </Path.Data>
                </Path>
        </telerik:PolarCustomAnnotation.Content>
    </telerik:PolarCustomAnnotation>
</telerik:RadPolarChart.Annotations>

Propeties

Common:

  • Content

    Used for setting the content of the annotation.

  • ContentTemplate

    Used for defining the DataTemplate used to display the contentof the annotation.

  • HorizontalOffset

    Specify an offset in pixels, applied after the annotation is positioned on the axis depending on its Horizontal/Vertical or Polar/Radial values.

  • VerticalOffset

    Specify an offset in pixels, applied after the annotation is positioned on the axis depending on its Horizontal/Vertical or Polar/Radial values.

Cartesian:

  • HorizontalValue

    The place on the Horizontal Axis, where the annotation is positioned.

    *When the axis is numeric (Linear or Logarithmic) a numeric value is expected and when it is a CategoricalAxis - a category.

  • VerticalValue

    The place on the Horizontal Axis, where the annotation is positioned.

    *When the axis is numeric (Linear or Logarithmic) a numeric value is expected and when it is a CategoricalAxis - a category.

Polar:

  • PolarValue

    The place on the Polar Axis, where the annotation is positioned.

  • RadialValue

    The place on the Radial Axis, where the annotation is positioned.

    *When the radial axis is NumericRadialAxis a numeric value is expected and when it is a CategoricalRadialAxis - a category.

Annotation Labels

The Cartesian Grid Line and Cartesian Plot Band annotations provide the ability to add labels to them.

The CartesianChartAnnotation class provides Label property to specify the label string and LabelDefinition to control its properties like Format, Template and positioning.

Location

The Location ChartAnnotationLabelDefinition property allows you to position the label in 5 different positions, as illustrated below:

Rad Chart View-annotations-label-location

Horizontal / Vertical Alignment

In conjunction with Location property, you can use the Horizontal/Vertical Alignment properties of the ChartAnnotationLabelDefinition to further specify the position of the label.

Refer to the table below for for possible combinations of these properties:

Rad Chart View-annotations-alignment-location

Horizontal / Vertical Offset

Besides the Location, HorizontalAlignment and Vertical Alignment, you can use the HorizontalOffset and VerticalOffset to specify a pixel offset.

Note that the offset is applied after the aforementioned properties.