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

A    TextServicesFep.h

Creating a Front-End Processor

Exploring Palm OS®


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