Using Silverlight Text Elements for Appropriate Accessibility Role

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 .

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.