Controls – Graphing

In reviewing the programmability of the Graphing control, an understanding of the core object hierarchy of the implementation is required:

The GraphHost class is a composite control that represents the single element to be consumed within an application for the representation of multiple graphs. It is this control that manages instances of the graph controls and the other key elements, such as state management, visual time window selection, and graph selection.

Instances of a graph control to which data is bound are either a TimeLineGraph or TimeIBarGraph class. The TimeLineGraph implementation allows plotting of a line graph with markers. The TimeIBarGraph implementation allows plotting of data, where each point is represented by a high and low value, such as in blood pressure.

When graphs are contained within a GraphHost control, the following keyboard shortcuts are available:

When focus in on an individual graph control, the following keyboard shortcuts are available:

When focus is on the VFL, the following keyboard shortcuts are available:

To consume the hosting control within Silverlight or WPF, a reference to the graph hosting class, GraphHost, needs to be created.

<local:GraphHost x:Name="GraphHost"
   Background="#F3F3F3" TimeFrequencySelectedIndex="9"
   BorderBrush="#999999" BorderThickness="1" FontFamily="Arial"
   DataPointLabelsVisibility="Collapsed"
   InterpolationLinesVisibility="True" GridLinesVisibility="Both">
   ... ... ...
</local:GraphHost>

The namespace element that needs to be added within the XAML is:

xmlns:local="clr-namespace:Microsoft.Cui.Controls;assembly=Microsoft.Cui.Controls"

At this point, the GraphHost control can be consumed within the application. The next step will be to define the graph elements that are to be represented within the control and, if necessary, override any necessary visual styles.

The key custom properties that are available for the GraphHost control are as follows:

Other control properties that should be defined to control the visual features of the GraphHost control are BorderThickness, BorderBrush, and FontFamily; all of which are based off the standard Control definition.

The FontFamily property, due to inheritance, defines the base font that will be used by all graphs within the host. The corresponding FontSize will have little effect as most elements independently define their own font size.

Other properties, such as Background, will have little effect as they are explicitly defined, within the XAML, for elements contained within the GraphHost control.

The possible set of graph panels that make up the data to be rendered by the Graphing control should to be defined with the GraphHost element. This is achieved through the GraphHost.Graphs collection property within the XAML definition.

The XAML that would define the required graphs for vital statistics covering Temperature, Pulse Rate, Respiratory Rate, Blood Pressure, and Oxygen Saturation would be:

<local:GraphHost.Graphs>
    <local:TimeLineGraph Title="Temperature" Units="°C"
        UnitsDescription="°C: Degrees Celsius"
        Background="#EBCCCC"
        InterpolationLineColor="#990000"
        DataMarkerTemplate="{StaticResource Square}"
        Style="{StaticResource OverriddenDefaultStyle}"
        Height="185"
        ShowNormalRange="True" 
        NormalRangeMaximumValue="37"
        NormalRangeMinimumValue="35"
        NormalRangeBrush="Beige"
        YAxisMajorInterval="1"
        YAxisIntervalMinimumHeight="20"
        YAxisMaxValue="45"
        YAxisMinValue="30" />
 
    <local:TimeLineGraph Title="Pulse rate" Units="beats per minute"
        Background="#F5E0CC"
        InterpolationLineColor="#CC6600"
        DataMarkerTemplate="{StaticResource Circle}"
        Style="{StaticResource OverriddenDefaultStyle}"
        Height="194"
        ShowNormalRange="True" 
        NormalRangeMaximumValue="100" 
        NormalRangeMinimumValue="60"
        NormalRangeBrush="Beige"
        YAxisMajorInterval="10"
        YAxisIntervalMinimumHeight="25"
        YAxisMaxValue="200"
        YAxisMinValue="0" />
 
    <local:TimeIBarGraph Title="Blood pressure" Units="mmHg"
        UnitsDescription="mmHg: Millimetres of mercury"
        Background="#D6EBD6"
        PointTemplate="{StaticResource IBarPoint}" 
        DataMarkerTemplate="{StaticResource IBarMarker}"
        LabelTemplate="{StaticResource IBarLabel}"
        Style="{StaticResource OverriddenDefaultStyle}"
        Height="210"
        ShowNormalRange="False"
        YAxisMajorInterval="10"
        YAxisIntervalMinimumHeight="17"
        YAxisMaxValue="300"
        YAxisMinValue="0" />
 
    <local:TimeLineGraph Title="Respiratory rate" Units="breaths per minute"
        Background="#E7D3E7"
        InterpolationLineColor="#B966B9"
        DataMarkerTemplate="{StaticResource Triangle}"
        Style="{StaticResource OverriddenDefaultStyle}"
        Height="162"
        ShowNormalRange="True"
        NormalRangeMaximumValue="20"
        NormalRangeMinimumValue="10"
        NormalRangeBrush="Beige"
        YAxisMajorInterval="10"
        YAxisIntervalMinimumHeight="40"
        YAxisMaxValue="80"
        YAxisMinValue="0" />
 
    <local:TimeLineGraph Title="Oxygen saturation" Units="%"
        Background="#96C4F3" 
        InterpolationLineColor="#2932E0"
        DataMarkerTemplate="{StaticResourceDiamond}"
        Style="{StaticResourceOverriddenDefaultStyle}"
        Height="144"
        ShowNormalRange="True"
        NormalRangeMaximumValue="100"
        NormalRangeMinimumValue="90"
        NormalRangeBrush="Beige"
        YAxisMajorInterval="10"
        YAxisIntervalMinimumHeight="50"
        YAxisMaxValue="100"
        YAxisMinValue="0"
        YAxisPadding="0,50,0,5" />
 
