Text Service Basics

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