Technique SL8:Displaying HelpText in Silverlight User Interfaces

Example 1: Displaying a long text alternative for an Image with XAML

Application authors can specify the AutomationProperties.HelpText attribute on the Image element. The value provided for the attribute should be a meaningful long text alternative for the image content. The value of AutomationProperties.HelpText should augment rather than duplicate any AutomationProperties.Name or an associated Label or LabeledBy caption. One or both of these is also typically specified to provide the basic (short-text) accessibility support for an image.

<StackPanel x:Name="imgContainer">
 <Image
   Height="400" Width="600"
   Source="/office.png"
   x:Name="imgOffice"
   AutomationProperties.HelpText=”The standard office layout
includes one corner desk unit in the corner farthest from the
door, and one file cabinet against the same wall as the door.”/>
 <sdk:Label x:Name="lblimgOffice" Target="{Binding ElementName=imgOffice}">Diagram of standard office layout</sdk:Label>
 <Button x:Name="HelpButton" Click="HelpButton_Click">Provide text-only alternative description of the previous image</Button>
</StackPanel>

The following event handler removes the Help button and replaces it in UI with a TextBox that displays the long text alternative.

       private void HelpButton_Click(object sender, RoutedEventArgs e)
       {
           imgContainer.Children.Remove(HelpButton);
           TextBox tb = new TextBox();
           tb.IsReadOnly=true;
           tb.Text = AutomationProperties.GetHelpText(imgOffice);
           imgContainer.Children.Add(tb);
           tb.Focus();
       }

Example 2: Using HelpText to augment existing form labels, to provide long text instructions

This example provides instructions for two form fields. The same text is also displayed for mouse users as a Tooltip and the AutomationProperties.HelpText string is used as a common source for both display options. In this example, the form submission does not perform client-side validation (although server-side validation following a data round trip might still exist, or validation could be added similar to the technique shown in ).

The following is the XAML UI:

<UserControl xmlns:sdk="http://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk" 
   x:Class="HelpTextAndToolTip.MainPage"
   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
>
       <Grid x:Name="LayoutRoot" Background="White" Margin="10">
           <Grid.RowDefinitions>
               <RowDefinition Height="Auto"/>
               <RowDefinition Height="Auto"/>
               <RowDefinition Height="Auto"/>
               <RowDefinition Height="Auto"/>
               <RowDefinition Height="Auto"/>
           </Grid.RowDefinitions>
           <Grid.ColumnDefinitions>
               <ColumnDefinition Width="Auto"/>
               <ColumnDefinition Width="200"/>
               <ColumnDefinition Width="Auto"/>
           </Grid.ColumnDefinitions>
           <TextBlock Text="Form With Tooltips" FontSize="16" FontWeight="Bold"
     Grid.Column="1" HorizontalAlignment="Center" />
           <sdk:Label x:Name="NameLabel" Target="{Binding ElementName=NameTextBox}"
     Grid.Row="2" Margin="3"/>
           <TextBox x:Name="NameTextBox" 
     AutomationProperties.Name="{Binding Content, ElementName=NameLabel}"
     Text="{Binding Name, Mode=TwoWay, UpdateSourceTrigger=Explicit}"
     Grid.Column="1" Grid.Row="2" Margin="3"
                    AutomationProperties.HelpText="{Binding NameTextBoxToolTipString,Source={StaticResource TooltipStrings}}">
           <ToolTipService.ToolTip>
               <ToolTip Content="{Binding NameTextBoxToolTipString,Source={StaticResource TooltipStrings}}" />
           </ToolTipService.ToolTip>
           </TextBox>
           <sdk:Label x:Name="AgeLabel" Target="{Binding ElementName=AgeTextBox}"
     Grid.Row="3" Margin="3" HorizontalAlignment="Right"/>
           <TextBox x:Name="AgeTextBox" 
     AutomationProperties.Name="{Binding Content, ElementName=AgeLabel}" 
     Text="{Binding Age, Mode=TwoWay, UpdateSourceTrigger=Explicit}"  
     Grid.Column="1" Grid.Row="3" Margin="3"
    AutomationProperties.HelpText="{Binding AgeTextBoxToolTipString,Source={StaticResource TooltipStrings}}">
           <ToolTipService.ToolTip>
               <ToolTip Content="{Binding AgeTextBoxToolTipString,Source={StaticResource TooltipStrings}}" />
           </ToolTipService.ToolTip>
       </TextBox>
       <StackPanel Orientation="Horizontal">
           <Button x:Name="SubmitButton" Content="Submit" Click="SubmitButton_Click" Grid.Column="1" Grid.Row="4" Width="50" Margin="3" />
           <Button x:Name="HelpButton" Click="HelpButton_Click">Get Help</Button>
       </StackPanel>
       </Grid>
</UserControl>

The following is the resource definition in app.xaml:

       <ResourceDictionary>
           <resources:Resource1 x:Key="TooltipStrings"/>
       </ResourceDictionary>
       

The generated resource code that defines the "Resource1" class is not shown here because it is mostly infrastructure that is produced by a generation task in Visual Studio. For more information about embedded resources in Silverlight, see Resources Overview on MSDN. The resources here contain just two strings:

• NameTextBoxToolTipString: Must be 10 characters or less. Required.
• AgeTextBoxToolTipString Must be a value between 0 and 120. Required.

The following is the event handler code, which changes the interface.

       private void HelpButton_Click(object sender, RoutedEventArgs e)
       {
           AgeLabel.Content = AgeLabel.Content + ": " + AutomationProperties.GetHelpText(AgeTextBox);
           NameLabel.Content = NameLabel.Content + ": " + AutomationProperties.GetHelpText(NameTextBox);
           NameTextBox.Focus();
       }
       

Note the call to Focus() - this puts the screen reader focus on the first form element so that the added text can be read. The very same text source as used for the Tooltip is added programmatically to the existing Label controls.

After the Get Help button is clicked, the visual appearance of the application is modified:

This example is shown in operation in the working example of HelpText and Tooltip.