ADC Home > Reference Library > Reference > Carbon > Text & Fonts > Text Services Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Text Services Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

CloseTextService

Closes a text service component, other than an input method, and disassociates it from the active TSM document. (Deprecated in Mac OS X v10.5.)

OSErr CloseTextService (
   TSMDocumentID idocID,
   ComponentInstance aComponentInstance
);

Parameters
idocID

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

aComponentInstance

The component instance created by a prior call to OpenTextService.

Return Value

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

Discussion

When a user wants to close an opened text service component, your client application should call the function CloseTextService.

If the text service component displays a menu, the Text Services Manager removes the menu from the menu bar. This function is for closing text service components other than input methods. Your application does not need to open or close input methods.

Availability
Declared In
TextServices.h

DeselectTextService

Notifies TSM that an input method has been closed. (Deprecated in Mac OS X v10.5.)

OSStatus DeselectTextService (
   Component aComp
);

Parameters
aComp
Return Value

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

Discussion

This API is currently only intended for use by Character Palette class input methods. It allows such an input method to notify TSM that it has been closed by the user as a result of interaction with the input method's own UI, such a palette's close button, instead of via the normal UI provided by the System, such as the Keyboard Menu.

Availability
Declared In
TextServices.h

GetDefaultInputMethod

Obtains the default input method text service component for a given script and language. (Deprecated in Mac OS X v10.5.)

Not recommended.

OSErr GetDefaultInputMethod (
   Component *ts,
   ScriptLanguageRecord *slRecordPtr
);

Parameters
ts

A pointer to the component identifier of the input method text service component that is associated with the script and language combination given in the slRecord parameter.

slRecordPtr

A pointer to a structure of type ScriptLanguageRecord. This structure describes the script and language combination that is associated with the input method text service specified in the ts parameter.

Return Value

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

Discussion

You should use the function GetDefaultInputMethodOfClass instead of this one.

The operating system uses GetDefaultInputMethod to find out which input method to activate when the user selects a new keyboard script from the Keyboard menu or by Command-key combination, or when an application calls KeyScript to change keyboard scripts. Your application should not typically need to call this function.

Version Notes

For systems prior to Mac OS X, in versions of Japanese system software starting with KanjiTalk 7, if the default input method is pre-KanjiTalk 7 and non-TSM-aware, GetDefaultInputMethod returns the error tsmInputMethodIsOldErr. In that case the ts parameter contains the script code of the old input method in its high-order word, and the reference ID of the old input method in its low-order word.

Availability
Declared In
TextServices.h

GetDefaultInputMethodOfClass

Obtains the default input method text service component for a given text service class. (Deprecated in Mac OS X v10.5.)

OSStatus GetDefaultInputMethodOfClass (
   Component *aComp,
   ScriptLanguageRecord *slRecPtr,
   TextServiceClass tsClass
);

Parameters
aComp

On return, a pointer to the component identifier of the input method text service component that is associated with the script and language combination given in the slRecord parameter.

slRecPtr

On return, a pointer to a structure of type ScriptLanguageRecord. This structure describes the script and language combination that is associated with the input method text service specified in the ts parameter.

tsClass

The text service class whose component and script language record you want to obtain. Pass kKeyboardInputMethodClass to specify a keyboard input method. Pass kInkInputMethod to specify an Ink input method.

Return Value

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

Discussion
Availability
Declared In
TextServices.h

GetInputModePaletteMenu

Obtains from an input method the menu to display for a pull-down menu on the input mode palette. (Deprecated in Mac OS X v10.5.)

ComponentResult GetInputModePaletteMenu (
   ComponentInstance inInstance,
   UInt32 inItemID,
   CFArrayRef *outMenuItemsArray
);

Parameters
inInstance

The component instance.

inItemID

The item ID of the pull-down menu button.

outMenuItemsArray

On return, points to an array of menu items. A pull-down menu consists of an array of CFDictionary objects that contain the keys described in Input Mode Palette Menu Definition Keys.

Return Value

Returns a non-null value on successful handling of the call.

Availability
Declared In
TextServices.h

GetScriptLanguageSupport

Notifies a text service component that it must produce a list of its supported languages and scripts. (Deprecated in Mac OS X v10.5.)

