TSF Aware : tour

Text services: Vista Extensions (UI Elements)

Eric Brown — Wed, 16 May 2007 17:00:00 GMT

The TSF tour ends here, with a brief discussion of UI Elements in Vista

If your text service wishes to be available in full-screen applications like games, it must implement ITfUIElement, and call the ITfUIElementMgr whenever the text service wants to display some UI. (See the discussion of UILess mode in MSDN.)

Interface	How Obtained
ITfUIElement	Passed to ITfUIElementMgr::BeginUIElement
ITfToolTipUIElement	QI from ITfUIElement
ITfCandidateListUIElementBehavior	QI from ITfUIElement
ITfCandidateListUIElement	QI from ITfUIElement
ITfReadingInformationUIElement	QI from ITfUIElement

Text services that implement ITfUIElement should also register in the GUID_TFCAT_TIPCAP_UIELEMENTENABLED category, as well.

Unfortunately, as of this date, I do not know of any sample text service that implements ITfUIElement.

Text Services: Vista Extensions

Eric Brown — Tue, 15 May 2007 17:00:00 GMT

In Windows Vista, TSF added the ability to run in locations where it had previously been disabled. For example, TSF is now available on secure desktops, in full screen (DirectX) applications, and in MTA threads. However, text services have to be aware of these new environments, and must tell TSF that it is aware of these environments.

A text service that wishes to run in one of these new environments (e.g., UI-less mode, secure mode, or console mode) must implement ITfTextInputProcessorEx instead of ITfTextInputProcessor:

Interface	How Created

ITfTextInputProcessorEx

TSF will CoCreateInstance() this interface.

Next, text services that implement ITfTextInputProcessorEx must also register under one or more of the appropriate categories: GUID_TFCAT_TIPCAP_COMLESS, GUID_TFCAT_TIPCAP_SECUREMODE, GUID_TFCAT_TIPCAP_UIELEMENTENABLED, or GUID_TFCAT_TIPCAP_WOW16.

What do these categories mean?

Category	Meaning
GUID_TFCAT_TIPCAP_SECUREMODE	Text service will be launched on the secure desktop.
GUID_TFCAT_TIPCAP_UIELEMENTENABLED	Text service implements ITfUIElement, and draws its UI accordingly.
GUID_TFCAT_TIPCAP_COMLESS	Text service can operate without COM. See below.
GUID_TFCAT_TIPCAP_WOW16	Text service can work with Win16 applications. All text services in this category are assumed to be in the GUID_TFCAT_TIPCAP_COMLESS category as well.

Text Services without COM

Previous versions of the TSF Manager had a number of application compatibility problems with COM threading models, particularly with applications that were not TSF-aware. In Vista, the TSF Manager can create text services without using COM (by loading the DLL directly and calling DllGetClassFactory). However, there are obvious restrictions on text services - namely, that the service itself cannot use COM, either. If a text service follows these restrictions, it can register under the GUID_TFCAT_TIPCAP_COMLESS category, and be active in more applications.

COM-less text services can still create COM objects, but they cannot use CoCreateInstance(). Instead, COM objects can be allocated off the heap, or ATL-based text services can use CComObject<T>::CreateInstance().

Text Services: Candidates

Eric Brown — Mon, 14 May 2007 17:00:00 GMT

If your text service supports multiple interpretations of the same input, and you wish to allow users to correct the initial interpretation (for dictation, we call this 'correction'; IMEs tend to call it 'reconversion'), your text service will need to implement these interfaces. Your service will also need to implement ITfFnReconversion (so that applications can get these interfaces), and ITfFunctionProvider (so that applications can get the ITfFnReconversion interface).

Interface	How Obtained
ITfCandidateList	Returned from ITfFnReconversion::GetReconversion
ITfCandidateString	Returned from ITfCandidateList::GetCandidate
IEnumTfCandidates	Returned from ITfCandidateList::EnumCandidates

There is a sample text service that implements candidates available on MSDN.

Text Services: Function Providers

Eric Brown — Fri, 11 May 2007 17:00:00 GMT

TSF allows text services to offer optional extension points through the ITfFunctionProvider interface. Indirection through the function provider allows text services to minimize memory usage and startup time by instantiating services when requested, rather than when loaded.

