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

5    Text Services FEP Reference

Creating a Front-End Processor

Exploring Palm OS®

This chapter provides information about the FEP API as declared in TextServicesFep.h (see Appendix A). For source code examples, see SampleFep.cpp in the Sample FEP.

This chapter also provides information about the system-level events specific to the Text Services Manager (TSM). These events and structures defined in the Palm OS® header files EventCodes.h and Event.h.

FEP Events
Text Services FEP Structures and Types
Text Services FEP Constants
Text Services FEP Launch Codes
Text Services FEP Functions
Text Services FEP Plugin Functions

Your FEP shared library must implement the API described in the section "Text Services FEP Plugin Functions."

FEP Events ^TOP^

tsmConfirmEvent ^TOP^

Purpose

Optionally sent by a FEP when converted text has been confirmed, either explicitly by the user or as a result of the field losing the focus.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _TSMConfirmType {
   char *yomiText;
   uint16_t formID;
   uint16_t padding_1;
} 

Fields

yomiText
A pointer to the raw text that the user entered during conversion, which corresponds to the converted text being confirmed.
formID
The ID of the form that was active when the converted text was confirmed. This is useful for proper event processing when tsmConfirmEvent is being generated while one form is being closed and other form is opened: the event won't be processed until after the new form has become active.
padding_1
Padding bytes.

Comments

An application (such as the Address Book) can use the data contained in this event to automatically set the data in a pronunciation field, instead of forcing users to re-enter the same text that they just passed to the FEP.

tsmFepButtonEvent ^TOP^

Purpose

Tapping on a Text Services Manager input area button posts a keyDownEvent with a virtual character code (vchrTsm1 through vchrTsm4) and the command bit set in the event's modifier field. If the keyDownEvent's character code matches one of the four that correspond to the input area buttons, SysHandleEvent() calls the Text Services Manager to remap the event to be a tsmFepButtonEvent.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _TSMFepButtonType {
   uint16_t buttonID;
} 

Fields

buttonID
This field can have one of the values defined in "Button ID Constants." Some FEPs may not use all of these values.

NOTE: The tsmFepButtonShorten and tsmFepButtonLengthen values don't correspond to any of the four input area buttons; typically these values are generated by a physical keyboard, and are used to indicate clause shortening and lengthening.

tsmFepModeEvent ^TOP^

Purpose

Used to change the FEP mode. This includes turning the FEP off, and turning it on (in its default mode). FEP mode changes must be handled through events to ensure proper FEP/field code synchronization.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _TSMFepModeEventType {
   uint16_t mode;
} 

Fields

mode
One of the constants described in "TsmFepModeType."

tsmFepChangeEvent ^TOP^

Purpose

Sent by the Text Services Manager when the FEP is changed, to make all threads aware of the change. This event is used only by the Text Services Manager and a FEP does not need to pay attention to it.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct tsmFepChange {
   uint32_t creator;
} tsmFepChange

Fields

creator
Creator ID of the new FEP.

tsmFepDisplayOptionsEvent ^TOP^

Purpose

Sent by the Text Services Manager when the user has requested that the FEP display the options list. This event is used only by the Text Services Manager and a FEP does not need to pay attention to it.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct tsmFepDisplayOptions {
   uint16_t numOptions;
   uint16_t curOption;
   uint16_t maxOptionWidth;
} tsmFepDisplayOptions

Fields

numOptions
Number of options in the list.
curOption
The number of the currently selected option in the list. List items are numbered beginning with 0.
maxOptionWidth
The maximum option width in pixels.

tsmFepSelectOptionEvent ^TOP^

Purpose

Sent by the Text Services Manager to the FEP when an item is selected in the FEP options list.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct tsmFepSelectOption {
   int16_t selection;
} tsmFepSelectOption

Fields

selection
The number of the selected option. List items are numbered beginning with 0.

Text Services FEP Structures and Types ^TOP^

FepPanelAddWordParamsType Struct ^TOP^

Purpose

The parameter block for the launch command sysAppLaunchCmdFepPanelAddWord.

Declared In

TextServicesFep.h

Prototype

typedef struct {
   const char *wordP;
   size_t wordLen;
} FepPanelAddWordParamsType

Fields

wordP
Pointer to the word to be added or looked up.
wordLen
Length of the word in wordP.

TsmFepActionType Struct ^TOP^

Purpose