ComponentResult GetScriptLanguageSupport (
   ComponentInstance ts,
   ScriptLanguageSupportHandle *scriptHdl
);

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.

scriptHdl

A handle to a structure of type ScriptLanguageSupport. The handle must be either NULL or a valid handle. If it is NULL, the text service component allocates a new handle. If it is already a valid handle, the text service component resizes it as necessary. GetScriptLanguageSupport should produce a list of scripts and languages in this parameter.

Return Value

The return value should contain 0 if the list is correct, or an error value if an error occurred. See the Component Manager documentation for a description of the ComponentResult data type.

Discussion

Text service components must implement a function for this call.

In response to this call, the component should list all its supported scripts and languages, starting with the primary script and language as specified in the componentFlags field of its component description structure. The Text Services Manager makes the GetScriptLanguageSupport call after a component is opened via the Component Manager function OpenComponent. One of the Text Services Manager’s uses of this script information is to determine whether to exchange information with the component in the Unicode text encoding.

For example, if a component is associated with a Macintosh script, but includes the smUnicodeScript constant in its enumeration of supported constants, then the Text Services Manager determines that the component produces and expects text in the Unicode encoding. Additionally, in this example, the Text Services Manager also concludes that the Unicode characters which the component supports are limited to those encoded in the repertoire of the encoding corresponding to the Macintosh script in the componentFlags field of its component description structure. Note that if the script specified in the componentFlags field is itself smUnicodeScript, the Text Services Manager imposes no restriction on the set of supported characters, and it treats the component as being capable of handling any Unicode character.

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

GetServiceList

Obtains a list of the text service components of a specified type that are currently available. (Deprecated in Mac OS X v10.5.)

OSErr GetServiceList (
   SInt16 numOfInterface,
   const OSType *supportedInterfaceTypes,
   TextServiceListHandle *serviceInfo,
   SInt32 *seedValue
);

Parameters
numOfInterface

The number of text service interface types supported by your client application.

supportedInterfaceTypes

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

serviceInfo

A pointer to a handle to a structure of type TextServiceList. If the handle is NULL, the Text Services Manager allocates the handle; otherwise, it assumes the handle is a valid text service component list handle, as defined by the TextServiceListHandle data type.

seedValue

A pointer to a value that indicates whether the list of text service components returned by GetServiceList may have been modified.

Return Value

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

Discussion

Your client application is responsible for providing a way—usually a menu—for the user to choose from among all available text service components. To get a list of available text service components to display in a menu, call the GetServiceList function. Be sure to filter out input methods, because the Keyboard menu already displays them.

When your application calls GetServiceList, the Text Services Manager locates all the text service components of the specified types and creates a text service component list, defined by the TextServiceList data type, containing an entry for each of the text service components.

It is possible to register text service components or withdraw them from registration at any time. Once it has compiled a list of text services, the Text Services Manager invokes the GetComponentListModSeed function and returns the value in the modseed parameter. You can save that value and, the next time you need to draw or regenerate the list of services, call the Component Manager GetComponentListModSeed function. If the seed value differs from the one you received from your last call to GetServiceList, you need to call GetServiceList once more to update the information. Alternately, you can simply call GetServiceList each time you need to update the list, although that may be less efficient.

Availability
Declared In
TextServices.h

GetTextServiceLanguage

Obtains the current input script and language. (Deprecated in Mac OS X v10.5.)

OSErr GetTextServiceLanguage (
   ScriptLanguageRecord *slRecordPtr
);

Parameters
slRecordPtr

A pointer to a structure of type ScriptLanguageRecord. Upon completion of the call, this structure describes the language supported by the default (current) text service component for the current keyboard script.

Return Value

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

Discussion

Your application should not typically need to call this function.

Availability
Declared In
TextServices.h

InputModePaletteItemHit

Informs an input method that a function button on the input mode palette was pressed. (Deprecated in Mac OS X v10.5.)

ComponentResult InputModePaletteItemHit (
   ComponentInstance inInstance,
   UInt32 inItemID,
   UInt32 inItemState
);

Parameters
inInstance

The component instance.

inItemID

The item ID of the function button pressed on the palette.

