Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

4    Text Services Manager Reference

Creating a Front-End Processor

Exploring Palm OS®

This chapter provides information about the public Text Services Manager (TSM) APIs.

Text Services Manager Constants
Text Services Manager Functions and Macros

The header file TextServicesMgr.h declares the API that this chapter describes.

Text Services Manager Constants ^TOP^

Feature Constants ^TOP^

Purpose

Constants used with the FtrGet() function.

Declared In

TextServicesMgr.h

Constants

#define tsmFtrCreator sysFileCTextServices
Creator ID of the Text Services Manager.
#define tsmFtrNumFlags 0
Selector passed to FtrGet() to get the Text Services Manager flags.
#define tsmFtrFlagsHasFep 0x00000001L
Indicates the bit set in the return value of FtrGet() if a FEP is installed.

TsmFepModeType Typedef ^TOP^

Purpose

Specifies the input modes used by the functions TsmGetFepMode() and TsmSetFepMode().

Declared In

TextServicesMgr.h

Prototype

typedef uint16_t TsmFepModeType

Constants

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

Text Services Manager Functions and Macros ^TOP^

TsmGetFepMode Function ^TOP^

Purpose

Returns the current input mode for the active FEP.

Declared In

TextServicesMgr.h

Prototype

TsmFepModeType TsmGetFepMode (
   void
)

Parameters

None.

Returns

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.

TsmSetFepMode Function ^TOP^

Purpose

Sets the input mode for the active FEP.

Declared In

TextServicesMgr.h

Prototype

TsmFepModeType TsmSetFepMode (
   TsmFepModeType inNewMode
)

Parameters

inNewMode
The new FEP input mode.

Returns

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 since it's 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.