WARNING! This file is provided here for illustrative purposes only. It is normally considered "private" because its contents are subject to change. Subsequent releases of Palm OS® make no guarantee of compatibility; any code that depends on the contents of this file is not guaranteed to work with future releases of the OS.
/****************************************************************************** * * Copyright (c) 1999-2003 PalmSource, Inc. All rights reserved. * * File: TextServicesFep.h * * Release: Palm OS 6.0 * * Description: * Header file for calling the FEP or its associated user dictionary editor. * *****************************************************************************/ #ifndef _TEXTSERVICESFEP_H_ #define _TEXTSERVICESFEP_H_ #include <PalmTypes.h> #include <Event.h> // EventType #include <SystemMgr.h> // sysAppLaunchCmdCustomBase #include <TextServicesMgr.h> // TsmFepModeType #include <TextMgr.h> // CharEncodingType /*********************************************************************** * Public constants ***********************************************************************/ // Our uint32_t version number available in TsmFepInfoType.apiVersion // 0xMMmfsbbb, where MM is major version, m is minor version // f is bug fix, s is stage: 3-release,2-beta,1-alpha,0-development, // bbb is build number for non-releases // V1.12b3 would be: 0x01122003 // V2.00a2 would be: 0x02001002 // V1.01 would be: 0x01013000 #define tsmFepAPIVersion(sysMakeROMVersion(6, 0, 0, sysROMStageRelease, 0)) // Creator code used to indicate no FEP, for get/set of current/system FEP. #define tsmInvalidFepCreator 0 // Possible values for the .buttonID field in a tsmFepButtonEvent event. #define tsmFepButtonConvert 0 #define tsmFepButtonConfirm 1 #define tsmFepButtonMode 2 // Was tsmFepButtonKana #define tsmFepButtonOnOff 3 #define tsmFepButtonShorten 4 #define tsmFepButtonLengthen 5 // Selector used with call to FtrGet(tsmFtrCreator, xxx) to get the // max number of extra stack bytes required by the FEP. #define tsmFtrNumFepStackExtra 128 // Selector used with call to FtrGet(tsmFtrCreator, xxx) to get the // max number of extra field bytes required by the FEP. #define tsmFtrNumFepFieldExtra129 // Errors specific to the Text Services Fep library. #define tsmErrUnimplemented (tsmErrorClass | 0) #define tsmErrFepNeedCommit (tsmErrorClass | 1) #define tsmErrFepCantCommit (tsmErrorClass | 2) #define tsmErrFepNotOpen (tsmErrorClass | 3) #define tsmErrFepStillOpen (tsmErrorClass | 4) #define tsmErrFepWrongAPI (tsmErrorClass | 5) #define tsmErrFepWrongEncoding (tsmErrorClass | 6) #define tsmErrFepWrongLanguage (tsmErrorClass | 7) #define tsmErrFepReentrancy (tsmErrorClass | 8) #define tsmErrFepCustom (tsmErrorClass | 128) /*********************************************************************** * Public types ***********************************************************************/ // Structure returned by TsmLibGetFepInfo routine. typedef struct { uint32_tapiVersion; // Tsm API implemented by library. uint32_tlibVersion; // Custom API implemented by library. uint32_tlibMaker; // Who made this input method (creator). CharEncodingType encoding; // e.g. charEncodingPalmLatin LmLanguageTypelanguage; // e.g. lJapanese size_t stackExtra; // Extra stack space needed by FEP size_t fieldExtra; // Extra field space needed by FEP. } TsmFepInfoType; // Structure returned by TsmFepHandleEvent/TsmFepTerminate routines // Note that the updateText and updateSelection flags are for efficiency // only - the field code can use these to reduce the amount of redrawing // required. typedef struct { size_t dumpLength; // Length of text to dump (or zero) size_t primedLength; // Length of priming text used by FEP Boolean updateText; // True -> update inline text. Boolean updateSelection; // True -> update selection range. Boolean handledEvent; // True -> Fep handled event. Boolean reserved; } TsmFepActionType; // Structure passed to TsmFepHandleEvent routine. typedef struct { size_t penOffset; // Offset (relative to start of inline text) // of event's screenX/screenY location. Boolean penLeading; // True -> position is on leading edge of the // character at penOffset. Boolean formEvent; // True -> caller is form code, thus NO CHANGES // to TsmStatusRec are allowed. uint16_t padding; size_t maxInline; // Max allowable size of inline, in bytes. char *primeText; // ptr to selected text (if inline not active) size_t primeOffset; // Offset to selected text. size_t primeLen; // Length of selected text. } TsmFepEventType; // Structure exchanged with many FEP routines. This is how // the FEP tells the editing code what to display, and how // to display it. Note that it's also the context record for the // FEP, thus additional (private) conversion information will // typically be appended by the FEP. typedef struct { char *inlineText; // ptr to inline text. size_t convertedLen; // Length of converted text. size_t pendingLen; // Length of unconverted (pending) text. size_t selectStart; // Start of selection range. size_t selectEnd; // End of selection range (can extend past // end of inline text) size_t clauseStart; // Start of converted clause highlighting size_t clauseEnd; // End of converted clause highlighting } TsmFepStatusType; // Parameter block passed with the sysAppLaunchCmdFepPanelAddWord command, // when the user selects "Add Word..." from the system edit menu. typedef struct { const char* wordP; // Ptr to word to add to FEP's user dictionary. size_t wordLen; // Length of word. } FepPanelAddWordParamsType; /*********************************************************************** * Public functions ***********************************************************************/ #ifdef __cplusplus extern "C" { #endif // Get the creator of the system FEP. Boolean TsmGetSystemFepCreator(uint32_t *oFepCreatorP); // Set the creator of the system FEP. void TsmSetSystemFepCreator(uint32_t iFepCreator); // Get the creator of the current FEP. Boolean TsmGetCurrentFepCreator(uint32_t *oFepCreatorP); // Set the creator of the current FEP, and make it active. status_t TsmSetCurrentFepCreator(uint32_t iFepCreator); status_t TsmFepHandleEvent(const EventType* inEventP, const TsmFepEventType* inTsmEventP, TsmFepStatusType **ioStatusP, TsmFepActionType *outActionP); Boolean TsmFepMapEvent(const EventType *inEventP); status_t TsmFepTerminate(TsmFepStatusType **ioStatusP, TsmFepActionType *outActionP); status_t TsmFepReset(void); status_t TsmFepCommitAction(void); // Display a deferred options list. Used by native FEPs in 6.0 to display // an options list at a later time, to avoid re-entrancy problems. void TsmFepOptionsList(uint16_t iNumOptions, uint16_t iCurOption, uint16_t iMaxOptionWidth); /*********************************************************************** * FEP Shared Library routines. These are the declarations of the * functions inside of the current FEP library, which will be called by the * cover routines above. ***********************************************************************/ // Open up an instance of the Fep. The Fep is responsible for allocating // the TsmFepStatusType structure (to which it might append additional // context information) and returning back a pointer to it. status_t TsmLibFepOpen(TsmFepStatusType** outStatusP); // Close down an instance of the Fep. The Fep is responsible // for disposing of the TsmFepStatusType which it allocated in TsmLibFepOpen(). status_t TsmLibFepClose(TsmFepStatusType* ioStatusP); // Return information about the Fep in the TsmFepInfoType structure. status_t TsmLibGetFepInfo(TsmFepInfoType* outInfoP); // Handle an event passed in <inEventP>. Additional information about the event // is passed in the TsmFepEventType structure. Update the inline text data in // the TsmFepStatusType, and tell the caller what happened by setting up the // TsmFepActionType structure (including whether the event was handled by the // Fep). status_t TsmLibFepHandleEvent(const EventType* inEventP, const TsmFepEventType* inTsmEventP, TsmFepStatusType* ioStatusP, TsmFepActionType* outActionP); // Decide if <inEvent> should be remapped to some other event. If so, return // true. If we return true, then go ahead and perform the remapping by posting // a new event with the remapped info. Boolean TsmLibFepMapEvent(const TsmFepStatusType* inStatusP, const EventType* inEventP); // Terminate an inline session. Typically this involves 'dumping' all of the // converted text, and potentially deleting any untransliterated input text. // As with TsmLibFepHandleEvent, update the inline text data in the // TsmFepStatusType, and indicate what was done in the TsmFepActionType. status_t TsmLibFepTerminate(TsmFepStatusType* ioStatusP, TsmFepActionType* outActionP); // Reset an inline session. The state of the Fep is reset to empty, raw // text, nothing to dump, etc. This call should only be made when the // conversion results are not required, otherwise TsmTerminate should be used. status_t TsmLibFepReset(TsmFepStatusType* ioStatusP); // The caller has processed the action which was returned by either the // TsmHandleEvent or TsmTerminate routine, so it is now safe to reset any // temporary state information (e.g. dumped text) in <ioStatus>. status_t TsmLibFepCommitAction(TsmFepStatusType* ioStatusP); // Draw the Fep mode indicator at location <x,y>. Boolean TsmLibFepDrawModeIndicator(TsmFepModeType inFepMode, uint16_t gsiState, Coord x, Coord y); // Draw an option in the FEP options list. void TsmLibFepDrawOption(const TsmFepStatusType *inStatusP, uint16_t iItemNumber, const RectangleType* iBounds); #ifdef __cplusplus } #endif #endif