inItemState

The new state of the button.

Return Value

Returns a non-null value on successful handling of the call.

Availability
Declared In
TextServices.h

IsTextServiceSelected

Determines if a text service component is selected. (Deprecated in Mac OS X v10.5.)

Boolean IsTextServiceSelected (
   Component aComp
);

Parameters
aComp

The component you want to determine is selected or not.

Return Value

Returns true if the component is selected.

Availability
Declared In
TextServices.h

OpenTextService

Opens a text service component, other than an input method, and associates it with a TSM document. (Deprecated in Mac OS X v10.5.)

OSErr OpenTextService (
   TSMDocumentID idocID,
   Component aComponent,
   ComponentInstance *aComponentInstance
);

Parameters
idocID

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

aComponent

A component identifier for this text service component. You can obtain the component identifier to pass in aComponent by comparing the menu item name selected by the user with the component item name found in a TextServiceInfo structure. You can obtain a TextServiceInfo structure by calling the function GetServiceList and examining the fServices field of the TextServiceList structure that it produces.

aComponentInstance

Upon completion of the call, a pointer to a component instance. This value identifies your application’s connection to a text service component. You must supply this value if you call the text service functions provided by the component directly.

Return Value

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

Discussion

This function instructs the Text Services Manager to open a text service component, other than an input method, that a user has chosen and to associate it with a TSM document. The Text Services Manager opens the requested component by calling the Component Manager OpenComponent function.

If the specified text service component is already open, the Text Services Manager does not open it again and the tsmComponentAlreadyOpenErr error message is returned as a result code. Whether or not the text service is open, the Text Services Manager calls the functions InitiateTextService and ActivateTextService for the given text service and returns a valid component instance. Upon completion of the OpenTextService call, the selected text service component is initialized and active.

This function is for opening text service components other than input methods. Your application does not need to open or close input methods.

Availability
Declared In
TextServices.h

SelectTextService

Selects a text service. (Deprecated in Mac OS X v10.5.)

OSStatus SelectTextService (
   Component aComp
);

Parameters
aComp

The text service you want to select.

Return Value

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

Discussion

This function is intended for use by input methods in text service classes which are additive in nature, that is where the input method can operate in parallel to other input methods in the same class and other additive text service classes. An example of such a class is the Character Palette class. This function is not for use by traditional input methods, such as those that belong to the keyboard input method class.

Availability
Declared In
TextServices.h

SendAEFromTSMComponent

Sends Apple events from a text service component to a client application. (Deprecated in Mac OS X v10.5.)

OSErr SendAEFromTSMComponent (
   const AppleEvent *theAppleEvent,
   AppleEvent *reply,
   AESendMode sendMode,
   AESendPriority sendPriority,
   SInt32 timeOutInTicks,
   AEIdleUPP idleProc,
   AEFilterUPP filterProc
);

Parameters
theAppleEvent

A pointer to the Apple event to be sent.

reply

A pointer to the reply Apple event returned by SendAEFromTSMComponent.

sendMode

The value that lets you specify one of the following modes specified by corresponding constants: the reply mode for the Apple event, the interaction level, the application switch mode, the reconnection mode, and the return receipt mode. To obtain the value for this parameter, add the appropriate constants. Comprehensive details about these constants are provided in the description of the Apple Event Manager AESend function.

sendPriority

The value that specifies whether to put the Apple event at the back of the event queue (set with the kAENormalPriority flag) or at the front of the queue (kAEHighPriority flag).

timeOutInTicks

The length of time (in ticks) that the client application is willing to wait for the reply or return receipt from the server application before it times out. If the value of this parameter is kNoTimeOut, the Apple event never times out.

idleProc

A pointer to a function for any tasks (such as displaying a globe, a wristwatch, or a spinning beach ball cursor) that the application performs while waiting for a reply or a return receipt.

filterProc

A pointer to a function that accepts certain incoming Apple events that are received while the handler waits for a reply or a return receipt and filters out the rest.

Return Value

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

Discussion

Component use of Apple events and the function SendAEFromTSMComponent is discouraged on Mac OS X. Text service components should use Carbon text input events and the function SendTextInputEvent on Mac OS X, instead. See “Carbon Porting Notes” below for more details.

