Colin Eberhardt's Adventures in .NET » attached behaviour

Automatically Showing ToolTips on a Trimmed TextBlock (Silverlight)

Colin Eberhardt — Thu, 06 Jan 2011 08:18:54 +0000

Silverlight 4 added TextTrimming=”WordEllipsis”, which trims the text that a TextBlock displays based on the available width. This blog post describes a simple method for automatically showing the full text as a tooltip whenever the text is trimmed. This is presented as an attached behaviour.

UPDATE: I have updated this solution to support both WPF and Silverlight, see my recent blog post.

The TextTrimming feature of SL4 allows us to worry a little less about the layout of our applications, giving the option to use fixed widths when rendering text. This can be particularly useful if you have to localize your application. However, arbitrarily trimming the text without providing the user with a mechanism to see the full text is not great for the user. A simple solution is to use a tooltip to present the full text.

Detecting whether the a TextBlock’s text is being trimmed is not something that is available from the TextBlock’s API, there is no IsTrimmed property! A quick search of the Silverlight forums drew a dead end. I did find a decent WPF solution, however this uses various parts of the WPF API that are not present in Silverlight.

Eventually I found that there is a very simple solution … quoting from the MSDN page on Text and Fonts:

You can detect clipped text programmatically because ActualWidth for a TextBlock always reports the expanded size of the text, even if it does not fit in the layout container. If you know where to read the Width for the layout container that is doing the clipping, you can compare these two values.

Therefore, if a TextBlock is trimming the text, the reported ActualWidth of the TextBlock will be the width that the TextBlock requires to render the text in its entirety, not the actual width of the rendered text!

In the example above, the Width of the TextBlock is set explicity, however it is more common that the width of TextBlock is determined by its parent container, a Grid for example.

To wrap this functionality up into something re-useable, I have created a AutoToolTip attached behaviour. The code for this is shown below:

public class TextBlockUtils
{
  /// 
  /// Gets the value of the AutoTooltipProperty dependency property
  /// 
  public static bool GetAutoTooltip(DependencyObject obj)
  {
    return (bool)obj.GetValue(AutoTooltipProperty);
  }
 
  /// 
  /// Sets the value of the AutoTooltipProperty dependency property
  /// 
  public static void SetAutoTooltip(DependencyObject obj, bool value)
  {
    obj.SetValue(AutoTooltipProperty, value);
  }
 
  /// 
  /// Identified the attached AutoTooltip property. When true, this will set the
  /// TextBlock TextTrimming property to WordEllipsis, and display a tooltip with
  /// the full text whenever the text is trimmed.
  /// 
  public static readonly DependencyProperty AutoTooltipProperty =  
           DependencyProperty.RegisterAttached("AutoTooltip", typeof(bool), typeof(TextBlockUtils),
            new PropertyMetadata(false, OnAutoTooltipPropertyChanged));
 
  private static void OnAutoTooltipPropertyChanged(DependencyObject d,
                                     DependencyPropertyChangedEventArgs e)
  {
    TextBlock textBlock = d as TextBlock;
    if (textBlock == null)
      return;
 
    if (e.NewValue.Equals(true))
    {
      textBlock.TextTrimming = TextTrimming.WordEllipsis;
      ComputeAutoTooltip(textBlock);
      textBlock.SizeChanged += TextBlock_SizeChanged;
    }
    else
    {
      textBlock.SizeChanged -= TextBlock_SizeChanged;
    }
  }
 
  private static void TextBlock_SizeChanged(object sender, SizeChangedEventArgs e)
  {
    TextBlock textBlock = sender as TextBlock;
    ComputeAutoTooltip(textBlock);
  }
 
    /// 
  /// Assigns the ToolTip for the given TextBlock based on whether the text is trimmed
  /// 
  private static void ComputeAutoTooltip(TextBlock textBlock)
  {
    FrameworkElement parentElement = VisualTreeHelper.GetParent(textBlock) as FrameworkElement;
    if (parentElement != null)
    {
      if (textBlock.ActualWidth > parentElement.ActualWidth)
      {
        ToolTipService.SetToolTip(textBlock, textBlock.Text);
      }
      else
      {
        ToolTipService.SetToolTip(textBlock, null);
      }
    }
  }
}

Most of this is boiler-plate attached behaviour code. The most interesting method is ComputeAutoTooltip which determines whether a tooltip is required. This simply looks at the ActualWidth of the parent and compares it to the ActualWidth of the TextBlock.

To use this code, ensure that your TextBlock is placed within its own Grid, then set the attached property to true. You can see this in action below:

 util:GridUtils.ColumnDefinitions="2*,"
      util:GridUtils.RowDefinitions=",">
 
   Grid.Column="0" Grid.Row="0" Grid.RowSpan="2"
                    ShowsPreview="True"
                    Background="LightGray"
                    Width="10"
                    HorizontalAlignment="Right"/>
 
   Grid.Column="0"
        Margin="0,0,10,0">
     Text="The rain in Spain stays mainly in the plain"   
                util:TextBlockUtils.AutoTooltip="True"/>
  >
 
   Grid.Column="2">
     Text="In Hertford, Hereford, and Hampshire, hurricanes hardly ever happen"
                util:TextBlockUtils.AutoTooltip="True"/>
  >
 
   Grid.Column="0" Grid.Row="1"
        Margin="0,0,10,0">
     Text="Peter Piper picked a peck of pickled peppers"
                util:TextBlockUtils.AutoTooltip="True"/>
  >
 
   Grid.Column="2" Grid.Row="1">
     Text="She sells sea-shells on the sea-shore"
                util:TextBlockUtils.AutoTooltip="True"/>
  >
>

Note the use of the simplified grid syntax which I blogged about earlier. You can see this code in action below. Move the grid splitter to see the tooltips automatically enabled when an ellipsis is displayed:

You can download the full sourcecode here: AutoTooltipTextBlock.zip

Regards, Colin E.

A Simplified Grid Markup for Silverlight and WPF

Colin Eberhardt — Tue, 21 Dec 2010 12:58:47 +0000

The WPF / Silverlight syntax is long and cumbersome. This blog post describe a simple attached property that allows you to specify row and column widths / heights as a simple comma separated list, e.g. RowDefinitions=”Auto,,3*,,,,2*”

The Grid is probably one of the most useful and versatile layouts that Silverlight and WPF offers. However, if you hand craft your XAML, as I do, you will probably start to find the Grid markup for defining rows and columns to be verbose and cumbersome. If we look at the following example, which uses a mixture of Auto, Star and Pixel widths / heights:

Despite this being a simple example, the required row and column definitions are highly verbose:

>
  >
     Height="Auto"/>
    />
    />
    />
    />
    />
     Height="2*"/>
  >
  >
     Width="100"/>
    />
  >
 
   Text="User Details" FontSize="20"
          HorizontalAlignment="Center"
          Grid.ColumnSpan="2"/>
 
   Text="Forename:"
              Grid.Row="1"/>
   Text="Jeremy"
            Grid.Column="1" Grid.Row="1"/>
 
   Text="Surname:"
              Grid.Row="2"/>
   Text="James"
            Grid.Column="1" Grid.Row="2"/>
 
   Text="Age:"
              Grid.Row="3"/>
   Text="24"
            Grid.Column="1" Grid.Row="3"/>
 
   Text="Phone:"
              Grid.Row="4"/>
   Text="+44 191 555467"
            Grid.Column="1" Grid.Row="4"/>
 
   Text="Notes:"
              Grid.Row="5"/>
   Text="A multi-line block of text ..." 
            TextWrapping="Wrap"
            Grid.Row="6" Grid.ColumnSpan="2"/>
>

To provide a simpler alternative, I have created attached properties, one for the column definitions, and the other for the rows. These attached properties allow you to specify the columns / rows as a comma separated list of heights and widths.

Using this technique, the above example becomes:

 local:GridUtils.ColumnDefinitions="100,"
      local:GridUtils.RowDefinitions="Auto,,,,,,2*">
 
   Text="User Details" FontSize="20"
          HorizontalAlignment="Center"
          Grid.ColumnSpan="2"/>
 
   Text="Forename:"
              Grid.Row="1"/>
   Text="Jeremy"
            Grid.Column="1" Grid.Row="1"/>
 
   Text="Surname:"
              Grid.Row="2"/>
   Text="James"
            Grid.Column="1" Grid.Row="2"/>
 
   Text="Age:"
              Grid.Row="3"/>
   Text="24"
            Grid.Column="1" Grid.Row="3"/>
 
   Text="Phone:"
              Grid.Row="4"/>
   Text="+44 191 555467"
            Grid.Column="1" Grid.Row="4"/>
 
   Text="Notes:"
              Grid.Row="5"/>
   Text="A multi-line block of text ..." 
            TextWrapping="Wrap"
            Grid.Row="6" Grid.ColumnSpan="2"/>