The FEP functions TsmLibFepHandleEvent() and TsmLibFepTerminate() use this structure to tell the caller what needs to be done to update the text display to synchronize it with the FEP.

Declared In

TextServicesFep.h

Prototype

typedef struct {
   size_t dumpLength;
   size_t primedLength;
   Boolean updateText;
   Boolean updateSelection;
   Boolean handledEvent;
} TsmFepActionType

Fields

dumpLength
Tells the caller how many bytes of text in the TsmFepStatusType.inlineText data should be removed from the front of the inline area and made part of the regular (non-inline) text. A value of zero means that nothing is being dumped.
primedLength
The FEP uses this field to tell the caller how much of the priming text (passed to it in TsmFepEventType.primeText) it was able to accept or use. The caller uses this value to trim unused bytes from the end of the inline area, because initially it assumes that all of the selected (priming) text became inline text.
updateText
This field is set to true whenever the contents or length of the TsmFepStatusType.inlineText data has been changed.
updateSelection
This field is set to true whenever the clause or highlighting offsets in the TsmFepStatusType structure have changed.
handledEvent
This field is true when TsmLibFepHandleEvent() has completely handled the event, and thus the caller should not do any further processing of the event.

TsmFepEventType Struct ^TOP^

Purpose

This structure is passed to the TsmLibFepHandleEvent() function. It contains extra information required by the FEP to correctly handle the event. This structure is filled in by the field object, and is read-only; the FEP does not need to update any of the fields in this structure.

Declared In

TextServicesFep.h

Prototype

typedef struct {
   size_t penOffset;
   Boolean penLeading;
   Boolean formEvent;
   uint16_t padding;
   size_t maxInline;
   char *primeText;
   size_t primeOffset;
   size_t primeLen;
} TsmFepEventType

Fields

penOffset
The offset (in bytes) from the beginning of the TsmFepStatusType.inlineText data to the offset of the character located at the event's screenX and screenY location. This field is only valid for penDownEvents.
Note that this field will contain a negative number if the user taps on text before the start of the inline area, and it could also be past the end of the inline text area.
penLeading
Indicates whether a penDownEvent occurred on the left side of the character following penOffset, or the right side of the character preceding penOffset. The value is true if the penDown Event was on the left (leading edge) side of the following character.
formEvent
This field is true if TsmLibFepHandleEvent() is being called by the form code (when there is no active field), and thus the status record should not be modified.
padding
Padding bytes.
maxInline
The maximum number of bytes allowable in the inline text area. It is up to the FEP to constrain the results it passes back in the TsmFepStatusType record such that convertedLen + pendingLen is always less than or equal to this limit. This limit is calculated by the field object, based on the amount of text in the field, the current size of the inline area, and the maximum allowable text in the field.
primeText
A pointer to text used to "prime" the conversion process. If there is no active inline area, its value is determined as follows: the user selects text in a field, and then the user turns the FEP on, taps the mode change button, or taps the convert button.
The field code will set primeText to be the field's text pointer.
primeOffset
The offset to the beginning of the selected text defined by the primeText pointer.
primeLen
The length of the selected text defined by the primeText pointer.

NOTE: The value of primeLen might be greater than the maximum amount of text that the FEP can handle. In that case, the FEP should ignore text beyond what it can handle, and set up the TsmFepActionType.primedLength field with the amount of text it was able to use for the inline text.

TsmFepInfoType Struct ^TOP^

Purpose

The TsmFepInfoType structure is returned by the TsmLibGetFepInfo() function, which is usually called before the FEP is actually opened.

Declared In

TextServicesFep.h

Prototype

typedef struct {
   uint32_t apiVersion;
   uint32_t libVersion;
   uint32_t libMaker;
   CharEncodingType encoding;
   LmLanguageType language;
   size_t stackExtra;
   size_t fieldExtra;
} TsmFepInfoType

Fields