The SendAEFromTSMComponent function is essentially a wrapper function for the Apple Event Manager function AESend. See the description of AESend for additional necessary information, including constants for the sendMode parameter and result codes.

SendAEFromTSMComponent identifies your text service component from the keyAEServerInstance parameter in the Apple event specified in the theAppleEvent parameter. If a reference constant in a TSM document that corresponds to this parameter is found in the internal data structures of the Text Services Manager, SendAEFromTSMComponent adds the reference constant as the keyAETSMDocumentRefcon parameter to the given Apple event before sending it to the application.

If the client application is not TSM-aware, SendAEFromTSMComponent routes the Apple events to the floating input window to allow bottom-line input.

If your text service component changes the environment in any way—such as by modifying the A5 world or changing the current zone—while constructing an Apple event, it must restore the previous settings before sending the Apple event.

Your text service component should always use the kCurrentProcess constant as the target address when it creates an Apple event to send to the Text Services Manager.

Availability
Carbon Porting Notes

Note that this function is superseded by the function SendTextInputEvent 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

SetDefaultInputMethod

Sets a default input method to a given script and language. (Deprecated in Mac OS X v10.5.)

Not recommended.

OSErr SetDefaultInputMethod (
   Component ts,
   ScriptLanguageRecord *slRecordPtr
);

Parameters
ts

The component identifier of the input method to be associated with the script and language combination given in the slRecord parameter.

slRecordPtr

A pointer to a structure of type ScriptLanguageRecord. This structure describes the script and language combination to be associated with the input method specified in the ts parameter.

Return Value

A result code. See “Text Services Manager Result Codes.” If the script code and language code specified in the script-language structure are incompatible, SetDefaultInputMethod returns the error paramErr.

Discussion

You should use the function SetDefaultInputMethodOfClass instead of this one.

The operating system uses SetDefaultInputMethod to associate an input method text service component with a given script and language. The operating system calls this function when the user expresses input method preferences through the Keyboard menu, Keyboard control panel, or other device. The associations made with this function are permanent; that is, they persist after restart. Your application should not typically need to call this function.

Availability
Declared In
TextServices.h

SetDefaultInputMethodOfClass

Sets the default input method text service component for a given text service class. (Deprecated in Mac OS X v10.5.)

OSStatus SetDefaultInputMethodOfClass (
   Component aComp,
   ScriptLanguageRecord *slRecPtr,
   TextServiceClass tsClass
);

Parameters
aComp

The component identifier of the input method to be associated with the script and language combination given in the slRecord parameter.

slRecPtr

A pointer to a structure of type ScriptLanguageRecord. This structure describes the script and language combination to be associated with the input method specified in the ts parameter.

tsClass

The text service class whose component and script language record you want to obtain. Pass kKeyboardInputMethodClass to specify a keyboard input method. Pass kInkInputMethod to specify an Ink input method.

Return Value

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

Discussion
Availability
Declared In
TextServices.h

SetTextServiceLanguage

Changes the current input script and language. (Deprecated in Mac OS X v10.5.)

OSErr SetTextServiceLanguage (
   ScriptLanguageRecord *slRecordPtr
);

Parameters
slRecordPtr

A pointer to a structure of type ScriptLanguageRecord specifying the new script and language combination.

Return Value

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

Discussion

The operating system calls this function when the user switches the keyboard script, so that the Text Services Manager can synchronize the input method with the current keyboard script.

Your application should not typically need to call this function.

Availability
Declared In
TextServices.h

TSMCopyInputMethodEnabledInputModes

Obtain the array of the enabled (and visible) input modes for a component. (Deprecated in Mac OS X v10.5.)

Boolean TSMCopyInputMethodEnabledInputModes (
   Component inComponent,
   CFArrayRef *outInputModeArray
);

Parameters
inComponent

The component whose input modes you want to obtain.

outInputModeArray

On return, points to an array of the enabled and visible input modes for the specified component. This function is meaningful only for input methods that adopt the input mode protocol. If the component passed is not input mode-savvy, the returned array is NULL. It is the responsibility of the caller to release the returned array.

Discussion