>

The comma separated list defines the widths / heights of each column / row. The number of items in this list defined the number of rows / column that are generated. This notation supports pixel, star and auto widths / heights. Also, if you want a row or column with the default size, just leave the value blank, i.e. a row definition of “,,,” will create four rows of default height.

The code to achieve this is pretty simple, involving a couple of attached properties and string parsing in their changed event handlers. The complete code for the GridUtils class is given below, feel free to copy and paste it into your project:

using System.Windows;
using System.Windows.Controls;
 
namespace SimplifiedGrid
{
  public class GridUtils
  {
    #region RowDefinitions attached property
 
    /// 
    /// Identified the RowDefinitions attached property
    /// 
    public static readonly DependencyProperty RowDefinitionsProperty =
        DependencyProperty.RegisterAttached("RowDefinitions", typeof(string), typeof(GridUtils),
            new PropertyMetadata("", new PropertyChangedCallback(OnRowDefinitionsPropertyChanged)));
 
    /// 
    /// Gets the value of the RowDefinitions property
    /// 
    public static string GetRowDefinitions(DependencyObject d)
    {
      return (string)d.GetValue(RowDefinitionsProperty);
    }
 
    /// 
    /// Sets the value of the RowDefinitions property
    /// 
    public static void SetRowDefinitions(DependencyObject d, string value)
    {
      d.SetValue(RowDefinitionsProperty, value);
    }
 
    /// 
    /// Handles property changed event for the RowDefinitions property, constructing
    /// the required RowDefinitions elements on the grid which this property is attached to.
    /// 
    private static void OnRowDefinitionsPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
      Grid targetGrid = d as Grid;
 
      // construct the required row definitions
      targetGrid.RowDefinitions.Clear();
      string rowDefs = e.NewValue as string;
      var rowDefArray = rowDefs.Split(',');
      foreach (string rowDefinition in rowDefArray)
      {
        if (rowDefinition.Trim() == "")
        {
          targetGrid.RowDefinitions.Add(new RowDefinition());
        }
        else
        {
          targetGrid.RowDefinitions.Add(new RowDefinition()
          {
            Height = ParseLength(rowDefinition)
          });
        }
      }
    }
 
    #endregion
 
 
    #region ColumnDefinitions attached property
 
    /// 
    /// Identifies the ColumnDefinitions attached property
    /// 
    public static readonly DependencyProperty ColumnDefinitionsProperty =
        DependencyProperty.RegisterAttached("ColumnDefinitions", typeof(string), typeof(GridUtils),
            new PropertyMetadata("", new PropertyChangedCallback(OnColumnDefinitionsPropertyChanged)));
 
    /// 
    /// Gets the value of the ColumnDefinitions property
    /// 
    public static string GetColumnDefinitions(DependencyObject d)
    {
      return (string)d.GetValue(ColumnDefinitionsProperty);
    }
 
    /// 
    /// Sets the value of the ColumnDefinitions property
    /// 
    public static void SetColumnDefinitions(DependencyObject d, string value)
    {
      d.SetValue(ColumnDefinitionsProperty, value);
    }
 
    /// 
    /// Handles property changed event for the ColumnDefinitions property, constructing
    /// the required ColumnDefinitions elements on the grid which this property is attached to.
    /// 
    private static void OnColumnDefinitionsPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
      Grid targetGrid = d as Grid;
 
      // construct the required column definitions
      targetGrid.ColumnDefinitions.Clear();
      string columnDefs = e.NewValue as string;
      var columnDefArray = columnDefs.Split(',');
      foreach (string columnDefinition in columnDefArray)
      {
        if (columnDefinition.Trim() == "")
        {
          targetGrid.ColumnDefinitions.Add(new ColumnDefinition());
        }
        else
        {
          targetGrid.ColumnDefinitions.Add(new ColumnDefinition()
          {
            Width = ParseLength(columnDefinition)
          });
        }
      }
    }
 
    #endregion
 
    /// 
    /// Parses a string to create a GridLength
    /// 
    private static GridLength ParseLength(string length)
    {
      length = length.Trim();
 
      if (length.ToLowerInvariant().Equals("auto"))
      {
        return new GridLength(0, GridUnitType.Auto);
      }
      else if (length.Contains("*"))
      {
        length = length.Replace("*","");
        if (string.IsNullOrEmpty(length)) length = "1";
        return new GridLength(double.Parse(length), GridUnitType.Star);
      }
 
      return new GridLength(double.Parse(length), GridUnitType.Pixel);
    }
  }
}

The code which parses the row and column strings is also executed by the Visual Studio designer, so you can see your new rows / columns immediately. It also works just fine in WPF and Silverlight.

You can download example projects in both technologies: SimplfiedGrid.zip

readers might also be interested in Mike Talbot’s AutoGrid which dynamically adds rows / columns based as children are added to the grid. A very neat idea!

(Thanks to Rob Newsome for coming up with this idea in the first place!)

Regards, Colin E.

Developing a Lookless Silverlight Gauge Control (part 2)

Colin Eberhardt — Wed, 20 Oct 2010 20:38:29 +0000

In a previous blog post I described the process of creating a lookless gauge control. I introduced the concept of an attached view model which separates view specific concepts from the control. In this post I demonstrate how this allows for great flexibility when re-templating the control.

In my previous post I described the development of a radial gauge control where I removed any view-specific logic and properties from the control by introducing an attached view model into the control’s template. My reasons for doing this were to create a completely lookless control in the order that this would permit greater flexibility when re-templating or themeing. The control I created was a gauge control, which in my previous blog post I rendered as a radial gauge. The ‘radial concepts’ of angle, and other derived properties are contained within the attached view model, with the Gauge control itself only containing concepts that are common across all gauges (radial or otherwise). The control is shown below:

In this post I will create two different templates for this control. The first is a small variation on the radial gauge which is rendered as a semi-circle. The second is very different, a bullet graph, where the gauge is rendered as a linear indicator. With each, an attached view model is introduced into the controls template in order to compute properties that aid in the rendering of the control.

A Semi-circular Gauge

The original attached view model I created was hard-coded to create a radial control where the needle has a sweep angle of 300 degrees. To support a semi-circular gauge we need to be able to configure this parameter. I achieved this by simply making SweepAngle a public property of the attached view model. This property is used wherever the view model needs to convert a gauge value to a radial location (i.e. when computing the tick mark rotation angles):

public class RadialGaugeControlViewModel : AttachedViewModelBase
{
  public RadialGaugeControlViewModel()
  {
    SweepAngle = 300;
  }
 
  /// 
  /// Gets / sets the sweep angle of the radial gauge
  /// 
  public double SweepAngle
  { get; set; }
 
  private double ValueToAngle(double value)
  {
    double minAngle = -SweepAngle / 2;
    double maxAngle = SweepAngle / 2;
    double angularRange = maxAngle - minAngle;
 
    return (value - Gauge.Minimum) / (Gauge.Maximum - Gauge.Minimum) *
        angularRange + minAngle;
  }
 
  ...
}

This allows it to be set in the control template of our re-templated gauge control where the view model is instantiated and attached:

 TargetType="local:GaugeControl" x:Key="themedGauge">
   Property="FontSize" Value="8"/>
   Property="Template">
    >
       TargetType="local:GaugeControl">
         x:Name="LayoutRoot" >
          >
            
            >
              
                     SweepAngle="180"/>
            >
 
            
        >
      >
    >
  >
>

This means that the various properties of the attached view model that the view binds to in order to render the various control parts, such as the needle, are now computed with a 180 degree sweep.

For the semi-circular gauge, I used a similar technique to the original radial gauge for creating the required layout, where a grid with various rows / columns with star widths / heights create a proportional layout within which elements such as the needle are placed:

>

>
   SweepAngle="180" Clip="false"/>
