Edit

Share via

About the Text and TextRange Control Patterns

  • Article

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 Microsoft UI Automation Value control pattern or through direct keyboard input. There's also a TextEdit pattern that supports programmatic change to text.

 

The functionality described in this topic 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 and the 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 the text store.

TSF was designed for applications that need to inject input into context-aware scenarios. The Text control pattern, however, is a read-only solution that is intended 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 must support the Text control pattern. For improved accessibility, Microsoft recommends 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 off-screen 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 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 off-screen 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 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 slide show 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 UIA_Text_TextChangedEventId event to notify clients that the text range is no longer valid and a new one must be retrieved.

Conceptual

How UI Automation Supports Embedded Objects

UI Automation Control Patterns Overview

UI Automation Support for Textual Content

Working with Text-based Controls

Other Resources

Text Services Framework