apiVersion
This field should always be set to tsmFepAPIVersion, which is a constant defined in TextServicesFep.h (see Appendix A). The tsmAPIVersion constant is a standard Palm OS version number of the format
x.y.z<release stage><release number>
and encoded as a 32-bit value. For example, version 1.12b3 would be encoded as 0x01122003.
The value in this field is used by the Text Services Manager to decide if the FEP implements an appropriate version of the API. If the value returned by the FEP matches the current API version number in the major and minor fields, then the FEP can be used. Otherwise the FEP is ignored.
libVersion
The version number for any custom APIs implemented by the FEP library. This field is useful for code that calls any of the library's extended functions; for example, a function that accesses the user dictionary.
libMaker
A four character "FEP Maker" code. This should always be the same as the FEP creator ID. Otherwise, by convention this code should match the creator code used by any associated panel or application that is part of the FEP software package.
encoding
A Text Manager character encoding value as defined in PalmLocale.h, for example charEncodingPalmSJIS for Japanese FEPs.
language
A Locale Manager language code as defined in LocaleMgrTypes.h; for example, lJapanese for Japanese FEPs.
stackExtra
The maximum amount of stack space in bytes that would be used by the FEP in response to the TsmLibFepHandleEvent() call.
fieldExtra
The number of extra bytes needed to auto-expand "short" fields so that the user can enter enough pre-conversion text to correctly specify the post-conversion results.
For example, some Japanese Kanji characters could require up to ten bytes of text entry in order to specify the Hiragana characters that will be converted into two double-byte Kanji characters. In this example, six extra bytes would be required to set the last two characters in a field to the converted Kanji. This value is primarily used by the Category code when the user is editing the names of categories.

TsmFepStatusType Struct ^TOP^

Purpose

This structure is allocated by TsmLibFepOpen(), and returned to the caller. It is then passed to many of the FEP functions, until TsmLibFepClose() deallocates it. The FEP uses this structure to tell the field object code what to display, and how to display it.

Declared In

TextServicesFep.h

Prototype

typedef struct {
   char *inlineText;
   size_t convertedLen;
   size_t pendingLen;
   size_t selectStart;
   size_t selectEnd;
   size_t clauseStart;
   size_t clauseEnd;
} TsmFepStatusType

Fields

inlineText
The reference number of the FEP shared library. This is filled in by the Text Services Manager after the call to TsmLibFepOpen() succeeds.
convertedLen
A pointer to the text that is controlled by the FEP. This text is often called the "active input area" text.
pendingLen
The amount of text (in bytes) in the inlineText data that has been entered but not yet converted. This text always follows the converted text.
selectStart
The offset (in bytes) from the beginning of the inlineText data to the beginning of the selected text.
selectEnd
The offset (in bytes) from the beginning of the inlineText data to the end of the selected text. If there is an insertion point, but no selection range, then this value will be the same as selectStart.
clauseStart
The offset (in bytes) from the beginning of the inlineText data to the beginning of the current clause text. Only converted text can contain clauses. If there is no converted text, or no clause, then this field should contain zero.
clauseEnd
The offset (in bytes) from the beginning of the inlineText data to the end of the current clause text. If there is no converted text, or no clause, then this field should contain zero.

NOTE: If the FEP is dumping text from the inline area into the field object, these offsets are still relative to the state of the inline text before any dumping has taken place. The TsmLibFepCommitAction() call should update the FEP's internal state to reflect the effect of dumping text.

NOTE: The FEP typically adds extra information to the end of this record, to maintain private information about the session.

Text Services FEP Constants ^TOP^

Button ID Constants ^TOP^

Purpose

Possible values for the buttonID field in a tsmFepButtonEvent event.

Declared In

TextServicesFep.h

Constants

#define tsmFepButtonConvert 0
The Convert button.
#define tsmFepButtonConfirm 1
The Confirm button.
#define tsmFepButtonMode 2
The Mode button.
#define tsmFepButtonOnOff 3
The On/Off button.
#define tsmFepButtonShorten 4
The Shorten button.
#define tsmFepButtonLengthen 5
The Lengthen button.

Comments

The tsmFepButtonShorten and tsmFepButtonLengthen values don't correspond to any of the four input area buttons; typically these values are generated by a physical keyboard, and are used to indicate clause shortening and lengthening.

Error Codes ^TOP^

Purpose

Error codes returned by FEP shared library functions.

Declared In

TextServicesFep.h

Constants

