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
tsmConfirmEvent
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
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
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
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
tsmFepDisplayOptionsEvent
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
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
Text Services FEP Structures and Types
FepPanelAddWordParamsType Struct
Purpose
The parameter block for the launch command sysAppLaunchCmdFepPanelAddWord
.
Declared In
TextServicesFep.h
Prototype
typedef struct { const char *wordP; size_t wordLen; } FepPanelAddWordParamsType
Fields
TsmFepActionType Struct
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 theTsmFepStatusType
.inlineText
data has been changed. -
updateSelection
- This field is set to
true
whenever the clause or highlighting offsets in theTsmFepStatusType
structure have changed. -
handledEvent
- This field is
true
whenTsmLibFepHandleEvent()
has completely handled the event, and thus the caller should not do any further processing of the event.
TsmFepEventType Struct
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'sscreenX
andscreenY
location. This field is only valid forpenDownEvents
. - 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 followingpenOffset
, or the right side of the character precedingpenOffset
. The value istrue
if thepenDown
Event was on the left (leading edge) side of the following character. -
formEvent
- This field is
true
ifTsmLibFepHandleEvent()
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 thatconvertedLen
+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
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 inTextServicesFep.h
(see Appendix A). ThetsmAPIVersion
constant is a standard Palm OS version number of the formatx.y.z<release stage><release number>
- and
- 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 examplecharEncodingPalmSJIS
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
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 asselectStart
. -
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
Button ID Constants
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
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
Purpose
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
sysAppLaunchCmdFepPanelAddWord
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
TsmFepCommitAction Function
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
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
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
orkeyDownEvent
. -
→ 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
-
errNone
- The event was handled successfully (
outActionP.handledEvent
istrue
), or the event was not completely handled by this function (outActionP.handledEvent
isfalse
). -
tsmErrFepReentrancy
- The FEP is currently running code.
-
tsmErrFepNeedCommit
- The FEP is waiting for a
TsmLibFepCommitAction()
call.
See Also
TsmFepMapEvent Function
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
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
Purpose
Pops up the list of options for the FEP.
Declared In
TextServicesFep.h
Prototype
void TsmFepOptionsList ( uint16_tiNumOptions
, uint16_tiCurOption
, uint16_tiMaxOptionWidth
)
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
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
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
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
Returns
errNone
if the call was successful. Returns tsmErrFepReentrancy
if the FEP is currently running code and cannot process the call.
TsmGetCurrentFepCreator Function
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
containstsmInvalidFepCreator
.
Returns
true
if there is a current FEP.
See Also
TsmSetCurrentFepCreator()
, TsmGetSystemFepCreator()
TsmGetSystemFepCreator Function
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
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
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
Purpose
Sets the creator ID of the system FEP.
Declared In
TextServicesFep.h
Prototype
void TsmSetSystemFepCreator (
uint32_t iFepCreator
)
Parameters
Returns
See Also
TsmGetSystemFepCreator()
, TsmSetCurrentFepCreator()
Text Services FEP Plugin Functions
Your FEP shared library must implement the functions described in this section.
TsmLibFepClose Function
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
Returns
-
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
TsmLibFepCommitAction Function
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
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
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 ( TsmFepModeTypeinFepMode
, uint16_tgsiState
, Coordx
, Coordy
)
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
inGraffitiShift.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:
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
Purpose
Draws an option in the FEP options list.
Declared In
TextServicesFep.h
Prototype
void TsmLibFepDrawOption ( const TsmFepStatusType*inStatusP
, uint16_tiItemNumber
, 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
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
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
orkeyDownEvent
. -
→ 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
-
errNone
- The event was handled successfully (
outActionP
.handledEvent istrue
), or the event was not completely handled by this function (outActionP
.handledEvent isfalse
). -
tsmErrFepReentrancy
- The FEP is currently running code.
-
tsmErrFepNeedCommit
- The FEP is waiting for a
TsmLibFepCommitAction()
call.
TsmLibFepMapEvent Function
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
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
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
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
TsmLibFepReset Function
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
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
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
Returns
errNone
if the call was successful. Returns tsmErrFepReentrancy
if the FEP is currently running code and cannot process the call.
TsmLibGetFepInfo Function
Purpose
Fills in the TsmFepInfoType
structure with information about the FEP.
Declared In
TextServicesFep.h
Prototype
status_t TsmLibGetFepInfo (
TsmFepInfoType *outInfoP
)
Parameters
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.