Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Text Services Manager Reference

Framework
Carbon/Carbon.h
Declared in
CarbonEvents.h
TextServices.h

Overview

The Text Services Manager ("TSM") provides an environment for applications to use non-application-specific text services. The Text Services Manager handles communication between client applications that request text services and the software modules, known as text service components, that provide them. The Text Services Manager exists so that these two types of programs can work together without needing to know anything about the internal structures or identities of each other.

A client application is any text-processing program that uses the Text Services Manager to request a service from a text service component. To accomplish this, a client application needs to make specific Text Services Manager calls during execution.

A text service component is a utility program that uses the Text Services Manager to provide a text service to an application. Text service components are registered components with the Component Manager. Text services can include many different types of specific text-handling tasks, including spell-checking, hyphenation, and handling the input of complex text.

The most prevalent category of text services are those that handle the entry of complex text, that is, input methods. A typical example of an input method is a service that converts keyboard input into text that cannot be directly entered via a keyboard. Text input in Japanese, Chinese, Korean, or Unicode usually requires an input method.

TSM introduces input modes in Mac OS X version 10.3. An input mode allows an input method to temporarily accept text input in a script other than the one it normally supports. An input method uses a CFDictionary to define the input modes it supports and the tag kTextServiceInputModePropertyTag to specify that the input method supports input modes. An application finds out what input modes are supported by an input method by calling the function CopyTextServiceInputModeList.

Also new in Mac OS X version 10.3 is a suite of Carbon events that allow a text service relatively direct access to a document's text content and text attributes, such as font and glyph information. To take advantage of this new functionality in TSM, all text and offsets in your application must map to and from a flattened Unicode space. Your application must also implement callback functions to handle the appropriate Carbon events.

Mac OS X version 10.4 introduces input mode palette configuration routines.

The Text Services Manager defines three separate programming interfaces:

Functions by Task

Applications - Facilitating User Interactions With Components

Applications - Managing TSM Documents

Components - Sending Events

Low Level - Accessing Text Service Properties

Low Level - Confirming Text Service Input

Low Level - Managing Text Service States

Low Level - Querying Text Services

Low Level - Sending Events to Text Services

Working With Document Properties

Input Mode Palette Configuration

Functions

ActivateTextService

Notifies a text service component that its associated document window is becoming active.