#define tsmErrFepCantCommit (tsmErrorClass | 2)
The TsmLibFepCommitAction() function encountered an error.
#define tsmErrFepCustom (tsmErrorClass | 128)
FEPs can return custom error codes starting from here.
#define tsmErrFepNeedCommit (tsmErrorClass | 1)
The FEP is waiting for a TsmLibFepCommitAction() call.
#define tsmErrFepNotOpen (tsmErrorClass | 3)
The FEP is not open.
#define tsmErrFepReentrancy (tsmErrorClass | 8)
The FEP is currently running code in another thread and cannot process the call.
#define tsmErrFepStillOpen (tsmErrorClass | 4)
The FEP has additional contexts that are still active.
#define tsmErrFepWrongAPI (tsmErrorClass | 5)
The FEP library API version does not match the Text Services Manager API version.
#define tsmErrFepWrongEncoding (tsmErrorClass | 6)
The FEP has received data in the wrong encoding. Currently the OS doesn't do anything special when this error code is returned by the FEP.
#define tsmErrFepWrongLanguage (tsmErrorClass | 7)
The FEP has received data in the wrong language. Currently the OS doesn't do anything special when this error code is returned by the FEP.
#define tsmErrUnimplemented (tsmErrorClass | 0)
The FEP doesn't implement the function. Currently the OS doesn't do anything special when this error code is returned by the FEP.

Miscellaneous Constants ^TOP^

Purpose

Miscellaneous constants.

Declared In

TextServicesFep.h

Constants

#define tsmFepAPIVersion (sysMakeROMVersion(6, 0, 0, sysROMStageRelease, 0))
Text Services Manager FEP API version information.
#define tsmFtrNumFepStackExtra 128
Selector used for FtrGet() to get the maximum number of extra stack bytes required by the FEP.
#define tsmFtrNumFepFieldExtra 129
Selector used for FtrGet() to get the maximum number of extra field bytes required by the FEP.
#define tsmInvalidFepCreator 0
Creator code used to indicate no FEP, for getting and setting the current and system FEP.

Text Services FEP Launch Codes ^TOP^

sysAppLaunchCmdFepPanelAddWord ^TOP^

Purpose

Send this launch code to the FEP panel to add a word to the FEP user dictionary.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdFepPanelAddWord 87


Parameters

The launch code's parameter block pointer references a FepPanelAddWordParamsType structure that indicates the word to be added.

Text Services FEP Functions ^TOP^

TsmFepCommitAction Function ^TOP^

Purpose

Unlocks or deallocates any buffers used to pass information back to the caller in the TsmFepStatusType record as a result of a TsmLibFepHandleEvent() or TsmLibFepTerminate() call.

Declared In

TextServicesFep.h

Prototype

status_t TsmFepCommitAction (
   void
)

Parameters

None.

Returns

errNone if the call was successful. Returns tsmErrFepReentrancy if the FEP is currently running code in another thread and cannot process the call. A FEP can prevent this error by doing reference counting.

Comments

This function also updates any status record or internal offsets that need adjusting because text is being dumped from the inline text area.

TsmFepHandleEvent Function ^TOP^

Purpose

Tells the caller whether or not the FEP completely handled the event. Updates the TsmFepStatusType record as appropriate, and sets fields in the TsmFepActionType record to tell the caller what needs to be updated.

Declared In

TextServicesFep.h

Prototype

status_t TsmFepHandleEvent (
   const EventType *inEventP,
   const TsmFepEventType *inTsmEventP,
   TsmFepStatusType **ioStatusP,
   TsmFepActionType *outActionP
)

Parameters

inEventP
A pointer to a system event record, such as a typical penDownEvent or keyDownEvent.
inTsmEventP
A pointer to a TsmFepEventType structure, which contains extra information about the event.
ioStatusP
Pointer to a status pointer for this context.
outActionP
A pointer to a TsmFepActionType structure, which the FEP fills in with information that the caller needs to know to correctly update the display to reflect the current FEP state.

Returns

Return one of the following:

errNone
The event was handled successfully (outActionP.handledEvent is true), or the event was not completely handled by this function (outActionP.handledEvent is false).
tsmErrFepReentrancy
The FEP is currently running code.
tsmErrFepNeedCommit
The FEP is waiting for a TsmLibFepCommitAction() call.

See Also

FEP Events

TsmFepMapEvent Function ^TOP^

Purpose

Determines whether or not an event should be remapped by the FEP. If it needs to be remapped, then it posts the remapped event to the event queue.

Declared In

TextServicesFep.h

Prototype

Boolean TsmFepMapEvent (
   const EventType *inEventP
)

Parameters

inEventP
A pointer to the event record.

Returns

true if the event was remapped.

Comments

