Text Services Manager
 

 < Home   < Developers   < Development Support   < Documentation

52 Text Services Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

52 Text Services Manager

Text Services Manager Data Structures

TsmFepModeType

Text Services Manager Functions

TsmGetFepMode

TsmSetFepMode

       

This chapter provides information about the Text Services Manager API as declared in TextServicesMgr.h. The Text Services Manager provides the caller with an API for interacting with various text services, including front-end processors (FEPs), which are sometimes known as input methods. This chapter discusses the following topics:

Text Services Manager Data Structures

Text Services Manager Functions

Text Services Manager Data Structures

TsmFepModeType

The TsmFepModeType type specifies the input modes used by the functions TsmGetFepMode and TsmSetFepMode.

typedef UInt16 TsmFepModeType; 

TsmFepModeType can be set to one of the defined modes listed in the following table.

Constant
Value
Description
tsmFepModeDefault
0
The default input mode for the FEP. For example, with the Japanese FEP, the default mode is Hiragana.
tsmFepModeOff
1
Indicates that there is no active FEP input mode (the FEP is off).
tsmFepModeCustom
128
A custom FEP input mode. You can have more than one custom mode; the starting value is 128. Katagana is an example of a custom input mode for the Japanese FEP.

Text Services Manager Functions

TsmGetFepMode

Purpose

Return the current input mode for the active front-end processor (FEP).

Prototype

TsmFepModeType TsmGetFepMode (void *nullParam)

Parameters

-> nullParamAn unused status pointer that must be set to NULL.

Result

If there is an active FEP, returns the current mode for the active FEP. If there is no active FEP, returns tsmFepModeOff.

Comments

The most common use for this function is to save the current FEP mode. You could then call TsmSetFepMode to set the current mode to "off" and again to restore the saved mode once the application has finished using a special text field.

Compatibility

Implemented only if 3.5 New Feature Set is present. In Palm OS 3.5, the nullParam parameter takes a non-NULL value, allowing the caller to maintain its own status record. In Palm OS 4.0, this parameter is unused and must be set to NULL. Any other value generates a non-fatal alert.

See Also

TsmSetFepMode

TsmSetFepMode

Purpose

Set the input mode for the active front-end processor (FEP) to be the mode defined by the parameter inNewMode.

Prototype

TsmFepModeType TsmSetFepMode (void *nullParam, TsmFepModeType inNewMode)

Parameters

-> nullParamAn unused status pointer that must be set to NULL.
-> inNewModeThe new FEP input mode.

Result

Returns the previous input mode. If there is no active FEP, returns tsmFepModeOff.

Comments

The most common use for this function is to set the FEP mode to "off" while the application is using a special text field, and then to restore the previous mode. See TsmGetFepMode for more information on saving and restoring the FEP mode.

One common reason for explicitly disabling the FEP in code is when a text field will only contain 7-bit ASCII (numeric fields automatically turn off the FEP). For example, if the application has a password field and the contents of that field will always be 7-bit ASCII, the application should turn off the FEP to help prevent the user from entering invalid characters into the field.

Another common case occurs when the application has a numeric field, but cannot just rely on the numeric field attribute. For example, if you want the user to be able to enter the minus ("-") sign, you cannot use a numeric field because the field code prevents the user from entering this character: its not a digit or a period. In this case, you should make it a regular field and have the application screen the characters. The application should disable the FEP when such a pseudo-numeric field is active.


IMPORTANT: A mode change is currently enqueued as a keyDown event so that the field and FEP can remain properly synchronized and so that the mode change doesn't affect any pending keyDown events. The mode change does not happen until the enqueued keyDown event is passed to FrmHandleEvent; if you call TsmGetFepMode immediately after calling TsmSetFepMode, you won't see a mode change.

There are also some current limitations with changing the mode: there must be an active form; and if there is an active field in the form, it must not be a numeric field.

Compatibility

Implemented only if 3.5 New Feature Set is present. In Palm OS 3.5, the nullParam parameter takes a non-NULL value, allowing the caller to maintain its own status record. In Palm OS 4.0, this parameter is unused and must be set to NULL. Any other value generates a non-fatal alert.

See Also

TsmGetFepMode, EvtEnqueueKey, FrmHandleEvent