DescriptionViewer in Silverlight 3

The function of the DescriptionViewer control in Silverlight 3 is to displays some information as a description and track error state for an associated control.

This control displays an information symbol (glyph). When the mouse hovers on the symbol, a tooltip with text description is shown. This can be useful for fields for which the label or content text alone is not sufficient and you want to provide some description for it.

Let's see this in action. Assume that you have created a Silverlight 3 application that enables the users to change the current background on the page. Users need to click the Background button in order for the effect to take place. To inform the users that clicking the button will make this happen, you could provide a tooltip next to the button. This tooltip with description is achieved in Silverlight 3 by means of the DescriptionViewer control.

Following is the fragment of the code in MainPage.xaml to demonstrate the use of DescriptionViewer control. Note that actual functionality to change the background is not added here as the purpose of this code is merely to show the function of DescriptionViewer control.

<UserControl x:Class="DescViewer.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-
    compatibility/2006"
    xmlns:dataInput="clr-namespace: System.Windows.Controls;
    assembly=System.Windows.Controls.Data.Input"
    xmlns:controls="clr-namespace: System.Windows.Controls;
    assembly=System.Windows.Controls"
    mc:Ignorable="d" d:DesignWidth="640" d:DesignHeight="480">

  <Canvas x:Name="LayoutRoot" Width=" 640" Height="480">
      <Button Content="Background" Background="MediumOrchid"   
        Canvas.Top="100" Canvas.Left="100" Width="70">
     </Button>
   <dataInput:DescriptionViewer Description="Clicking this button will
    change the background" Canvas.Top="100" Canvas.Left="165"/>
  </Canvas>
</UserControl>

To align the DescriptionViewer control next to the control for which you are providing the tooltip, you can either use Canvas coordinates as shown above or else you could use a StackPanel or Grid with rows and columns and then arrange it appropriately.

This was just a very basic example of using the DescriptionViewer control.

The Target property of the DescriptionViewer is set in order to associate a DescriptionViewer with the Button control. Though here, it has been done in XAML, you can also achieve the same through C# code. The Target is a reference to a UIElement.

When the Target property is set, a DescriptionViewer inspects each DependencyProperty on the Target control for a Binding.

The Description property allows you to set the text of a DescriptionViewer.

The DescriptionViewer control by default does not display validation errors. If you wish to provide validation, you can use the IsValid property for tracking validation states. When the Target property is set, a DescriptionViewer responds to the BindingValidationError event for the Target control. It changes to its Invalid visual state when an error occurs. It then changes to its Valid visual state when there are no errors. To receive error notifications, you must set the ValidatesOnExceptions and NotifyOnValidationError properties on the Target control's Binding to true.

For example, consider the code shown below:

<UserControl x:Class="DescViewer.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:dataInput="clr
namespace:System.Windows.Controls;assembly=System.Windows.Controls.Data.Input"
    xmlns:controls="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls"
             mc:Ignorable="d" d:DesignWidth="640" d:DesignHeight="480">
  <Canvas x:Name="LayoutRoot" Width=" 640" Height="480">
      <Button Content="Background" Background="MediumOrchid"   
        Canvas.Top="100" Canvas.Left="100" Width="70">
        </Button>
            <dataInput:DescriptionViewer
                Description="Clicking this button will change the    
         background" Canvas.Top="100" Canvas.Left="165" />
        <TextBox x:Name="Name" Text="{Binding Name, Mode=TwoWay,
                          ValidatesOnExceptions=true, NotifyOnValidationError=true}"
                          Height="23" Width="100" Canvas.Top="70" Canvas.Left="100"/>
          <dataInput:DescriptionViewer Target="{Binding ElementName=Name}"
            Description="Please enter name"
            Canvas.Top="70" Canvas.Left="195"/>
     <dataInput:ValidationSummary Canvas.Top="150" Canvas.Left="165" />
    </Canvas>
</UserControl>

Here, the TextBox is specified with the properties ValidatesOnExceptions and NotifyOnValidationError. And when a DescriptionViewer is associated with the TextBox, it will not just display a tooltip with the specified message but also track the validation state.

Note that in the above case, you won't really see any validation taking place because this is just a fragment, in order to implement validation rules, you will need to write a lot more code in the code behind files. Refer ValidationSummary class on MSDN library to see a complete example of validation. The above example only intends to show how to specify the validation properties with a control that is associated with DescriptionViewer.

Conclusion: This article explored how to use DescriptionViewer in Silverlight 3.