Part II: System Management

38 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 Graffiti Manager" of the Palm OS Programmer's Companion, vol. I.

Graffiti Manager Functions ^TOP^

GrfAddMacro Function ^TOP^

Purpose

Add a macro to the macro list.

Declared In

Graffiti.h

Prototype

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

Parameters

nameP

Name of macro.

macroDataP

Data of macro.

dataLen

Size of macro data in bytes.

Returns

Returns 0 if no error; returns grfErrNoMacros, grfErrMacroPtrTooSmall, dmErrNotValidRecord, dmErrWriteOutOfBounds if an error occurs.

See Also

GrfGetMacro(), GrfGetMacroName(), GrfDeleteMacro()

GrfAddPoint Function ^TOP^

Purpose

Add a point to the Graffiti point buffer.

Declared In

Graffiti.h

Prototype

Err GrfAddPoint (
   PointType *pt
)

Parameters

pt

Pointer to point buffer.

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

GrfFlushPoints()

GrfCleanState Function ^TOP^

Purpose

Remove any temporary shifts from the dictionary state.

Declared In

Graffiti.h

Prototype

Err GrfCleanState (
   void
)

Parameters

None

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

GrfInitState()

GrfDeleteMacro Function ^TOP^

Purpose

Delete a macro from the macro list.

Declared In

Graffiti.h

Prototype

Err GrfDeleteMacro (
   UInt16 index
)

Parameters

index

Index of the macro to delete.

Returns

Returns 0 if no error, or grfErrNoMacros, grfErrMacroNotFound if an error occurs.

See Also

GrfAddMacro()

GrfFilterPoints Function ^TOP^

Purpose

Filter the points in the Graffiti point buffer.

Declared In

Graffiti.h

Prototype

Err GrfFilterPoints (
   void
)

Parameters

None.

Returns

Always returns 0.

Compatibility

If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.

See Also

GrfMatch()

GrfFindBranch Function ^TOP^

Purpose

Locate a branch in the Graffiti dictionary by flags.

Declared In

Graffiti.h

Prototype

Err GrfFindBranch (
   UInt16 flags
)

Parameters

flags

Flags of the branch you're searching for.

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 ^TOP^

Purpose

Dispose of all points in the Graffiti point buffer.

Declared In

Graffiti.h

Prototype

Err GrfFlushPoints (
   void
)

Parameters

None.

Returns

Always returns 0.

Compatibility

If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.

See Also

GrfAddPoint()

GrfGetAndExpandMacro Function ^TOP^

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

GrfAddMacro(), GrfGetMacro()

GrfGetGlyphMapping Function ^TOP^

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

GrfMatch()

GrfGetMacro Function ^TOP^

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

GrfAddMacro()

GrfGetMacroName Function ^TOP^

Look up a macro name by index.

Declared In

Graffiti.h

Prototype

Err GrfGetMacroName (
   UInt16 index,
   Char *nameP
)

Parameters

index

Index of macro.

nameP

Name returned here.

Returns

Returns 0 if no error, or grfErrNoMacros or grfErrMacroNotFound if an error occurs.

See Also

GrfAddMacro(), GrfGetMacro()

GrfGetNumPoints Function ^TOP^

Purpose

Return the number of points in the point buffer.

Declared In

Graffiti.h

Prototype

Err GrfGetNumPoints (
   UInt16 *numPtsP
)

Parameters

numPtsP

Returned number of points.

Returns

Always returns 0.

Compatibility

If the Graffiti 2 Feature Set is present, this function has no effect. It simply returns 0.

See Also

GrfAddPoint()

GrfGetPoint Function ^TOP^

Purpose

Return a point out of the Graffiti point buffer.

Declared In

Graffiti.h

Prototype

Err GrfGetPoint (
   UInt16 index,
   PointType *pointP
)

Parameters

index

Index of the point to get.

pointP

Returned point.

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 ^TOP^

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

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

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

GrfSetState()

GrfInitState Function ^TOP^

Purpose

Reinitialize the Graffiti dictionary state.

Declared In

Graffiti.h

Prototype

Err GrfInitState (
   void
)

Parameters

None.

Returns

Always returns 0.

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

GrfGetState(), GrfSetState()

GrfMatch Function ^TOP^

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, or NULL.

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 ^TOP^

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

GrfMatch()

GrfProcessStroke Function ^TOP^

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

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.

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

SysHandleEvent()

GrfSetState Function ^TOP^

Purpose

Set the current shift state.

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

Always returns 0.

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.

See Also

GrfGetState()