Exposing basic information about UI elements

Assistive technologies such as screen readers need information about the UI elements in an app. The system provides the information based on an app's representation in the Microsoft UI Automation framework. Basic accessibility information is sometimes categorized into name, role, and value. This topic describes XAML or other code to help your app expose the basic information that assistive technologies need.

Accessible name

An accessible name is a short, descriptive text string that a screen reader uses to announce a UI element. Set the accessible name for UI elements that have a meaning that is important for understanding the content or interacting with the UI. Such elements typically include images, input fields, buttons, controls, and regions.

This table describes how to define or obtain an accessible name for various types of elements in a XAML UI.

Most container elements such as panels do not promote their content as accessible name. This is because it is the item content that should report a name and corresponding role, not its container. The container element might report that it is an element that has children in a UI Automation representation, such that the assistive technology logic can traverse it. But users of assistive technologies don't generally need to know about the containers and thus most containers aren't named.

Role and value

The controls and other UI elements that are part of the Windows Runtime implement UI Automation support for reporting role and value as part of their definitions. You can use UI Automation tools to examine the role and value information for the Windows Runtime controls, or you can read the documentation for the AutomationPeer implementations of each control. The available roles in a UI Automation framework are defined in the AutomationControlType enumeration. UI Automation clients such as assistive technologies can obtain role information by calling GetAutomationControlType from the control's AutomationPeer.

Not all controls have a value. Controls that do have a value report this information to UI Automation through the peers and patterns that are supported by that control. For example, a TextBox form element does have a value. An assistive technology can be a UI Automation client and so discover both that a value exists and what the value is. This is because TextBox supports the IValueProvider pattern through the TextBoxAutomationPeer.

Note  For cases where you use AutomationProperties.Name or other techniques to supply the accessible name explicitly, do not include the same text as is used by the control role or type information in the accessible name. For example do not include strings such as "button" or "list" in the name. The role and type information comes from a different UI Automation property (LocalizedControlType) that is supplied by the default control support for UI Automation. Many assistive technologies append the LocalizedControlType to the accessible name, so duplicating the role in the accessible name can result in unnecessarily repeated words (such as "button button").

Name from inner text

To make it easier to use strings that already exist in the visible UI for accessible name values, many of the controls and other UI elements provide support for automatically determining a default accessible name based on inner text within the element, or from string values of content properties.

• TextBlock, RichTextBlock, TextBox and RichTextBlock each promote the value of the Text property as the default accessible name.
• Any ContentControl subclass uses an iterative "ToString" technique to find strings in its Content value, and promotes these strings as the default accessible name.

Note   The accessible name length cannot be greater than 2048 characters. If a string used for automatic accessible name determination exceeds that limit, the accessible name is truncated at that point.

Accessible names for images

To support screen readers and to provide the basic identifying information for each element in the UI, you sometimes must provide text alternatives to non-textual information such as images and charts (excluding any purely decorative or structural elements). You can do this by setting the AutomationProperties.Name attached property as shown in this example.

<Image Source="product.png"
  AutomationProperties.Name="An image of a customer using the product."/>

Alternatively, consider including a text caption that appears in the visible UI and that also serves as the label-associated accessibility information for the image content. The following example shows how.

<Image HorizontalAlignment="Left" Width="480" x:Name="img_MyPix"
  Source="snoqualmie-NF.jpg"
  AutomationProperties.LabeledBy="{Binding ElementName=caption_MyPix}"/>
<TextBlock Name="caption_MyPix">
Mount Snoqualmie Skiing
</TextBlock>

Labels and LabeledBy

The preferred way to associate a label with a form element is to use a TextBlock with an x:Name for label text, and then to set the AutomationProperties.LabeledBy attached property on the form element to reference the labeling TextBlock by its XAML name . If you use this pattern, when the user clicks the label, the focus moves to the associated control and assistive technologies can use the label text as the accessible name for the form field. Here's an example that shows this technique.

 <StackPanel x:Name="LayoutRoot" Background="White">
   <StackPanel Orientation="Horizontal">
     <TextBlock Name="lbl_FirstName">First name</TextBlock>
     <TextBox
      AutomationProperties.LabeledBy="{Binding ElementName=lbl_FirstName}"
      Name="tbFirstName" Width="100"/>
   </StackPanel>
   <StackPanel Orientation="Horizontal">
     <TextBlock Name="lbl_LastName">Last name</TextBlock>
     <TextBox
      AutomationProperties.LabeledBy="{Binding ElementName=lbl_LastName}"
      Name="tbLastName" Width="100"/>
   </StackPanel>
 </StackPanel>

Accessible description (optional)

An accessible description provides additional accessibility information about a particular UI element. You typically provide an accessible description when an accessible name alone does not adequately convey an element's purpose.

The Narrator screen reader reads an element's accessible description only when the user requests more information about the element by pressing Caps Lock+F.

The accessible name is meant to identify the control rather than to fully document its behavior. If a brief description is not enough to explain the control, you can set the AutomationProperties.HelpText attached property in addition to AutomationProperties.Name.

Testing accessibility early and often

Ultimately, the best approach for supporting screen readers is to test your app using a screen reader yourself. That will show you how the screen reader behaves and what basic accessibility information might be missing from the app. Then you can adjust the UI or UI Automation property values accordingly. For more info, see Testing your app for accessibility.

Accessible names from dynamic data

The Windows Runtime supports many controls that can be used to display values that come from an associated data source, through a feature known as data binding. When you populate lists with data items, you may need to use a technique that sets accessible names for data-bound list items after the initial list is populated. For more info, see "Scenario 4" in the XAML accessibility sample.

Accessible names and localization

To make sure that the accessible name is also an element that is localized, you should use correct techniques for storing localizable strings as resources and then referencing the resource connections with x:Uid values. If the accessible name is coming from an explicitly set AutomationProperties.Name usage, make sure that the string there is also localizable. For more info, see Quickstart: Translating UI resources.

Related topics

AutomationProperties.Name

XAML accessibility sample

Testing your app for accessibility

Build date: 11/29/2012