UI Automation TextPattern Overview

This overview describes how to use Microsoft UI Automation to expose the textual content, including format and style attributes, of text controls in UI Automation-supported platforms. These controls include, but are not limited to, the Microsoft .NET Framework TextBox and RichTextBox as well as their Win32 equivalents.

Exposing the textual content of a control is accomplished through the use of the TextPattern control pattern, which represents the contents of a text container as a text stream. In turn, TextPattern requires the support of the TextPatternRange class to expose format and style attributes. TextPatternRange supports TextPattern by representing contiguous or multiple, disjoint text spans in a text container with a collection of Start and End endpoints. TextPatternRange supports functionality such as selection, comparison, retrieval and traversal.

The functionality described in this overview is vital to assistive technology vendors and their end users. Assistive technologies can use UI Automation to gather complete text formatting information for the user and provide programmatic navigation and selection of text by TextUnit (character, word, line, or paragraph).

UI Automation TextPattern vs. Text Services Framework

Text Services Framework (TSF) is a simple and scalable system framework that enables natural language services and advanced text input on the desktop and within applications. In addition to providing interfaces for applications to expose their text store it also supports metadata for that text store.

However, TSF was designed for applications that need to inject input into context-aware scenarios whereas TextPattern is a read-only solution (with the limited workaround noted above) meant to provide optimized access to a text store for screen-readers and Braille devices.

In short, accessible technologies that require read-only access to a text store can use TextPattern, but will need the more complex functionality of TSF for context-aware input.

Control Types

Text

The Text control is the basic element representing a piece of text on the screen.

A standalone text control can be used as a label or static text on a form. Text controls can also be contained within the structure of a ListItem, TreeItem or DataItem.

Edit

Edit controls enable a user to view and edit a single line of text.

Document

Document controls let a user navigate and obtain information from multiple pages of text.

TextPattern Client APIs

TextPattern Provider APIs

UI elements or controls that support TextPattern by implementing the ITextProvider and ITextRangeProvider interfaces, either natively or through Microsoft UI Automation proxies, are capable of exposing detailed attribute information for any text they contain in addition to providing robust navigational capabilities.

A TextPattern provider does not have to support all text attributes if the control lacks support for any particular attributes.

A TextPattern provider must support the GetSelection and Select functions if the control supports text selection or placement of the text cursor (or system caret) within the text area. If the control does not support this functionality, then it does not need to support either of these methods. However, the control must expose the type of text selection it supports by implementing the SupportedTextSelection property.

A TextPattern provider must always support the TextUnit constants Character and Document as well as any other TextUnit constants it is capable of supporting.

Security

The UI Automation architecture was designed with security in mind (see UI Automation Security Overview). However, the TextPattern classes described in this overview require some specific security considerations.

• Microsoft UI Automation text providers supply read-only interfaces and do not provide the ability to change the existing text in a control.

• UI Automation clients can only use Microsoft UI Automation if they are fully "trusted". An example of this would be the protected Logon Desktop, where only known and trusted applications can run.

• Developers of UI Automation providers should be aware that all information they choose to expose in their controls through Microsoft UI Automation is essentially public and fully accessible by other code. Microsoft UI Automation makes no effort to determine the trustworthiness of any UI Automation client and therefore the UI Automation provider should not expose protected content or sensitive textual information (such as password fields).

• One of the most significant changes in security for Windows Vista is broadly referred to as "Secure Input" which encompasses technologies such as Least-privileged (or Limited) User Accounts (LUA) and UI Privilege Level Isolation (UIPI).

  • UIPI prevents one program from controlling and/or monitoring another more "privileged" program, preventing cross-process window message attacks that spoof user input.

  • LUA sets limits on the privileges of applications being run by users in the Administrators group. Applications won't necessarily have administrator privileges, but will instead run with the least privileges necessary. As a consequence, there may be some restrictions enforced in LUA scenarios. Most notably string truncation (including TextPattern strings), where it may be necessary to limit the size of strings being retrieved from administrator-level applications so they aren't forced to allocate memory to the point of disabling the application.

Performance

Because TextPattern relies on cross-process calls for most of its functionality, it does not provide a caching mechanism to improve performance when processing content. This is unlike other control patterns in Microsoft UI Automation that can be accessed using the GetCachedPattern or TryGetCachedPattern methods.

One tactic for improving performance is by making sure UI Automation clients attempt to retrieve moderately-sized blocks of text using GetText. For example, GetText(1) calls will incur cross-process hits for each character whereas one GetText(-1) call will incur one cross-process hit, but can have high latency depending on the size of the text provider.

TextPattern Terminology

Attribute
A formatting characteristic of a text range (for example, IsItalicAttribute or FontNameAttribute).

Degenerate Range
A degenerate range is an empty or zero-character text range. For the purposes of the TextPattern control pattern, the text insertion point (or system caret) is considered a degenerate range. If no text is selected, GetSelection would return a degenerate range at the text insertion point and RangeFromPoint would return a degenerate range as its starting endpoint. RangeFromChild and GetVisibleRanges may return degenerate ranges when the text provider cannot find any text ranges that match the given condition. This degenerate range can be used as a starting endpoint within the text provider. FindText and FindAttribute return a null reference (Nothing in Microsoft Visual Basic .NET) to avoid confusion with a discovered range versus a degenerate range.

Embedded Object
There are two types of embedded objects in the UI Automation text model. They consist of text-based content elements such as hyperlinks or tables, and control elements such as images and buttons. For more detailed information, see Access Embedded Objects Using UI Automation.

Endpoint
The absolute Start or End point of a text range within a text container.

The following illustrates a set of start and end points.

TextRange
A representation of a span of text, with start and end points, in a text container including all associated attributes and functionality.

TextUnit
A pre-defined unit of text (character, word, line, or paragraph) used for navigating through logical segments of a text range.

See also

• UI Automation Control Patterns for Clients
• UI Automation Control Patterns Overview
• UI Automation Tree Overview
• Use Caching in UI Automation
• Support Control Patterns in a UI Automation Provider
• Control Pattern Mapping for UI Automation Clients
• Text Services Framework