>
 

 Stroke="Black" StrokeThickness="3" StrokeLineJoin="Round"
      Stretch="Uniform">
  >
    >
      >
         IsClosed="True" 
                    StartPoint="0.5,0">
          >
             Size="0.5,0.5" RotationAngle="45" IsLargeArc="False"
                      SweepDirection="Clockwise"
                      Point="1,0.5"/>
             Point="1,0.55"/>
             Point="0,0.55"/>
             Point="0,0.5"/>
             Size="0.5,0.5" RotationAngle="45" IsLargeArc="False"
                            SweepDirection="Clockwise"
                            Point="0.5,0"/>
          >
         >
      >
    >
  >
>
 
 ShowGridLines="true">
  >
     Height="3.5*"/>
     Height="4*"/>
     Height=".6*"/>
     Height=".6*"/>
     Height="*"/>
  >
  >
     Width="8.0*"/>
     Width=".7*"/>
     Width=".7*"/>
     Width="8.0*"/>
  >
 
  
   Stretch="Uniform"
    Grid.Row="1" Grid.Column="1"
    Grid.ColumnSpan="2" Grid.RowSpan="2"
    Fill="Black"
    HorizontalAlignment="Center"
    Stroke="Black" StrokeThickness="0.5"
    Data="M 0,0 l 5,60 l -10, 0"
    RenderTransformOrigin="0.5,1">
    >
       Angle="{Binding Path=ValueAngle}"/>
    >
  >
 
  
   Fill="White"
            Stroke="Black" StrokeThickness="2"
            Width="13" Height="13"
            HorizontalAlignment="Center" VerticalAlignment="Bottom"
            Grid.Row="2" Grid.Column="1"
            Grid.RowSpan="2" Grid.ColumnSpan="2"/>
>

You can see the various gridlines below:

The code for creating the major / minor ticks and qualitative ranges are much the same as before. However, for a bit of variation I did not want the labels on this gauge to be rotated. In order to achieve this I used the same technique as before where each label is initially constructed at the same location, then a translate / rotate transform is used to move it to the correct location on the dial. In this control, the text label is rotated a second time in the opposite direction in order to bring it back to its original orientation:

>
  >
     Width="50" Height="20">
      >
        >
           X="-25" Y="-10"/>
           Y="{Binding Path=Parent.GridHeight,
              Converter={StaticResource ScaleFactorConverter}, ConverterParameter=-0.69}"/>
           Angle="{Binding Path=Angle}"/>
        >
      >
       Text="{Binding Path=Value}" 
            VerticalAlignment="Center" HorizontalAlignment="Center"
            RenderTransformOrigin="0.5, 0.5">
        
        >
           Angle="{Binding Path=Angle,
                Converter={StaticResource ScaleFactorConverter}, ConverterParameter=-1}" />
        >
      >
    >
  >
>

The finished semi-circular gauge can be seen here next to my original radial gauge control:

So, the original control has proven to be pretty versatile in that it can be re-templated to look quite different. To allow this, the attached view model was modified to expose a few view-centric properties that could be set when it is created and attached within the template.

However, the example above is still a radial gauge. A much bigger challenge would be to re-template the control to look completely different. That was my next challenge!

A Bullet Graph Template

Radial gauge controls look very pretty; however they eat up a lot of screen real-estate, and are not the best way of visualising a one-dimensional metric. A much clearer visualisation can be achieved by using a linear gauge, a bullet-graph for example. This section describes how a new attached view model can be applied to the gauge control, to support a template which produces a bullet graph.

Using the same process as in the above example, the basic structure of the control is defined using a Grid:

 TargetType="local:GaugeControl" x:Key="bulletGraphGauge">
   Property="FontSize" Value="8"/>
   Property="Template">
    >
       TargetType="local:GaugeControl">
         x:Name="LayoutRoot" Background="LightBlue">
           ShowGridLines="True">
            
            >
              />
            >
 
            
            >
               Height="3*"/>
               Height="*"/>
               Height="2*"/>
               Height="*"/>
               Height="3*"/>
            >                
 
            
             Fill="Black"
                        Grid.Row="2"
                        HorizontalAlignment="Left"
                        Width="{Binding Path=FeaturedMeasureLength}"/>
          >
        >
      >
    >
  >
>

The ‘featured measure’, which is a thermometer-like bar which indicates the current value of the gauge has its Width property bound to the view model which is attached at the top of the template. To simplify the code, I refactored the attached view model concept to extract a base class which is shared by both the radial and bullet-graph subclasses. This base class takes care of attaching to its parents DataContext, adapting the control’s properties, exposing the actual width / height of the control and the other bits and pieces I described in my previous blog post. The bullet graph view model is then much simpler as a result. In the code below you can see how the FeaturedMeasureLength is computed in the view model:

public class BulletGraphGaugeViewModel : AttachedViewModelBase
{
  public BulletGraphGaugeViewModel()
  {
  }
 
  private GaugeControl Gauge
  {
    // the view model’s DataContext is bound to the Gauge
    get { return DataContext != null ? (GaugeControl)DataContext : null; }
  }
 
  public double FeaturedMeasureLength
  {
    get
    {
      if (Gauge == null)
        return 0;
 
      return ValueToWidth(Gauge.Value - Gauge.Minimum);
    }
  }
 
  /// 
  /// Converts the given value (which should be between Gauge.Maximum / Gauge.Minimum)
  /// into suitable width for rendering within the view.
  /// 
  private double ValueToWidth(double value)
  {
    double range = Gauge.Maximum - Gauge.Minimum;
    return (value) / range * ElementWidth;
  }
}

Next we’ll add the ‘qualitative range’ scale:


 ItemsSource="{Binding Path=Ranges}"
              Grid.Row="1" Grid.RowSpan="3">
  >
    >
       Orientation="Horizontal"/>
    >
  >
  >
    >
       Width="{Binding Path=Width}"
                  Stroke="Black" StrokeThickness="0.2"
                  Fill="{Binding Path=Color, Converter={StaticResource ColorToBrushConverter}}"/>
    >
  >
>
 BorderBrush="Black" BorderThickness="1.0"
        Grid.Row="1" Grid.RowSpan="3" Margin="-1"/>

Once again, the attached view model is used to adapt the properties exposed by the control in order to provide properties which are easier to bind to in order to create the required UI. Here the Gauge controls QualitativeRange is adapted to expose a Range property, which the ItemsControl in the XAML above binds to, this property is an enumeration of RangeItems which each have the correct width and colour for our UI:

public IEnumerable<RangeItem> Ranges
{
  get
  {
    if (Gauge == null)
      yield break;
 
    for (int i = 0; i < Gauge.QualitativeRange.Count; i++)
    {
      var range = Gauge.QualitativeRange[i];
      if (i == 0)
      {
        // first RangeItem, width is determined from the first range value
        yield return new RangeItem()
        {
          Color = range.Color,
          Width = ValueToWidth(range.Maximum - Gauge.Minimum)
        };
      }
      else
      {
        // subsequent items, width computed as the difference between the
        // current value and its predecessor
        var previousRange = Gauge.QualitativeRange[i - 1];
        yield return new RangeItem()
        {
          Color = range.Color,
          Width = ValueToWidth(range.Maximum - previousRange.Maximum)
        };
      }
    }
  }
}
 
...
 
public class RangeItem
{
  public double Width { get; set; }
  public Color Color { get; set; }
}

Finally, the scales are added:


 ItemsSource="{Binding Path=MajorTicks}"
              VerticalAlignment="Center"
              Grid.Row="0"
              ItemsPanel="{StaticResource CanvasTemplate}">
  >
    >
       Width="50" Height="20">
        >
          >
            
             X="-25" Y="-10"/>
             X="{Binding Path=Position}"/>
          >
        >
         Text="{Binding Path=Label}"
                    VerticalAlignment="Center"
                    HorizontalAlignment="Center"/>
      >
    >
  >
>
 

 ItemsSource="{Binding Path=MajorTicks}"
              VerticalAlignment="Bottom"
              Grid.Row="0"
              ItemsPanel="{StaticResource CanvasTemplate}">
  >
    >
       X1="{Binding Path=Position}" Y1="0" X2="{Binding Path=Position}" Y2="-5"
            Stroke="Black"/>
    >
  >
>
 
          
 ItemsSource="{Binding Path=MinorTicks}"
              VerticalAlignment="Bottom"
              Grid.Row="0"
              ItemsPanel="{StaticResource CanvasTemplate}">
  >
    >
       X1="{Binding}" Y1="0" X2="{Binding}" Y2="-3"
            Stroke="Black"/>
    >
  >
>

Again, exactly the same pattern is employed, with the MajorTicks and MinorTicks properties exposed by the attached view model, each providing an enumeration of simple value objects with a Position and Label properties, which are bound to the three ItemsControls above to create the required UI.

