Templated Silverlight Rating Control

Anyone that has been working with the standard set of controls for Silverlight 2 Beta 2 has been exposed to the concept of template binding and how VisualStateManager (VSM) controls state.   In this example I will build a templated control  to learn how to use VSM, template binding and the ContentControl base class. 

The control I choose to create is a Rating control .  The goal is to display a series of Stars that both visualize an overall average score, and allows a user to submit their own rating.  Here is what the control looks like.

RatingControl

The control is comprised of two components: RatingControl and RatingButton. The RatingControl is derived from ContentControl and can either be given an explicit set of RatingButtons, or can automatically create them based on a user setting. Here are the properties I have chosen to expose in RatingContorl:

• Max (Int): The number of RatingButtons to display
• Total (double): The number of votes that have been cast
• Score (double): The average rating across all  submissions
• UseIndicators(bool): Determines if we will display indicators for what each star represents.

There are two ways in which you can populate the rating control.  The first is to set the Max property and allow the control to add the appropriate number of children.  This works great if you don’t need to specify an individual Indicator (ToolTip) for each RatingButton.  The second approach is to explicitly add RatingButtons to the content property of the RatingControl.  Here is what that would look like in Xaml.

By choosing to have our RatingControl inherent from ContentControl it takes care of giving us the ability to set the children of our Content property.  In this example I am assuming a FrameworkElement derived from Panel (Grid or StackPanel) is placed inside of Content.  This makes it very easy to iterate through the panels children and identify each RatingButton.  The following shows the code I used to make the decisions if I would create my own RatingButtons, or use those specified in the RatingControl.Content element.

Since I was allowing this control to be templated, I choose to do this setup in the controls Loaded event handler.  This allows me to set the controls Content property equal to my manually created StackPanel, prior to the controls ApplyTemplate method being executed.  This ensures that any special formatting around the panel is applied after the RatingButtons have been added.

RatingButton

To minimize the amount of code I needed to write for this control I decided to build my RatingButton control on top of the System.Windows.Controls.Primitives.ToggleButton.  If you are not familiar with this control it is a very flexible Button that supports three states (Checked, Uncheked, Null).  This is perfect for my example where I will need my star to be visualizes as either filled, empty or half filled star.

For all extensive purposes I left the ToggleButton alone and only overrode OnToggle, OnMouseEnter and OnMouseDown.  Here is what that code looks like.

Since each RatingButton needs to behave as a group, I had to circumvent how the ToggleButton would change visual state, and allow RatingControl to manage this process.  The first method UpdateChecked, simply iterates over each rating button, and based on the Score, determines which ones would be checked.  For my visualization I decide that an average score > N.3, but < N.7 would visualize a half star, where as anything above or below would visualize a full or empty star.  I allow the IsChecked property of ToggleButton to switch to the appropriate visual state (Checked, UnChecked or Intermediate).

In the event that a user is hovering over the rating control, I want to visualize a different color of filled star.  Once again I need to allow the RatingControl to determine which RatingButtons need to react to the hover.  The following demonstrates how I achieved this effect.

Since once again we choose to circumvent how the ToggleButton switches state on hover, we must  use VisualStateManger.GotToState to trigger the appropriate state of the RatingButton we are evaluating (MouseOver or Normal).  

To  customize the visualization of the this control you can either edit my default style in Blend 2.5, or you can clone it and make your own changes. The Control template is as simple as I could make it to allow users full control over how the RatingButton icons look, and how the states are visualized. 

Code: Rating.zip