Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

38    Graffiti Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 (
   constChar*nameP,
   UInt8*macroDataP,
   UInt16dataLen
)

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 (
   UInt16index
)

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 (
   UInt16flags
)

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 (
   UInt16glyphID,
   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 (
   UInt16index,
   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 (
   UInt16index,
   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,
   GrfMatchInfoPtrmatchInfoP
)

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 (
   GrfMatchInfoPtrmatchInfoP,
   Int16maxUnCertainty,
   UInt16maxMatches
)

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 Graffiti2 engine.

Declared In

Graffiti.h

Prototype

Err GrfProcessStroke (
   PointType*startPtP,
   PointType*endPtP,
   BooleanupShift
)

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 (
   BooleancapsLock,
   BooleannumLock,
   BooleanupperShift
)

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()