ConfigHREC

2.0

Allows an application to set or query recognizer-specific values. All calls to ConfigHREC are serviced by the recognizer's ConfigRecognizer function. In version 2.0 of the Pen API, applications must call ConfigHREC rather than ConfigRecognizer.

int ConfigHREC( HREC hrec, UINT uSubFunction, WPARAM wParam, LPARAM lParam )

Parameters
hrec

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

uSubFunction

Recognizer subfunction identifier. See the "Comments" section below.

wParam

Depends on the value of uSubFunction.

lParam

Address of a buffer. The contents of the buffer depend on the value of uSubFunction.

Return Value
If successful, returns 0 or a positive value as described in the list of uSubfunction constants below; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Missing recognizer, invalid parameter, or other error.
HRCR_MEMERR	Insufficient memory.

Comments
The uSubFunction parameter contains one of the following WCR_ values that identifies the requested configuration service:

WCR_CONFIGDIALOG

Instructs the recognizer to open a dialog box to set any recognizer-specific parameters. (This is analogous to DEVMODE in printer drivers, which is called when a user sets up a printer.) Some examples of the kind of settings a recognizer might implement are whether or not to allow cursive input, how much to depend on stroke order, and how rapidly to modify prototypes based on the user's own style.

The lParam parameter points to the name of the user currently selected in the Control Panel application. The wParam parameter is used by the recognizer as the parent window for any dialog boxes it displays. The return value is always TRUE.

WCR_DEFAULT

Returns TRUE if the recognizer is capable of being a default recognizer. A default recognizer must support the standard character set as well as standard gestures.

WCR_GETALCPRIORITY

Returns the current default alphabet priority being used by the recognizer. The lParam parameter points to a variable that specifies the alphabet priority as a bitwise-OR combination of ALC_ values. The wParam parameter is not used. This subfunction is used by the system; applications should instead get alphabet priority by calling GetAlphabetPriorityHRC. The return value is TRUE if successful.

WCR_GETANSISTATE

Returns TRUE if the recognizer can recognize all of the ANSI character set; otherwise, returns FALSE or HRCR_ERROR.

WCR_GETDIRECTION

If successful, returns the current writing direction assumed by the recognizer; otherwise, returns HRCR_ERROR.

WCR_GETHAND

If successful, returns 0 if the user writes with the right hand or nonzero if the user writes with the left hand; otherwise, returns HRCR_ERROR.

WCR_PRIVATE

Values above WCR_PRIVATE have a meaning dependent on the recognizer.

WCR_PWVERSION

Returns the version number of the Pen API for which this recognizer was created. This value is 2 for the current version.

WCR_QUERY

Returns TRUE if the recognizer supports a configuration dialog box.

WCR_QUERYLANGUAGE

The wParam parameter is not used. The lParam parameter points to a null-terminated language string. The return value is TRUE if the recognizer supports the language; otherwise, it is FALSE.

WCR_RECOGNAME

Retrieves an identification string from the recognizer. The lParam parameter is treated as a far pointer to a buffer that is filled with an identification string from the recognizer. The wParam parameter is the size of the buffer to fill. The identification string is a short description of the recognizer that Control Panel presents to the user. A sample string is "US English character set, cursive & print." The return value is always 0.

WCR_SETALCPRIORITY

Sets the current default alphabet priority for the recognizer to the value in lParam. Note that setting a priority for individual characters is not supported for defaults. The wParam parameter is not used. This subfunction is used by the system; applications should set priority explicitly in an HRC with the SetAlphabetPriorityHRC function. The return value is TRUE if successful.

WCR_SETANSISTATE

Sets a flag to enable or disable recognition of the entire ANSI character set. Setting lParam to 1 enables recognition of the entire ANSI set; setting lParam to 0 allows recognition of only English (ASCII) characters. The wParam parameter is not used.

The WCR_SETANSISTATE subfunction determines the default setting when CreateCompatibleHRC creates an HRC. An application can explicitly override the setting for the HRC with the SetInternationalHRC function. The return value is TRUE if successful.

WCR_SETDIRECTION

Sets the current writing direction for the recognizer to the value in lParam, which can be an appropriate combination of the RCD_ values. The wParam parameter is not used. The return value is TRUE if successful.

WCR_SETHAND

Sets the current writing hand preference for the recognizer. The lParam parameter is 0 for a right-handed user or 1 for a left-handed user. The wParam parameter is not used. The return value is TRUE if successful.

WCR_TRAIN

This subfunction returns TRAIN_NONE if the recognizer does not support training. A return value of TRAIN_DEFAULT indicates support for the default trainer, including the capability of resetting its database to the original "factory" setting (see WCR_TRAINSAVE). A return value of TRAIN_CUSTOM indicates that the recognizer also provides its own custom trainer. A return value of TRAIN_BOTH indicates support for both kinds of training.

WCR_TRAINMAX

The recognizer returns the maximum number of SYV_ symbol values that it can train for any given shape.

The recognizer should return 0 if it can train any number of characters. For example, the Microsoft recognizer can train one character for a shape; a cursive recognizer may allow more.

WCR_TRAINSAVE

The trainer calls the ConfigHREC function with the parameters set to (WCR_TRAINSAVE, TRAIN_SAVE, 0) when it is time to save the data-base. This happens when the user closes the trainer. After this call, the recognizer should return TRUE if it can successfully save the database; otherwise, it should return FALSE.

The trainer calls the function with (WCR_TRAINSAVE, TRAIN_REVERT, 0) before it discards any changes made to the database that have not yet been saved to disk (that is, revert to saved). This happens when the user cancels the changes. The recognizer should return TRUE if it is successful.

The trainer can alternatively call ConfigHREC with (WCR_TRAINSAVE, TRAIN_RESET, 0) to reset the database to the original "factory" settings. The recognizer should return TRUE if it is successful.

WCR_TRAINDIRTY

The recognizer returns TRUE if the recognizer needs to save training. The recognizer returns FALSE if no training occurred, if the recognizer does not use a database for training, if the recognizer saves as it works, or if the recognizer cannot revert the training.

The hwnd parameter is a handle to the requesting window. The trainer can use this as the parent window for a dialog box, for example. If there has been a recent recognition, a pointer to it is passed in the lParam parameter, although this may be NULL.

The format for the WCR_TRAINDIRTY subfunction call is:

ConfigHREC( hrec, WCR_TRAINDIRTY, 0, 0 );

WCR_TRAINCUSTOM

If the recognizer returns TRAIN_CUSTOM or TRAIN_BOTH in response to WCR_TRAIN, it will receive a WCR_TRAINCUSTOM message when it is time to display its own training system.

The format for the WCR_TRAINCUSTOM subfunction call is:

ConfigHREC( hrec, WCR_TRAINCUSTOM, hwnd, lprcresult );

WCR_USERCHANGE

Notifies the recognizer of a change in user. The lParam parameter points to a null-terminated string containing the user's name. The wParam parameter specifies the required modification:

A wParam value of CRUC_NOTIFY indicates a new user, the name of whom is in the string that lParam points to.

A wParam value of CRUC_REMOVE indicates that the user identified by lParam should be removed from the recognizer's user list. If the recognizer has saved any files or settings for the user, they should be deleted in response to this notification.

WCR_VERSION

Returns the version number. The low-order byte of the return value specifies the major (version) number. The high-order byte specifies the minor (revision) number.