Automation Properties for Accessibility Support in UI

UI automation reports UI elements by name, based on the GetName method from the base automation peer class. This name can also be provided in localized form based on current culture of the run time, through the GetLocalizedControlType method. But each of these potentially reports the class-based information, so if you had a screen reader reporting the UI contents of an application that contained two buttons, information might be provided to the user as "button, button."

Most existing Silverlight controls provide further integrated UI Automation support for key UI Automation properties. For example, the GetName implementation in text container controls attempts to walk the automation tree. If any valid plain-text strings can be obtained from content within the element, this string is used for Name in UI Automation and is promoted through the automation tree. However, this still might not be the accessibility information you want to present to users.

For these situations, you can use the AutomationProperties.Name attached property to set specific values in the UI. The name is often the most important accessibility clue for what the user is supposed to do when interacting with the control in your application, and is the automation property that is most often consumed by UI Automation clients. As stated previously, Silverlight automation support often generates a default for AutomationProperties.Name, in order to provide a baseline accessibility experience. Provide an override if the default is not suitable. This is particularly important for images or media elements, where the AutomationProperties.Name can provide a brief equivalent of the HTML paradigm of "alt text" for a UI, but no Silverlight default could be generated.

Note that if you set this value in XAML, you will then potentially need to localize the XAML, because it now contains culture-specific information. This is true for many of the AutomationProperties properties. There are some recommended techniques for doing this, through Silverlight data binding and separate resource dictionaries. For more information, see How to: Make XAML Content Localizable.

A control might be a TextBox that is part of a conceptual form for data entry, and an entry for that TextBox is required by your subsequent validation routine (using Validation or other techniques). In this case, you could report the fact that this TextBox is a required form entry to the UI automation layer, at a time when the UI is initially displayed rather than waiting for a failed validation to come back to the user. You do this by setting a value as an attached property:

<TextBox Name="tb_PhoneNumber" AutomationProperties.IsRequiredForForm="true"/>

Help text is any text or label that might assist a user to determine how an element in the UI should be used, or what it represents. Conceptually, help text can be used like the ALT label of an HTML image. However, in Silverlight accessibility, you can apply this help text to any UI element that is visible and reports itself to mouse-over and hit testing. For example, the help text for a MediaElement might be "Introductory Video." The help text for a Play button connected to the MediaElement might be "Click this button to play Introductory Video."

Apply help text to any UI element by setting a value for the AutomationProperties.HelpText attached property in XAML. This is generally a string that must be localized if the other UI of your application is localized. For more information, see How to: Make XAML Content Localizable.

Users who use the accessibility features often want to use access keys or accelerator keys as a way to avoid the need to precisely position the mouse or go through a long tab sequence. You can report access key or accelerator key information through the AutomationProperties.AcceleratorKey and AutomationProperties.AccessKey attached properties.

Control implementations might already implement access key behavior. If you are consuming a third part control, you may need to consult available documentation for that control to determine if there is existing key handling when you use a control instance in your application. The purpose of AutomationProperties.AccessKey and the System.Windows.Automation.AutomationProperties attached properties is to provide instance values for behavior that are not already present, defined in the control class definition or in a control's applied generic template. Note that the control-based key handling might be specifically handling the KeyDown and KeyUp events, which prevents your instance from handling any such key values and makes them unavailable for instance-based event handling. In these cases the control may already be reporting AccessKey/AcceleratorKey information to UI Automation.

In UI design there are often labels that assist all users in discovering the purpose of elements in the UI. For accessibility, it is useful to know that certain elements are purely a label and refer to other elements that represent the actual purpose or functionality. Silverlight implements a Label control that serves this purpose and reports the necessary labeling-characteristic information to UI automation. But you can also define other elements to serve as labels, and then set the AutomationProperties.LabeledBy attached property. Use an ElementName binding to reference the labeled-by object if you set it in XAML, or use an object reference for the second parameter of the SetLabeledBy method if you set it in code.

The AutomationProperties.AutomationId property is useful for automation frameworks and testing, in order to distinguish UI elements that do not have any other distinguishable properties, such as Name, x:Name, or AutomationProperties.Name. This is not specifically an accessibility scenario. For accessibility, if users need to distinguish between control instances, you should use one of the UI Automation properties that are more relevant for accessibility-related clients such as screen readers. For example, use AutomationProperties.Name, not AutomationProperties.AutomationId.

The AutomationProperties.ItemType and AutomationProperties.ItemStatus attached properties are useful for overriding automation information that is reporting compositing information that is not useful to the user. For example, an AutomationProperties.ItemStatus might report a text string that parallels the control's applied VisualStateManager template. An AutomationProperties.ItemType might replace a non-friendly control name with a friendly name or accessibility information that is more task-oriented for the user.