This chapter provides reference material for the Graffiti® manager. The Graffiti manager API is declared in the header file Graffiti.h.
For more information on the Graffiti manager, see the section "Receiving User Input" in the Palm OS Programmer's Companion, vol. I.
Graffiti Manager Functions

GrfAddMacro

Purpose
Add a macro to the macro list.
Prototype
Err GrfAddMacro (const Char *nameP, UInt8 *macroDataP, UInt16 dataLen)
Parameters
dataLen | Size of macro data in bytes. |
Result
Returns 0 if no error; returns grfErrNoMacros, grfErrMacroPtrTooSmall, dmErrNotValidRecord, dmErrWriteOutOfBounds if an error occurs.
See Also
GrfGetMacro, GrfGetMacroName, GrfDeleteMacro
GrfAddPoint

Purpose
Add a point to the Graffiti point buffer.
Prototype
Err GrfAddPoint (PointType *pt)
Parameters
pt | Pointer to point buffer. |
Result
Returns 0 if no error; returns grfErrPointBufferFull if an error occurs.
See Also
GrfFlushPoints
GrfCleanState

Purpose
Remove any temporary shifts from the dictionary state.
Prototype
Err GrfCleanState (void)
Parameters
None
Result
Returns 0 if no error, or grfErrNoDictionary if an error occurs.
See Also
GrfInitState
GrfDeleteMacro

Purpose
Delete a macro from the macro list.
Prototype
Err GrfDeleteMacro (UInt16 index)
Parameters
index | Index of the macro to delete. |
Result
Returns 0 if no error, or grfErrNoMacros, grfErrMacroNotFound if an error occurs.
See Also
GrfAddMacro
GrfFilterPoints

Purpose
Filter the points in the Graffiti point buffer.
Prototype
Err GrfFilterPoints (void)
Parameters
None.
Result
Always returns 0.
See Also
GrfMatch
GrfFindBranch

Purpose
Locate a branch in the Graffiti dictionary by flags.
Prototype
Err GrfFindBranch (UInt16 flags)
Parameters
flags | Flags of the branch you're searching for. |
Result
Returns 0 if no error, or grfErrNoDictionary or grfErrBranchNotFound if an error occurs.
See Also
GrfCleanState, GrfInitState
GrfFlushPoints

Purpose
Dispose of all points in the Graffiti point buffer.
Prototype
Err GrfFlushPoints (void)
Parameters
None.
Result
Always returns 0.
See Also
GrfAddPoint
GrfGetAndExpandMacro

Purpose
Look up and expand a macro in the current macros.
Prototype
Err GrfGetAndExpandMacro (Char *nameP, UInt8 *macroDataP, UInt16 *dataLenP)
Parameters
nameP | Name of macro to look up. |
macroDataP | Macro contents returned here. |
dataLenP | On entry, size of macroDataP buffer; on exit, number of bytes in macro data. |
Result
Returns 0 if no error, or grfErrNoMacros or grfErrMacroNotFound if an error occurs.
See Also
GrfAddMacro, GrfGetMacro
GrfGetGlyphMapping

Purpose
Look up a glyph in the dictionary and return the text.
Prototype
Err GrfGetGlyphMapping (UInt16 glyphID, UInt16 *flagsP, void *dataPtrP, UInt16 *dataLenP, UInt16 *uncertainLenP)
Parameters
glyphID | Glyph ID to look up. |
flagsP | Returned dictionary flags. |
dataPtrP | Where returned text goes. |
dataLenP | On entry, size of dataPtrP; on exit, number of bytes returned. |
uncertainLenP | Return number of uncertain characters in text. |
Result
Returns 0 if no error, or grfErrNoDictionary or grfErrNoMapping if an error occurs.
See Also
GrfMatch
GrfGetMacro

Purpose
Look up a macro in the current macros.
Prototype
Err GrfGetMacro (Char *nameP, UInt8 *macroDataP, UInt16 *dataLenP)
Parameters
nameP | Name of macro to lookup. |
macroDataP | Macro contents returned here. |
dataLenP | On entry: size of macroDataP buffer. On exit: number of bytes in macro data. |
Result
Returns 0 if no error or grfErrNoMacros, grfErrMacroNotFound.
See Also
GrfAddMacro
GrfGetMacroName