This function is commonly used to remap FEP button shortcut characters (that is, space or linefeed) to their FEP button equivalents. For example, it maps the shift left and right arrow keyDownEvents to shorten/lengthen clause events. Note that the remapping is conditional on the state of the FEP. For example, a space is only remapped to a convert event if the FEP has inline text, otherwise it gets treated like a regular space character (no remapping).

TsmFepOptionsList Function ^TOP^

Purpose

Pops up the list of options for the FEP.

Declared In

TextServicesFep.h

Prototype

void TsmFepOptionsList (
   uint16_t iNumOptions,
   uint16_t iCurOption,
   uint16_t iMaxOptionWidth
)

Parameters

iNumOptions
Number of options in the list.
iCurOption
The currently selected item.
iMaxOptionWidth
Maximum width of the list in pixels.

Returns

The index of the list item selected, or noListSelection if no item was selected.

Comments

This function queues an event to pop up the FEP options list. When this event is handled by TsmFepHandleEvent(), the TsmLibFepDrawOption() function is called to draw each item in the list. This function is passed the item number and the bounds in which the option item is to be drawn.

TsmFepReset Function ^TOP^

Purpose

Calls through to the current FEP's TsmLibFepReset() function, which resets the FEP by clearing all buffers and setting the state back to raw text.

Declared In

TextServicesFep.h

Prototype

status_t TsmFepReset (
   void
)

Parameters

None.

Returns

errNone if the call was successful. Returns tsmErrFepReentrancy if the FEP is currently running code and cannot process the call.

Comments

This function does not change the mode. It also ignores any pending commits (see TsmLibFepCommitAction()).

TsmFepTerminate Function ^TOP^

Purpose

Calls through to the current FEP's TsmLibFepTerminate() function, which ends the conversion session, if active, updates the TsmFepStatusType record with the new status, and fills in the TsmFepActionType record to tell the caller what needs to be updated.

Declared In

TextServicesFep.h

Prototype

status_t TsmFepTerminate (
   TsmFepStatusType **ioStatusP,
   TsmFepActionType *outActionP
)

Parameters

ioStatusP
Pointer to the FEP's status record.
outActionP
Pointer to the FEP's action record.

Returns

errNone if the call was successful. Returns tsmErrFepReentrancy if the FEP is currently running code and cannot process the call.

TsmGetCurrentFepCreator Function ^TOP^

Purpose

Gets the creator ID of the current FEP.

Declared In

TextServicesFep.h

Prototype

Boolean TsmGetCurrentFepCreator (
   uint32_t *oFepCreatorP
)

Parameters

oFepCreatorP
Pointer to the current FEP creator ID. If there is no current FEP, then *oFepCreatorP contains tsmInvalidFepCreator.

Returns

true if there is a current FEP.

See Also

TsmSetCurrentFepCreator(), TsmGetSystemFepCreator()

TsmGetSystemFepCreator Function ^TOP^

Purpose

Gets the creator ID of the system FEP. The system FEP is the FEP that will be used to initialize the current FEP when you perform a soft-reset of the handheld.

Declared In

TextServicesFep.h

Prototype

Boolean TsmGetSystemFepCreator (
   uint32_t *oFepCreatorP
)

Parameters

oFepCreatorP
Pointer to the returned FEP plugin library creator ID, or tsmInvalidFepCreator if there is no system FEP.

Returns

true if there is a system FEP.

See Also

TsmSetSystemFepCreator(), TsmGetCurrentFepCreator()

TsmSetCurrentFepCreator Function ^TOP^

Purpose

Sets the current FEP to be the FEP with the specified creator ID, opens it and makes it usable.

Declared In

TextServicesFep.h

Prototype

status_t TsmSetCurrentFepCreator (
   uint32_t iFepCreator
)

Parameters

iFepCreator
FEP plugin library creator ID.

Returns

errNone if the current FEP was changed to the FEP with the specified creator ID. Otherwise, it returns one of the following result codes:

tsmErrFepWrongAPI
The FEP library API version does not match the Text Services Manager API version.
sysInvalidRefNum
The FEP library could not be opened.
tsmErrFepStillOpen
The previous FEP is still open.

Comments

All FEP plugin libraries are of type sysFileTFep.

See Also

TsmGetCurrentFepCreator(), TsmSetSystemFepCreator()

TsmSetSystemFepCreator Function ^TOP^

Purpose

Sets the creator ID of the system FEP.

Declared In

TextServicesFep.h

Prototype

