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 >);