Overview of the Technology

Text Services Framework was designed to provide applications with a next- generation input solution that supports a wide range of advanced text services including accessibility, speech, handwriting, and keyboard input, as well as proofing and reference services. These services are supported through a single application programming interface (API), which is device- and language-independent.

Through the TSF APIs, applications expose document content and meta-content to services for inspection and editing. Text services can, in turn, associate and persist state with that content. The rich exchange of information between the text services and the application document enables recognition services to provide more accurate conversion results and seamless, natural input and correction behavior. Since the text services themselves are solely responsible for implementing input behavior, they are able to present a consistent user interface (UI) across applications.

TSF Capabilities

Again, one of the general benefits of TSF is its ability to provide text services within the context of a document, which improves conversion accuracy. Data persistence, the negotiation of text services, and interfaces for creating a custom UI are other capabilities that TSF offers.

Empowering Services and Applications

TSF has access to the document buffer and can use this context to provide optimal conversion results. For example, in the scenario represented in Figure 23-1, a speech service can examine the current selection and, in this case, can see the insertion point is before the word "apple." Consequently, the speech service inserts "red" instead of "read." Additionally, TSF enables applications to share both metadata and hints related to a document object or specific range of text-such as "This is a date or number field." Metadata such as this allows recognizers to significantly narrow the recognition domain and to provide optimal accuracy.

Figure 23.1 - The speech service within TSF.

Data Persistence

In addition to providing context to services and applications, TSF offers further capabilities through data persistence. With data persistence, a text service can store and retrieve important state information (such as a language ID or conversion alternatives) with text in the document. For example, a user reviewing a document into which text was dictated might see "wreck a nice beach," when the actual dictation was "recognize speech." Since the audio and alternatives were stored with the document, the user can listen to the original audio to understand what was intended. Similarly, a keyboard service can store the keystrokes or perhaps phonetic data to capture the original user input.

Data persistence can also be used to simply defer recognition. For example, a handwriting service, via the TSF text interfaces, can insert the raw ink objects into the document until it has sufficient information and confidence to perform the conversion. Another possibility is to enable the user to insert handwritten input into the document (like an "analog" notepad today) until the user wants it converted.

Moreover, data persistence makes it possible to have dynamic text and seamless, natural input. Services make changes and store state directly with the application text buffer, so input compositions need never be "final." The service can always retrieve the original device and conversion information and resume its recognition. The information and data that are persisted are, by default, completely transparent to the application, though the application can choose to be picky about what it serializes.

Negotiation of Text Services and Creation of Custom UI

TSF also provides support for text services to be utilized simultaneously and for them to interact behind the scenes at the UI level. For instance, a user can dictate text while typing with a keyboard text service, and correct the dictation with a handwriting text service. In addition, TSF manages input so it does not collide and allows services to be enabled or disabled as required.

In addition to managing activation and document access, TSF provides optional interfaces that text services can use to host their UI elements (for example, mode buttons). This customized UI is incorporated into a central UI element-the system Language bar. The Language bar allows text services to expose a custom UI within it, so there is less need for individual toolbars that are specific to a particular text service. Nonetheless, text services can still choose to provide their own individual toolbars.

Architecture and Object Model

You have seen some of the benefits that TSF offers. This section examines the architecture of TSF and demonstrates how TSF works. TSF is divided into three distinct components:

• Applications. An application is responsible for display, direct editing (such as of formatting or layout, which are functions that do not pass through the TSF layer), and storage of the text. The application provides access to its text by implementing support for TSF's ITextStore interfaces (among others), and communicates with TSF using the interfaces that the TSF manager exposes.
• Text services. A text service, which acts as a service provider to an application, can obtain text from and write text into the application. It can also associate data and properties with a block of text. A text service is implemented as a Component Object Model (COM) in-process server that registers itself with TSF. Once registered, the user interacts with the text service using the Language bar or keyboard shortcuts.
• TSF manager. The TSF manager acts as a communication mediator between an application and one or more text services. A text service does not need to interact directly with an application and, likewise, an application does not need to interact directly with a text service. The TSF manager is implemented by the operating system and cannot be replaced.

Figure 23-2 shows the architectural divisions in TSF, along with some of the important objects within the divisions.

Figure 23.2 - Architecture of TSF.