Interface	How Obtained
ITfFunctionProvider	Obtained by QI from ITfTextInputProcessor
ITfFunction	Returned from ITfFunctionProvider::GetFunction

Text services that implement ITfFunctionProvider must register the interface with the TSF manager by QueryInterface'ing the ITfThreadMgr object for ITfSourceSingle, and then calling ITfSourceSingle::AdviseSingleSink().

Standard Functions

These interfaces are implemented by a text service, and are all optional. These interfaces are returned from a call to ITfFunctionProvider::GetFunction, and all derive from ITfFunction. Note that your text service can implement other functions via ITfFunctionProvider; these are just the predefined interfaces.

Interface	When should a text service implement this?
ITfFnShowHelp	Implement this if your service has a help dialog.
ITfFnReconversion	Implement this if your service supports candidates (ITfCandidateList, et. al.)
ITfFnPropertyUIStatus	Implement this if you want to serialize your custom properties.
ITfFnConfigure	Implement this if your text service has a configuration dialog.
ITfFnBalloon	Think about implementing this if your text service implements ITfLangBarItemBalloon.

Text Services: Language Bar

Eric Brown — Thu, 10 May 2007 17:00:00 GMT

If your text service wishes to display some UI on the language bar, then your service will need to create objects that implement one (or more) of the following interfaces:

Interface	How Obtained
ITfLangBarItem	Pass this base interface to ITfLangBarItemMgr::AddItem
ITfLangBarItemButton	Derived from ITfLangBarItem
ITfLangBarItemBitmapButton	Derived from ITfLangBarItem
ITfLangBarItemBitmap	Derived from ITfLangBarItem
ITfLangBarItemBalloon	Derived from ITfLangBarItem

If your text service has an object that implements ITfLangBarItem (or one of its subclasses), and that object updates the item, that object must also implement ITfSource (and call ITfLangBarItemSink::OnUpdate) so that TSF can redraw the language bar correctly. See the article in MSDN on Implementing a Language Bar Object, and the sample source code.

Text Service: Display Attributes

Eric Brown — Wed, 09 May 2007 17:00:00 GMT

If your text service wishes to display text in different colors (e.g., displaying the current composition in red), then your text service needs to implement these interfaces:

Interface	How Obtained
ITfDisplayAttributeProvider	Obtained by QI from ITfTextInputProcessor
IEnumTfDisplayAttributeInfo	Returned from ITfDisplayAttributeProvider::EnumDisplayAttributeInfo
ITfDisplayAttributeInfo	Returned from ITfDisplayAttributeProvider::GetDisplayAttributeInfo

If you implement ITfDisplayAttributeProvider, you must also understand how properties work (because display attributes are set via properties), and you must also register your text service as a display attribute property provider at install time, like this:

ITfCategoryMgr::RegisterCategory(<clsid of text service>, GUID_TFCAT_DISPLAYATTRIBUTEPROVIDER, <clsid of text service>);

MSDN also mentions GUID_TFCAT_DISPLAYATTRIBUTEPROPERTY, but it doesn't seem to be used in the samples or in any text service I can find.

A working example of a text service that implements display attributes can be found in MSDN.

Text Service Properties

Eric Brown — Tue, 08 May 2007 17:00:00 GMT

The next thing that I'd like to talk about are properties. While the TSF manager implements basic property handling (via ITfProperty), a text service has the ability to customize the way TSF handles properties.

If your text service wishes to attach private information to the inserted text, it can do so by calling ITfProperty::SetValue. If you need to control the lifetime of that information (for example, when the property is removed during edits, or how the property will be serialized, or if your data doesn't easily fit in a VARIANT), then your property object needs to implement ITfPropertyStore, and your text service needs to call ITfProperty::SetValueStore instead of ITfProperty::SetValue.

If your text service has a property that implements ITfPropertyStore, and the properties are being serialized, then your text service also must implement ITfCreatePropertyStore (so that your properties can be deserialized), and it's a good idea to implement ITfFnPropertyUIStatus, as well. (I'll talk more about ITfFnPropertyUIStatus later.)

Interface	How Obtained
ITfPropertyStore	Passed to ITfProperty::SetValueStore
ITfCreatePropertyStore	Obtained by QI from ITfTextInputProcessor