The complete bullet graph template is shown below next to the original radial gauge:

In conclusion, the use of an attached view model provides a mechanism for exposing view-specific properties to the view logic within the XAML template. This enables the construction of a control which really is entirely lookless.

You can download the sourcecode for this project: GaugeControl.zip

Regards, Colin E.

Developing a (very) Lookless Silverlight Radial Gauge Control

Colin Eberhardt — Thu, 19 Aug 2010 11:13:20 +0000

This blog post describes the development of a lookless radial gauge control. In this post I will explore the use of an attached view model in order to move view specific properties and logic out of the control code in order to give a truly lookless control.

Today I had to get up far too early in order to catch an early morning flight to Copenhagen with a connection in Amsterdam. What to do for the six hours I would be travelling? Armed with a netbook and Visual Studio 2010 Express I thought it would be fun to have a go at developing a Silverlight gauge control. I know that there are already one or two free ones out there, with a decent looking one available on codeproject, however, it still felt like a good way to pass the time!

In order to make things a little more challenging I wanted to create a control that was truly lookless. So, what do I mean by this? Firstly a gauge control in its simplest sense displays the location of some indicator between a maximum and minimum value. There is nothing inherently circular about a gauge, thermometers are a good example of a linear gauge. So, I don’t want any ‘circular’ logic in the control itself. Secondly, custom controls often have certain expectations about the presence of named elements within their template. By this I mean that the template must contain, for example, a Path element called ‘needle’ which the control code will manipulate (The gauge published in the codeproject article above requires the presence of four named elements in the template). This forces certain constraints regarding how the control can be templated, this isn’t really lookless is it?

The following example shows the gauge control which I created, and the rest of this post describes the implementation:

 Value="65" Width="200" Height="200"  
                    Maximum="100" Minimum="50"
                    x:Name="gauge">
  >
    >
       Color="Yellow" Maximum="75"/>
       Color="Orange" Maximum="90"/>
       Color="Red" Maximum="100"/>
    >
  >
>

The Starting Point

The first step was to create a Gauge custom control with Value, Maximum and Minimum dependency properties. The only logic defined within the control itself is to set the DataContext of the root visual element to the control instance itself. This is quite a common approach to control design, allowing elements within the template to bind to the control properties:

public override void OnApplyTemplate()
{
  base.OnApplyTemplate();
 
  Grid root = GetTemplateChild("LayoutRoot") as Grid;
  root.DataContext = this;
}

The first thing I added to the control template was the ‘face’ of the radial gauge. This is simply an Ellipse with a pretty gradient fill and stroke:


 Stretch="Fill" StrokeThickness="8">
  >
     Center="0.5,0.5">
       Color="#EEF"/>
       Color="#99B" Offset="0.9"/>
       Color="#335" Offset="1"/>
    >
  >
  >
     StartPoint="0,0" EndPoint="0,1">
       Color="#BBD" Offset="0"/>
       Color="#003" Offset="1"/>
    >
  >
>

Adding the Needle

The next thing I added to the control was a needle. This is rendered using a simple Path with a LinearGradient in order to give it some sense of depth. I want the needle to have a length of approximately 70% of the gauge’s radius, a simple way to achieve this is to construct it within a Grid that uses ‘star’ widths / heights to provide a proportional layout and configure the Path to stretch to fill the cell it occupies:

              
>
  >
     Height="3*"/>
     Height="7*"/>
     Height="10*"/>
  >
  >
    />
    />
  >
 
   Stretch="Uniform"
      Grid.Row="1" Grid.ColumnSpan="2"
      HorizontalAlignment="Center"
      Stroke="Black" StrokeThickness="0.5"
      Data="M 0,0 l 10,60 l -10, 40 l -10 -40">
    >
       StartPoint="0,0" EndPoint="1,0">
         Color="DarkRed" Offset="0"/>
         Color="DarkRed" Offset="0.45"/>
         Color="Red" Offset="0.55"/>
         Color="Red" Offset="1"/>
      >
    >
  >
>

Here you can see how the needle is scaled by its parent Grid:

Rotating the needle to reflect the current Gauge Value is achieved quite simply via RotateTransform. However, this needs to be converted into a rotation angle which depends on the Gauge Maximum /Minimum values together with the overall angle of sweep on the gauge. I initially approach this problem by applying bindings via value converters and multibindings, however I found myself repeating the same conversion logic in numerous places within the template in order to render the ticks etc… Ideally the angle of rotation would be something that the template could bind to. The template DataContext is bound to the Gauge control itself, however as stated earlier I do not want ‘circular’ concepts to leak into the control.

An attached View Model

The solution I came up with for this problem was to create a view model that lives entirely within the control template that acts as an adapter for the Gauge, supplementing its properties with the needed ‘circular’ concepts. In keeping with my aims I could not instantiate this view model within the Gauge control itself, so instead it is created via an attached behaviour within the control template:

 TargetType="local:GaugeControl">
   Property="FontSize" Value="10"/>
   Property="Template">
    >
       TargetType="local:GaugeControl">
         x:Name="LayoutRoot" >
          >
            
            >
              />
            >
 
            
          >
        >
      >
    >
  >
>

The view model defines the Attach property and in its change handler performs the logic required to bind to the DatatContext of the parent (which is the Gauge control itself), and set itself as the DataContext of the Grid to which it is being attached. This allows the rest of the template to bind to properties of the RadialGaugeControlViewModel.

public class RadialGaugeControlViewModel : FrameworkElement, INotifyPropertyChanged
{
  #region Attach attached property
 
  public static readonly DependencyProperty AttachProperty =
      DependencyProperty.RegisterAttached("Attach", typeof(object), typeof(RadialGaugeControlViewModel),
          new PropertyMetadata(null, new PropertyChangedCallback(OnAttachChanged)));
 
  public static RadialGaugeControlViewModel GetAttach(DependencyObject d)
  {
    return (RadialGaugeControlViewModel)d.GetValue(AttachProperty);
  }
 
  public static void SetAttach(DependencyObject d, RadialGaugeControlViewModel value)
  {
    d.SetValue(AttachProperty, value);
  }
 
  /// 
  /// Change handler for the Attach property
  /// 
  private static void OnAttachChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
  {
    Grid targetElement = d as Grid;
    RadialGaugeControlViewModel viewModel = e.NewValue as RadialGaugeControlViewModel;
 
    // handle the loaded event
    targetElement.Loaded += new RoutedEventHandler(Grid_Loaded);
 
  }
 
  /// 
  /// Handle the Loaded event of the Grid to enable the attached
  /// view model to bind to properties of the Grid Parent element
  /// 
  static void Grid_Loaded(object sender, RoutedEventArgs e)
  {
    FrameworkElement targetElement = sender as FrameworkElement;
    FrameworkElement parent = targetElement.Parent as FrameworkElement;
 
    // use the attached view model as the DataContext of the element it is attached to
    RadialGaugeControlViewModel attachedModel = GetAttach(targetElement);
    targetElement.DataContext = attachedModel;
 
    // bind the DataContext of the view model to the DataContext of the parent.
    attachedModel.SetBinding(RadialGaugeControlViewModel.DataContextProperty,
      new Binding("DataContext")
      {
        Source = parent
      });
  }
}

It is now possible to expose a property on the view model which provides the Gauge Value as an angle:

public double ValueAngle
{
  get
  {
    if (Gauge == null)
      return 0.0;
 
    return ValueToAngle(Gauge.Value);
  }
}
 
private double ValueToAngle(double value)
{
  double minAngle = -150;
  double maxAngle = 150;
  double angularRange = maxAngle - minAngle;
 
  return (value - Gauge.Minimum) / (Gauge.Maximum - Gauge.Minimum) *
      angularRange + minAngle;
}

This can then be bound to in the template in order to rotate the needle. For an extra ‘flourish’ a drop shadow is also added to the needle which binds to this same rotation angle in order to give a subtle ‘3D’ effect:

 Stretch="Uniform"
    Grid.Row="1" Grid.ColumnSpan="2"
    HorizontalAlignment="Center"
    Stroke="Black" StrokeThickness="0.5"
    Data="M 0,0 l 10,60 l -10, 40 l -10 -40"
    RenderTransformOrigin="0.5,1">
  >
    
     Angle="{Binding Path=ValueAngle}"/>
  >
  >
     StartPoint="0,0" EndPoint="1,0">
       Color="DarkRed" Offset="0"/>
       Color="DarkRed" Offset="0.45"/>
       Color="Red" Offset="0.55"/>
       Color="Red" Offset="1"/>
    >
  >
  >
     Color="Black" Direction="{Binding Path=ValueAngle}"
                      BlurRadius="3"
                      Opacity="0.6"
                      ShadowDepth="5"/>
  >