void TsmSetSystemFepCreator (
   uint32_t iFepCreator
)

Parameters

iFepCreator
FEP plugin library creator ID.

Returns

Nothing.

See Also

TsmGetSystemFepCreator(), TsmSetCurrentFepCreator()

Text Services FEP Plugin Functions ^TOP^

Your FEP shared library must implement the functions described in this section.

TsmLibFepClose Function ^TOP^

Purpose

Deallocates a TsmFepStatusType structure previously returned by TsmLibFepOpen(). If this closes the last active FEP session, then disposes of any shared information (for example, unlocks dictionary data).

Declared In

TextServicesFep.h

Prototype

status_t TsmLibFepClose (
   TsmFepStatusType *ioStatusP
)

Parameters

ioStatusP
Status pointer for this context.

Returns

Return one of the following:

errNone
No error; call succeeded.
tsmErrFepNotOpen
The FEP is not open.
tsmErrFepReentrancy
The FEP is currently running code in another thread.
tsmErrFepStillOpen
The FEP has additional contexts that are active.

Comments

This function ignores any pending commits (see TsmLibFepCommitAction()).

See Also

TsmLibFepOpen()

TsmLibFepCommitAction Function ^TOP^

Purpose

Unlocks or deallocates any buffers used to pass information back to the caller in the TsmFepStatusType record as a result of a TsmLibFepHandleEvent() or TsmLibFepTerminate() call.

Declared In

TextServicesFep.h

Prototype

status_t TsmLibFepCommitAction (
   TsmFepStatusType *ioStatusP
)

Parameters

ioStatusP
Status pointer for this context.

Returns

errNone if the call was successful. Returns tsmErrFepReentrancy if the FEP is currently running code in another thread and cannot process the call.

Comments

This function also updates any status record or internal offsets that need adjusting because text is being dumped from the inline text area.

TsmLibFepDrawModeIndicator Function ^TOP^

Purpose

If the FEP is active, then draws a mode indicator which corresponds to the FEP's current mode.

Declared In

TextServicesFep.h

Prototype

Boolean TsmLibFepDrawModeIndicator (
   TsmFepModeType inFepMode,
   uint16_t gsiState,
   Coord x,
   Coord y
)

Parameters

inFepMode
The FEP input mode; see "TsmFepModeType." This is the current FEP mode as maintained by the server.
gsiState
Mode indicator state. It can have the values defined by GsiShiftState in GraffitiShift.h.
x
x coordinate of the location where the character is to be drawn (left bound).
y
y coordinate of the location where the character is to be drawn (top bound).

Returns

true if the call drew the mode indicator.

Comments

For Japanese, the recommended mode indicators are as follows:

FEP off, regular mode

lower-case, full-width Latin "a"

FEP off, shifted mode

upper-case, full-width Latin "a"

FEP on, default (Hiragana)

Hiragana "a"

FEP on, Katakana

Katakana "a"

For Chinese handhelds, which may have multiple FEPs, use a character that will identify the FEP that is currently active. For example, the Palm OS standard Pinyin FEP uses the "pin" character to indicate that the FEP is on.


NOTE: The mode indicator doesn't change based on the state of the FEP. For example, the FEP mode stays the same whether or not the inline session contains converted text.

TIP: You can use the constants kMaxGsiWidth and kMaxGsiHeight to limit the size of your mode indicator. These constants are defined in GraffitiShift.h. All of the pixels in the rectangle defined by these constants must be set (that is, erased or redrawn) if the FEP draws the indicator, to ensure proper updating.

TsmLibFepDrawOption Function ^TOP^

Purpose

Draws an option in the FEP options list.

Declared In

TextServicesFep.h

Prototype

void TsmLibFepDrawOption (
   const TsmFepStatusType *inStatusP,
   uint16_t iItemNumber,
   const RectangleType *iBounds
)

Parameters

inStatusP
Pointer to the FEP status record.
iItemNumber
The item number of the option to draw.
iBounds
The bounds where the option is to be drawn.

Returns

Nothing.

Comments

This function is called by the list code, once for each item in the list. This function should draw the appropriate options item within the bounds indicated by iBounds.

TsmLibFepHandleEvent Function ^TOP^

Purpose

Tells the caller whether or not the FEP completely handled the event. Updates the TsmFepStatusType record as appropriate, and sets fields in the TsmFepActionType record to tell the caller what needs to be updated.