Properties can be of 3 styles - static, static-compact, and custom.

Static properties store simple variants. TSF always discards static properties when the range is modified, and serializes static properties that are not of type VT_UNKNOWN.

Static-compact properties are similar to static properties, except that the range data for the properties are not stored; therefore, if two adjacent text ranges have the identical static-compact property applied to them, the ranges will be collapsed. This can make a difference if you're enumerating the ranges of text covered by a particular property.

Custom properties store an ITfPropertyStore object, which owns the data. TSF will ask the ITfPropertyStore object what to do when the range is modified or serialized.

If your text service defines one or more properties (i.e., not one of the predefined properties), your text service must also register each property via the category manager at install time. You must register the property style so that TSF knows what to do when the text changes. The property style is registered like this:

ITfCategoryMgr::RegisterCategory(<clsid of text service>, GUID_TFCAT_PROPSTYLE_XXX, <guid of property>);

If your text service stores ink or audio data in a property, your text service must also register the property in a property category, like this:

ITfCategoryMgr::RegisterCategory(<clsid of text service>, GUID_TFCAT_PROP_XXX, <guid of property>);

Text Service Basics

Eric Brown — Mon, 07 May 2007 17:00:00 GMT

We have finally finished looking at the interfaces that TSF implements for you. Now we start looking at the interfaces that text services must implement. The first step are the essential interfaces.

Every text service must implement these two interfaces. It may optionally implement other interfaces (described in future posts).

Interface	How Created
ITfTextInputProcessor	TSF will CoCreateInstance() this interface.
ITfEditSession	Your text service will create objects that implement this interface in order to read or write the document text. TSF will call ITfEditSession::DoEditSession when the application is ready to let your service access the document.

Text Service Categories

All text services need to install themselves with the TSF manager; usually at DLL registration time, but this can also be done at setup time (which would keep the registration code out of the text service DLL). Registration is not clearly described in either the samples or the MSDN documentation, so I'm going to walk through a couple of examples to show how it's done.

A text service is installed in 3 steps. All three steps write to the machine registry (HKLM), so you will need full admin rights.

First, the text service must register as an in-proc COM server; this is identical to the usual COM registration process.

Second, the text service must register with TSF. You do this by calling ITfInputProcessorProfileMgr::RegisterProfile . This is the new Vista function that does all the registration in one step; in XP, registration required several steps. This function talks about a ‘profile', without ever really defining what that is. A ‘profile' is a combination of a text service, language ID, and, possibly, a replacement keyboard layout. Text services are often specific to a particular language; for example, the Japanese IME is, rather obviously, only suited to typing Japanese, and won't be available in English.