</local:GraphHost.Graphs>

Currently, when defining a graph element, two supported graph types are allowed:

• TimeLineGraph
• TimeIBarGraph

In addition to being contained within a GraphHost element, graph can also be referenced individually. In this instance the hosting page will be responsible for any necessary state management that is undertaken by the GraphHost element.

The key custom properties that are available to the graph control are as follows:

In addition to the key custom properties, various visual elements of a graph can be defined to alter the appearance of an individual graph. These visual elements are as follows:

An additional property for the TimeIBarGraph is available, called:

• EnableIBarInterpolations

This property defines if interpolation lines are enabled for the TimeIBarGraph. The default value for this property is false, and is used to prevent interpolation lines from being displayed. This enables the TimeIBarGraph to be displayed without interpolation lines, whilst hosted by a GraphHost control, yet have them displayed for the TimeLineGraph.

Data binding of the graph to the required data elements is achieved via the UserControl DataContext.

Binding data to a specific graph instance is best achieved through code; unless binding to static data which can also be achieved through XAML as follows:

DataContext="{StaticResource PatientTemperatureData}"

To perform the data binding a reference to the required graph instance is required. For an individual graph, this can be achieved via the control name. For a collection of graphs within a GraphHost, these can be referenced using:

ObservableCollection<TimeGraphBase> graphs = this.GraphHost.Graphs;

Once the collection of graph objects has been referenced, the DataContext for each graph can be defined. The method GetGraphByName(string), of GraphHost, allows a single graph within the collection to be directly accessed.

The DataContext for a graph must implement the IEnumerable interface. The Toolkit provides the following collection types:

• FilteredCollection
• NonFilteredCollection

The definition of a FilteredCollection within XAML, where the FilteredCollection contains a collection of objects of type TimePoint, would be:

<local:FilteredCollection x:Key="Patient1TemperatureData">
    <local:TimePoint Y1="38.4" Value="30-Oct-2008 21:37:00" />
    <local:TimePoint Y1="38.5" Value="30-Oct-2008 21:50:00" />
    ...
    <local:TimePoint Y1="36.4" Value="03-Nov-2008 08:00:00" />
    <local:TimePoint Y1="36.4" Value="03-Nov-2008 14:00:00" />
</local:FilteredCollection>

The objects that are returned from the IEnumerable interface must support casting to a DateTime value. This can be achieved either through the implementation of the IConvertible interface, or through support for an implicit cast to a DateTime value. This casted value is used to determine the X-axis value of the point.

The X-axis value of the point is determined through the definition of the previously mentioned PointTemplate. This template merely has to define the mapping of the Y-axis values to the required internal GraphPoint properties for Y1 and Y2.

The XAML used to achieve this mapping for the TimeIBarGraph implementation is as follows:

<DataTemplate x:Key="IBarPoint">
    <ctl:GraphPoint Y1="{Binding Y1}" Y2="{Binding Y2}"/>
</DataTemplate>

In this instance the properties Y1 and Y2 from the TimePoint object are mapped to the corresponding Y1 and Y2 properties of GraphPoint.

When defining a graph element one of the optional properties that can be defined is a DataMarkerTemplate. By default, the template is defined as a square of 5 pixels; achieved through the XAML specification:

<DataTemplate x:Key="ELEMENT_dataMarkerTemplate">
    <Rectangle Canvas.ZIndex="10" Height="5" Width="5"
        Fill="Blue" Stroke="Black" StrokeThickness="3"
        local:GraphBase.XOffset="-2.5" local:GraphBase.YOffset="-2.5" />