>

Adding a Scale

The gauge control needs to have tick marks and labels render around the dial face at regularly spaced intervals between the Maximum and Minimum values. Here the view model comes into its own by providing a list of ‘Tick’ value objects, each of which provide the view with the required information to render tick marks and their labels:

public IEnumerable<Tick> MajorTicks
{
  get
  {
    if (Gauge == null)
      yield break;
 
    double tickSpacing = (Gauge.Maximum - Gauge.Minimum) / 10;
    for (double tick = Gauge.Minimum; tick <= Gauge.Maximum; tick += tickSpacing)
    {
      yield return new Tick()
      {
        Angle = ValueToAngle(tick),
        Value = tick.ToString("N0"),
        Parent = this
      };
    }
  }
}
 
public class Tick
{
  public double Angle { get; set; }
  public string Value { get; set; }
  public RadialGaugeControlViewModel Parent { get; set; }
}

The XAML which renders the major tick marks uses an ItemsControl to create each tick instance:


 ItemsSource="{Binding Path=MajorTicks}"
              VerticalAlignment="Center" HorizontalAlignment="Center">
  >
    >
      >>
    >
  >
  >
    >
       Fill="Black" Width="8" Height="8">
        >
          >
            
             X="-4" Y="-4"/>
            
             X="0"
                Y="{Binding Path=Parent.GridHeight, Converter={StaticResource ScaleFactorConverter},
                                                                 ConverterParameter=-0.37}"/>
            
             Angle="{Binding Angle}"/>
          >
        >
      >
    >
  >
>

As you can see each tick is simply an ellipse. The clever part is how each Ellipse is transformed to position it appropriately. It is first centre to make subsequent transforms a little simpler, it is then translated y an offset which moves it to the edge of the gauge face. The offset factor is computed as some fraction of the overall size of the gauge control. In order to achieve this I reluctantly had to angle SizeChanged events on the template Grid in order to expose its ActualHeight / ActualWidth, this is because ElementName binding on these properties appears to be broken.

On attachment the view model handles SizeChanged events as follows:

/// 
/// Handle SizeChanged events from the grid so that we can inform elements
/// of changes in the ActualHeight / ActualWidth
/// 
private void Grid_SizeChanged(object sender, SizeChangedEventArgs e)
{
  OnPropertyChanged("GridHeight");
  OnPropertyChanged("GridWidth");
 
  Grid.Clip = new EllipseGeometry()
  {
    RadiusX = _grid.ActualWidth / 2,
    RadiusY = _grid.ActualHeight / 2,
    Center = new Point(_grid.ActualWidth / 2, _grid.ActualHeight / 2)
  };
}
 
public double GridWidth
{
  get { return _grid.ActualWidth; }
}
 
public double GridHeight
{
  get { return _grid.ActualHeight; }
}

Adding tick labels and minor tick marks both use a simple variation on the above described approach:

I also added a ‘qualitative value’ range which renders a colour coded band beneath the needle. Again, this uses variations on the same approach, with the view model adapting the properties of the Gauge control and the template binding to these properties, together with the Grid size information in order to provide any required scaling.

The last flourish was to add a ‘glass’ effect to the Gauge. This was ‘borrowed’ directly from this fantastic codeproject article on creating ‘round glassy buttons’.

The finished Gauge is shown below, where its value is bound to a Slider control:

Conclusions

I am pretty happy with how this Gauge control turned out, visually I think it looks pretty good. I am also happy that I have succeeded in my initial aim of making it completely lookless. The attached view model within the control template is an interesting approach that moves view specific concepts (in this case angular properties) into the view, which is where the belong.

This radial Gauge control could certainly be improved to allow a more flexible scale calculation. Also, the RadialGaugeControlViewModel could also expose some of the view specific properties such as the radial sweep angle (currently hard-coded to 300 degrees) allowing them to be set in the template. For now, I think I will leave this control as it is.

Tomorrow I am on another early flight, this time heading back home. I might take this as an opportunity to provide a view for this control making use of a different attached view model.

You can download the full source for this article: GaugeControl.zip

(Apologies for the lack of project structure, this code was written using VS 2010 Express).

Regards, Colin E.

Exposing and Binding to a Silverlight ScrollViewer’s Scrollbars

Colin Eberhardt — Wed, 21 Jul 2010 19:59:26 +0000

The Silverlight ScrollViewer exposes readonly properties which indicate the current vertical and horizontal scroll offset, and methods for setting the current offset. In this blog post I demonstrate a simple attached behaviour that exposes these offsets as read / write dependency properties allowing them to be bound to.

The Silverlight ScrollViewer is a very useful control, if you have some content that is larger than the space available in your application, just sit it inside a ScrollViewer and it will automatically add vertical or horizontal scrollbars as required. Simple.

The ScrollViewer exposes readonly properties which indicate the current vertical and horizontal scroll offset. I have been used a ScrollViewer on many occasions without finding this to be an issue, however, recently I was creating an MVVM application which contained a list of items within a ScrollViewer. When the user clicks on an item, they are taken to its ‘details’ page, they then have the option to return to the list. I wanted the list to have the same state when the user returned to it, i.e. the same scroll location. Naturally, with this being an MVVM application, the scroll position belongs on the ViewModel and should be relayed to the View via a binding. However, with the offset properties on the ScrollViewer being readonly, this was not possible. Time to get creative!

The template of the ScrollViewer contains two ScrollBar instances, one horizontal and one vertical. The basic idea behind my solution is to add an attached behaviour (i.e. an attached property, that on attachment performs some logic on the target element) which walks the visual tree to find these scrollbars exposing their offset values.

Firstly, we’ll start by defining an attached property called VerticalOffset, which will be used to expose the position of the vertical scrollbar. Dependency property boiler plate code follows:

public static class ScrollViewerBinding
{
  #region VerticalOffset attached property
 
  /// 
  /// Gets the vertical offset value
  /// 
  public static double GetVerticalOffset(DependencyObject depObj)
  {
    return (double)depObj.GetValue(VerticalOffsetProperty);
  }
 
  /// 
  /// Sets the vertical offset value
  /// 
  public static void SetVerticalOffset(DependencyObject depObj, double value)
  {
    depObj.SetValue(VerticalOffsetProperty, value);
  }
 
  /// 
  /// VerticalOffset attached property
  /// 
  public static readonly DependencyProperty VerticalOffsetProperty =
      DependencyProperty.RegisterAttached("VerticalOffset", typeof(double),
      typeof(ScrollViewerBinding), new PropertyMetadata(0.0, OnVerticalOffsetPropertyChanged));
 
  #endregion
}

We’ll also define a private attached property of type ScrollBar, which will be used to store a reference to the scrollbar once it has been located within the ScrollViewers visual tree:

/// 
/// An attached property which holds a reference to the vertical scrollbar which
/// is extracted from the visual tree of a ScrollViewer
/// 
private static readonly DependencyProperty VerticalScrollBarProperty =
    DependencyProperty.RegisterAttached("VerticalScrollBar", typeof(ScrollBar),
    typeof(ScrollViewerBinding), new PropertyMetadata(null));

Because this attached property is private, I haven’t bothered to create CLR property accessors which are only used for convenience.

The VerticalOffset attached property has a changed event handler. When the property is first attached to a ScrollViewer, this allows us to walk the visual tree constructed from the ScrollViewer’s template and extract the scrollbars. It is this extra logic that adds new functionality to the ScrollViewer which is what makes this an attached behaviour, as opposed to a regular attached property which merely holds state.

When an attached property is first associated with its target, the visual tree described by the target’s template has not yet been constructed. With WPF, you would typically register for the Loaded event on the target, and on handling this event walk the visual tree that will have been constructed. However, in Silverlight there is a very subtle difference, apparently the Loaded event is not guaranteed to occur after the template is applied. Oh dear. The only other alternative is to handle the LayoutUpdated which is fired whenever changes are made to the visual tree. However, there is another complication! The LayoutUpdated event always has a null sender, this might look like a bug, but it is actually by design. This means that if we handle the LayoutUpdated event on the ScrollViewer element which the property is attached to, the method invoked as the event handler no longer has a reference to the ScrollViewer!

