Graffiti Manager
 

 < Home   < Developers   < Development Support   < Documentation

35 Graffiti Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

35 Graffiti Manager

Graffiti Manager Functions

GrfAddMacro

GrfAddPoint

GrfCleanState

GrfDeleteMacro

GrfFilterPoints

GrfFindBranch

GrfFlushPoints

GrfGetAndExpandMacro

GrfGetGlyphMapping

GrfGetMacro

GrfGetMacroName

GrfGetNumPoints

GrfGetPoint

GrfGetState

GrfInitState

GrfMatch

GrfMatchGlyph

GrfProcessStroke

GrfSetState

       

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

namePName of macro.
macroDataPData of macro.
dataLenSize 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

ptPointer 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

indexIndex 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

flagsFlags 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

namePName of macro to look up.
macroDataPMacro contents returned here.
dataLenPOn 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

glyphIDGlyph ID to look up.
flagsPReturned dictionary flags.
dataPtrPWhere returned text goes.
dataLenPOn entry, size of dataPtrP; on exit, number of bytes returned.
uncertainLenPReturn 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

namePName of macro to lookup.
macroDataPMacro contents returned here.
dataLenPOn 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

indexIndex of macro.
namePName returned here.

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

numPtsPReturned 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

indexIndex of the point to get.
pointPReturned point.

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

capsLockPReturns true if caps lock on.
numLockPReturns true if num lock on.
tempShiftPCurrent temporary shift.
autoShiftedPReturns 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

flagsPGlyph flags are returned here.
dataPtrPReturn text is placed here.
dataLenPSize of dataPtrP on exit; number of characters returned on exit.
uncertainLenPReturn number of uncertain characters.
matchInfoPArray 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

matchInfoPPointer to array of matches to fill in.
maxUnCertaintyMaximum number of errors to tolerate.
maxMatchesSize 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

startPtPStart point of stroke.
endPtPEnd point of stroke.
upShiftSet 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

capsLockSet to true to turn on caps lock.
numLockSet to true to turn on num lock.
upperShiftSet to true to put into upper shift.

Result

Always returns 0.

See Also

GrfGetState