Techniques for WCAG 2.0

Skip to Content (Press Enter)

This document is a draft, and is designed to show changes from a previous version. It is presently showing added text,changed text,deleted text,[start]/[end] markers,and Issue Numbers.

Hide All Edits   |   Toggle Deletions  |   Toggle Issue Numbers   |   Toggle [start]/[end] Markers   |   Show All Edits

Changes are displayed as follows:

-

SL32: Using Silverlight Text Elements for Appropriate Accessibility Role

Applicability

This technique relates to:

User Agent and Assistive Technology Support Notes

See User Agents Supported for general information on user agent support.

JAWS version 12 misreports a read-only RichTextBox as "edit", despite it reporting its role as "document" to both UIA and MSAA. Text is still read by JAWS 12, but users might expect that they would be able to enter text in an element that JAWS 12 reports as edit, whereas in fact they cannot enter text.

Description

The objective of this technique is to choose a Silverlight text container that provides appropriate behavior and accessibility roles for different types of text content. How those roles interact with existing assistive technologies that are interpreting Silverlight under the larger concept of being an "HTML control part" is also a factor in which Silverlight text container should be used in an application's composition.

Text containers can identified by role to accessibility frameworks, and each type of Silverlight text container uses a different role. Application authors should choose text containers that combine the desired behavior in the user interface with an accessibility role that can be consumed by existing assistive technology implementations.

The Silverlight core libraries define the following classes that are specifically intended as text containers:

UI Automation programmatic access

For programming information that is relevant for how Silverlight application authors produce the application, each text container has its own object model/API. That API is documented on MSDN, specifically for each class TextBox; RichTextBox; TextBlock.) However, rather than using the Silverlight-specific object models, most assistive technologies that are capable of reporting on Silverlight will choose to use UI Automation (or MSAA) to obtain information about the Silverlight elements in general. Text containers within the Silverlight content are identified through UIA accessibility roles. This is because the assistive technologies can use UI Automation to query for ANY relevant text items from the content (and chrome) of the user agent / browser host, not just those that come from Silverlight. That can include the HTML content, items created from scripting, CSS or other plugin-internal object models and so on. In other words, text from Silverlight is integrated into the overall UI Automation view of the user agent host as the top-level application in a platform view. Different types of "text" in a general sense might appear as different UI Automation patterns, as is described below.

TextBox

A TextBox within the Silverlight content area is reported to UI Automation as an Edit role (through MSAA, as Editable Text).

Edit controls are expected to implement the Value pattern for UIA, so that the value of the edit area can be queried or set by a client. Assistive technologies can use this value as a text-string value for screen readers or other purposes.

In typical user interface design, a form with an input field also includes a label or other explanatory text that is proximally close to the input field. In order to maintain proper reading order, the label should typically appear immediately before the input field. This general model should also be used for Silverlight user interface design. For more information on labeling for TextBox controls, see SL26: Using LabeledBy to Associate Labels and Targets in Silverlight.

RichTextBox

A RichTextBox within the Silverlight content area is reported to UI Automation and MSAA as a Document role.

A RichTextBox can either be set to be a read-only control, or left as a read-write control. In the latter case, users can insert a text cursor and make changes to the text. It is more common in Silverlight programming to set the RichTextBox to be read-only; in this scenario the reason for using RichTextBox is because TextBlock did not offer the range of text formatting options that are possible from a RichTextBox.

In UIA, a document is generally expected to support the Text pattern for UI Automation. However, to read the text from a RichTextBox, the assistive technology does not necessarily have to implement code that handles the entirety of the information that the Text pattern reports.

More about the Text pattern

The Text pattern provides APIs to iterate over the internal structure of a document and return text ranges. Each such text range can be queried for specific properties, and can return its plain text string value to UI Automation. Ranges can also be programmatically adjusted by the TextPattern/TextRange APIs. The following is a snippet of a Silverlight-specific UI Automation tree utility to give a general idea of the APIs involved. Note that these are not specifically Silverlight APIs; they are .NET Framework APIs. .NET Framework or Windows Automation APIs are generally what is used for programming a UI Automation client, which runs on a platform runtime rather than the Silverlight runtime. Using the Text pattern is generally what is necessary in order for an assistive technology to obtain a comprehensive view of the "value" for a document role object.