You use this function to allow an input method to query the system for the subset of its own input modes that are enabled. This allows you to omit from the component UI any input modes that are disabled by the user or the system. The enabled input modes returned in the array are always visible ones. That is, the array contains those input modes for which kTSInputModeIsVisibleKey is true; non-visible input modes are not tracked by the system.

Availability
Declared In
TextServices.h

TSMInputModePaletteLoadButtons

Notifies the input mode palette of changes to the controls for an input method and replaces the current controls with the new control array. (Deprecated in Mac OS X v10.5.)

void TSMInputModePaletteLoadButtons (
   CFArrayRef paletteButtonsArray
);

Parameters
paletteButtonsArray

A CFArray that contains descriptions of the controls. Use a CFDictionary to describe each control. See “Input Mode Palette Control Keys” for a description of the keys you can supply.

Availability
Declared In
TextServices.h

TSMInputModePaletteUpdateButtons

Notifies the input mode palette of changes to the controls for an input method and updates the controls. (Deprecated in Mac OS X v10.5.)

void TSMInputModePaletteUpdateButtons (
   CFArrayRef paletteButtonsArray
);

Parameters
paletteButtonsArray

A CFArray that contains descriptions of the controls. Use a CFDictionary to describe each control. See “Input Mode Palette Control Keys” for a description of the keys you can supply.

Discussion

This function updates controls based on the control tag ID. It doe not replace or remove existing controls.

Availability
Declared In
TextServices.h

TSMSelectInputMode

Sets the specified input method input mode as the current input source. (Deprecated in Mac OS X v10.5.)

OSStatus TSMSelectInputMode (
   Component inComponent,
   CFStringRef inInputMode
);

Parameters
inComponent

The component whose input mode you want to set.

inInputMode

The input mode you want to set as the current input source.

Discussion

You use this function to allow an input method to select one of its own input modes as the current input source and update the Text Input menu icon in the menu bar. This function is only meaningful for input methods that adopt the input mode protocol.

Availability
Declared In
TextServices.h

TSMSetInlineInputRegion

Defines a region within a TSM document in which inline input can occur. (Deprecated in Mac OS X v10.5.)

OSStatus TSMSetInlineInputRegion (
   TSMDocumentID inTSMDocument,
   WindowRef inWindow,
   RgnHandle inRegion
);

Parameters
inTSMDocument

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

inWindow

A reference to the window that contains the inline input session. You can pass NULL for this parameter to indicate the window that currently has user focus.

inRegion

The current inline input region. This region should be in coordinates local to the port associated with the window specified in the inWindow parameter. The region must be recomputed each time the text content of the inline input session changes (such as after an Update Active Input Area event) and when the region moves for other reasons (such as window resizing or scrolling). If you pass NULL for this parameter, the Text Service Manager defaults to intercepting mouse events for the window’s entire content region.

Return Value

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

Discussion

The TSMSetInlineInputRegion function informs the Text Services Manager of the region occupied by an inline input session. If certain mouse events (such as clicks and mouse-moved events) occur within this region, the Text Services Manager forwards these events to the current input method, so the component can respond to the user’s actions.

When a mouse-moved event occurs inside an inline input region (as registered via the TSMSetInlineInputRegion function), the Text Services Manager promotes the kEventMouseMoved event, after it has been received by the applicable control or window, to the window-specific kEventWindowCursorChange event. The Text Services Manager first delivers the kEventWindowCursorChange event to the active input method, then, if it is not handled, to any other active text services. If the event has still not been handled, the Text Services Manager finally passes the event to the application’s kEventWindowCursorChange event handler, if any. This event-dispatching process gives applications that need to see the low-level mouse-moved events a chance to see these events first, while providing a mechanism for text services and applications to act on these events without conflict. After completing this process, the Carbon Event Manager converts any kEventWindowCursorChange event that remains unhandled to a “classic” mouse-moved event for WaitNextEvent clients.

If an application does not call this function, when an input method is active the Text Services Manager by default intercepts mouse events in the entire content region of the window that currently has user focus.

Availability
Declared In
TextServices.h

< Previous PageNext Page > Hide TOC

© 2002, 2005 Apple Computer, Inc. All Rights Reserved. (Last updated: 2005-11-09)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.