</DataTemplate>

However, it is possible to define templates specific to a graph instance. This is achieved by specifying the required DataTemplate within the application XAML. An example of DataTemplate specification for a Square, Circle, Triangle and Diamond would be:

<DataTemplate x:Key="Square">
    <Rectangle Canvas.ZIndex="10" Width="5" Height="5" Fill="#990000"
        Stroke="Black" StrokeThickness="1" 
        local:GraphBase.XOffset="-2.5" local:GraphBase.YOffset="-2.5" />
</DataTemplate>
<DataTemplate x:Key="Circle">
    <Ellipse Canvas.ZIndex="10" Width="5" Height="5" Fill="#CC6600"
        Stroke="Black" StrokeThickness="1"
        local:GraphBase.XOffset="-2.5" local:GraphBase.YOffset="-2.5" />
</DataTemplate>
<DataTemplate x:Key="Triangle">
    <Polygon Canvas.ZIndex="10" Width="6" Height="6" Fill="#B966B9"
        Stroke="Black" StrokeThickness="1"
        local:GraphBase.XOffset="-3" local:GraphBase.YOffset="-3"
        Points="0,6 6,6 3,0" />
</DataTemplate>
<DataTemplate x:Key="Diamond">
    <Rectangle Canvas.ZIndex="10" Width="5" Height="5" Fill="#2932E0"
        Stroke="Black" StrokeThickness="1"
        local:GraphBase.XOffset="-2.5" local:GraphBase.YOffset="-2.5">
        <Rectangle.RenderTransform>
            <RotateTransform Angle="45" CenterX="2.5" CenterY="2.5" />
        </Rectangle.RenderTransform>
    </Rectangle>
</DataTemplate>

The specifications of the X and Y offset are necessary to ensure the center of the data marker represents the actual point on the graph.

For TimeIBarGraph implementation of the data marker template is a little different. In this case the height of the template needs be determined by the data bounds values. The XAML for the two common representations for range values, namely an IBar and an Arrow, is defined as:

<DataTemplate x:Key="IArrowMarker">
    <Grid Canvas.ZIndex="10" Height="10" Width="8"
        ctl:GraphBase.XOffset="-4" ctl:GraphBase.YOffset="0"
                ctl:GraphBase.SnapToPixels="True">
        <Grid.RowDefinitions>
            <RowDefinition Height="4"/>
            <RowDefinition Height="*"/>
            <RowDefinition Height="4"/>
        </Grid.RowDefinitions>
    <Grid Grid.Row="0" Height="4">
        <Polyline Points="0,4, 4,0, 8,4" Stroke="Black" StrokeThickness="1"
            StrokeStartLineCap="Round" StrokeEndLineCap="Round" />
        <Polyline Points="4,4, 4,0"  Stroke="Black" StrokeThickness="2"
            StrokeStartLineCap="Square" StrokeEndLineCap="Round"/>
    </Grid>
    <Rectangle Grid.Row="1" HorizontalAlignment="Center" Fill="Black" Width="2"/>
        <Grid Grid.Row="2" Height="4">
            <Polyline Points="0,0, 4,4, 8,0" Stroke="Black" StrokeThickness="1"
                StrokeStartLineCap="Round" StrokeEndLineCap="Round" />
            <Polyline Points="4,0, 4,4"  Stroke="Black" StrokeThickness="2"
                StrokeStartLineCap="Square" StrokeEndLineCap="Round"/>
        </Grid>
    </Grid>
</DataTemplate>
 
<DataTemplate x:Key="IBarMarker">
    <Grid Canvas.ZIndex="10" Height="9" Width="9" ctl:GraphBase.XOffset="-4.5"
        ctl:GraphBase.YOffset="-1.5" ctl:GraphBase.SnapToPixels="True">
        <Grid.RowDefinitions>
            <RowDefinition Height="3"/>
            <RowDefinition Height="*"/>
            <RowDefinition Height="3"/>
        </Grid.RowDefinitions>
        <Rectangle Grid.Row="0" VerticalAlignment="Top"
            Height="3" Width="9" Fill="Black"/>
        <Rectangle Grid.Row="1" HorizontalAlignment="Center"
            Fill="Black" Width="1"/>
        <Rectangle Grid.Row="2" VerticalAlignment="Bottom"
            Height="3" Width="9" Fill="Black"/>
    </Grid>
</DataTemplate>

Once the DataTemplate specifications have been made, the corresponding DataMarkerTemplate property can be defined for each Graph; such as:

