RC • Microsoft Windows Pen API Programmer's Reference • WinAPI Reference

RC

0 2.0

Defines a recognition context (RC) for applications compatible with version 1.0 of the Pen API. Applications that do not call the superseded functions Recognize or RecognizeData do not use the RC structure. These applications instead use HRC objects, which render RC obsolete.

The RC structure is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

typedef struct {

HREC hrec;

HWND hwnd;

UINT wEventRef;

UINT wRcPreferences;

LONG lRcOptions;

RCYIELDPROC lpfnYield;

BYTE lpUser[cbRcUserMax];

UINT wCountry;

UINT wIntlPreferences;

char lpLanguage[cbRcLanguageMax];

LPDF rglpdf[MAXDICTIONARIES];

UINT wTryDictionary;

CL clErrorLevel;

ALC alc;

ALC alcPriority;

BYTE rgbfAlc[cbRcrgbfAlcMax];

UINT wResultMode;

UINT wTimeOut;

LONG lPcm;

RECT rectBound;

RECT rectExclude;

GUIDE guide;

UINT wRcOrient;

UINT wRcDirect;

int nInkWidth;

COLORREF rgbInk;

DWORD dwAppParam;

DWORD dwDictParam;

DWORD dwRecognizer;

UINT rgwReserved[cwRcReservedMax];

} RC;

Members
hrec

Handle of recognizer to use.

hwnd

Window to which results are sent.

wEventRef

Index into ink buffer.

wRcPreferences

Flags specifying preferences, described in "Comments" section.

lRcOptions

Recognition options, described in "Comments" section.

lpfnYield

Procedure called during processing of the Yield Windows function.

lpUser[cbRcUserMax]

Current writer.

wCountry

Country code.

wIntlPreferences

Flags for international preferences.

lpLanguage[cbRcLanguageMax]

Language strings.

rglpdf[MAXDICTIONARIES]

List of dictionary functions.

wTryDictionary

Maximum enumerations to search.

clErrorLevel

Level where recognizer should reject input.

alc

Enabled ALC_ alphabet codes.

alcPriority

Sets priority of the ALC_ codes.

rgbfAlc[cbRcrgbfAlcMax]

Bit field for enabled characters.

wResultMode

Result return mode specifying when to send (either as soon as possible or when complete). The RRM_ codes are described in "Comments" section.

wTimeOut

Recognition time-out in milliseconds.

lPcm

Bitwise-OR combination of PCM_ flags for ending the recognition session.

rectBound

Bounding rectangle for inking. By default, the rectangle is in screen coordinates.

rectExclude

A pen-down event inside this rectangle terminates recognition.

guide

GUIDE structure that defines guidelines for recognizer.

wRcOrient

Orientation of writing with regard to the tablet.

wRcDirect

Direction of writing.

nInkWidth

Ink width of 1

15 pixels. A value of 0 prevents display of the ink.

rgbInk

Ink color.

dwAppParam

For application use.

dwDictParam

For application use; to be passed on to dictionaries.

dwRecognizer

For application use; to be passed on to recognizer.

rgwReserved[cwRcReservedMax]

Reserved.

Comments
The following paragraphs discuss the RC members, listed in the order in which they appear in the preceding structure.

hrec
The hrec member is the handle of the recognizer to use. This value should be set to the value returned by a previous call to InstallRecognizer, or to RC_WDEFAULT for the default recognizer.

If hrec is NULL, no recognizer is used. WM_RCRESULT messages are generated as with a real recognizer, but the wResultsType member of RCRESULT is set to RCRT_NORECOG, and the hSyv and lpsyv members are set to NULL. (For a list of other values in wResultsType, see the entry for RCRT_ values in Chapter 13, "Pen Application Programming Interface Constants.")

hwnd
The hwnd member specifies the window to send recognition results to. This member cannot be NULL. Also, the mouse capture is set to this window to clear the queue of pending mouse messages that were meant for recognition.

wEventRef
The value for wEventRef indicates which tablet data to begin recognition with. The wEventRef member is returned from the GetMessageExtraInfo function.

InitRC sets this member to RC_WDEFAULT. If Recognize is called during the processing of the WM_LBUTTONDOWN message that initiates the input session, the application need take no other action.

Before an application starts recognition on some other Windows event, it should use GetMessageExtraInfo to save the event reference of the appropriate mouse message and place this value in wEventRef before calling Recognize.

This member is not used on calls to RecognizeData.

wRcPreferences
The wRcPreferences member specifies the user preferences as a combination of RCP_ constants.

lRcOptions
The lRcOptions member specifies various options for recognition. It is a bitwise-OR combination of RCO_ constants.

lpfnYield
The lpfnYield member points to a callback function used by the recognizer before it yields. The application sets this to NULL for no yield processing. Recognition can often take more than a few seconds; therefore, a recognizer should periodically call the yield function to yield control to other Windows tasks. The default yield function is:

BOOL FAR PASCAL StandardYieldFunction()

{

Yield( );

return 1;

}

If Recognize or RecognizeData is called with lpfnYield set to RC_LDEFAULT, then the default yield function is called. If the lpfnYield member is not NULL, the recognizer calls lpfnYield every time before it yields.

lpUser

#define cbRcUserMax 32

BYTE lpUser[cbRcUserMax];

The lpUser member specifies the name of the current writer. The current writer is used to specify any custom prototype sets that might be available to the recognizer. If the lpUser member is NULL, it means that the recognizer should use the standard prototype set

that is, the prototype set as it existed before it was modified (through training, for example).

wCountry
The wCountry member contains the country code. The values for country code are the same as the values used by the International item of the Control Panel for the iCountry member in the [intl] section of the WIN.INI file.

wIntlPreferences
The wIntlPreferences member contains a combination of various RCIP_ flags. Currently, this member can be only 0 or RCIP_ALLANSICHAR. If 0, only characters from the current language or languages are enabled. If wIntlPreferences is RCIP_ALLANSICHAR, the entire ANSI character set is enabled.

lpLanguage

#define cbRcLanguageMax 44

char lpLanguage[cbRcLanguageMax]

The lpLanguage member is a list of language strings. Each string is null-terminated and the list ends with a null string.

The set of values for each language string is the same as the set used by the International item of the Control Panel for the sLanguage member in the [Intl] section of the WIN.INI file. These three-letter codes are documented in the Microsoft Windows Software Development Kit.

A recognizer should implement recognition of the ANSI character set and then use this information during recognition to limit a match to the appropriate subset. The lpLanguage member holds strictly optional information; a recognizer may choose to ignore it. By definition, the character set implied by a language string is the set of characters that can be generated from the country-specific keyboard without using the ALT+numeric keypad combinations. It is still possible to enter ANSI characters outside the given language through the use of the onscreen keyboard and ALT+numeric keypad combinations.

rglpdf

#define MAXDICTIONARIES 16

LPDF rglpdf[MAXDICTIONARIES]

The dictionary path member rglpdf specifies which dictionaries are called by the RC Manager to convert symbol graphs into strings.

If rglpdf[0] is NULL, the NULL dictionary path is used. The NULL dictionary path indicates that the first enumeration from the symbol graph is used as the best enumeration. The array of dictionary functions is null-terminated. During recognition, the dictionary functions are called in the order in which they appear. For more details, see the entry for the DictionarySearch function.

wTryDictionary
The wTryDictionary member specifies the maximum number of enumerations generated from the symbol graph during dictionary processing on the results of recognition. The minimum number allowed is 1 and the maximum is 4096. The default value is 100.

clErrorLevel
Recognition accuracy is defined as the percentage of times the recognizer accurately assigns a symbol to an input. There is no penalty or gain if the recognizer does not attempt a match and returns "unknown." The value can range from 0 to 100.

There are situations in which a higher accuracy rating is preferable despite an increased number of unknown results. For example, in a forms application, the Social Security field must be correctly recognized. If the recognizer is unsure, it can get the application to prompt the user again for the input (or a portion of it). At other times, it is preferable that the recognizer make a guess, no matter how wild, in order to limit the number of unknown results. For example, while taking notes in a meeting, the user may not care whether all of the results are transcribed perfectly.

The clErrorLevel member allows the application to signal its preference to the recognizer. Recognizers should return the SYV_UNKNOWN symbol for any symbol having a confidence level below clErrorLevel.

alc
The alc member is used to define the enabled alphabet for any RC structure with ALC_ constants. Any of the ALC_ constants can be combined together with a bitwise-OR operator to form the desired set of characters.

The actual characters enabled depend on the language. For example, if the user has requested French language support, the letter "è" is included in the lowercase alphabet. In the same way, "£" replaces "$" if ALC_MONETARY is set in British systems. For a list of alphabet values, see the entry for ALC_ values in Chapter 13, "Pen Application Programming Interface Constants."

Setting the RCIP_ALLANSICHAR flag in the wIntlPreferences member of the RC structure enables all characters of the appropriate set regardless of the language setting.

A recognizer that recognizes characters other than ANSI can ignore this member. If you want an application to pass character subset information to private non-ANSI recognizers, you can use the dwRecognizer member.

A recognizer should not return a symbol value outside the specified subset. However, a recognizer does not have to force a match to the subset; it can return SYV_UNKNOWN if a suitable match is not found.

alcPriority
The alcPriority member sets the priority of the ALC_ codes used to enable alphabets. It does this by telling the recognizer in which order to list options in the symbol graph.