Purpose
Look up a macro name by index.
Prototype
Err GrfGetMacroName (UInt16 index, Char *nameP)
Parameters
Result
Returns 0 if no error, or grfErrNoMacros or grfErrMacroNotFound if an error occurs.
See Also
GrfAddMacro, GrfGetMacro
GrfGetNumPoints

Purpose
Return the number of points in the point buffer.
Prototype
Err GrfGetNumPoints (UInt16 *numPtsP)
Parameters
numPtsP | Returned number of points. |
Result
Always returns 0.
See Also
GrfAddPoint
GrfGetPoint

Purpose
Return a point out of the Graffiti point buffer.
Prototype
Err GrfGetPoint (UInt16 index, PointType *pointP)
Parameters
index | Index of the point to get. |
Result
Returns 0 if no error, or grfErrBadParam if an error occurs.
See Also
GrfAddPoint, GrfGetNumPoints
GrfGetState

Purpose
Return the current Graffiti shift state.
Prototype
Err GrfGetState (Boolean *capsLockP, Boolean *numLockP, UInt16 *tempShiftP, Boolean *autoShiftedP)
Parameters
capsLockP | Returns true if caps lock on. |
numLockP | Returns true if num lock on. |
tempShiftP | Current temporary shift. |
autoShiftedP | Returns TRUE if shift not set by the user but by the system, for example, at the beginning of a line. |
Result
Always returns 0.
Compatibility
Palm OS® 2.0 and later has more user-friendly auto shifting. It uses an upper case letter under these conditions:
after an empty field
after a period or other sentence terminator (such as ? or !).
after two spaces
See Also
GrfSetState
GrfInitState

Purpose
Reinitialize the Graffiti dictionary state.
Prototype
Err GrfInitState (void)
Parameters
None.
Result
Always returns 0.
See Also
GrfGetState, GrfSetState
GrfMatch

Purpose
Recognize the current stroke in the Graffiti point buffer and return with the recognized text.
Prototype
Err GrfMatch (UInt16 *flagsP, void *dataPtrP, UInt16 *dataLenP, UInt16 *uncertainLenP, GrfMatchInfoPtr matchInfoP)
Parameters
flagsP | Glyph flags are returned here. |
dataPtrP | Return text is placed here. |
dataLenP | Size of dataPtrP on exit; number of characters returned on exit. |
uncertainLenP | Return number of uncertain characters. |
matchInfoP | Array of grfMaxMatches, or nil. |
Result
Returns 0 if no error, or grfErrNoGlyphTable, grfErrNoDictionary, or grfErrNoMapping if an error occurs.
See Also
GrfAddPoint, GrfFlushPoints
GrfMatchGlyph

Purpose
Recognize the current stroke as a glyph.
Prototype
Err GrfMatchGlyph (GrfMatchInfoPtr matchInfoP, Int16 maxUnCertainty, UInt16 maxMatches)
Parameters
matchInfoP | Pointer to array of matches to fill in. |
maxUnCertainty | Maximum number of errors to tolerate. |
maxMatches | Size of matchInfoP array. |
Result
Returns 0 if no error, or grfErrNoGlyphTable if an error occurs.
See Also
GrfMatch
GrfProcessStroke

Purpose
Translate a stroke to keyboard events using Graffiti.
Prototype
Err GrfProcessStroke (PointType *startPtP, PointType *endPtP, Boolean upShift)
Parameters
startPtP | Start point of stroke. |
endPtP | End point of stroke. |
upShift | Set to true to feed an artificial upshift into the engine. |
Result
Returns 0 if recognized.
Comments
Called by SysHandleEvent when a penUpEvent is detected in the writing area. This routine recognizes the stroke and sends the recognized characters into the key queue. It also flushes the stroke out of the pen queue after recognition.
See Also
SysHandleEvent
GrfSetState

Purpose
Set the current shift state of Graffiti.
Prototype
Err GrfSetState (Boolean capsLock, Boolean numLock, Boolean upperShift)
Parameters
capsLock | Set to true to turn on caps lock. |
numLock | Set to true to turn on num lock. |
upperShift | Set to true to put into upper shift. |
Result
Always returns 0.
See Also
GrfGetState
|