33 Graffiti Manager

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.

Graffiti Manager Functions

GrfAddMacro

Purpose

Add a macro to the macro list.

Prototype

Err GrfAddMacro (Char* nameP, UInt8* macroDataP, UInt16 dataLen)

Parameters

nameP

Name of macro.

macroDataP

Data of macro.

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

index

Index of macro.

nameP

Name 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

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.

pointP

Returned 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

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 Note

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.

dataLenPSize of dataPtrP on exit; number of characters

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