Declared In

TextServicesFep.h

Prototype

status_t TsmLibFepHandleEvent (
   const EventType *inEventP,
   const TsmFepEventType *inTsmEventP,
   TsmFepStatusType *ioStatusP,
   TsmFepActionType *outActionP
)

Parameters

inEventP
Pointer to a system event record, such as a typical penDownEvent or keyDownEvent.
inTsmEventP
Pointer to a TsmFepEventType structure, which contains extra information about the event.
ioStatusP
Status pointer for this context.
outActionP
Pointer to a TsmFepActionType structure, which the FEP fills in with information that the caller needs to know to correctly update the display to reflect the current FEP state.

Returns

One of the following:

errNone
The event was handled successfully (outActionP.handledEvent is true), or the event was not completely handled by this function (outActionP.handledEvent is false).
tsmErrFepReentrancy
The FEP is currently running code.
tsmErrFepNeedCommit
The FEP is waiting for a TsmLibFepCommitAction() call.

TsmLibFepMapEvent Function ^TOP^

Purpose

Determines whether or not an event should be remapped by the FEP. If it needs to be remapped, then this function posts the remapped event to the event queue.

Declared In

TextServicesFep.h

Prototype

Boolean TsmLibFepMapEvent (
   const TsmFepStatusType *inStatusP,
   const EventType *inEventP
)

Parameters

inStatusP
Pointer to the FEP status record.
inEventP
Pointer to the event record.

Returns

true if the event was remapped.

Comments

This function is commonly used to remap FEP button shortcut characters (that is, space or linefeed) to their FEP button equivalents. For example, it maps the shift left and right arrow keyDownEvents to shorten/lengthen clause events. Note that the remapping is conditional on the state of the FEP. For example, a space is only remapped to a convert event if the FEP has inline text, otherwise it gets treated like a regular space character (no remapping).

TsmLibFepOpen Function ^TOP^

Purpose

Allocates and initializes a new instance of the TsmFepStatusType structure, and returns this structure to the caller. If this is the first TsmLibFepOpen() call, it should also set up any shared information, such as dictionary data.

Declared In

TextServicesFep.h

Prototype

status_t TsmLibFepOpen (
   TsmFepStatusType **outStatusP
)

Parameters

outStatusP
Pointer to a pointer to the new instance (status) record.

Returns

errNone if the call was successful; otherwise, returns a standard error code that indicates the nature of the problem, such as memErrNotEnoughSpace or dmErrCantFind.

Comments

Note that typically a FEP will allocate extra space at the end of the TsmFepStatusType structure to hold extra information about the session.

See Also

TsmLibFepClose()

TsmLibFepReset Function ^TOP^

Purpose

Resets the FEP (input method) by clearing all buffers and setting the state back to raw text. However, does not change the mode.

Declared In

TextServicesFep.h

Prototype

status_t TsmLibFepReset (
   TsmFepStatusType *ioStatusP
)

Parameters

ioStatusP
Status pointer for this context.

Returns

errNone if the call was successful. Returns tsmErrFepReentrancy if the FEP is currently running code and cannot process the call.

Comments

This function ignores any pending commits (see TsmLibFepCommitAction()).

TsmLibFepTerminate Function ^TOP^

Purpose

Ends the conversion session, if active. Updates the TsmFepStatusType record with the new status, and fills in the TsmFepActionType record to tell the caller what needs to be updated.

Declared In

TextServicesFep.h

Prototype

status_t TsmLibFepTerminate (
   TsmFepStatusType *ioStatusP,
   TsmFepActionType *outActionP
)

Parameters

ioStatusP
Pointer to the FEP's status record
outActionP
Pointer to the FEP's action record.

Returns

errNone if the call was successful. Returns tsmErrFepReentrancy if the FEP is currently running code and cannot process the call.

TsmLibGetFepInfo Function ^TOP^

Purpose

Fills in the TsmFepInfoType structure with information about the FEP.

Declared In

TextServicesFep.h

Prototype

status_t TsmLibGetFepInfo (
   TsmFepInfoType *outInfoP
)

Parameters

outInfoP
Pointer to the information record to be filled in.

Returns

errNone if the call was successful. Returns tsmErrFepReentrancy if the FEP is currently running code and cannot process the call.

Comments

This function can and will get called before the FEP library has been opened, so potentially no globals have been set up. This function should just fill in the information record with the available information and return.