Controls – Timeline

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

The TimeActivityGraphHost 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 TimeActivityGraph or TimeLineGraph or TimeIBarGraph class. The TimeActivityGraph implementation allows plotting of markers with start and end dates such as medical prescriptions. 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 TimeActivityGraphHost control, the following keyboard shortcuts are available:

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

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

<local:TimeActivityGraphHost x:Name="TimeActivityGraphHost"
   Background="#F3F3F3" TimeFrequencySelectedIndex="9"
   BorderBrush="#999999" BorderThickness="1" FontFamily="Arial"   ... ... ...
</local:TimeActivityGraphHost>

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 TimeActivityGraphHost 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 TimeActivityGraphHost control are as follows:

Other control properties that should be defined to control the visual features of the TimeActivityGraphHost 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 TimeActivityGraphHost control.

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

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

• TimeActivityGraph
• TimeLineGraph
• TimeIBarGraph

The XAML that would define the three supported graphs would be:

<local:TimeActivityGraphHost.Graphs>
    <local:TimeActivityGraph Title="Paracetamol"
        Background="#EBCCCC"
        Style="{StaticResource MedsTimelineStyle}"
        local:TimeActivityGraphHost.SectionName="MEDICATIONS" />
 
    <local:TimeLineGraph Title="Temperature" Units="°C"
        UnitsDescription="°C: Degrees Celsius"
        Background="#EBCCCC"
        InterpolationLineColor="#990000"
        DataMarkerTemplate="{StaticResource Square}"
        Style="{StaticResource TimelineStyle}"
        Height="185"
        ShowNormalRange="True" 
        NormalRangeMaximumValue="37"
        NormalRangeMinimumValue="35"
        NormalRangeBrush="Beige"
        YAxisMajorInterval="1"
        YAxisIntervalMinimumHeight="20"
        YAxisMaxValue="45"
        YAxisMinValue="30"
        local:TimeActivityGraphHost.SectionName="OBSERVATIONS" />
 
    <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 TimelineStyle}"
        Height="210"
        ShowNormalRange="False"
        YAxisMajorInterval="10"
        YAxisIntervalMinimumHeight="17"
        YAxisMaxValue="300"
        YAxisMinValue="0"
        local:TimeActivityGraphHost.SectionName="OBSERVATIONS" />
</local:TimeActivityGraphHost.Graphs>

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

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

Common properties available to all graphs

Additional properties for TimeActivityGraph

Additional properties for TimeLineGraph and TimeIBarGraph

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 TimeActivityGraphHost 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 ParacetamolData}"

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 TimeActivityGraphHost, these can be referenced using:

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

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 TimeActivityPoint, would be:

<local:FilteredCollection x:Key="ParacetamolData">
    <local:TimeActivityPoint StartDate="16-Mar-2006 12:10:00" EndDate="23-Mar-2006 22:00:00" 
                             DataMarkerTemplate="{StaticResource DataMarker}" />
    <local:TimeActivityPoint StartDate="05-Jan-2008 11:40:00" EndDate="05-Jan-2008 11:55:00"
                             DataMarkerTemplate="{StaticResource DataMarker}" />
    ...
    <local:TimeActivityPoint StartDate="05-Jan-2008 12:10:00" EndDate="12-Jan-2008 22:00:00"
                             DataMarkerTemplate="{StaticResource DataMarker}" />
    <local:TimeActivityPoint StartDate="16-Mar-2009 11:40:00" EndDate="16-Mar-2009 11:55:00"
                             DataMarkerTemplate="{StaticResource DataMarker}" />
</local:FilteredCollection>

For TimeActivityGraph, the X-axis values of the point are determined through the definition of the previously mentioned PointTemplate. This template merely has to define the mapping of the X-axis values to the required internal GraphPoint properties for X1 and X2.

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

<DataTemplate x:Key="TimeActivityPoint">
    <local:GraphPoint X1="{Binding StartDate}" X2="{Binding EndDate}" 
                      DataMarkerTemplate="{Binding DataMarkerTemplate}" />
</DataTemplate>

In this instance the properties StartDate, EndDate and DataMarkerTemplate from the TimeActivityPoint object are mapped to the corresponding X1, X2 and DataMarkerTemplate properties of GraphPoint.

For TimeLineGraph and TimeIBarGraph, in addition to the X-axis values, it is also required to map 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}" X1="{Binding DateTime}" />
</DataTemplate>

TimeActivityGraph

Unlike TimeLineGraph and TimeIBarGraph, TimeActivityGraph can have different data marker for anything that is plotted on the graph and different label for each item. For example, the sample application has different markers for items with different types of duration (no duration, specific duration and open duration).

The Toolkit has provided the TimeActivityPoint object which exposes two properties DataMarkerTemplate and LabelTemplate. As mentioned in the data binding section, these properties need to be mapped with the internal GraphPoint class. The sample application has an example DataMarker called CurvedInterpolationLine.

In order to provide a custom data marker we would need to define a DataTemplate and then specify it in the TimeActivityPoint object.

<DataTemplate x:Key="DataMarker">
    <samplepages:CurvedInterpolationLine />
</DataTemplate>

<local:TimeActivityPoint StartDate="16-Mar-2006 12:10:00" EndDate="23-Mar-2006 22:00:00" 
                         DataMarkerTemplate="{StaticResource DataMarker}" />

TimeLineGraph and TimeIBarGraph

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 TimeActivityGraphStyles.xaml and generic.xaml files that contain the full template specification for all the styles and data templates, specifying the layout and visuals for the rendering of the Timeline control. The key Style elements Target Type definitions are:

• TimeActivityGraphHost
• TimeActivityGraph
• TimeLineGraph
• TimeIBarGraph

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

The TimeActivityGraph, TimeLineGraph and TimeIBarGraph derive from TimeGraphBase. As such, a new style for the TimeGraphBase 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:TimeGraphBase" x:Key="TimelineStyle">
   ... ... ...
</Style>

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

Style="{StaticResource TimelineStyle}"

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 TimeActivityGraphHost, 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 TimeActivityGraphHost template within the TimeActivityGraphStyles.xaml file.

To modify these values, the application XAML for the TimeActivityGraphHost 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).