Parameter	Meaning
rclsid	CLSID of the text service being registered.
langid	The language id of the profile.
guidProfile	The GUID to identify the profile.
pchDesc	The (user-visible) name of the profile. (For example, ‘My Text Service'.)
cchDesc	The length of pchDesc.
pchIconFile	The full path of the icon file. TSF displays this icon as part of the language bar.
cchFile	The length of pchIconFile.
uIconIndex	The location of the icon within the icon file. Often zero, if there's only one icon in the file.
hklSubstitute	The substitute keyboard layout of this profile. When this profile is active, the keyboard will use this keyboard layout instead of the default keyboard layout. This can be NULL if your text service doesn't change the keyboard layout.
dwPreferredLayout	Unused. Must be 0.
bEnabledByDefault	True if this profile is enabled by default.
dwFlags	Usually zero. Refer to MSDN for more details.

Third, the text service must register its categories. This is done by calling ITfCategoryMgr::RegisterCategory. It takes 3 GUIDs as parameters - the CLSID of the text service, the category GUID (almost always one of the predefined categories), and the GUID of the item being registered. Every text service must register the TIP category (keyboard, speech, handwriting); it may also need to make other registration calls if it implements other functions, like display attributes or custom properties. To register as a keyboard text service, the call would look like this:

ITfCategoryMgr::RegisterCategory(<clsid of text service>, GUID_TFCAT_TIP_KEYBOARD, < clsid of text service >);

A Tour through TSF: Miscellaneous Functions

Eric Brown — Sat, 05 May 2007 17:00:00 GMT

The last set of interfaces implemented by the TSF manager are the 'odd-ball' interfaces that don't really fall into any other logical groups.

Helpers

The interfaces in this category provide auxiliary services for applications or text services.

Interface	How to Obtain
ITextStoreACPServices	QI on ITextStoreACPSink
ITextStoreACPSink	Passed to ITextStoreACP::AdviseSink
ITfEditRecord	Passed to ITfTextEditSink::OnEndEdit

MSAA interoperability

These interfaces were originally created to allow TSF to interoperate with MSAA. Unfortunately, no 3^rd party developers implemented the MSAA client support needed to make these interfaces work, so at this point, these interfaces are effectively obsolete.

Interface
IAnchor
ITfMSAAControl
ITextStoreAnchor
ITextStoreAnchorSink

A Tour through TSF: Language Bar

Eric Brown — Fri, 04 May 2007 17:00:00 GMT

These interfaces manage the language bar and the items that display on the language bar. These interfaces are used exclusively by text services, and will be discussed further in a future post.

Interface	How to Obtain
ITfLangBarMgr	CoCreateInstance(CLSID_TF_LangBarMgr)
ITfMenu	Passed to: ITfLangBarItemBitmapButton::InitMenu ITfLangBarItemButton::InitMenu
ITfSystemDeviceTypeLangBarItem	QI on ITfLangBarItem
ITfSystemLangBarItem	QI on ITfMenu
ITfTransitoryExtensionUIElement	QI on ITfUIElement

A Tour through TSF: Enumerators

Eric Brown — Thu, 03 May 2007 17:00:00 GMT

The next set of TSF manager interfaces are the enumerators. These are rather boring interfaces; they just enumerate things.

Generally speaking, the enumerators enumerate things owned by the item that provides the enumerator. For example, IEnumTfContexts is returned from ITfDocumentMgr. Therefore, it enumerates the contexts owned by that document manager, and not by any other document manager. Similarly, IEnumTfFunctionProviders is returned from ITfThreadMgr. Therefore, it enumerates the function providers registered with that thread, and not any others.

The only interesting thing about these interfaces is how you get them.

Interface	How to Obtain
IEnumITfCompositionView	ITfContextComposition::FindComposition
IEnumTfContexts	ITfDocumentMgr::EnumContexts
IEnumTfDocumentMgrs	ITfThreadMgr::EnumDocumentMgrs
IEnumTfFunctionProviders	ITfThreadMgr::EnumFunctionProviders
IEnumTfLangBarItems	ITfLangBarItemMgr::EnumItems
IEnumTfLanguageProfiles	ITfInputProcessorProfiles::EnumLanguageProfiles
IEnumTfProperties	ITfContext::EnumProperties
IEnumTfPropertyValue	ITfContext::TrackProperties
IEnumTfRanges	ITfReadOnlyProperty::EnumRanges (and therefore, ITfProperty::EnumRanges) ITfEditRecord::GetTextAndPropertyChanges
IEnumTfUIElements	ITfUIElementMgr::EnumUIElements

A Tour through TSF: Event sinks

Eric Brown — Wed, 02 May 2007 17:00:00 GMT

The interfaces in this category allow you to be called back when certain events happen on another interface. These callbacks are generally referred to as 'event sinks'.

Interface	How to Obtain
ITfSource	QI on ITfThreadMgr, ITfContext, ITfCompartment, ITfInputProcessorProfiles, ITfDocumentMgr, or ITfLangBarItem
ITfSourceSingle	QI on ITfThreadMgr or ITfContext

Event Sinks

TSF can call your application or text service back when certain events occur. Many event sinks are installed by a two-step process:

1) Call QueryInterface() on a host interface (described in the table) for ITfSource;
2) Call ITfSource::AdviseSink() with the target interface IID and the target interface pointer.

You will get back a cookie that you will need to pass back to ITfSource::UnadviseSink() when it's time to detach from the event source (e.g., when the host or target object is about to be destroyed, or the text service is uninitializing).

Your application or text service must implement the target interface; these interfaces are typically implemented on the main object (i.e., the object that implements either ITextStoreACP or ITfTextInputProcessor for applications or text services, respectively).

