RC
- 0 2.0
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.
|
| 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.
|
- 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 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.
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 exclusionis 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.
See Also
GUIDE, PCMINFO
ALC_, RCRT_, PCM_, RCD_, RCOR_
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers - More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples