Legacy Document

Inside Macintosh: Text /

Chapter 7 - Text Services Manager / Using the Text Services Manager (for Text Service Components)

Responding to Calls

When a client application makes certain calls to the Text Services Manager application interface, the Text Services Manager in turn calls your text service component. Your text service component responds to these calls by initiating or closing a text service, manipulating text service windows, responding to events or menu commands, and confirming text input.

Initiating a Text Service

When your text service component receives the InitiateTextService call, it can commence its operations to provide its text service. That may include opening windows or palettes, initializing data structures, communicating with the user or application, or otherwise getting started with its tasks.

The Text Services Manager may call InitiateTextService on its own or in response to receiving the application-interface call OpenTextService.

Activating Text Service Component Windows

If a window associated with a TSM document associated with your text service is being activated, your text service component receives the ActivateTextService call. You should show floating windows associated with your component instance and prepare to receive and handle events.

If the window is being deactivated, your text service component receives the DeactivateTextService call. You should perform any necessary cleanup or other tasks associated with deactivating your current component instance. If your text service component is not an input method, you should also hide all floating windows associated with the document being deactivated. If your text service component is an input method and if the newly activated document does not use your text services, you will receive the HidePaletteWindows call. At that point you should hide all floating windows associated with the component instance being deactivated.

The Text Services Manager calls ActivateTextService and DeactivateTextService in response to receiving the application-interface calls ActivateTSMDocument and DeactivateTSMDocument, respectively.

Responding to Events and Updating the Cursor and Menu

The Text Services Manager (or a client application) is responsible for adding your
text service component's menu to the menu bar. When your text service component receives a GetTextServiceMenu call, it needs to return a menu handle. The section "Providing Menus and Icons" on page 7-38 gives instructions for creating text service menus and icons.

When your text service component receives the call TextServiceEvent, TextServiceMenuSelect, or SetTextServiceCursor, it should handle the event, menu command, or cursor-drawing if appropriate. For example, when the user enters text, you receive and handle the key-down events; you in turn inform the application what characters to draw in the active input area. When the user makes a menu selection, you are given an opportunity to check whether it is from your menu and then to act on it. You are regularly given the opportunity to redraw the cursor, in case it may be over an area under your control (such as a palette window or the active input area).

The Text Services Manager may call GetTextServiceMenu on its own or in response to receiving the application-interface call OpenTextService. The Text Services Manager calls TextServiceEvent, TextServiceMenuSelect, and SetTextServiceCursor in response to receiving the application-interface calls TSMEvent, TSMMenuSelect, and SetTSMCursor, respectively.

Confirming Active Text Input

A client application may need your input method text service component to terminate input immediately and confirm any text currently in the active input area. When your text service component receives the call FixTextService, it should confirm all text in the active input area, just as if the user had pressed Return. It should send the confirmed text to the client application through the Update Active Input Area Apple event.

The Text Services Manager calls FixTextService in response to receiving the application-interface call FixTSMDocument.

Closing a Text Service

When your text service is no longer needed, the Text Services Manager calls your text service component's TerminateTextService function before calling the Component Manager to close the component. Your text service component should use this time to confirm any active input in progress and then dispose of memory as needed.

The Text Services Manager may call TerminateTextService on its own or in response to receiving the application-interface call CloseTextService.

Identifying the Supported Scripts and Languages

The Operating System, the Text Services Manager, or a client application may need to determine which scripts and languages your text service component supports. When you receive the GetScriptLanguageSupport call, you return that information in a script-language support record.

The GetScriptLanguageSupport function and several Text Services Manager application-interface routines use the script-language record--and the script-language support record--to pass information about the scripts and languages associated with text service components.

The script-language record provides a script code and language code for the script system and the language associated with a given text service component. The script-language record is defined by the ScriptLanguageRecord data type as follows:

TYPE ScriptLanguageRecord = 
   RECORD
      fScript:    ScriptCode;
      fLanguage:  LangCode;
   END;

Field Description

fScript

The number that identifies a script system supported by the text service component

fLanguage

The number that identifies a language associated with the script supported by the text service component

For a list of constants for all defined script and language codes, see the chapter "Script Manager" in this book.

The script-language support record consists of an array of script-language records. It is defined by the ScriptLanguageSupport data type as follows:

TYPE ScriptLanguageSupport = 
   RECORD
      fScriptLanguageCount:   Integer;
      fScriptLanguageArray:   ARRAY[0..0] of ScriptLanguageRecord;
   END;

Field Description

fScriptLanguageCount

The number of script-language records in this script-language support record.

fScriptLanguageArray

A variable-length array of script-language records.

The Text Services Manager can call GetScriptLanguageSupport on its own or in response to receiving the application-interface call GetTextServiceLanguage.

Listing 7-10 gives an example of the response to the GetScriptLanguageSupport call by a Chinese input method.

Listing 7-10 Determining the script and language for a text service component

TYPE
   scriptHandlePtr= ^ScriptLanguageSupportHandle;
   
VAR
   scriptHdlPtr:scriptHandlePtr;

{The following is part of the case statement that dispatches }
{ text service component routines. It is the component's }
{ response to receiving a GetScriptLanguageSupport call}

kCMGetScriptLangSupport:
   BEGIN
      scriptHdlPtr := (scriptHandlePtr) @(cmParams^.params[0]);
      IF scriptHdlPtr^ = NIL THEN
         scriptHdlPtr^ := (ScriptLanguageSupportHandle)NewHandle
                                 (sizeof(ScriptLanguageSupport));
      IF scriptHdlPtr^ <> NIL THEN
            WITH scriptHdlPtr^^^ DO BEGIN
               fScriptLanguageCount := 1;
               fScriptLanguageArray[0].fScript:= smTradChinese;
               fScriptLanguageArray[0].fLanguage:= 
                                                langTradChinese;
               result := noErr;
            END;
      ELSE
         result := memFullErr;
   END;