Target Interface	Hosting Interface
ITfActiveLanguageProfileNotifySink	ITfThreadMgr
ITfCompartmentEventSink	ITfCompartment
ITfContextKeyEventSink	ITfContext
ITfDisplayAttributeNotifySink	ITfThreadMgr
ITfEditTransactionSink	ITfContext
ITfKeyTraceEventSink	ITfThreadMgr
ITfLangBarItemSink	ITfLangBarItem
ITfLanguageProfileNotifySink	ITfInputProcessorProfiles
ITfPreservedKeyNotifySink	ITfThreadMgr
ITfStatusSink	ITfContext
ITfSystemLangBarItemSink	ITfLangBarItem
ITfTextEditSink	ITfContext
ITfTextLayoutSink	ITfContext
ITfThreadFocusSink	ITfThreadMgr
ITfThreadMgrEventSink	ITfThreadMgr
ITfTransitoryExtensionSink	ITfDocumentMgr
ITfUIElementSink	ITfUIElementMgr

Single sinks

Some event sources can only have a single sink attached. Attaching an single event sink is similar to installing a regular event sink, except that you QueryInterface() for ITfSourceSingle instead of ITfSource; one then attaches the sink by calling ITfSourceSingle::AdviseSingleSink().

Interface	Hosting Interface
ITfCleanupContextSink	ITfContext
ITfCleanupContextDurationSink	ITfThreadMgr

Specialized Sinks

Some event sinks are attached by calling specific methods. The following table describes the installation method for these sinks:

Interface	Installation Method
ITfMouseSink	ITfMouseTracker::AdviseMouseSink
ITfCompositionSink	ITfContextComposition::StartComposition
ITfLangBarEventSink	ITfLangBarMgr::AdviseEventSink
ITfKeyEventSink	ITfKeystrokeMgr::AdviseKeyEventSink

A Tour through TSF: Contexts and Ranges

Eric Brown — Tue, 01 May 2007 17:00:00 GMT

Our next stop on our tour through TSF brings us to the two most heavily used interfaces in text services: Contexts and Ranges. But first, a quick diversion to discuss the relationship between threads, documents, and contexts.

The ITfThreadMgr object is the primary object implemented by TSF. TSF ensures that no more than one ITfThreadMgr object exists in each thread. The ITfThreadMgr object manages documents, text services, and handles focus changes between documents.

The ITfDocumentMgr object represents a logical document. It isn't heavily used, though; its primary purpose is to be a container for edit contexts. There is usually only one context in the document manager, although sometimes there can be two.

The ITfContext object represents a view of the document that you can interact with; it manages selections, properties, & ranges.

Contexts

A context represents a view of the document that a text service can interact with.

Interface	How to Obtain
ITfContext	Varies widely. Common examples: ITfDocumentMgr::GetTop() ITfDocumentMgr::CreateContext()
ITfContextView	ITfContext::GetActiveView
ITfContextComposition	QI on ITfContext
ITfContextOwnerCompositionServices	QI on ITfContext
ITfContextOwnerServices	QI on ITfContext
ITfInsertAtSelection	QI on ITfContext
ITfMouseTracker	QI on ITfContext
ITfQueryEmbedded	QI on ITfContext
ITfComposition	ITfContextComposition::StartComposition
ITfCompositionView	Passed to any of: ITfContextOwnerCompositionSink::OnStartComposition ITfContextOwnerCompositionSink::OnUpdateComposition ITfContextOwnerCompositionSink::OnEndComposition

Once you have a context (and usually an edit cookie - most of the things you can do with contexts can only be done from within edit sessions), you can start to manipulate the document.

Ranges

These interfaces deal with pieces of text within a logical document.

Interface	How to Obtain
ITfRange	Varies widely; common instances are: ITfContext::GetSelection
ITfRangeACP	QI on ITfRange
ITfRangeBackup	ITfContext::CreateRangeBackup

A Tour through TSF: TSF Managers

Eric Brown — Mon, 30 Apr 2007 17:46:00 GMT

The next stop on the tour is an extended visit through the TSF manager interfaces. Since TSF implements a lot of interfaces, I decided to break them up into separate posts.