The alcPriority member uses the same ALC_ codes used in the alc member. The bits set in alcPriority should be a subset of those set in alc. Bits set in alcPriority that are not also set in the alc member have no effect.

A recognizer can recognize a glyph that belongs to more than one enabled ALC_ subset. For example, a vertical stroke can be the letter "l" in the ALC_LCALPHA subset or the number "1" in the ALC_NUMERIC subset. The alcPriority member specifies that the recognizer should first return those interpretations that are in the subsets indicated in alcPriority. If no interpretations are in any of the alcPriority sets, or no priority members are set, the recognizer returns all possibilities within the enabled sets.

For example, suppose the user writes a symbol that looks like either a "q" or a "9." The generated symbol graph contains {q | 9 }. The alcPriority member determines the exact look of the symbol graph. If alcPriority has the ALC_ALPHA bit set, the recognizer should return { q | 9 } in the symbol graph. If alcPriority has the ALC_NUMERIC bit set, the recognizer should return { 9 | q } in the symbol graph.

Note that alcPriority does not affect the dictionary processing directly.

If ALC_USEBITMAP is set, the rgbfAlc member indicates which characters have priority.

rgbfAlc

#define cbRcrgbfAlcMax 32

BYTE rgbfAlc[cbRcrgbfAlcMax];

The rgbfAlc member is the bit field used for enabled characters. For more details, see the description of ALC_ constants. If ALC_USEBITMAP is set, the 256-bit bit field in rgbfAlc is used to indicate which characters from the ANSI character set are currently enabled. Character 0 is the low bit of the low-order byte in the array. Characters thus indicated are connected by OR operators to any characters enabled using the other ALC_ codes. A "1" set in a bit array indicates that the character is enabled.

As an example, to enable the "$" character, set the fifth bit of byte four like this:

rgbfAlc[4] |= 0x10

A recognizer that recognizes characters other than ANSI can ignore this member. If an application wants to pass character subset information to private non-ANSI recognizers, it can use the dwRecognizer member of the RC structure.

A set of macros, defined in PENWIN.H, simplifies user setting and testing the rgbfAlc bits for an RC structure. The ANSI macros listed in the following table set (bit=1), clear (bit=0), or test (TRUE if bit==1, else FALSE) the appropriate bits in lprc->rgbfAlc corresponding to the index i, which is the ANSI value to use. The lprc is a pointer to the RC structure containing the rgbfAlc[] array.

Macro	Description
SetAlcBitAnsi( lprc, i )	Sets the bit specified by i in rgbfAlc of lprc to 1.
ResetAlcBitAnsi( lprc, i )	Resets the bit specified by i in rgbfAlc of lprc to 0.
IsAlcBitAnsi( lprc, i )	Returns TRUE if the bit specified by i in rgbfAlc of lprc is set.

Only the IsAlcBitAnsi macro returns a value (BOOL). The return values of the other macros are undefined.

Setting bits in rgbfAlc[] also requires combining ALC_USEBITMAP by an OR operator with alc for the bits to have meaning. The bits are used in addition to other alc settings. For example, adding ALC_NUMERIC does not also set the bits in rgbfAlc that correspond to 0 through 9. Thus, to recognize octal numbers (the set 0 to 7), use the following code:

RC rc;

int i;

rc.alc = ALC_USEBITMAP; // Note no ALC_NUMERIC

for (i = (int)'0'; i <= (int)'7'; i++)

SetAlcBitAnsi( &rc, i );

wResultMode
The wResultMode member specifies the timing and granularity of the results messages to be sent back to the specified window. The following times are defined.

Constant	Description
RRM_WORD	The granularity is set at a word boundary. As soon as the recognizer sees a word break, it can send all symbols up to the point of the word break.
RRM_NEWLINE	The granularity is set at a new line. As soon as the recognizer sees a line break, it sends the result to that point.
RRM_COMPLETE	When recognition is completed by one of the methods (for example, time-out or barrel button), the results message is sent just before Recognize returns.
RRM_STROKE	The granularity is set at the stroke level. A result message is sent at each stroke. This is used in the NULL recognizer.
RRM_SYMBOL	The granularity is set at the symbol level. A result message is sent at each symbol. Default dictionary processing is disabled when this value is used.

A recognizer is free to send the messages any time after the requested time (defined in the preceding order), but it cannot send any messages sooner. Because of recognizer constraints, a recognizer may combine intermediate results messages. For example, if an application requests RRM_WORD, the recognizer may choose to return results on a line-by-line basis instead.

Results sent at a word boundary do not have to be sent strictly one word at a time. The requirements are as follows:

