SL26: Using LabeledBy to Associate Labels and Targets in Silverlight

Applicability

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

Note

Microsoft has stopped updating and distributing Silverlight, and authors are encouraged to use HTML for accessible web content.

This technique relates to:

Success Criterion 1.1.1: Non-text Content (Sufficient)
Success Criterion 1.3.1: Info and Relationships (Sufficient as a way to meet an unwritten technique)
Success Criterion 3.3.2: Labels or Instructions (Sufficient)
Success Criterion 4.1.2: Name, Role, Value (Sufficient as a way to meet G135: Using the accessibility API features of a technology to expose names and notification of changes)

Description

The objective of this technique is to use the AutomationProperties.LabeledBy property to associate a non-interactive text label with an interactive field such as a Silverlight TextBox or RichTextBox. By using this technique, application authors can use the label text as the default source for AutomationProperties.Name on the target, and do not need to specify an explicit AutomationProperties.Name.

This technique relies on several Silverlight features: the Name property for identifying specific UI elements, the AutomationProperties API, and the ElementName variation of Silverlight data binding. AutomationProperties.Name can be set on and can target any Silverlight UIElement. The two most common uses of this labeling technique are for labeling a form field, and for associating an image caption with an image.

Examples

Example 1: Two TextBox form fields, each with a LabeledBy reference to a text label

The following is XAML for the UI (and can be inserted into a UserControl XAML root or elsewhere). No code-behind is necessary for this example; the element relationships are established by the {Binding} values in the XAML and interpreted appropriately by the Silverlight run time.

   <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>

This example is shown in operation in the working example of Labels.

Example 2: Labeling / captioning an image

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

Note

If the caption is not a usable text alternative, use the technique , or change the caption text.

Resources

Resources are for information purposes only, no endorsement implied.

AutomationProperties.LabeledBy
Tools: SilverlightSpy or UIAVerify

Tests

Procedure

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.
Use a verification tool that is capable of showing the full automation tree. (For example, use UIAVerify or Silverlight Spy; see Resources links.)
Verify that any element that has a LabeledBy value has an associated visible label.
Verify that any element that has a LabeledBy value uses the Name value from that label.

Expected Results

#3 and #4 are true.

Using LabeledBy to Associate Labels and Targets in Silverlight

Important Information about Techniques