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

7    Handwriting Recognition Engine

Input Services

Exploring Palm OS®

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

CharData Struct ^TOP^

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

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

HWRInit()

HWRConfigModeArea Struct ^TOP^

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

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 the chars array, so if the value of uncertain is three and the chars 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 call HWRTimeout().
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) or HWRProcessStroke() (if the user completes the stroke).
reserved
Reserved for future use.

Handwriting Recognition Engine Constants ^TOP^

Ink Hint Constants ^TOP^

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

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 of HWRResult.
#define kMaxHWRModeAreas 4
The maximum number of input modes allowed in HWRConfig.

Handwriting Recognition Engine Functions and Macros ^TOP^

HWRClearInputState Function ^TOP^

Purpose

Clears the handwriting recognition engine's internal state.

Declared In

HWREngine.h

Prototype

status_t HWRClearInputState (
   void
)

Parameters

None.

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

Purpose

Returns the current input mode.

Declared In

HWREngine.h

Prototype

uint16_t HWRGetInputMode (
   void
)

Parameters

None.

Returns

One of the constants described in "Pinlet Input Modes."

See Also

PINGetInputMode(), PinletGetInputModeProcPtr()

HWRInit Function ^TOP^

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

HWRShutdown()

HWRProcessStroke Function ^TOP^

Purpose

Interprets a pen stroke.

Declared In

HWREngine.h

Prototype

status_t HWRProcessStroke (
   const PointType *points,
   uint32_t numPoints,
   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 ^TOP^

Purpose

Sets the input mode.

Declared In

HWREngine.h

Prototype

void HWRSetInputMode (
   uint16_t inputMode
)

Parameters

inputMode
One of the constants described in "Pinlet Input Modes."

Returns

Nothing.

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

Purpose

Displays a dialog that provides user help for the handwriting recognition engine.

Declared In

HWREngine.h

Prototype

void HWRShowReferenceDialog (
   void
)

Parameters

None.

Returns

Nothing.

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

Purpose

Frees the handwriting recognition resources.

Declared In

HWREngine.h

Prototype

status_t HWRShutdown (
   void
)

Parameters

None.

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

HWRInit()

HWRTimeout Function ^TOP^

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"