TrainHREC - Microsoft Windows Pen API Programmer's Reference (penapi.hlp)

Microsoft Windows Pen API
Programmer's Reference

Index Commented Search About

TrainHREC

Passes ink and its symbol interpretation to the recognizer for training.

int TrainHREC( HREC hrec, LPSYV lpsyv, UINT cSyv, HPENDATA hpndt, UINT uConflict )

Parameters
hrec

Module handle of the recognizer library. If this value is NULL, the system default recognizer is used.

lpsyv

Address of an array of symbols to train.

cSyv

Count of symbols in lpsyv. This must be greater than 0.

hpndt

Handle to an HPENDATA object.

uConflict

One of the following TH_ values that specify how to handle training conflicts:

Constant	Description
TH_QUERY	Query the user if the proposed training conflicts with symbols in the database.
TH_FORCE	Perform the training without querying the user, even if there is a conflict with the database.
TH_SUGGEST	Abandon the training if there is any conflict with the database and return an error (HRCR_CONFLICT).

Return Value
Returns HRCR_OK if training is successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_CONFLICT	TH_SUGGEST was specified but there was a conflict with the database. No training was done.
HRCR_INVALIDPNDT	Invalid HPENDATA object.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.

Comments
Typically, an application calls TrainHREC to train a single symbol. In other words, lpsyv points to a single symbol that is followed by an SYV_NULL terminator. However, multiple symbols

for example, those representing the character string "ng"

may also be trainable, depending on the recognizer.

If uConflict is TH_QUERY, the recognizer is free to prompt the user with a dialog box to resolve training conflicts. If it is TH_FORCE, the training is performed regardless of conflicts and the original conflicting data may be lost. TH_SUGGEST trains the recognizer only if there are no conflicts; otherwise, the call fails and returns HRCR_CONFLICT.

If the user picks a meaning for some ink from a list of alternatives, such as in a boxed edit control, the application can elect to train the recognizer with this information. In this case, either TH_FORCE or TH_SUGGEST is a suitable value for uConflict.

Training gestures depends on the recognizer. The Microsoft Handwriting Recognizer (GRECO.DLL) does not support training for gestures.