TSF Aware : TSF Manager

Where are the TSF Samples?

Eric Brown — Wed, 22 Oct 2008 23:57:41 GMT

Many people have emailed me asking about the TSF samples on MSDN. They’re supposed to be on MSDN code gallery, although they don’t appear to be there.

They are, however, part of the Windows SDK. After installation, you'll find them in %programfiles%\Microsoft SDKs\Windows\v6.1\Samples\winui\Input\tsf.

There are actually more samples in the Windows SDK than were on MSDN, including some examples of how to write a text store, as well as how to interact with TSF in UILess mode.

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.