ComponentResult ActivateTextService (
   ComponentInstance ts
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

Return Value

See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components must implement a function for this call.

The appropriate response to ActivateTextService is for the text service component to restore its active state, including displaying all floating windows if they have been hidden. (Note that typically an input-method component should not hide its windows in response to being deactivated. If the subsequent document being activated is using the same component’s service, it would be irritating to the user to hide and then immediately redisplay the same windows. An input-method component should hide its windows only in response to a HidePaletteWindows call.) If the component is an input method, it should specify the redisplay of any unconfirmed text currently in the active input area.

The Text Services Manager makes this call either on its own or in response to application-interface calls it receives from client applications. Client applications may directly make this call, but the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

ActivateTSMDocument

Informs the Text Services Manager that a TSM document is active.

OSErr ActivateTSMDocument (
   TSMDocumentID idocID
);

Parameters
idocID

A TSM document identification number created by a prior call to the NewTSMDocument function.

Return Value

A result code. See “Text Services Manager Result Codes.”

Discussion

When a window that has an associated TSM document becomes active, your client application must call the ActivateTSMDocument function to inform the Text Services Manager that the document is activated and is ready to use text service components.

ActivateTSMDocument calls the equivalent text service component function ActivateTextService for all open text service components associated with the TSM document.

If a text service component has a menu, the Text Services Manager inserts the menu into the menu bar.

Availability
Declared In
TextServices.h

CopyTextServiceInputModeList

Obtains a copy of the set of input modes supported by a keyboard-class input method.

ComponentResult CopyTextServiceInputModeList (
   ComponentInstance ts,
   CFDictionaryRef *outInputModes
);

Parameters
ts

The component whose set of input modes you want to obtain.

outInputModes

On output, the CFDictionary contains the list of supported input modes. See the Discussion for more information on the structure and requirements of the dictionary.

Return Value

See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

This function is supported by input methods that adopt the input mode protocol. If this component call is not supported by an input method, calls to functions that access text service properties (using the tag kTextServiceInputModePropertyTag) return the result tsmComponentPropertyUnsupportedErr.

The CFDictionary of input modes (available in TSM 2.2 and later) must have the following form:

<dict>
<key> kTSInputModeListKey </key>
<dict>
<key> modeSignature : (internal ascii name)</key>
<!-- This can be any of the generic input modes defined in this  file,-->
<!-- such as kTextServiceInputModeRoman,or can be a private input-->
<!-- mode such as CFSTR("com.apple.MyInputmethod.Japanese.CoolMode")  -->
 <dict>
<key>menuIconFile</key>
<string> (path for menu icon image file)</string>
<key>alternateMenuIconFile</key>
<string> (path for alternate menu icon image file, when item  is hilited)</string>
<key>paletteIconFile</key>
<string> (path for palette icon image file) </string>
<key>defaultState</key>
<boolean> (default on/off state) </boolean>
<key>script</key>
<string> (scriptCode string for this mode, for example, "smRoman")  </string>
<key>primaryInScript</key>
<boolean> (true if this is primary mode in this script) </boolean>
<key>isVisible</key>
<boolean> (true if this input mode should appear in System  UI) </boolean>
<key>keyEquivalentModifiers</key>
<integer> (modifiers)</integer>
<key>keyEquivalent</key>
<string> (key equivalent character) </string>
<key>JISKeyboardShortcut</key>
<integer> (optional: 0=none,1=hiragana, 2=katakana, 3=eisu)  </integer>
</dict>
</dict>
</dict>

This dictionary must also be present in the Info.plist for the component bundle, in addition to being available through this component call. Availability in the Info.plist allows retrieval of input modes by the system without opening the component. The component call is used whenever the system is notified of a change in the contents of the input mode list, such as when the name or key-equivalents of individual input modes have changed.

If, when the input method is first activated in a login session, the settings of the individual input modes (names or key-equivalents) differ from the default settings as found in the component bundle Info.plist, the system needs to be notified of the change. The input method does this by sending out the Carbon event kEventTextInputInputMenuChanged, just as when the change originally took place.

For more information on the dictionary keys used to define input modes and the input mode dictionary, see “Input Mode Dictionary Key” and “Individual Input Mode Keys.”

Availability
Declared In
TextServices.h

DeactivateTextService

Notifies a text service component that its associated document window is becoming inactive.

ComponentResult DeactivateTextService (
   ComponentInstance ts
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

Return Value

See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components must implement a function for this call.

When it receives a DeactivateTextService call, the text service component is responsible for saving whatever state information it needs to save, so that it can restore the proper information when it becomes active again. Note that an input method should not confirm any unconfirmed text in the active input area, but should save it until reactivated.

A component other than an input method should hide all its floating windows and menus. However, an input-method component should not hide its windows in response to this call. If the subsequent document being activated is using the same component’s service, it would be irritating to the user to hide and then immediately redisplay the same windows. An input-method component should hide its windows only in response to a HidePaletteWindows call.

The Text Services Manager makes this call either on its own or in response to application-interface calls it receives from client applications. Client applications may directly make this call, but the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

DeactivateTSMDocument

Informs the Text Services Manager that a TSM document is inactive.

OSErr DeactivateTSMDocument (
   TSMDocumentID idocID
);

Parameters
idocID

A TSM document identification number created by a prior call to the NewTSMDocument function.

Return Value

A result code. See “Text Services Manager Result Codes.”

Discussion

The DeactivateTSMDocument function lets you inform the Text Services Manager that a TSM document in your client application is no longer active and must temporarily stop using text service components.

The Text Services Manager calls the equivalent text service component function DeactivateTextService for any text service component associated with the TSM document being deactivated.

An application that supports inline input should always strive to have a TSM document active at all times. If a situation arises in which all TSM documents are inactive and keyboard input occurs, the Text Services Manager automatically interacts with the user via its floating input window. (This is the same floating window that the Text Services Manager displays if an application calls the function UseInputWindow with a value of TRUE for the useWindow parameter.)

Availability
Declared In
TextServices.h

DeleteTSMDocument

Closes all opened text service components for the TSM document.

OSErr DeleteTSMDocument (
   TSMDocumentID idocID
);

Parameters
idocID

A TSM document identification number created by a prior call to the NewTSMDocument function.

Return Value

A result code. See “Text Services Manager Result Codes.”

Discussion

When your application disposes of a TSM document, it must call the DeleteTSMDocument function to inform the Text Services Manager that the document is no longer using text service components. DeleteTSMDocument invokes the Component Manager CloseComponent function for each open text service component associated with this document. It also disposes of the internal data structure for the TSM document.

Availability
Declared In
TextServices.h

FixTextService

Notifies a text service component that it must complete the processing of any input that is in progress.

ComponentResult FixTextService (
   ComponentInstance ts
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

Return Value

See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components must implement a function for this call.

For input method components, this function is equivalent to the user explicitly confirming text, but in this case the request comes instead from the application or from the Text Services Manager. Typically, users confirm text explicitly (such as by pressing the Return key), and input methods continually process these user events and send the confirmed text to client applications. Circumstances may arise, however, in which an application needs the input method to confirm and send input without an explicit confirmation from the user.

If, for example, the user clicks the mouse in text outside the active input area, that constitutes an implicit user acceptance of the text in the active input area. In this case, applications should explicitly terminate any active input by calling the FixTSMDocument function, which notifies the Text Services Manager. The Text Services Manager then calls the FixTextService function, which notifies the text service component that it must stop accepting further input and pass the current contents (both converted and unconverted) of the active input area as confirmed text to the client application.

Client applications may directly make this call, but the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

FixTSMDocument

Informs the Text Services Manager that user input for a TSM document has been interrupted.

OSErr FixTSMDocument (
   TSMDocumentID idocID
);

Parameters
idocID

The identification number of a TSM document created by a prior call to the NewTSMDocument function.

Return Value

A result code. See “Text Services Manager Result Codes.”

Discussion

Typically, an inline input text service component removes confirmed input from the active input area each time the user presses the Return key, and passes the confirmed text to your application through a Carbon event or an Apple event.

In certain situations, however, your client application may need to inform the text service component that input in the active input area of a specified TSM document has been interrupted, and that the text service component must confirm the text and terminate user input.In this case you call the FixTSMDocument function to give the input method text service component the opportunity to confirm any input in progress.

For instance, if the user clicks in the close box of the window in which active input is taking place, call FixTSMDocument before you close the window. The text service component will pass you the current contents (both converted and unconverted) of the active input area as confirmed text.

For simple activating and deactivating of your application’s window, it is not necessary to confirm the text in the active inline area. The input method saves the text and restores it when your window is reactivated.

Availability
Declared In
TextServices.h

GetTextServiceMenu

Notifies a text service component that it must produce a handle to its menu.

ComponentResult GetTextServiceMenu (
   ComponentInstance ts,
   MenuRef *serviceMenu
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

serviceMenu

A pointer to a menu handle (defined by the Menu Manager MenuHandle data type) for the text service component that is to be updated. The menu handle may be preallocated or it may be NULL. If the menu handle is NULL, the text service component should allocate a new menu and return it. On Mac OS 8 and 9, note that all instances of a component must share a single menu handle, allocated in the system heap. On Mac OS X, all instances of a component must share a single menu handle within an application’s context.

Return Value

If the text service component does not have a menu, it should return a ComponentResult value of TSMHasNoMenuErr. See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components must implement a function for this call.

The Text Services Manager calls GetTextServiceMenu when a component is opened or activated, so that it can put the component’s menu on the menu bar.

Client applications may directly make this call, but the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

GetTextServiceProperty

Notifies a text service component that it must identify the current value of one of its properties.

ComponentResult GetTextServiceProperty (
   ComponentInstance ts,
   TextServicePropertyTag inPropertyTag,
   TextServicePropertyValue *outPropertyValue
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

propertySelector

A constant identifying a general property of a text service. For descriptions of the system-defined property selectors, see “Text Service Properties.”

result

On return, a constant specifying the value for a text service property. For descriptions of the system-defined property values, see “Text Service Properties.”

Return Value

See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components have the option of implementing a function for this call.

Both the Text Services Manager and client applications can call this function to manage text service properties. If client applications directly make this call, the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

HidePaletteWindows

Notifies a text service component that it must hide its floating windows.

ComponentResult HidePaletteWindows (
   ComponentInstance ts
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

Return Value

If the text service component has no palettes, it should return a ComponentResult value of noErr. See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components must implement a function for this call.

If a window associated with a TSM document associated with your text service 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 receive the HidePaletteWindows call. When it receives a HidePaletteWindows call, your input method should hide all its floating and nonfloating windows associated with the component instance being deactivated. Its menus, if any, will be removed from the menu bar by the Text Services Manager.

The Text Services Manager makes this call either on its own or in response to application-interface calls it receives from client applications. Client applications may directly make this call, but the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

InitiateTextService

Notifies a text service component that it must perform any necessary set-up tasks and begin operating.

ComponentResult InitiateTextService (
   ComponentInstance ts
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

Return Value

This function should return a ComponentResult value of zero if there is no error, and an error code if there is one. See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components must implement a function for this call.

The Text Services Manager can call InitiateTextService to any component that it has already opened with the Component Manager OpenComponent or OpenDefaultComponent functions. Text service components should be prepared to handle InitiateTextService calls at any time.

Any text service component can receive multiple InitiateTextService calls. The Text Services Manager calls InitiateTextService each time the user adds a text service to a TSM document, even if the text service component has already been opened. This provides an opportunity for the component to restart or to display user interface elements that the user may have closed.

The Text Services Manager makes this call either on its own or in response to application-interface calls it receives from client applications. Client applications may directly make this call, but the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

NewTSMDocument

Creates a TSM document and returns a handle to the document’s ID.

OSErr NewTSMDocument (
   SInt16 numOfInterface,
   InterfaceTypeList supportedInterfaceTypes,
   TSMDocumentID *idocID,
   SRefCon refcon
);

Parameters
numOfInterface

The number of text service interface types that your application supports.

supportedInterfaceTypes

A value of type InterfaceTypeList specifying the kinds of text services that your program supports. This list helps the Text Services Manager locate the text services that have the correct interface type.

idocID

Upon successful completion of the call, a pointer to the document identification number of the TSM document created. If NewTSMDocument fails to create a new TSM document, it returns an error and sets idocID to NULL.

refcon

A reference constant to be associated with the TSM document. This may have any value you wish.

Return Value

A result code. See “Text Services Manager Result Codes.”

Discussion

Each time your client application calls the NewTSMDocument function, the Text Services Manager creates an internal structure called a TSM document and returns its ID.

If the call is successful, NewTSMDocument opens the default input method text service component of the current keyboard script and assigns it to this document. If NewTSMDocument returns tsmScriptHasNoIMErr, it has still created a valid TSM document, but has not associated an input method with it.

Starting in Mac OS X v10.3, the NewTSMDocument function turns on the kTSMDocumentUnicodeInputWindowPropertyTag implicitly for TSMDocuments of interface type kUnicodeDocumentInterfaceType. The effect is that Unicode input sources (keyboard layouts) can remain available, not only in an editing mode where Unicode is supported by an application, but also outside of editing mode where no TSMDocument in particular is active.

This change also provides compatibility with many applications that relied on Unicode input being available even without activating any of their own TSMDocuments, as well as other applications that do create their own Unicode TSMDocument but call the function UseInputWindow passing true (which was really an undefined operation in the original Unicode/TSM specification).

Availability
Declared In
TextServices.h

SendTextInputEvent

Sends Carbon text input events from a text service component to a client application.

OSStatus SendTextInputEvent (
   EventRef inEvent
);

Parameters
inEvent

A reference to the Carbon event to be sent.

Return Value

A result code. See “Text Services Manager Result Codes.” The SendTextInputEvent function returns noErr if the event is successfully handled. If the event is not handled, the function may return a Carbon Event Manager error, as well as Apple event or Text Encoding Conversion Manager errors.

Discussion

The SendTextInputEvent function allows a Carbon text service component on Mac OS X to send a Carbon text input event to the Text Services Manager for dispatching to a client application. This function can be used for events of Carbon event class kEventClassTextInput as well as for events of class kEventClassTSMDocumentAccess.

If the client application does not handle a particular Carbon text input event, the Text Services Manager converts the event to the corresponding Apple event and sends it again. An exception to this is when the application is not Unicode-aware (that is, the active TSM document was not created with the kUnicodeDocument interface type). In this case, a kEventUnicodeForKeyEvent Carbon event would not be converted to the corresponding Apple event (kUnicodeNotFromInputMethod). In every case, if the application handles neither the Unicode Carbon text input event nor the corresponding Apple event, the Text Services Manager converts the component’s text input event into a stream of “classic” key events for delivery to WaitNextEvent clients.

If the application has no active TSM documents or has called the function UseInputWindow to request input via the Text Services Manager’s floating input window—that is, if the application does not handle the event at all—the Text Services Manager routes the component’s text input event to the floating input window to allow bottom-line input.

Availability
Carbon Porting Notes

Note that this function replaces the function SendAEFromTSMComponent on Mac OS X only. With Mac OS X, text service components must be Carbon clients. This is in contrast to Mac OS 8 and 9, where text service components must not be Carbon clients. (This restriction is due to the fact that it is potentially destabilizing for a Carbon-based component to load Carbon in the context of a non-Carbon application.) Therefore, text service components use Carbon text input events and the SendTextInputEvent function only on Mac OS X. The function SendAEFromTSMComponent must be used by components running on Mac OS 8 and 9.

On any system, the Text Services Manager automatically converts component-originated text input events to the proper form for client applications. On Mac OS X, the Text Services Manager automatically converts component-originated Carbon events to Apple events, if a client application does not provide handlers for Carbon events. Conversely, on Mac OS 8 and 9, the Text Services Manager automatically converts component-originated Apple events to Carbon events and provides these Carbon events to applications, so they have the option of handling them.

Declared In
TextServices.h

SetTextServiceProperty

Notifies a text service component that one of its properties has been selected.

ComponentResult SetTextServiceProperty (
   ComponentInstance ts,
   TextServicePropertyTag inPropertyTag,
   TextServicePropertyValue inPropertyValue
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

propertySelector

A constant identifying a general property of a text service. For descriptions of the system-defined property selectors, see “Text Service Properties.”

value

A constant specifying a particular value for the text service property. For descriptions of the system-defined property values, see “Text Service Properties.”

Return Value

See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components have the option of implementing a function for this call.

An application can call SetTextServiceProperty to request that a text service component use a specific feature or functionality of the component’s program. For example, if an application knows that a Japanese input method which supports various typing methods is the currently active input method, the application can solicit the user’s preference of typing methods. Then the application can call SetTextServiceProperty to request that the input method use the preferred typing method, for example, Roman or Kana. Currently, the only properties that are defined by the system are typing methods for Japanese input methods.

Both the Text Services Manager and client applications can call this function to manage text service properties. If client applications directly make this call, the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

TerminateTextService

Notifies a text service component that it must terminate its operations in preparation for closing.

ComponentResult TerminateTextService (
   ComponentInstance ts
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

Return Value

If the text service component needs to remain open, it should return an OSErr value in the component result return value. This could happen, for example, if the user chooses Cancel in response to a text service component dialog box. See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components must implement a function for this call.

The Text Services Manager calls TerminateTextService before closing the component instance. A text service component must use this opportunity to confirm any inline input in progress. If this call is made to the last open instance of a text service component, the component should hide any open palette windows. If it is an input method, the component should not dispose of its menu handle if it has a menu.

The Text Services Manager makes this call either on its own or in response to application-interface calls it receives from client applications. Client applications may directly make this call, but the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

TextServiceEventRef

Provides an opportunity for a text service component to handle a Carbon event.

ComponentResult TextServiceEventRef (
   ComponentInstance ts,
   EventRef event
);

Parameters
ts

A Component Manager value of type ComponentInstance that identifies the component being called. When the Text Services Manager makes this call, it passes the ComponentInstance value returned by its call to the OpenComponent function. If an application makes this call, it may use the ComponentInstance value obtained from the kEventParamTextInputSendComponentInstance parameter of the Carbon event or the keyAEServerInstance parameter of an Apple event sent by the component being called. Alternately, an application may obtain a ComponentInstance value from a prior call to the function OpenTextService.

event

A reference to the Carbon event being passed to the component.

Return Value

If the text service component handles the event, it should return a nonzero value for componentResult. If it does not handle the event, it should return 0. Note that the Text Services Manager clones an event before passing it to a component, so any changes made to the contents of an event by the text service have no effect on the original event. See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Carbon text service components (that is, Mac OS X text services) must implement a function for this call.

The Text Services Manager automatically passes raw keyboard Carbon events (events of class kEventClassKeyboard) and some Carbon mouse events to text service components associated with an active TSM document. The Text Services Manager passes mouse-click events (kEventMouseDown, kEventMouseUp, kEventMouseDragged) to active text services directly. However, the Text Services Manager does not send kEventMouseMoved events to text service components. Instead, when a mouse-moved event occurs inside an inline input region (as registered via an application call to the TSMSetInlineInputRegion function), the Text Services Manager promotes the kEventMouseMoved event to the window-specific kEventWindowCursorChange event, which it then sends to the text service. For more details, see the function TSMSetInlineInputRegion.

Both the Text Services Manager and client applications can call this function to send Carbon events to components. If client applications directly make this call, the Text Services Manager does not then play a role in the connection between the client application making the call and the text service component receiving it.

Availability
Declared In
TextServices.h

TSMGetActiveDocument

Obtains the active TSM document in the current application context.

TSMDocumentID TSMGetActiveDocument (
   void
);

Parameters
Return Value

If the Text Services Manager has enabled bottom line input because no TSM document is active, NULL is returned. See the description of the TSMDocumentID data type.

Discussion

This function can be useful to identify whether the currently active TSM document belongs to the application, or whether it may belong to a control or a plug-in which has user focus within the application’s window.

Availability
Declared In
TextServices.h

TSMGetDocumentProperty

Obtains a TSM document property.

OSStatus TSMGetDocumentProperty (
   TSMDocumentID docID,
   TSMDocumentPropertyTag propertyTag,
   UInt32 bufferSize,
   UInt32 *actualSize,
   void *propertyBuffer
);

Parameters
docID

The TSMDocumentID that identifies the document whose property you want to obtain.

propertyTag

A tag that specifies the property you want to obtain.

bufferSize

The size of the data pointed to by the propertyBuffer parameter. See the Discussion for what to supply.

actualSize

On return, the actual size of the data.

propertyBuffer

On return, a pointer to the property data.

Return Value

A result code. See “Text Services Manager Result Codes.”

Discussion

You can call the function TSMGetDocumentProperty to retrieve arbitrary data with a specific TSM document. You associated arbitrary data with a TSM document by calling the function TSMSetDocumentProperty.

Input methods can call the function TSMGetDocumentProperty to determine whether the application that owns the document supports the glyph ID specification (kTSMDocumentPropertySupportGlyphInfo).

You can call the function TSMGetDocumentProperty to check for the following predefined properties:

These properties do not have any data associated with them. If the function TSMGetDocumentProperty returns noErr when you call the function with one of these properties, it indicated the property is present.

Typically you need to call this function twice, as follows:

  1. Pass the document ID for the document, the tag that specifies the property you want to obtain, 0 for the bufferSize parameter, NULL for the actualSize parameter, and NULL for the propertyBuffer parameter.

  2. Allocate enough space for a buffer of the returned size, then call the function again, passing a pointer in the propertyBuffer parameter. On return, the pointer references the property data.

Availability
Declared In
TextServices.h

TSMRemoveDocumentProperty

Removes a property from a TSM document.

OSStatus TSMRemoveDocumentProperty (
   TSMDocumentID docID,
   TSMDocumentPropertyTag propertyTag
);

Parameters
docID

The TSMDocumentID that identifies the document whose property you want to obtain.

propertyTag

A tag that specifies the property you want to remove.

Return Value

A result code. See “Text Services Manager Result Codes.”

Availability
Declared In
TextServices.h

TSMSetDocumentProperty

Sets a property for a TSM document.

OSStatus TSMSetDocumentProperty (
   TSMDocumentID docID,
   TSMDocumentPropertyTag propertyTag,
   UInt32 propertySize,
   void *propertyData
);

Parameters
docID

The TSMDocumentID that identifies the document whose property you want to set.

propertyTag

A tag that specifies the property you want to set.

propertySize

The size of the property data.

propertyData

A pointer to the property data.

Return Value

A result code. See “Text Services Manager Result Codes.”

Discussion

You can call the function TSMSetDocumentProperty to associate arbitrary data with a specific TSM document. You can call the function TSMGetDocumentProperty to retrieve arbitrary data.

If your application supports input of unencoded glyphs you must notify the Text Service Manager and input methods by setting the glyph ID specification (kTSMDocumentPropertySupportGlyphInfo) as a property of each TSM document.

Availability
Declared In
TextServices.h

UseInputWindow

Associates a floating input window with one or more TSM documents.

OSErr UseInputWindow (
   TSMDocumentID idocID,
   Boolean useWindow
);

Parameters
idocID

The TSM document ID of the particular TSM document to be associated with the floating input window. If NULL, this call affects all your application’s TSM documents.

useWindow

Indicates whether to use the floating input window. Pass TRUE if you want to use a floating window; pass FALSE if you do not want to use a floating window.

Return Value

A result code. See “Text Services Manager Result Codes.”

Discussion

The Text Services Manager provides a floating input window for your application’s use if you call UseInputWindow with a value of TRUE in the useWindow parameter. To specify inline input instead, call UseInputWindow with a value of FALSE in the useWindow parameter.

The default value for useWindow is FALSE; if you do not call UseInputWindow, the Text Services Manager assumes that your application wants to use inline input. If your application wants to save the user’s choice, it can put the last-used value for useWindow in a preferences file before quitting.

If you pass a valid TSM document ID for the idocID parameter, the useWindow parameter affects only that TSM document. If you pass NULL for the idocID parameter, the useWindow parameter affects all your application’s TSM documents, including documents you create after making this call.

Availability
Declared In
TextServices.h

Data Types

TSM Document Interface Type

Defines an interface type for a TSM document.

typedef OSType TSMDocumentInterfaceType;

Discussion

As of Mac OS X version 10.3, TSM interface types are also stored as TSM document properties. Interface types are a subset of TSM document properties; not all properties are interface types. Once a TSM document is created, you can easily find out its interface types at document creation. See “TSM Document Interfaces” for a list of the possible interface types.

Availability
Declared In
TextServices.h

InterfaceTypeList

An array of four-character codes identifying Text Services Manager interface types.

typedef OSType InterfaceTypeList[1];

Discussion

The InterfaceTypeList type is used in the function NewTSMDocument to identify the type of interfaces that an application supports and in the function GetServiceList to identify the types of interfaces that are currently available. See “TSM Document Interfaces” for a list of the possible interfaces.

Availability
Declared In
TextServices.h

ScriptLanguageRecord

Identifies a specific script-language combination.

struct ScriptLanguageRecord {
   ScriptCode fScript;
   LangCode fLanguage;
};
typedef struct ScriptLanguageRecord ScriptLanguageRecord;

Fields
fScript

A ScriptCode value identifying a particular set of written characters (for example, Roman versus Cyrillic) and their encoding.

fLanguage

A LangCode value identifying a particular language (for example, English), as represented using a particular ScriptCode value.

Discussion

Structures of type ScriptLanguageRecord are used in the functions SetDefaultInputMethod, GetDefaultInputMethod, SetTextServiceLanguage, and GetTextServiceLanguage.

Availability
Declared In
TextServices.h

ScriptLanguageSupport

Lists a component’s supported scripts and languages.

struct ScriptLanguageSupport {
   short fScriptLanguageCount;
   ScriptLanguageRecord fScriptLanguageArray[1];
};
typedef struct ScriptLanguageSupport ScriptLanguageSupport;
typedef ScriptLanguageSupport * ScriptLanguageSupportPtr;
typedef ScriptLanguageSupportPtr * ScriptLanguageSupportHandle;

Fields
fScriptLanguageCount

An integer specifying the number of ScriptLanguageRecord structures provided in the fScriptLanguageArray field.

fScriptLanguageArray

A variable-length array of structures of type ScriptLanguageRecord. Each of these structures identifies a specific script-language combination.

Discussion

A structure of type ScriptLanguageSupport is used in the function GetScriptLanguageSupport to list all of a component’s supported scripts and languages. If you are a component developer filling out a ScriptLanguageSupport structure, you should start with the component’s primary script and language as specified in the componentFlags field of its ComponentDescription structure.

Availability
Declared In
TextServices.h

TextServiceInfo

Identifies a single text service component by name and Component value.

struct TextServiceInfo {
   Component fComponent;
   Str255 fItemName;
};
typedef struct TextServiceInfo TextServiceInfo;
typedef TextServiceInfo *TextServiceInfoPtr;

Fields
fComponent

A Component Manager value of type Component. A Component value is a pointer to an opaque structure called a ComponentRecord that describes a component. You must supply a Component value in the function OpenTextService.

fItemName

A Pascal string with the name of a text service component. (The script system to use for displaying the string is specified in the componentFlags field of a ComponentDescription structure.

Availability
Declared In
TextServices.h

TextServiceList

Lists one or more text service components by name and Component value.

struct TextServiceList {
   short fTextServiceCount;
   TextServiceInfo fServices[1];
};
typedef struct TextServiceList TextServiceList;
typedef TextServiceList * TextServiceListPtr;
typedef TextServiceListPtr * TextServiceListHandle;

Fields
fTextServiceCount

An integer specifying the number of TextServiceInfo structures in the text service component list provided in the fServices field.

fServices

A variable-length array of structures of type TextServiceInfo. Each TextServiceInfo structure identifies a specific component by name and Component value.

Discussion

A structure of type TextServiceInfo is used in the function GetServiceList to list of all the text service components of a specified type that are currently available on a system.

Availability
Declared In
TextServices.h

TextServicePropertyValue

Defines a data type for text service property values.

typedef SInt32 TextServicePropertyValue;

Discussion

The property values associated with this data type are “Text Services Property Values.” Note that these values are declared as CFStringRef data types, so they require a cast to the SInt32 data type before you can supply them as a TextServicePropertyValue.

Availability
Declared In
TextServices.h

TSMContext

A reference to an opaque object that specifies a TSM context.

typedef struct OpaqueTSMContext * TSMContext;

Availability
Declared In
TextServices.h

TSMDocumentID

A reference to an opaque object that identifies a specific TSM document.

typedef struct OpaqueTSMDocumentID * TSMDocumentID;

Discussion

Each time a client application calls the function NewTSMDocument, the Text Services Manager creates an opaque internal structure called a TSM Document and returns a pointer to the document’s identification number.

Availability
Declared In
TextServices.h

TSMGlyphInfo

Describes one glyph embedded in a run of text.

struct TSMGlyphInfo {
   CFRange range;
   ATSFontRef fontRef;
   UInt16 collection;
   UInt16 glyphID;
};
typedef struct TSMGlyphInfo TSMGlyphInfo;

Fields
range

A CFRange data structure that specifies, in UTF-16 offsets, a range within the text to which this TSMGlyphInfo data structure applies. I

fontRef

An ATS font reference that specifies the font with which the glyph should be displayed. Note that the character collection ROS (Adobe Registry, Ordering, Supplement) is a property of the font.

collection

A glyph collection type that specifies how the glyphID parameter should be interpreted. When the value is kGlyphCollectionID, glyphID specifies the glyph's ID. When collection is a non-zero value, it specifies a character collection and glyphID specifies a CID. Note that collection must match the character collection of the font specified by the fontRef parameter.

When collections do not match, the TSMGlyphInfo data structure is invalid and should be ignored. You need to supply an ATSUI constant of type GlyphCollection to specify the character set you want to use. See Inside Mac OS X: ATSUI Reference for a list of the glyph collection constants you can specify.

glyphID

A glyph ID that specifies the glyph to use you to use in place of the current glyph. If you pass 0 instead of specifying a glyph, the TSMGlyphInfo data structure is used to attach a font to a range of text. In this case, the fontRef parameter specifies a font that should be used to display the range of text specified by the range parameter. This is useful when using characters in the Unicode private use area. Windings and other Windows based pi fonts are examples of such characters. When glyphID is zero, collection should also be zero and applications should ignore its value.

Discussion

The TSMGlyphInfo data structure is used as an item in the TSMGlyphInfoArray data structure. You use these structures to provide TSM with glyph and font information when you want to override the current glyph or font.

Availability
Declared In
TextServices.h

TSMGlyphInfoArray

Contains an array of glyph information structures.

struct TSMGlyphInfoArray {
   ItemCount numGlyphInfo;
   TSMGlyphInfo glyphInfo[1];
};
typedef struct TSMGlyphInfoArray TSMGlyphInfoArray;

Fields
numGlyphInfo

The number of items in the glyphInfo array.

glyphInfo

An array of glyph information structures.

Availability
Declared In
TextServices.h

Constants

Attribute Bits for TSM Document Access Carbon Events

Represents TSM document attributes. 

enum {
   kTSMDocAccessFontSizeAttributeBit = 0,
   kTSMDocAccessEffectiveRangeAttributeBit = 1
};

Constants
kTSMDocAccessFontSizeAttributeBit

When this bit is set, indicates to obtain font size information; used in the Carbon event kEventTSMDocumentAccess