Freigeben über

  • Artikel

Automation Properties for Accessibility Support in UI

Microsoft Silverlight will reach end of support after October 2021. Learn more.

This topic describes the attached properties for UI accessibility support that are available in Silverlight. These attached properties can be set either in code or in XAML markup. The support class for the attached properties is System.Windows.Automation.AutomationProperties.

This topic contains the following sections:

  • Scenarios for Setting Automation Properties in UI

  • Using References for AutomationProperties Values

  • Other Automation Values

Scenarios for Setting Automation Properties in UI

The attached properties provided by AutomationProperties are useful for scenarios that report accessibility information when consuming an existing control. The control is used by declaring instances of it in XAML, as part of your application UI.

The attached properties provided by AutomationProperties often specifically override values that may be available as part of a control's existing automation peer and automation pattern behavior. This is useful if you know that the peer and pattern behavior is not providing specific accessibility information that you anticipate your users will need in order to interact with the UI.

For example, a default instance of a Button control uses a ButtonAutomationPeer peer. This peer implements the IInvokeProvider pattern, and otherwise uses FrameworkElementAutomationPeer behavior. It also uses a behavior that promotes any inner text found within the button content to be the Name property value for UI Automation. Programs that are a UI Automation client might use UI Automation exposed information. For example, the Narrator application in Windows 7 can read the Name property as part of audio input that reports UI elements on the screen. As a default behavior, many Silverlight controls provide a ToString evaluation of the control content, and provide this evaluated Name to automation clients such as Narrator. However, this might not be an appropriate string for accessibility purposes. By changing the instance value of AutomationProperties.Name, you can override the default behavior and instead provide your specific AutomationProperties.Name string.

The attached properties on AutomationProperties cannot be set on all XAML elements. Specifically, the object where the attached properties are being set must be a UIElement. Examples of objects that might be present in the UI that are not UIElement objects include classes that derive from TextElement, such as Run, Hyperlink, and Paragraph.

Replacing a Code-Centric Name With a Useful UI Name

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.

Reporting Required Form Elements

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

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.

Accelerator Keys and Access Keys

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.

LabeledBy

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.

AutomationID

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.

ItemType and ItemStatus

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.

Using References for AutomationProperties Values

Often, you want to use references to other property values rather than hard-coded strings or new objects in order to provide accessibility information.

The user information presented by a control often comes from templates or styles. AutomationProperties attached properties can be set through a style's setters. In order to do so, you specify the AutomationProperties attached property as the Property value of a Setter. You use an ownerType.propertyName form for this usage, for example <Setter Property="AutomationProperties.Name" Value="Submit Button" />.

In control templates or data templates, you often use references to hook up the instance values and the visual appearance. In control templates, you can use a TemplatedParent reference to alias one of the AutomationProperties attached properties to one of the instance values from the templated control.

You might also want to specifically set AutomationProperties values in code on template application. In this scenario, you are supporting a control that can be templated by host applications, and want the accessibility support to be able to obtain values from any template so long as it meets certain requirements. To enable this, add calls to the AutomationProperties attached property set accessors as part of your OnApplyTemplate implementation.

For data templates and data binding, if you are obtaining values from data, you might also want to use data binding to provide accessibility information from the same data source. Alternatively, you can reference some of the existing UI-visible properties that are databound.

As mentioned previously, most accessibility information reported through System.Windows.Automation.AutomationProperties attached properties needs to be localizable. This generally requires one of two techniques: writing separate XAML definitions per culture, or using a technique that involves data binding and thus necessitates a reference technique for most or all of the System.Windows.Automation.AutomationProperties attached properties you use. For more information, see How to: Make XAML Content Localizable.

Other Automation Values

If you want to set automation properties other than those exposed as an AutomationProperties attached property, then you must implement an automation peer. Through the automation peer, you can override various GetCore methods of FrameworkElementAutomationPeer, which correspond to defined UI Automation properties. Some of these are properties that also have AutomationProperties attached property exposure, but some are only able to be influenced by the peer. For example, you must implement a peer and override the GetClassNameCore method in order to change the values reported by the UI Automation property ClassName 

Silverlight implementation of automation peers for UI Automation does not expose all possible UI Automation properties. For more information about the UI Automation properties that are exposed, see FrameworkElementAutomationPeer.