private void FindTheTextPatterns_Click(object sender, RoutedEventArgs e)
{
   if (allSilverlight != null && allSilverlight.Count>0)
   {
       //for simplicity just processing item 0, not assuming more than one SL control
       //on the page because this app controls the page being loaded
       AutomationElementCollection documentsList = allSilverlight[0].FindAll(TreeScope.Descendants,
           new PropertyCondition(AutomationElement.ControlTypeProperty,ControlType.Document)
   );
   for (int j=0; j< documentsList.Count;j++) {
       TextPattern targetTextPattern = 
         documentsList[j].GetCurrentPattern(TextPattern.Pattern) as TextPattern;
       if (targetTextPattern!=null) {
           TextPatternRange tr = targetTextPattern.DocumentRange;
           MessageBox.Show(tr.GetText(Int16.MaxValue));
       }
   }
}
private void GetAllSilverlight()
{
   allSilverlight = this._clientAppRootInstance.FindAll(TreeScope.Descendants,
      new PropertyCondition(AutomationElement.ClassNameProperty, "MicrosoftSilverlight"));
}

MSAA has only limited possibilities for interacting with a Document role, and MSAA code for attempting to do so is not shown.

TextBlock

TextBlock is reported as a Text role in UI Automation. TextBlock has several important characteristics:

  • A TextBlock is always read-only; only the application author can declare the text, users cannot change it.

  • A TextBlock is not considered to be a true control in the Silverlight object model (it is not a class derived from Control). The practical implications of this to accessibility scenarios is that a TextBlock is not in the default tab sequence, cannot be manually added to any tab sequence, and cannot be keyboard-focused either programatically or by the user.

  • TextBlock has a deliberately limited range of block / span formatting options. If the application author desires a wider range of formatting options, for example supporting a "Paragraph" metaphor for blocks of text, a read-only RichTextBox should be used instead.

If the user relies solely on navigating a Silverlight application using the TAB sequence, such navigation will skip over any TextBlock in the interface. This could have implications for how users who use screen readers can interact with the Silverlight content. Screen readers typically read text only from the currently focused element in cases where the user is moving through the TAB sequence or changing focus within the application, and thus cannot read the text from a TextBlock in such a mode. However, most screen readers also have modes for reading text that is not necessarily focusable. These are generally the same modes that screen readers use for a conventional non-interactive HTML document text. For example, some screen readers support a mode that reads text by line, or by word. These modes can read text from a TextBlock.

Examples

Example 1: Structure from a container that has non-semantic role in UI Automation, and TextBlock for text

If viewed as a UI Automation tree, the StackPanel and Grid do not exist explicitly in the tree view, because they do not serve a semantic role (only a presentation role). Rather, the tree consists of the items that report some kind of semantic control type. The semantic children of the containers are still reported in the order that they were declared, when viewed as children of the next semantic container upwards in the tree, and despite the containers themselves being abstracted out of the tree. This defines the reading order. This example is a large block of text with intentionally simple formatting, where the only formatting is to represent paragraphs as separate TextBlock elements to support an adaptive layout, but no Run blocks within.

When viewed with assistive technologies that represent the contents, each TextBlock is a control type of Text. Screen readers can use document reading modes such as virtual cursor modes to read the content from each element and each element's content, following the same reading order as is declared in the XAML. For example, in JAWS 12, readers can read out this text container line by line using (Jaws Key)+DownArrow. It is actually JAWS that determines the line length, because the line length otherwise is defined only by the adaptive layout at runtime, which is not reported to UIA.

  <StackPanel x:Name="LayoutRoot" Background="White">
          <TextBlock>Call me Ishmael. Some years ago--never mind how long precisely--
having little or no money in my purse, and
nothing particular to interest me on shore, I thought I would sail about a little 
and see the watery part of the world. It is a way I have of driving off the spleen 
and regulating the circulation. Whenever I find 
myself growing grim about the mouth; whenever it is a damp, drizzly November in 
my soul; whenever I find myself involuntarily pausing before coffin warehouses, 
and bringing up the rear of every funeral I meet;
and especially whenever my hypos get such an upper hand of me, that it requires a strong moral 
principle to prevent me from
deliberately stepping into the street, and methodically knocking people's hats off--then, 
I account it high time to get to sea as
soon as I can. This is my substitute for pistol and ball. With a philosophical flourish Cato 
throws himself 
upon his sword; I quietly take to the ship. There is nothing surprising in this. If they but knew it, 
almost all men in their degree, some time or other, cherish very nearly the same feelings towards the 
ocean with me.
          </TextBlock>
          <TextBlock>There now is your insular city of the Manhattoes, belted round by wharves as Indian isles 
          by coral reefs--
commerce surrounds it with her surf. Right and left, the streets take you waterward. 
Its extreme downtown is the battery, where
that noble mole is washed by waves, and cooled by breezes, which a few hours previous 
were out of sight of land. Look at the crowds of water-gazers there.
          </TextBlock>
          <TextBlock>Circumambulate the city of a dreamy Sabbath afternoon. Go from Corlears Hook 
          to Coenties Slip, and from thence, by Whitehall, northward.
What do you see?--Posted like silent sentinels all around the town, stand thousands 
upon thousands of mortal men fixed in ocean
reveries. Some leaning against the spiles; some seated upon the pier-heads; 
some looking over the bulwarks of ships from China; 
some high aloft in the rigging, as if striving to get a still better seaward peep. 
But these are all landsmen; of week days pent
up in lath and plaster--tied to counters, nailed to benches, clinched to desks. 
How  then is this? Are the green fields gone? What do they here?
          </TextBlock>
  </StackPanel>

Example 2: Text containers and their UIA representation

The following example is intended as sample XAML to view in an accessibility framework viewer, to see the various names, roles, and patterns for obtaining value.

Resources

Resources are for information purposes only, no endorsement implied.

Tests

Procedure

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

  2. Use a verification tool that is capable of showing the full automation tree. (For example, use UIAVerify or Silverlight Spy; see Resources links.)

  3. Verify that TextBox elements in the Silverlight user interface have the Edit role, that RichTextBox elements have the Document role, and TextBlock has Text role in UI Automation.

  4. Verify that the text content can be programmatically determined by techniques that are appropriate for that role.

Expected Results

#3 and #4 are true.

If this is a sufficient technique for a success criterion, failing this test procedure does not necessarily mean that the success criterion has not been satisfied in some other way, only that this technique has not been successfully implemented and can not be used to claim conformance.