The raw data returned must be contiguous, and it must begin with a pen-down and end with a pen-up.
The returned "word" may contain spaces. For example, "fat{space | NULL}cat" would be resolved into two words, "fat cat." This is also necessary if the raw data for successive words overlaps.
The recognizer should not send a word until it knows what follows the word. If the word is followed by a word on the same line, the word should be space-terminated. If the word is followed by text on a new line, the recognizer should append a soft newline symbol. The key point is that the recognizer must make it possible for the application to detect word and line spacing so it can display the recognized text appropriately.
Once a word has been sent, the recognizer cannot change the results because of the late arrival of more strokes.

The rules for returning results with RRM_NEWLINE are similar:

The new line should be included with the symbol graph in the result.
Once a word has been sent, the recognizer cannot change the results because of the late arrival of more strokes.

wTimeOut
The wTimeOut member specifies the time-out threshold. After the time-out threshold has passed, the recognizer stops the recognition process.

Time-out occurs if more than wTimeOut milliseconds elapse between the most recent pen-up and the next pen-down. If time-out occurs, the recognition context is closed. Closing a recognition context means no more data is accepted; the existing data is processed and the results are sent to the application. This value is ignored if lPcm does not enable time-out.

In general, applications should use the value set by the user in the Control Panel. This value can be set by setting this member to RC_WDEFAULT.

The maximum value allowed is 65,534 milliseconds. If wTimeOut is set to 0xFFFF (65,535), the system-level value is used.

lPcmrectBound
rectExclude
These three members of the RC structure set the conditions for ending recognition. The lPcm member sets the flags for ending recognition, expressed as a bitwise-OR combination of PCM_ values.

The two RECT members specify inclusive and exclusive rectangles for inking. The rectangle values are in screen coordinates or, if RCO_TABLETCOORD is set, in tablet coordinates. RCO_TABLETCOORD cannot be used with ProcessWriting.

When RCRESULT is returned, the rectBound and rectExclude values are converted from screen to tablet coordinates and the RCO_TABLETCOORD flag is set.

Only pen events within rectBound are collected as part of the recognition context. If PCM_RECTBOUND is set in lPcm, the first pen-down event outside the rectangle closes the context. Dragging the pen outside the rectangle after starting inside does not close the context; the data is still collected outside the rectangle.

If PCM_RECTEXCLUDE is set in lPcm, any pen-down event within rectExclude closes the context. The event that ends pen collection mode

that is, an event outside the bounding rectangle or inside the exclusion

is entered into Windows as a mouse event. For hit-testing the rectangles, the top and left borders are included, but not the right or bottom borders.

The bounding rectangle set by InitRC is valid only until the window is resized or moved. If the window is moved or resized, the application should specify again the rectBound member in the RC structure.

guide
The guide member is a structure of the GUIDE type. It contains information that specifies the placement of guidelines in the writing area for the recognizer's use.

wRcOrient
The wRcOrient member specifies the orientation of the tablet, expressed as RCOR_ values. For a list of orientation values, see the entry for RCOR_ values in Chapter 13, "Pen Application Programming Interface Constants."

wRcDirect
The wRcDirect member informs the recognizer of the direction of writing, expressed as RCOR_ values. There are both primary and secondary directions. For example, English is written from left to right (primary) and then down the page (secondary). Chinese is often written from the top down (primary) and then right to left across the page (secondary). For a list of direction values, see the entry for RCD_ values in Chapter 13, "Pen Application Programming Interface Constants."

The high byte of the direction indicates primary direction; the low byte, secondary direction. A recognizer can choose to ignore this word and support only the natural direction of the given language. The default value is determined by the recognizer.

Not all recognizers can respond to this member.

nInkWidth
rgbInk
These two members specify the ink width and color to be used during inking. The nInkWidth member is the thickness in pixels of the pen to use during inking. If this value is 0, no ink is drawn. The current maximum value allowed is 15. The default is the ink width set in the global RC.

The rgbInk member is the color to use for inking. If this is not a solid color, it is mapped to the closest solid color. The default is the ink color set in the global RC.

dwAppParam
dwRecognizer
These two members are analogous to the dwDictParam member described below. The dwAppParam value is provided for use by the application and passed to the application by way of the lprc member in the RCRESULT structure.

The dwRecognizer value is passed to the recognizer specified in rc.hrec. Applications can use this to pass information to a private recognizer for functionality not directly supported.

These values are set to 0 by InitRC and should remain 0 if they are not used by the application or recognizer.

dwDictParam
The dwDictParam parameter is set by an application and passed on to the dictionary by the RC Manager. It is intended to provide for dictionary functionality not directly supported. For example, a dictionary can request that the application pass in a pointer to a structure that contains a given sentence. You can use this information to extend the dictionary functionality

to highlight misspelled words, for example.

If it is not used by the application, dwDictParam should be left to the value (0) set by InitRC.

rgwReserved[cwRcReservedMax]
The rgwReserved member is reserved. Applications should not change the values set by InitRC for this member.