UI Automation Text Pattern 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. Text controls include, but are not limited to, documents, tooltips, edit controls, and rich edit controls.
The textual content of a control is exposed by using the Text control pattern, which represents the contents of a text container as a text stream. The Text control pattern requires the support of the TextRange control pattern to expose format and style attributes. The TextRange control pattern supports the Text control pattern by representing contiguous or multiple, disjoint text spans (or ranges) in a text container with a collection of Start and End endpoints. The TextRange control pattern supports functionality such as selection, comparison, retrieval and traversal.
Note The Text control pattern does not provide a means to insert or modify text. However, depending on the control, this may be accomplished by using the UI Automation Value control pattern or through direct keyboard input.
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).
This topic contains the following sections:
- UI Automation TextPattern vs. Text Services Framework
- Control Types
- Provider Interfaces
- Client Interfaces
- Performance
- Text Pattern and Virtualized Embedded Objects
- Using the Custom Control Type with the Text Control Pattern
- Lifetime of a Text Range
- Related Topics
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 in applications. In addition to providing interfaces for applications to expose their text store, it also supports metadata for that text store.
TSF was designed for applications that need to inject input into context-aware scenarios, while the Text control pattern is a read-only solution (with the limited workaround noted in the previously section) that is meant to provide optimized access to a text store for screen-readers and Braille devices.
Accessible technologies that require read-only access to a text store can use the Text control pattern, but will need the functionality of TSF for context-aware input.
For more information, see Text Services Framework.
Control Types
The UI Automation Edit control type and Document control type are required to support the Text control pattern. For improved accessibility, we recommend that the ToolTip and Text control types also support the Text control pattern, but it is not required.
Provider Interfaces
UI Automation providers support the Text control pattern for a control by implementing the ITextProvider and ITextRangeProvider interfaces. These interfaces expose detailed attribute information for text in the control and provide robust navigational capabilities.
A provider does not need to support all text attributes if the control lacks support for any particular attribute.
A provider must support the ITextProvider::GetSelection and ITextRangeProvider::Select methods 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, 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 ITextProvider::SupportedTextSelection property.
A provider must always support the TextUnit constants, TextUnit_Character and TextUnit_Document, as well as any others it is capable of supporting.
Note The provider may skip support for a specific TextUnit by deferring to the next largest unit supported in the following order: TextUnit_Character, TextUnit_Format, TextUnit_Word, TextUnit_Line, TextUnit_Paragraph, TextUnit_Page, and TextUnit_Document.
Client Interfaces
UI Automation client applications use the IUIAutomationTextPattern and IUIAutomationTextRange interfaces to access the textual content of a text control. Clients use IUIAutomationTextPattern to select spans of text called text ranges, and to retrieve pointers to IUIAutomationTextRange interfaces for the ranges. The IUIAutomationTextRange interface enables clients to manipulate the text range, and to retrieve information about the text in the range, including attributes such as font name, foreground color, underline style, and so on. For more information, see Text Attribute Identifiers.
Performance
The Text control pattern relies on cross-process calls for most of its functionality, so it does not provide a caching mechanism to improve performance when it processes content. Other control patterns in Microsoft UI Automation can be accessed by using the IUIAutomationElement::GetCachedPattern method.
One technique for improving performance is to ensure that UI Automation clients attempt to retrieve moderately sized blocks of text by using the IUIAutomationTextRange::GetText method. For example, using GetText to retrieve single characters will incur cross-process hits for each character, whereas not specifying a maximum length when calling GetText will incur one cross-process hit, but can have high latency depending on the size of the text range.
Text Pattern and Virtualized Embedded Objects
Whenever possible, a provider implementation of ITextProvider and ITextRangeProvider should support the entire text of a document, including any text outside of the viewport. For offscreen text or embedded objects that are virtualized, providers should support the VirtualizedItem control pattern (IVirtualizedItemProvider).
If a document is virtualized while the entire text stream is still available, the ITextProvider::DocumentRange property will retrieve a text range that includes the entire document. However, calling the ITextRangeProvider::GetChildren method will retrieve a collection of virtualized objects that represent all embedded objects in the document. To interact with a virtualized embedded object, clients must call the IVirtualizedItemProvider::Realize method, which makes the items fully accessible as UI Automation elements. Clients must follow a similar process to work with grid elements in an embedded table where a portion of the table is offscreen and virtualized.
Using the Custom Control Type with the Text Control Pattern
While the Text control pattern supports many text attributes and embedded objects, it is not possible to define in advance all possible document elements and presentation types. For document elements that are not supported by the existing attributes or standard control types, providers can use the extensibility features provided by the UI Automation Custom control type.
For example, UI Automation does not define text attributes for document headers, often represented as "header 1", "header 2", and so on, in HTML and other text markup languages. Instead of exposing the heading information, providers can allocate custom child objects whose LocalizedControlType property contains heading information. Because LocalizedControlType is a human readable string, clients can read or display it directly to the user.
For applications and user interfaces that are based on page presentations, the boundary and layout presentation of "page" can also be expressed as an embedded object that has a custom control type (that is, LocalizedControlType="page"). That way, the embedded object can host other page elements that cannot easily be part of the document text stream, such as the header and footer fields of each page, as children of the "page" embedded object. Alternatively, each "page" object can support the Text control pattern independently, which works well for applications such as authoring tools for slideshow presentations, or page-based desktop publishing environments.
Lifetime of a Text Range
If possible, a provider should ensure that any text changes, such as deletions, insertions, and moves, are reflected in the associated text range. If updating the text range is not possible, the provider should raise a TextChanged event to notify clients that the text range is no longer valid and a new one must be retrieved.