Technique SL32:Using Silverlight Text Elements for Appropriate Accessibility Role
About this Technique
This technique is not referenced from any Understanding document.
This technique applies to content implemented in Microsoft Silverlight.
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 .
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
TextBlockis always read-only; only the application author can declare the text, users cannot change it. - A
TextBlockis not considered to be a true control in the Silverlight object model (it is not a class derived fromControl). The practical implications of this to accessibility scenarios is that aTextBlockis 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. -
TextBlockhas 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-onlyRichTextBoxshould 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.
<StackPanel x:Name="LayoutRoot">
<TextBox Text="This is a TextBox"/>
<RichTextBox>
<Paragraph>This is a RichTextBox.</Paragraph>
</RichTextBox>
<TextBlock Text="This is a TextBlock"/>
</StackPanel>
Related Resources
No endorsement implied.
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
TextBoxelements in the Silverlight user interface have the Edit role, thatRichTextBoxelements have the Document role, andTextBlockhas Text role in UI Automation. - Verify that the text content can be programmatically determined by techniques that are appropriate for that role.
Expected Results
#3 and #4 are true.