I've also included a (very brief) description of how a text service (or application) would obtain an instance of each interface. By default, an instance of the interface is returned by the method listed. Some interfaces are obtained by calling QueryInterface() on the specified interface, other interfaces are passed as parameters to specified methods, and yet others are obtained by calling CoCreateInstance() with a particular CLSID.

This post describes the 'top-level' interfaces in TSF. You either create them directly, or you obtain them either when your application initializes TSF, or when your text service is activated.

Interface	How to Obtain
ITfCategoryMgr	CoCreateInstance(CLSID_TF_CategoryMgr)
ITfDisplayAttributeMgr	CoCreateInstance(CLSID_TF_DisplayAttributeMgr)
ITfDocumentMgr	Application: ITfThreadMgr::CreateDocumentMgr Text Service: ITfThreadMgr::GetFocus ITfThreadMgrEventSink::OnInitDocumentMgr ITfThreadMgrEventSink::OnSetFocus ITfThreadMgrEventSink::OnUninitDocumentMgr
ItfInputProcessorProfileMgr	QI on ITfInputProcessorProfiles
ITfInputProcessorProfiles	CoCreateInstance(CLSID_TF_InputProcessorProfiles)
ITfInputProcessorProfilesEx	QI on ITfInputProcessorProfiles
ITfInputProcessorProfileSubstituteLayout	QI on ITfInputProcessorProfiles
ITfThreadMgr	Application: CoCreateInstance(CLSID_TF_ThreadMgr) Text Service: Passed to ITfTextInputProcessor::Activate
ITfThreadMgrEx	QI on ITfThreadMgr
ITfClientId	QI on ITfThreadMgr
ITfConfigureSystemKeystrokeFeed	QI on ITfThreadMgr
ITfKeystrokeMgr	QI on ITfThreadMgr
ITfLangBarItemMgr	QI on ITfThreadMgr
ITfMessagePump	QI on ITfThreadMgr
ITfUIElementMgr	QI on ITfThreadMgr

Update (7/3): I incorrectly listed ItfInputProcessorProfileMgr as an interface that could be directly created. Gael pointed out that this was incorrect, and I've updated the table to list the correct method.

TSF Application interfaces

Eric Brown — Sat, 28 Apr 2007 01:36:00 GMT

The first stop on the TSF tour is the application interfaces. These are implemented by applications or text controls.

An application (or text control) must implement ITextStoreACP to be considered ‘TSF-aware'. It may choose to implement any of the other interfaces described in the table below. I also describe how TSF obtains an instance of each interface.

Interface	Optional?	How Obtained?
ITextStoreACP	No	Passed to ITfDocumentMgr::CreateContext
ITfInputScope	Yes	Returned from ITextStoreACP::RequestSupportedAttrs with GUID_PROP_INPUTSCOPE.
ITfInputScope2	Yes	QI from ITfInputScope
ITfPersistentPropertyLoaderACP	Yes	Passed to ITextStoreACPServices::Unserialize
ITfMouseTrackerACP	Yes	QI from ITextStoreACP
ITfContextOwnerCompositionSink	Yes	Passed to ITfDocumentMgr::CreateContext
ITfUIElementSink	Yes	Passed to ITfSource::AdviseSink (see below)

Note: I put ITfUIElementSink here because text services never implement this interface, even though it's an event sink (described in a future post). Full-screen applications (or games) would implement this interface if they wish to control the UI drawn by text services. (See the discussion of UILess mode in MSDN.)

Interface	When to implement
ITextStoreACP	Always implement this.
ITfInputScope	Consider implementing this. It's not hard, and some text services use it to improve recognition (e.g., Windows Speech Recognition knows about the URL input scope, and has special code for that).
ITfInputScope2	Implement this if you implemented ITfInputScope, and you need the extra functionality (string enumeration).
ITfPersistentPropertyLoaderACP	Implement this if you support asynchronous property loading. If you don't know what that means, you don't need to implement this.
ITfMouseTrackerACP	Implement this to help handwriting recognition (I believe that you must implement this to get gestures).
ITfContextOwnerCompositionSink	Implement this if you need control over compositions.
ITfUIElementSink	Only implement this if your application takes over the screen, and you still want IMEs to work inside your application. It's a fair amount of work to implement this.