In order to get around this problem, the attached property changed handler is as follows:

/// 
/// Invoked when the VerticalOffset attached property changes
/// 
private static void OnVerticalOffsetPropertyChanged(DependencyObject d,
    DependencyPropertyChangedEventArgs e)
{
  ScrollViewer sv = d as ScrollViewer;
  if (sv != null)
  {
    // check whether we have a reference to the vertical scrollbar
    if (sv.GetValue(VerticalScrollBarProperty) == null)
    {
      // if not, handle LayoutUpdated, which will be invoked after the
      // template is applied and extract the scrollbar
      sv.LayoutUpdated += (s, ev) =>
        {
          if (sv.GetValue(VerticalScrollBarProperty) == null)
          {
            GetScrollBarsForScrollViewer(sv);
          }
        };
    }
    else
    {
      // update the scrollviewer offset
      sv.ScrollToVerticalOffset((double)e.NewValue);
    }
  }
}

Firstly, we check whether we have already got a reference to the scrollbar, if not, we attached a LayoutUpdated event handler. But instead of defining this handler as a method, it is written as an lambda expression (i.e. an anonymous delegate), so that the ScrollViewer reference is captured using closure.

When the LayoutUpdated event is fired the following method is invoked:

/// 
/// Attempts to extract the scrollbars that are within the scrollviewers
/// visual tree. When extracted, event handlers are added to their ValueChanged events.
/// 
private static void GetScrollBarsForScrollViewer(ScrollViewer scrollViewer)
{
  ScrollBar scroll = GetScrollBar(scrollViewer, Orientation.Vertical);
  if (scroll != null)
  {
    // save a reference to this scrollbar on the attached property
    scrollViewer.SetValue(VerticalScrollBarProperty, scroll);
 
    // scroll the scrollviewer
    scrollViewer.ScrollToVerticalOffset(
      ScrollViewerBinding.GetVerticalOffset(scrollViewer));
 
 
    // handle the changed event to update the exposed VerticalOffset
    scroll.ValueChanged += (s, e) =>
      {
        SetVerticalOffset(scrollViewer, e.NewValue);
      };
  }
}
 
/// 
/// Searches the descendants of the given element, looking for a scrollbar
/// with the given orientation.
/// 
private static ScrollBar GetScrollBar(FrameworkElement fe, Orientation orientation)
{
  return fe.Descendants()
            .OfType<ScrollBar>()
            .Where(s => s.Orientation == orientation)
            .SingleOrDefault();
 
}

The GetScrollBar method is invoked, which then uses Linq-to-VisualTree to walk the descendants of the ScrollViewer in an attempt to find scrollbars of a given orientation. If one is found, it is stored in the private attached property. We also subscribe to the events which the scrollbar raises when its value changes, in order to update the VerticalOffsetProperty. Again, a lambda expression is used to capture the ScrollViewer which this scrollbar is associated with, so that we do not have to store a relationship from scrollbar to scrollviewer.

As an aside, it would have been a bit more elegant to use binding to connect our VerticalScrollOffset to the scrollbar value as follows:

scroll.SetBinding(ScrollBar.ValueProperty,
  new Binding("(ScrollViewerBinding.VerticalOffset)")
  {
    Source = scrollViewer
  });

However, it appears that there is a bug in Silverlight which makes binding to custom attached properties in code behind fail with a critical error. Until this is fixed, we have to take care of the ‘binding’, by handling change events from both properties, manually.

Using this attached behaviour is as simple as the following:

 
    local:ScrollViewerBinding.VerticalOffset="{Binding YPosition, Mode=TwoWay}"
    local:ScrollViewerBinding.HorizontalOffset="{Binding XPosition, Mode=TwoWay}">
    
>

The following little demo binds the X & Y offset of the scrollviewer to two CLR properties (with property changed notifications) defined in code behind. These same properties are bound to the text fields below:

You can download the complete sourcecode for this blog post: ScrollOffsetBinding.zip

Regards, Colin E.

Silverlight ClipToBounds – Can I Clip It?, Yes You Can!

Colin Eberhardt — Tue, 12 May 2009 07:30:47 +0000

With Silverlight, Panels do not clip their contents by default. See the following example:

Where we have a Grid containing another Grid which itself contains an ellipse, and a Canvas which contains an ellipse:

 x:Name="LayoutRoot" Background="White">
    >
         Width="*"/>
         Width="*"/>
    >
 
     Grid.Column="0" Background="Blue" Margin="20">                        
         Background="Yellow" Margin="20,40,-20,20">
             Fill="LightGreen" Width="80" Height="80" Margin="-40, -40, 0, 0"/>
        >
    >
 
     Grid.Column="1"  Background="Aqua" Margin="20" >
         Fill="Red" Canvas.Top="-10" Canvas.Left="-10" Width="130" Height="130"/>
    >
>

Often this is not the desired effect (although it is actually quite a useful feature of Canvas; You can simply add a Canvas to your visual tree without explicitly or implicitly setting its Size and use it as a mechanism for absolute positioning its children).

Fortunately Silverlight provides a Clip property on UIElement, allowing you to provide the clipping geometry for the element:

 Width="200" Height="100">       
    >
         Rect="0, 0, 200, 100"/>
    >
>

The above example creates a clipping geometry which matches the rectangular geometry of the Grid itself. Clearly more funky clipping geometries can be created, allowing for really cool effects, however most of the time I simply want my Panel clipped so that its children cannot escape!

The above example has a few problems, Firstly, it is a bit long-winded having to explicitly create the geometry each time I want to clip; Secondly, if my Grid’s size is calculated from its parent’s layout, how can I define the clip geometry in my XAML?; Finally, if my Grid’s geometry changes, its clipped geometry does not change.

In order to solve this problem I created a simple little attached behaviour, which allows you to define the clipping using the attached property Clip.ToBounds as illustrated below:

 x:Class="SilverlightClipToBounds.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    xmlns:util="clr-namespace:Util" Width="300" Height="200">
     x:Name="LayoutRoot" Background="White">
        >
             Width="*"/>
             Width="*"/>
        >
 
         Grid.Column="0" Background="Blue" Margin="20" util:Clip.ToBounds="true">       
             Background="Yellow" Margin="20,40,-20,20" util:Clip.ToBounds="true">
                 Fill="LightGreen" Width="80" Height="80" Margin="-40, -40, 0, 0"/>
            >
        >
 
         Grid.Column="1"  Background="Aqua" Margin="20" util:Clip.ToBounds="true">
             Fill="Red" Canvas.Top="-10" Canvas.Left="-10" Width="130" Height="130"/>
        >
    >
>

The result can be seen below:

And here is the code for the attached behaviour itself:

public class Clip
{
    public static bool GetToBounds(DependencyObject depObj)
    {
        return (bool)depObj.GetValue(ToBoundsProperty);
    }
 
    public static void SetToBounds(DependencyObject depObj, bool clipToBounds)
    {
        depObj.SetValue(ToBoundsProperty, clipToBounds);
    }
 
    /// 
    /// Identifies the ToBounds Dependency Property.
    /// 
    public static readonly DependencyProperty ToBoundsProperty =
        DependencyProperty.RegisterAttached("ToBounds", typeof(bool),
        typeof(Clip), new PropertyMetadata(false, OnToBoundsPropertyChanged));
 
 
    private static void OnToBoundsPropertyChanged(DependencyObject d,
        DependencyPropertyChangedEventArgs e)
    {
        FrameworkElement fe = d as FrameworkElement;
        if (fe != null)
        {
            ClipToBounds(fe);
 
            // whenever the element which this property is attached to is loaded
            // or re-sizes, we need to update its clipping geometry
            fe.Loaded += new RoutedEventHandler(fe_Loaded);
            fe.SizeChanged += new SizeChangedEventHandler(fe_SizeChanged);
 
        }
    }
 
    /// 
    /// Creates a rectangular clipping geometry which matches the geometry of the
    /// passed element
    /// 
    private static void ClipToBounds(FrameworkElement fe)
    {
        if (GetToBounds(fe))
        {
            fe.Clip = new RectangleGeometry()
            {
                Rect = new Rect(0, 0, fe.ActualWidth, fe.ActualHeight)
            };
        }
        else
        {
            fe.Clip = null;
        }
    }
 
    static void fe_SizeChanged(object sender, SizeChangedEventArgs e)
    {
        ClipToBounds(sender as FrameworkElement);
    }
 
    static void fe_Loaded(object sender, RoutedEventArgs e)
    {
        ClipToBounds(sender as FrameworkElement);
    }    
}

