Techniques for WCAG 2.0

Skip to Content (Press Enter)

-

SL19: Providing User Instructions With AutomationProperties.HelpText in Silverlight

Applicability

This technique relates to:

User Agent and Assistive Technology Support Notes

See User Agents Supported for general information on user agent support.

Not all assistive technologies choose to read or present information from the UI Automation tree for Silverlight in cases where the corresponding UI object is not focusable in the tab sequence. This technique provides the support for introducing the information into the UI Automation tree for that element, but cannot guarantee that a given assistive technology provides the user with access to the element information from that UIA tree.

The HelpText property is readable in the UIA framework by any client that programs against the basic UIA property model, and that property is forwarded/bridged to MSAA through the get_accHelp method. However, as of 13 January 2011, no known assistive technology provides users with a technique or interface option that accesses the HelpText / get_accHelp information.

Description

The objective of this technique is to provide a long text alternative that serves the same purpose and presents the same information as the original non-text content when a short text alternative is not sufficient, and to show the practice of storing that information in a dedicated property of the Silverlight-supported UI Automation support system. The technique can also be used on text controls (such as TextBox), for cases where the control text itself does not provide enough context to suggest an appropriate user action.

The relevant UI Automation property is named HelpText, to connote its possible usage to provide imperative instructions for interactive elements. However, the same property can instead be used for long text alternatives for nontext objects. The Silverlight API AutomationProperties.HelpText directly sets HelpText in the UI Automation tree. The properties in the UI Automation tree are reported to assistive technologies, when the assistive technology implements behavior that acts as a UI Automation client.

AutomationProperties.HelpText can be set in code, but is most typically set as an attribute in XAML that defines a Silverlight UI.

The same information as is present in AutomationProperties.HelpText could also be useful to sighted users. In this case, the same text could be displayed in a Silverlight ToolTip control. The reason that application authors should use both AutomationProperties.HelpText AND Tooltip in conjunction is because the Tooltip information is not introduced into the runtime accessibility framework information set. This is because a tooltip is transient and not conventionally focusable. In Silverlight programming, a useful technique for sharing the same resource is to combine the Silverlight data binding feature with the .NET Framework embedded resource feature. For more information on combining Silverlight data binding and resources for common string sources, see How to Make XAML Content Localizable.

Examples

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

To introduce the necessary information to Silverlight XAML for an application UI definition, specify the AutomationProperties.HelpText attribute on the Image element. The value provided for the attribute is a meaningful long text alternative for the image content. The value of AutomationProperties.HelpText should augment rather than duplicate AutomationProperties.Name, which is also typically specified to provide accessibility support for an image.

 <Image
   Height="400" Width="600"
   Source="/office.png"
   AutomationProperties.Name="Diagram of standard office layout"
   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.”/>

Example 2: Using HelpText as form instructions

This example provides instructions for two form fields by using both Tooltip and AutomationProperties.HelpText. The strings used for these purposes are shared to both methodologies by defining the strings as resources and binding to them. In this example, the form submission does not perform client-side validation (although server-side validation following a data round trip might still exist).

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>
           <Button x:Name="SubmitButton" Content="Submit" Click="SubmitButton_Click"
             Grid.Column="1" Grid.Row="4" Width="50" Margin="3" />
       </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, each of which would typically be defined in a Visual Studio .resx file. Resources in a .resx file can be localized or changed separately from code by the appropriate localization toolsets for Microsoft localization/development.

These examples are shown in operation in the working example of Automation Properties Help Text and working example of HelpText and ToolTip.

Resources

Resources are for information purposes only, no endorsement implied.

Tests

Procedure

  1. Using a browser that supports Silverlight, open an HTML page that references a Silverlight application through an object tag. To see UI Automation, use Microsoft Windows as platform.

  2. Use a verification tool that is capable of showing the full automation tree, and an object’s long text alternative as part of the tree. (For example, use UIAVerify or Silverlight Spy; see Resources links.)

  3. Focus an element that is known to have a long text alternative. Check that the AutomationProperties.HelpText as applied to individual UI elements appears as the HelpText or acc_Help value in the automation tree.

Expected Results

#3 is true.

If this is a sufficient technique for a success criterion, failing this test procedure does not necessarily mean that the success criterion has not been satisfied in some other way, only that this technique has not been successfully implemented and can not be used to claim conformance.