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 |
|---|---|
TSF will CoCreateInstance() this interface. |
|
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 >);