When the ToBounds property is associated with an element, ClipToBounds is invoked to create a rectangular clip geometry. We also add event handlers for Loaded, which is a very useful event which is fired when an element has been laid out and rendered, in other words it’s size will have been computed, and SizeChanged. In the event handlers for both we simply update the clipping geometry.

This can be seen in action here, where clicking on the Grids or Canvas increases their size, with the clipping geometry growing accordingly:

You can download a demo project here: sliverlightcliptobounds.zip

Can I Clip It?, Yes You Can!

Regards, Colin E.

Using CSS Selectors for Styling in WPF

Colin Eberhardt — Wed, 11 Mar 2009 17:14:31 +0000

When I first encountered WPF I was really impressed by its styling and templating features which are more powerful than anything else I had previously seen for desktop software development. The property-value pairing within styles instantly reminded me of CSS, however the WPF styles lack the most powerful feature of CSS – the selector. This blog post describes an attached behaviour for styling WPF application using CSS selectors.

Let’s first look at the anatomy of CSS. A CSS stylesheet is composed of a number of rules, each rule is composed of a selector which provides a pattern which the CSS selector engine matches against the target HTML document to locate nodes which to apply the style to. The styling information itself is defined within a declaration block, which consists of a number of comma-separated declarations enclosed within braces. The declaration block looks quite similar to a style within WPF …

div {
   font-size: 10px;
}

 TargetType="TextBlock">
     Property="FontSize" Value="10"/>
>

So let’s ignore the declaration block for the moment and concentrate on the interesting part, the CSS selector.

Selectors define a pattern which is matched, the information which the selector contains can include the element (tag) type, class or ID. More complex selectors might also include element attribute values or use pseudo-classes. We can easily find parallel concepts to these within WPF …

