This chapter describes the handwriting recognition engine API. It covers:
Handwriting Recognition Engine Structures and Types
Handwriting Recognition Engine Constants
Handwriting Recognition Engine Functions and Macros
The header file HWREngine.h
declares the API that this chapter describes. For more information on using or implementing the handwriting recognition engine APIs, see Chapter 3, "Customizing the Dynamic Input Area."
Handwriting Recognition Engine Structures and Types
CharData Struct
Purpose
Information about a character. This structure is used as an entry in the chars
array of HWRResult
.
Declared In
HWREngine.h
Prototype
typedef struct { wchar32_t chr; uint32_t flags; } CharData
Fields
-
chr
- A character code. The Graffiti® 2 engine returns characters in the device-specific encoding.
-
flags
- 0 or pinCharFlagVirtual if the character is a virtual character.
HWRConfig Struct
Purpose
Information used to initialize the handwriting recognition engine.
Declared In
HWREngine.h
Prototype
typedef struct { uint16_t hDotsPerInch; uint16_t vDotsPerInch; RectangleType writingBounds; uint32_t numModeAreas; HWRConfigModeArea modeArea[kMaxHWRModeAreas]; } HWRConfig
Fields
-
hDotsPerInch
- The number of horizontal pixels per inch of resolution on the device. You can use
WinGetCoordinateSystem()
to determine this value. -
vDotsPerInch
- The number of vertical pixels per inch of resolution on the device. You can use
WinGetCoordinateSystem()
to determine this value. -
writingBounds
- The bounds of the writing area within the pinlet.
- The size of a window is not known until runtime. Depending on how you've created your pinlet's form, the size of its writing area bounds may change each time the pinlet is opened.
-
numModeAreas
- The number of areas within the
writingBounds
for different input modes. -
modeArea
- An array of
HWRConfigModeArea
structures describing each mode area. A pinlet may provide different areas for different input modes, such as punctuation, numbers, capital letters, accented characters, and so on. - The normal input mode is never given a mode area. For example, if a handwriting recognition engine's normal mode is to return lowercase letters and you've designed a pinlet that has an area for entering numbers on the right and lowercase letters on the left, you would supply only one entry in this array.
- Not all handwriting recognition engines support all input modes, so these areas should be considered suggestions only.
Comments
When you pass points to the engine using HWRProcessStroke()
, use the same coordinate system as you use when you specify the bounds and the dots per inch. No handwriting recognition engine should require a particular coordinate system.
See Also
HWRConfigModeArea Struct
Purpose
Information about a writing mode area. Used for the modeArea
field within the HWRConfig
struct.
Declared In
HWREngine.h
Prototype
typedef struct { uint16_t writingMode; uint16_t reserved; RectangleType modeBounds; } HWRConfigModeArea
Fields
-
writingMode
- One of the constants described in "Pinlet Input Modes."
-
reserved
- Reserved for future use.
-
modeBounds
- The bounds of the mode area.
HWRResult Struct
Purpose
Provides the character result of the pen stroke. Used as a return parameter for HWRProcessStroke()
.
Declared In
HWREngine.h
Prototype
typedef struct { CharData chars[kHWRMaxData]; uint16_t numChars; uint16_t uncertain; uint16_t deleteUncertain; uint16_t inputMode; uint16_t inkHint; Boolean timeout; uint8_t reserved; } HWRResult
Fields
-
chars
- One or more characters that the user drew. See
CharData
. -
numChars
- The number of entries in the
chars
field. -
uncertain
- The number of uncertain characters in the
chars
field. An uncertain character is one that may be the first stroke of a multistroke character. The uncertain characters are always at the end of thechars
array, so if the value of uncertain is three and thechars
array has five characters, the uncertain characters are the last three entries in the array. -
deleteUncertain
- The number of uncertain characters that were previously sent and should be deleted before adding any new characters.
- For example, suppose the K character is a multistroke character that begins with a stroke that could also be the L character. If the user draws the stroke for an L, the engine might return the L and indicate that it is an uncertain character. If the next stroke completes the K character, the engine should return the K and set
deleteUncertain
to 1 to indicate that the pinlet should delete the previous L character. - Engines are not required to return ambiguous characters. Instead, they may hold them and use the
timeout
field to request that a timeout value be set. -
inputMode
- The engine's current input mode. This is one of the constants described in "Pinlet Input Modes." The stroke that was entered may have changed the input mode. If this value changed, the pinlet should change its display of the input mode indicator.
-
inkHint
- One of the Ink Hint Constants. Pinlets that provide live ink (which mirrors the stroke as the user writes it) use this field to determine when to erase the ink.
-
timeout
-
true
if the pinlet should set a timeout and wait for more user input.false
otherwise. If the pinlet sets a timeout and that value is reached, it should callHWRTimeout()
. - There is no guarantee that a timeout is reached if one is requested. If the user switches to a new text field or completes the stroke, the timeout is cancelled and the engine receives either a
HWRClearInputState()
call (when the user switches fields) orHWRProcessStroke()
(if the user completes the stroke). -
reserved
- Reserved for future use.
Handwriting Recognition Engine Constants
Ink Hint Constants
Purpose
Used to set the inkHint
field of a HWRResult
structure.
Declared In
HWREngine.h
Constants
-
#define hwrInkHintNone 0
- Erase the last stroke drawn but preserve any previous strokes. This is the default behavior.
-
#define hwrInkHintEraseAll 1
- All inking should be erased because either a full character was entered or a timeout value was reached.
-
#define hwrInkHintKeepAll 2
- All current inking should remain on the screen.
-
#define hwrInkHintKeepLastOnly 3
- Only the inking for the last stroke should remain on the screen.
Maximum Value Constants
Purpose
Constants used to size the arrays in HWRResult
and HWRConfig
.
Declared In
HWREngine.h
Constants
-
#define kHWRMaxData 32
- The maximum number of bytes allowed in the
chars
field ofHWRResult
. -
#define kMaxHWRModeAreas 4
- The maximum number of input modes allowed in
HWRConfig
.
Handwriting Recognition Engine Functions and Macros
HWRClearInputState Function
Purpose
Clears the handwriting recognition engine's internal state.
Declared In
HWREngine.h
Prototype
status_t HWRClearInputState ( void )
Parameters
Returns
errNone
to indicate success or an error code if a failure occurs.
Comments
Pinlets should call this function when they receive PinletClearStateProcPtr()
. Pinlets receive PinletClearStateProcPtr()
when the user performs an action that indicates that the internal state should be cleared. For example, suppose the user enters the first stroke of a multistroke character and then taps on the next field in the form. The user clearly intends not to complete the character. The engine should respond by clearing the internal state that it keeps to indicate that a character is in progress.
HWRGetInputMode Function
Purpose
Returns the current input mode.
Declared In
HWREngine.h
Prototype
uint16_t HWRGetInputMode ( void )
Parameters
Returns
One of the constants described in "Pinlet Input Modes."
See Also
PINGetInputMode()
, PinletGetInputModeProcPtr()
HWRInit Function
Purpose
Initializes the handwriting recognition engine.
Declared In
HWREngine.h
Prototype
status_t HWRInit (
const HWRConfig *config
)
Parameters
-
→ config
- Information that should be used to initialize the handwriting recognition engine. See
HWRConfig
.
Returns
errNone
upon success or an error code if a failure occurs.
Comments
A pinlet calls this function when it is being launched or at any time before it begins using the engine. It should open any necessary databases and allocate global variables.
See Also
HWRProcessStroke Function
Purpose
Declared In
HWREngine.h
Prototype
status_t HWRProcessStroke ( const PointType*points
, uint32_tnumPoints
, HWRResult*result
)
Parameters
-
→ points
- An array of
PointType
structures giving the coordinates of each area of pen movement. -
→ numPoints
- The number of points in the
points
parameter. -
← result
- An
HWRResult
structure indicating what characters, if any, should be sent to Palm OS®.
Returns
errNone
upon success, hwreErrPointBufferFull
if too many points were specified, or an error if the engine failed to recognize the stroke.
Comments
Pinlets should call this function on a penUpEvent
.
The sending of a pen stroke to this function does not always result in a character being returned. See the description of HWRResult
for more information.
HWRSetInputMode Function
Purpose
Declared In
HWREngine.h
Prototype
void HWRSetInputMode (
uint16_t inputMode
)
Parameters
-
→ inputMode
- One of the constants described in "Pinlet Input Modes."
Returns
Comments
The input mode determines how the engine translates the next set of input from the user. The modes that an engine uses or accepts are up to the engine. Typically, in the normal or default input mode, the engine translates user input into lowercase letters. Translation into any other type of character or symbol requires a different input mode.
Not all input modes apply to all handwriting recognition engines. If the engine does not support the specified input mode, it should choose the closest equivalent that is supported, which could be the default mode.
See Also
PINSetInputMode()
, PinletSetInputModeProcPtr()
HWRShowReferenceDialog Function
Purpose
Displays a dialog that provides user help for the handwriting recognition engine.
Declared In
HWREngine.h
Prototype
void HWRShowReferenceDialog ( void )
Parameters
Returns
Comments
This function must display a dialog of some form. If no help is available, it should display an alert indicating no help is available.
See Also
PINShowReferenceDialog()
, PinletShowReferenceDialogProcPtr()
HWRShutdown Function
Purpose
Frees the handwriting recognition resources.
Declared In
HWREngine.h
Prototype
status_t HWRShutdown ( void )
Parameters
Returns
errNone
upon success or an error code if a failure occurs.
Comments
A pinlet calls this function in response to the appStopEvent
. It should close any open databases and deallocate global variables.
See Also
HWRTimeout Function
Purpose
Specifies that a pinlet's timeout value has been reached.
Declared In
HWREngine.h
Prototype
status_t HWRTimeout (
HWRResult *result
)
Parameters
-
← result
- A
HWRResult
structure indicating what characters, if any, should be sent to Palm OS.
Returns
errNone
upon success or an error if a failure occurs.
Comments
The result
parameter may or may not contain a character when a timeout value is reached.
For example, consider the Graffiti 2 handwriting recognition engine. In this engine, some strokes may be strokes for a single character or they may be the first stroke for a multistroke character. For example, the letter L could be the first stroke for several characters, such as a K or an I.
When this engine receives the stroke for an L in a HWRProcessStroke()
call, it stores that stroke and returns true
in the timeout
field of the HWRResult
structure indicating that the pinlet should set a timeout. If the timeout value is reached, the pinlet calls this function. The engine responds by returning in the result
parameter an HWRResult
structure that contains the letter L.
See Also
"Handling Multistroke Characters"