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 Graffiti Manager" of the Palm OS Programmer's Companion, vol. I.
Graffiti Manager Functions
GrfAddMacro Function
Purpose
Add a macro to the macro list.
Declared In
Graffiti.h
Prototype
Err GrfAddMacro ( const Char *nameP, UInt8 *macroDataP, UInt16 dataLen )
Parameters
Returns
Returns 0 if no error; returns grfErrNoMacros, grfErrMacroPtrTooSmall, dmErrNotValidRecord, dmErrWriteOutOfBounds
if an error occurs.
See Also
GrfGetMacro()
, GrfGetMacroName()
, GrfDeleteMacro()
GrfAddPoint Function
Purpose
Add a point to the Graffiti point buffer.
Declared In
Graffiti.h
Prototype
Err GrfAddPoint ( PointType *pt )
Parameters
Returns
Returns 0 if no error; returns grfErrPointBufferFull
if an error occurs.
Compatibility
If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.
See Also
GrfCleanState Function
Purpose
Remove any temporary shifts from the dictionary state.
Declared In
Graffiti.h
Prototype
Err GrfCleanState ( void )
Parameters
Returns
Returns 0 if no error, or grfErrNoDictionary
if an error occurs.
Compatibility
If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.
See Also
GrfDeleteMacro Function
Purpose
Delete a macro from the macro list.
Declared In
Graffiti.h
Prototype
Err GrfDeleteMacro ( UInt16 index )
Parameters
Returns
Returns 0 if no error, or grfErrNoMacros
, grfErrMacroNotFound
if an error occurs.
See Also
GrfFilterPoints Function
Purpose
Filter the points in the Graffiti point buffer.
Declared In
Graffiti.h
Prototype
Err GrfFilterPoints ( void )
Parameters
Returns
Compatibility
If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.
See Also
GrfFindBranch Function
Purpose
Locate a branch in the Graffiti dictionary by flags.
Declared In
Graffiti.h
Prototype
Err GrfFindBranch ( UInt16 flags )
Parameters
Returns
Returns 0 if no error, or grfErrNoDictionary
or grfErrBranchNotFound
if an error occurs.
Compatibility
If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.
See Also
GrfCleanState()
, GrfInitState()
GrfFlushPoints Function
Purpose
Dispose of all points in the Graffiti point buffer.
Declared In
Graffiti.h
Prototype
Err GrfFlushPoints ( void )
Parameters
Returns
Compatibility
If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.
See Also
GrfGetAndExpandMacro Function
Purpose
Look up and expand a macro in the current macros.
Declared In
Graffiti.h
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.
Returns
Returns 0 if no error, or grfErrNoMacros
or grfErrMacroNotFound
if an error occurs.
See Also
GrfGetGlyphMapping Function
Purpose
Look up a glyph in the dictionary and return the text.
Declared In
Graffiti.h
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.
Returns
Returns 0 if no error, or grfErrNoDictionary
or grfErrNoMapping
if an error occurs.
Compatibility
If the Graffiti 2 Feature Set is present, this function is deprecated and always returns grfErrBadParam
.
See Also
GrfGetMacro Function
Purpose
Look up a macro in the current macros.
Declared In
Graffiti.h
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.
Returns
Returns 0 if no error or grfErrNoMacros
, grfErrMacroNotFound
.
See Also
GrfGetMacroName Function
Look up a macro name by index.
Declared In
Graffiti.h
Prototype
Err GrfGetMacroName ( UInt16 index, Char *nameP )
Parameters
Returns
Returns 0 if no error, or grfErrNoMacros
or grfErrMacroNotFound
if an error occurs.
See Also
GrfGetNumPoints Function
Purpose
Return the number of points in the point buffer.
Declared In
Graffiti.h
Prototype
Err GrfGetNumPoints ( UInt16 *numPtsP )
Parameters
Returns
Compatibility
If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.
See Also
GrfGetPoint Function
Purpose
Return a point out of the Graffiti point buffer.
Declared In
Graffiti.h
Prototype
Err GrfGetPoint ( UInt16 index, PointType *pointP )
Parameters
Returns
Returns 0 if no error, or grfErrBadParam
if an error occurs.
Compatibility
If the Graffiti 2 Feature Set is present, this function is deprecated and always returns grfErrBadParam
.
See Also
GrfAddPoint()
, GrfGetNumPoints()
GrfGetState Function
Purpose
Return the current shift state.
Declared In
Graffiti.h
Prototype
Err GrfGetState ( Boolean *capsLockP, Boolean *numLockP, UInt16 *tempShiftP, Boolean *autoShiftedP )
Parameters
-
capsLockP
- Returns
true
if caps lock is on. -
numLockP
- Returns
true
if num lock is on. -
tempShiftP
- Current temporary shift.
-
autoShiftedP
- Returns
true
if shift is not set by the user but by the system, for example, at the beginning of a line.
Returns
Compatibility
Palm OS® 2.0 and later has more user-friendly auto shifting. It uses an upper case letter under these conditions:
If the Graffiti 2 Feature Set is present and the Palm OS version is 4.1.2 or 5.2, the capsLockP
and numLockP
parameters are ignored. In later versions of Palm OS 4 beginning with 4.1.3, and later versions of Palm OS Garnet beginning with 5.2.1, all parameters work normally.
See Also
GrfInitState Function
Purpose
Reinitialize the Graffiti dictionary state.
Declared In
Graffiti.h
Prototype
Err GrfInitState ( void )
Parameters
Returns
Compatibility
If the Graffiti 2 Feature Set is present and the Palm OS version is 5.2, this function has no effect. It simply returns 0. In version 5.3SC, this function was reinstated.
See Also
GrfMatch Function
Purpose
Recognize the current stroke in the Graffiti point buffer and return with the recognized text.
Declared In
Graffiti.h
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
, orNULL
.
Returns
Returns 0 if no error, or grfErrNoGlyphTable
, grfErrNoDictionary
, or grfErrNoMapping
if an error occurs.
Compatibility
If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.
See Also
GrfAddPoint()
, GrfFlushPoints()
GrfMatchGlyph Function
Purpose
Recognize the current stroke as a glyph.
Declared In
Graffiti.h
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.
Returns
Returns 0 if no error, or grfErrNoGlyphTable
if an error occurs.
Compatibility
If the Graffiti 2 Feature Set is present, this function is deprecated and always returns grfErrBadParam
.
See Also
GrfProcessStroke Function
Purpose
Translate a stroke to keyboard events using the Graffiti or Graffiti 2 engine.
Declared In
Graffiti.h
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.
Returns
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.
Compatibility
If the Graffiti 2 Feature Set is present, the stroke is recognized using the Graffiti 2 engine rather than the Graffiti engine.
See Also
GrfSetState Function
Purpose
Declared In
Graffiti.h
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.
Returns
Compatibility
If the Graffiti 2 Feature Set is present and the Palm OS version is 4.1.2 or 5.2, the capsLockP
and numLockP
parameters are ignored. In later versions of Palm OS 4 beginning with 4.1.3, and later versions of Palm OS Garnet beginning with 5.2.1, all parameters work normally.