HTML element type (e.g. div, p, a) => dependency object type (e.g. TextBlock, Button)
HTML ID (#menu) => dependency object Name (e.g. x:Name=”menu”)
HTML class (.title) => attached class property (e.g. css:Css.Class=”menu”)

The only concept for which there really is no correspondent in WPF is CSS class. This can easily be introduced via an attached property.

So now that we have the concept mapping, all we need now is a CSS selector engine that can apply our selector in order to extract matching objects from our visual / logical tree. Luckily I found a .NET CSS selector engine implementation in codeplex called Fizzler, you can read about it on the authors blog, or go straight to codeplex to download it. The author of this engine, Colin Ramsay, had done a great job of the implementation and had also written an exhaustive set of unit tests. The engine itself was tightly coupled to HtmlDocumentNodes, however I was able to slide a simple interface between the selector engine and the HTML document types as follows:

public interface IDocumentNode
{
    IAttributeCollection Attributes { get; }
    List<IDocumentNode> ChildNodes { get; }
    IDocumentNode ParentNode { get; }
    IDocumentNode PreviousSibling { get; }
    string Id { get; }
    string Class { get; }
    string Name { get; }
    bool IsElement { get; }
}
 
public interface IAttributeCollection
{
    IAttribute this[string name] { get; }
}
 
public interface IAttribute
{
    string Value { get; }
}

Again, thanks to the extensive unit tests, this refactor only took ~ 40 minutes.

The next job was to create an implementation of the above interfaces that walks the visual / logical trees, both were pretty easy to implement using the LogicalTreeHelper and VisualTreeHelper classes. With these classes implemented, I was able to query the visual tree using selectors as follows:

SelectorEngine engine = new SelectorEngine();
IList<IDocumentNode> matchingNodes = engine.Parse(".form TextBlock.warning");
 
// apply the style to all matching nodes
foreach (DependencyObjectNode matchingNode in matchingNodes)
{
   ...
}

In the above example, the selector engine returns any TextBlock with the class ‘warning’, which is a descendant of any element with the class ‘form’. This is certainly a novel way of querying the visual tree!

The next step is to define the declaration block and apply the style which they define to any matching elements.

public class StyleDeclarationBlock : List<StyleDeclaration>
{
}
 
public class StyleDeclaration
{
    public string Property { get; set; }
    public object Value { get; set; }
}

We can construct style declarations within XAML as follows:

>
     Property="BorderThickness" Value="2"/>
     Property="BorderBrush" Value="Black"/>
     Property="CornerRadius" Value="5"/>
     Property="Margin" Value="10,10,10,10"/>
>

The process for applying a style is pretty straightforward, the only subtle complication is that styles, once applied are frozen (i.e. immutable). Therefore, each time an element is selected via our selector engine, we clone the existing style then merge it with the new one. See the attached source-code for details.

Putting it all together involves the creation of an Attached Behaviour which associates a stylesheet with an element within our XAML. When the element is loaded, the rules within the stylesheet are applied. Let’s look at a simple demo …

Here is a simple UI defined in XAML. Note the absence of any styling information:

>
     css:Css.Class="form">                
         Orientation="Vertical">
             css:Css.Class="title" Text="User Details"/>
             VerticalAlignment="Top" >
                >
                     Width="*"/>    
                     Width="*"/>
                >  
 
                >
                    />
                    />
                    />
                    />
 
                >        
 
 
                 css:Css.Class="mandatory" Text="Name"/>
                  css:Css.Class="mandatory" Grid.Column="1" Text="Anthony Gatto"/>
 
                 Grid.Row="1" Text="Age"/>
                 Grid.Row="1"  Grid.Column="1" Text="36"/>
 
                 Grid.Row="2" Text="Profession"/>
                 Grid.Row="2"  Grid.Column="1" Text="Performer"/>
 
                 Grid.Row="3" Grid.Column="1" >Submit>
            > 
        >
    >
>

The resulting UI looks like this:

Now we apply our stylesheet to the root element in our XAML:

 x:Key="cssStyles">
    >
 
         Selector=".form Grid *" SelectorType="LogicalTree">
            >
                >
                     Property="Margin" Value="4,4,4,4"/>
                >
            >
        >
 
         Selector=".form TextBlock.mandatory">
            >
                >
                     Property="Foreground" Value="Red"/>
                >
            >
        >
 
         Selector="Border.form">
            >
                >
                     Property="BorderThickness" Value="2"/>
                     Property="BorderBrush" Value="Black"/>
                     Property="CornerRadius" Value="5"/>
                     Property="Margin" Value="10,10,10,10"/>
                >
            >
        >
 
         Selector=".form .title">
            >
                >
                     Property="HorizontalAlignment" Value="Stretch"/>
                     Property="HorizontalContentAlignment" Value="Center"/>
                     Property="Background" Value="DarkBlue"/>
                     Property="Foreground" Value="White"/>
                     Property="FontSize" Value="13"/>
                     Property="Padding" Value="3,3,3,3"/>
                     Property="FontWeight" Value="Bold"/>
                >
            >
        >
 
    >
>
 
...
 
 css:Css.StyleSheet="{StaticResource cssStyles}">

Which styles our WPF application as follows:

Let’s look at those selector in a little more detail. The first one, is quite interesting. Here we are selecting everything within the Grid within our form and applying a margin. Note that here we are using a selector on the logical tree, otherwise we will also match elements within the control template of our TextBoxes and Buttons and will hence apply the margin internally within these elements also. However, in other contexts the ability to be able to apply styles within a controls template is a powerful concept.

The next selector styles our mandatory fields, the others styling the form title and borders.

The above is a pretty simple demonstration. The Fizzler CSS engine implements most of the CSS2.1 selectors and also some CSS3, so much more complex selector logic is possible. You can also include multiple comma-separated selectors on a rule.

Currently this code is not what I would call production-ready. It is just an idea that has been bugging me for a while that I wanted to get out of my head and share. I think this approach has a number of merits and it overcomes some of the restrictions in WPF styling. It provides a much more flexible mechanism for styling your UI, WPF gives you explicit styles and implicit styles, neither of which match the power of the CSS selector. This approach also adds the ability to merge styles, so if an element is matched by multiple rules these styles are merged. Furthermore, this approach does not impose the restriction that styles must have a TargetType, if the matching element does not have a corresponding dependency property, it simply does not pick up that piece of style information.

However, this implementation is not quite complete. I have not considered how to apply styles to dynamically generated content, ItemsControls for example.

I would be very interested to hear peoples opinions on this idea. Do you thin kit has potential? Perhaps if it was ported to Silverlight – it could even include mapping rules form ‘real’ CSS documents so that your Silverlight application could share style information with the rest of the web page which hosts it. But that is a job for another day …

You can download the code for this blog post here: wpfcssstyling.zip

UPDATE – the concept of using CSS to style WPF and Silvelight applications has been discussed on the WPF Discisples Group.

Regards, Colin E.

Implementing RelativeSource binding in Silverlight

Colin Eberhardt — Fri, 27 Feb 2009 14:57:35 +0000

In my previous post I demonstrated how an the WPF ElementName style binding can be emulated with Silverlight via an attached behaviour. As a brief recap, the technique involved creating an attached property, which when bound, adds a handler for the elements Loaded event. When the element is loaded, the even handler locates the named element and constructs a binding via a relay object. Here is the attached property in use:

 Height="20" Fill="Green">
    >
         ElementName="Slider" SourceProperty="Value" TargetProperty="Width"/>
    >
>
 x:Name="Slider" Value="20" Minimum="0" Maximum="300"/>

Where the Rectangle’s Width is bound to the Slider’s Value. For details, and sourcecode, visit this blog post. Here I am going to extend this attached behaviour in order to emulate WPF’s RelativeSource binding.

For much of the time you will want to bind your visual elements to your data objects via their DataContext property. However, there are often times when you want too perform a binding for pure presentation purposes, for example, binding the width of two elements together. In this context WPFs RelativeSource and ElementName binding prove to be powerful and useful features of the binding framework.

Here I will extend the attached behaviour I described in my previous post to add RelativeSource binding capabilities. The properties of the attached property type have been extended:

public class BindingProperties
{
    public string SourceProperty { get; set; }
    public string ElementName { get; set; }
    public string TargetProperty { get; set; }
    public IValueConverter Converter { get; set; }
    public object ConverterParameter { get; set; }
    public bool RelativeSourceSelf { get; set; }
    public string RelativeSourceAncestorType { get; set; }
    public int RelativeSourceAncestorLevel { get; set; }
 
    public BindingProperties()
    {
        RelativeSourceAncestorLevel = 1;
    }
}

With the RelativeSourceSelf, RelativeSourceAncestorType and RelativeSourceAncestorLevel properties being used for relative source bindings. Taking RelativeSourceSelf as our first example, within WPF a RelativeSource.Self property indicates that the source of a binding should be the element which the binding is associated with. (I know – it sounds a bit crazy, but search google, it is surprisingly useful!).

private static void OnBinding(
    DependencyObject depObj, DependencyPropertyChangedEventArgs e)
{
    FrameworkElement targetElement = depObj as FrameworkElement;
 
    targetElement.Loaded += new RoutedEventHandler(TargetElement_Loaded);
}
 
private static void TargetElement_Loaded(object sender, RoutedEventArgs e)
{
    FrameworkElement targetElement = sender as FrameworkElement;
 
    // get the value of our attached property
    BindingProperties bindingProperties = GetBinding(targetElement);
 
    if (bindingProperties.ElementName != null)
    {
        // perform our 'ElementName' lookup
        ...
    }
    else if (bindingProperties.RelativeSourceSelf)
    {
        // bind an element to itself.
        CreateRelayBinding(targetElement, targetElement, bindingProperties);
    }
}

When the attached property becomes attached to our target element it adds a handler for the elements Loaded event (this is the attached behaviour). Within the event handler, we determine whether this is a relative source binding. If this is the case, the CreateRelayBinding method is invoked where the source and target element parameters are the same element. For details of how the CreateRelayBinding method works, see the previous blog post. An example of a relative-source self binding is show below, where a TextBox’s Width property is bound to its Text, if you trype in a new text value, the TextBox Width adjusts accordingly.

 Text="200" Margin="0,5,0,0">
    >
         TargetProperty="Width" SourceProperty="Text"
                                 RelativeSourceSelf="True"/>                                
    >
>

The next type of RelativeSource binding I am going to tackle is the FindAncestor mode. You use this type of binding when you want to bind to an element of a specific type that is located further up the visual tree that the target element. The following code snippet shows how the attached behaviour achieves this type of binding:

private static void TargetElement_Loaded(object sender, RoutedEventArgs e)
{
    FrameworkElement targetElement = sender as FrameworkElement;
 
    // get the value of our attached property
    BindingProperties bindingProperties = GetBinding(targetElement);
 
    if (bindingProperties.ElementName != null)
    {
        // perform our 'ElementName' lookup
        ...
    }
    else if (bindingProperties.RelativeSourceSelf)
    {
        // bind an element to itself.
        ...
    }
    else if (!string.IsNullOrEmpty(bindingProperties.RelativeSourceAncestorType))
    {
 
        // navigate up the tree to find the type
        DependencyObject currentObject = targetElement;
 
        int currentLevel = 0;
        while (currentLevel < bindingProperties.RelativeSourceAncestorLevel)
        {
            do
            {
                currentObject = VisualTreeHelper.GetParent(currentObject);
            }
            while (currentObject.GetType().Name != bindingProperties.RelativeSourceAncestorType);
            currentLevel++;
        }
 
        FrameworkElement sourceElement = currentObject as FrameworkElement;
 
        // bind them
        CreateRelayBinding(targetElement, sourceElement, bindingProperties);
    }
}

The code above simply navigates up the visual tree to find the n’th element of a given type. When the given type has been located, the relay binding between the two is constructed.

This type of binding is incredibly flexible, the following shows a number of examples:

 x:Class="SilverlightBinding.PageTwo">
 
    >
         x:Key="VisibilityConverter"/>
    >
 
     x:Name="TheOuterStackPanel" Background="White"> 
         Name="theInnerStackPanel" Width="400">
            
             Text="200" Margin="0,5,0,0">
                >
                     TargetProperty="Width" SourceProperty="Text"
                                             RelativeSourceSelf="True"/>                                
                >
            >
            
             Margin="0,5,0,0">
                >
                     TargetProperty="Text" SourceProperty="Width"
                                             RelativeSourceAncestorType="PageTwo"/>                                
                >
            >
            
             Margin="0,5,0,0">
                >
                     TargetProperty="Text" SourceProperty="Name"
                                             RelativeSourceAncestorType="StackPanel"/>                                
                >
            >
            
             Margin="0,5,0,0">
                >
                     TargetProperty="Text" SourceProperty="Name"
                                             RelativeSourceAncestorType="StackPanel"
                                             RelativeSourceAncestorLevel="2"/>                                
                >
            >
            
             Height="30"  Margin="0,5,0,0" Background="CadetBlue" HorizontalAlignment="Left" >
                 Width="400"  HorizontalAlignment="Left" Minimum="10" Maximum="40">
                    >
                         TargetProperty="Value" SourceProperty="Height"
                                             RelativeSourceAncestorType="Grid"/>
                    >
                >
            >
        >     
    >
>

You can see in the above XAML, examples of relative-source self and find ancestor bindings with a variety of types and ancestor-levels. And here it is in action:

If you type in a new value in the top text box its width will change, or move the slider to see the height of its parent grid changing. And all without any code-behind of course!

Many of these effects shown above could be performed via element-name bindings. However, you are not always the creator, or template provider for all the visual elements rendered to screen. One common example is that of the ItemsControl, the ListBox being an example of this type of control. Here you supply a DataTemplate, with your visual elements being rendered inside a ListBoxItem container. Therefore, there is no way to bind to the ListBoxItem via an element name or otherwise. However, you can reach the ListBoxItem by navigating up the tree using a relative-source binding as show below:

 Name="grid" Width="200" HorizontalAlignment="Left">
    >
        >
             Width="180">
                 Text="{Binding Forename}"/>
 
                 Width="10" Height="10" Fill="Red" HorizontalAlignment="Right">
                    >
                         TargetProperty="Visibility" SourceProperty="IsSelected"
                                                 Converter="{StaticResource VisibilityConverter}"
                                                 RelativeSourceAncestorType="ListBoxItem"/>
                    >
                >
            >
        >
    >
>

In the above example we have a DataTemplate which contains an ellipse. As the ListBox generates each ‘row’, it creates a ListBoxItem and populates it with the visual elements from our data template. When our ellipse is created, and loaded, the attached behaviour fires, navigating up the visual tree to find the first ListBoxItem it encounters. When it finds it, it creates a single instance of our relay object, binding both the ListBoxItem.IsSelected and Ellipse.Visibilty (via a suitable value converter) together via the relay object.

And here it is in action (click an item to see the ellipse) …

You can download a visual studio project with all the sourcecode: silverlightrelativesourcebinding.zip.

Enjoy, Colin E.