DataMarkerTemplate="{StaticResource Square}"
DataMarkerTemplate="{StaticResource Diamond}"
DataMarkerTemplate="{StaticResource IBarMarker}"

The source code for the control includes a generic.xaml file that contains the full template specification for all the styles and data templates, specifying the layout and visuals for the rendering of the Graphing control. The key Style elements Target Type definitions are:

• GraphHost
• TimeLineGraph
• TimeIBarGraph

To change the layout of the elements within the control, the GraphHost entry must be modified. It is this entry that defines the component of the GraphHost and how graphs are laid out within the control.

The TimeLineGraph and TimeIBarGraph both derive from TimeAndYGraphBase. As such, a new style for the TimeAndYGraphBase can be created that overrides any required templates for a graph instance. For example, a new style can be defined in the application XAML file, with the element:

<Style TargetType="ctl:TimeAndYGraphBase" x:Key="OverriddenDefaultStyle">
   ... ... ...
</Style>

This style can then be applied to a graph using the following Style property definition:

Style="{StaticResource OverriddenDefaultStyle}"

Creating a new style in this fashion allows not only the style of a graph, but also the layout to be changed. To change specific elements within the graph, such as Title Area, Point Templates and Button Definitions, the corresponding XAML definition would be taken from the generic version, copied into the application XAML file, and modified accordingly.

Within GraphHost, two special graph templates are defined that represent the top and bottom axis markers. These graph templates are not data bound, but are used solely to show a common set of axis markers; rather than each individual graph having their own axis markers.

By default, the time ranges defined for the control span a range covering 5 minutes to 100 years. This definition is contained within the definition of the GraphHost template within the generic.xaml file.

To modify these values, the application XAML for the GraphHost element should be modified. The element defining the time ranges is a TimeFrequency collection, which is Data Bound to a ComboBox control:

<local:TimeFrequencyCollection x:Key="tfc">
    <local:TimeFrequency Unit="Minute" Value="5"/>
    <local:TimeFrequency Unit="Minute" Value="15"/>
    <local:TimeFrequency Unit="Hour" Value="1"/>
    <local:TimeFrequency Unit="Hour" Value="2"/>
    <local:TimeFrequency Unit="Hour" Value="4"/>
    <local:TimeFrequency Unit="Hour" Value="6"/>
    <local:TimeFrequency Unit="Hour" Value="12"/>
    <local:TimeFrequency Unit="Hour" Value="24"/>
    <local:TimeFrequency Unit="Hour" Value="48"/>
    <local:TimeFrequency Unit="Day" Value="5"/>
    <local:TimeFrequency Unit="Day" Value="10"/>
    <local:TimeFrequency Unit="Day" Value="15"/>
    <local:TimeFrequency Unit="Day" Value="20"/>
    <local:TimeFrequency Unit="Month" Value="1"/>
    <local:TimeFrequency Unit="Month" Value="3"/>
    <local:TimeFrequency Unit="Month" Value="6"/>
    <local:TimeFrequency Unit="Month" Value="9"/>
    <local:TimeFrequency Unit="Month" Value="12"/>
    <local:TimeFrequency Unit="Month" Value="18"/>
    <local:TimeFrequency Unit="Year" Value="2"/>
    <local:TimeFrequency Unit="Year" Value="5"/>
    <local:TimeFrequency Unit="Year" Value="10"/>
    <local:TimeFrequency Unit="Year" Value="20"/>
    <local:TimeFrequency Unit="Year" Value="100"/>
</local:TimeFrequencyCollection>

To modify the values that are allowed to be selected, this collection should be modified. The supported units are Second, Minute, Hour, Day, Week, Month, and Year. It is assumed there are 31 days in a month, 62 days in 2 months, 92 days in 3 months, 365 days in a year (corrected to 366 days for each possible interval of 4 years).

The tables below list some of the key XAML elements parts found within generic.xaml.

Within GraphHost, there are some key elements that define the layout and visuals of the components of the control. The position and visual definition of these elements can be modified as required. These elements are defined in the table below:

Within each graph element, the public properties that can be specified are defined as XAML elements within the base Style. To override the default visuals for all graph instances, these values can be changed accordingly.  These elements are defined in the table below.

The definitions contained within generic.xaml for the base TimeLineGraph and TimeIBarGraph are defined based on the assumption that graphs will be rendered as independent elements. When graphs are hosted within GraphHost, overridden style that hides certain elements, such as the start and end dates, should be used; as these are managed as specialized graph entries within GraphHost. The sample application has an example of such a style; called OverriddenDefaultStyle.