TSF is a single-process global COM object. A hierarchy of apartment-threaded objects are exposed through the main interface. At the top of the hierarchy is a thread manager (TM), inside of which are document managers (DM). The TM creates a DM at the application's request, for each stream of editable text.

ITextStore and Editing

The ITextStore interface is a means for applications to share text streams with TSF text services or Microsoft Active Accessibility clients. Each document is exposed as a stream of Unicode characters, some of which might reference embedded content. Clients can read or potentially modify the document content.

Applications are responsible for implementing either ITextStoreACP or ITextStoreAnchor. (If an object exposes both, TSF will use ITextStoreAnchor.) Clients advise their servers with either ITextStoreACPSink or ITextStoreAnchorSink. If an application decides to implement ITextStoreAnchor, it must also implement IAnchor.

Table 23-1 shows the ITextStore family of interfaces, though this is not meant to be a complete list.

Table 23-1 ITextStore family of interfaces.

ITextStore::GetSelection	ITextStoreSink::OnLockGranted
ITextStore::SetSelection	ITextStoreSink::OnStatusChange
ITextStore::GetText	ITextStore::AdviseSink
ITextStore::SetText	ITextStore::UnadviseSink
ITextStore::GetEmbedded	ITextStore::RequestLock
ITextStore::InsertEmbedded	ITextStore::GetStatus
ITextStoreACP::GetEndACP	ITextStore::QueryInsert
ITextStore::GetACPFromPoint	ITextStore::GetFormattedText
ITextStore::GetTextExt	ITextStore::GetActiveView
ITextStoreSink::OnTextChange	ITextStore::GetScreenExt
ITextStoreSink::OnSelectionChange	ITextStore::GetWnd
ITextStoreSink::OnLayoutChange

How an application offers its ITextStore implementation differs among TSF and Active Accessibility. The details are covered in the Microsoft Windows Platform software developer kit (SDK) documentation, available at http://msdn.microsoft.com.

ITextStore generates notifications that inform the client as to when text is changed, inserted, or deleted, as well as when the selection changes, when the insertion point moves, or when the layout changes. Notifications are also used to grant a lock to the client. (Clients must have a lock to perform certain operations on a document.)

TSF documents are linear streams of (mostly) Unicode text. In addition to plaintext, documents can contain embedded OLE objects and regions. Objects in the stream are represented with the Unicode object replacement character 0xfffc. Methods are available to insert or query objects at arbitrary locations. Text services are able to hit test for pixel-to-text transformations and for text-to-pixel transformations, or they can retrieve the boundaries of the display region. TSF allows some applications to embed private data within their text streams, and transparently hides the private data from the text services.

Document Access

As stated previously, in order to perform certain operations on a document, a client must first obtain an appropriate lock, which can be read-only or read/write. When holding a read-only lock, operations that modify the document's content are not permitted. A client can request that a lock be granted immediately (synchronous) or at some later stage (asynchronous). If a client requests an asynchronous lock, it can either be granted immediately or later, at the discretion of the application.

Properties and Persistence

Properties are markup information for text. This information includes the metadata that provides hints about how the text should be displayed, alternative conversions, or the raw device from which text data was originally derived. Properties can be associated with individual characters. For example, a text service can tag runs of text as belonging to a specific language (perhaps to clear up ambiguity introduced by Unicode's Han unification). Or the text service might tag incomplete compositions (such as a single letter that will be transformed into kana as soon as another keystroke arrives, generally underlined or highlighted by an application).

Properties can also be associated with ranges of text. (See Figure 23-3.) This might include candidate lists or reading strings that other text services can examine for hints during an ongoing composition.

Figure 23.3 - Associating properties with text.

TSF defines a set of standard properties, but services and applications are free to post arbitrary markup data. Properties are inherently public; if a service wants to associate private data with document text, it can do so with range objects or contexts.

Using TSF in Your Application

Equipped with a better understanding of TSF, how can you implement this knowledge and leverage the benefits that TSF offers? The simplest way to utilize TSF in your application is to host one of the system-provided controls that support it. (For a list of controls that support TSF and for information on how to use them in your application, see the Windows Platform SDK.)If your application uses its own editing control, you'll need to implement support for TSF. (For information on TSF APIs and for samples, see the Windows Platform SDK.)