# Providing Text Equivalent for Nontext Silverlight Controls With AutomationProperties.Name

ID: SL18

Technology: silverlight

Type: Technique

## When to Use

- Microsoft Silverlight, versions 3 and greater
- Silverlight managed programming model and Silverlight XAML

## Description

The objective of this technique is to use the Silverlight `AutomationProperties.Name` property to provide a short text alternative for controls that do not otherwise contain text. The text is intended to provide human-readable identifiers and short-descriptions or user instructions for accessibility frameworks, which can then be reported to assistive technologies.

"Control" in this technique refers to any element that is based on the Silverlight `Control` class, and is keyboard-focusable either by user action or calling focus to the control programmatically. The non-text control in question might be something like a button that communicates information using only an icon or image. For example, a triangle image rotated 90 degrees clockwise is commonly used in many user interfaces to indicate a "Play" button control. This "Play" icon mimics interface metaphors from many non-software consumer products, and is often presented in a user interface without any nearby visible text information that explains the purpose of the control. Another example is a "thumbnail" metaphor where a small image serves as a control that can be activated, and where the action results in the display of a larger version of the same image, or enters an editing mode that loads the same image.

For cases of controls such as buttons that invoke actions, the text alternative also identifies link purpose.

In Silverlight, a text-only identifier for any control can be set specifically as `AutomationProperties.Name` on the parent control. Silverlight control compositing techniques enable either per-control images that are specified by the application author, or a general-purpose image/icon for a control that is part of the control's template and displays that way by default. The Silverlight API `AutomationProperties.Name` directly sets `Name` 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 (or as an MSAA client, which relies on the UIA-MSAA bridge).

## Examples

### Applying a text alternative for an icon Button with XAML

Application authors can specify the `AutomationProperties.Name` attribute on the `Button` element, and leave accessibility information for the composited `Image` content unspecified. It is the button and its action that is relevant to users, not the non-interactive `Image` component. The value provided for `AutomationProperties.Name` is a meaningful text alternative for the action conveyed by the button's icon/image, but where the functionality is conceptually embodied in the button and not its images or other constituent parts in compositing or visual design.

     <Button
       Height="20" Width="50"
       AutomationProperties.Name="Pause Media">
       <Image Height="12" Width="12" Source="/icon_pause.png"/>
     </Button>

This example is shown in operation in the working example of Button Text Alternative.

## Tests

### Accessibility framework view

### Procedure

1. Using a browser that supports Silverlight, open an HTML page that references a Silverlight application through an object tag.
2. Use a verification tool that is capable of showing the full accessibility framework tree, and an object’s "Name" text alternative as part of the tree. Verify that all interactive elements such as buttons without visible text provide a human-readable text identifier "Name" in the automation tree.

### Expected Results

#2 is true.

### Screen Reader

### Procedure

1. Using a browser that supports Silverlight, open an HTML page that references a Silverlight application through an object tag.
2. Engage the screen reader. Press TAB to traverse the tab sequence inside the Silverlight content area to focus to a composite control that has no visible text, but has an `AutomationProperties.Name` applied.
3. Check that the "Name" as applied to the control instance, along with the class name of the named control, is read by the screen reader.

### Expected Results

#3 is true.

## Related Techniques

- SL30

## Resources

- Automation Properties for Accessibility Support in UI
- AutomationProperties.Name Attached Property
- Tools: SilverlightSpy or UIAVerify