A Typing Program Sample based on TSF (Text Service Framework)

By Y Lam (yick.lam@gmail.com), Hong Kong, China (Last Update: 2007-06-28)

    This tutorial is based on a sample code YLam TSF Example. You enter an email address below to get a link to download it.

I will first describe what YLam TSF Example does, how to install etc. Later on, I will talk about the code.

What does YLAM TSF Example does? How to install?

YLam TSF Example is a dll written in Microsoft Text Service Framework (TSF) that

• show up a yellow rectangular area with a red line that can be moved around when dragged
• when any key is hit, it will send the word "Hello World!" to the application
• The key that has been hit will be shown in the yellow rectangular area

The purpose of this example is to show:

• how to capture all key stroke
• how to draw simple UI and implement basic UI functionality like dragging
• how to send strings to applications
• serve as basic building block for more complicated input method

However, many of TSF features are not shown, for example:

• floating input windows
• modification of composition strings
• etc.....

Please refer to Microsoft's MSDN Example son Text Service Framework. There are 9 such examples and very detailed documentation is given. In fact this example is based on that.

The installation process is first described. The following description is based on Windows Vista (English Version). The process should be similar in other language version of Windows Vista and also Windows XP.

• Type your name and email address in the beginning of this page and obtain ylamTSF_Example.zip
• Decompress ylamTSF_Example.zip in desktop. Assume the path is C:\Users\bsiu\Desktop\ylamTSF_Example
• Start command line windows by typing cmd in "Start menu":

• There is a precompiled version of YLamTSF_Example. In the command prompt windows, type the following:

C:\Users\bsiu\Desktop\ylamTSF_Example\ylam_Example\Release
regsvr32 ylam.dll

• The following dialog window will pop up showing the installation of ylamTSF_Example is successful.

•  You should be able to see a Chinese (Hong Kong S.A.R.) input method in the language bar

• To guarantee the input method run smoothly, it is recommended you also install the U.S. Keyboard for Chinese (Hong Kong S.A.R.). Start the control panel as below:

• Click "Change Keyboards or other input methods" in control panel

• Click "Change Keyboards"

• Add US Keyboard for Chinese (Hong Kong S.A.R.)

• Quit control panel.
• Start any application for example Notepad
• Start ylamTSF_Example as like below:

• Now you can
  • drag the yellow window around
  • press ALT+ ~ to turn on / off the Chinese Input Method
  • press 'A' to 'Z' to send "Hello World!"

How to compile ylamTSF_Example?

• Install Visual C++ Version 6.0 (the version that has been tested) Make sure you install the Unicode library as like below:

• Install Microsoft Platform SDK (R2). You need to download the CD image from Microsoft and burn a CD and then install. Here is the installation window. Assume you installed it in D:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2

• Double click ylamTSF_Example\ylam_Example\ylam.dsw to start the project.

• Change to Win32 Release mode when build:

• Change in Menu Project -> Settings, the include path to wherever you install the Windows Platform SDK. For example D:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include

• Change in Menu Project -> Settings, the library path to wherever you install the platform SDK. For example D:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib

• Then you can compile the example by Menu Build -> Build "ylam.dll". After building, you should be able to see ylam.dll in Release directory. Follow the installation process described above.

Some discussion of the source code

• Here are some points worth discussion:

  • The constructor only inherited required ITF classes, i.e

class CTextService : public ITfTextInputProcessor,
                     public ITfThreadMgrEventSink,
                     public ITfTextEditSink,
                     public ITfKeyEventSink

                    Other unnecessary classes are not included.

• How to insert string?

  • In CTextService::Activate(), _pInsertStringEditSession=new CEditSession() is called

  • When a key is hit, the following code is executed
    HRESULT hr;
    _pInsertStringEditSession->SetPContext(pContext);
    pContext->RequestEditSession(_tfClientId, _pInsertStringEditSession,    TF_ES_READWRITE | TF_ES_ASYNCDONTCARE, &hr);

  • After RequestEditSession is called, _pInsertStringEditSession->DoEditSession() be called and you can insert the string to application as described in MSDN TSF Example 5 of 9.

  • This is the way how TSF insert string. Strange, right?
    　

• How to write call back function for when a key is hit?

  • In constructor of TextService,  _InitPreservedKey is called so that ALT+~ is the key to turn on / off the input method.

  • When ALT+~ key is hit, OnPreservedKey will be called.

  • _SetKeyboardOpen will then be called, which get “Compartment” GUID_COMPARTMENT_KEYBOARD_OPENCLOSE from text service framework and turn the keyboard on/off.

  • Once the keyboard is turned on, when key is hit, the following functions will be called:

    • TextService::OnTestKeyDown

    • TextService::OnKeyDown

    • TextService::OnTestKeyUp

    • TextService::OnKeyUp

  • You should handle these keystrokes through the above functions.

• How to draw Candidate Window?

  • In the CTextService::Activate(), a _pCandidateWindow is new'ed. The candidate window is then created, moved and displayed. You should read the relevant source code in CandidateWindow.cpp

Reference:

1. Sample TSF source code from Microsoft: http://msdn2.microsoft.com/en-us/library/ms629032.aspx

2. http://www.pkucn.com/viewthread.php?tid=189364&extra=page=1 (输入法编辑器概述)

3. http://www.pkucn.com/viewthread.php?tid=189370&extra=page=1