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

Microsoft Windows Pen API
Programmer's Reference

RCRESULT

0 2.0

Applications that do not call the superseded functions RecognizeData or Recognize do not use the RCRESULT structure. In conforming to version 2.0 of the Pen API, applications instead use HRCRESULT objects, which render RCRESULT obsolete.

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

typedef struct {

SYG syg;

UINT wResultsType;

int cSyv;

LPSYV lpsyv;

HANDLE hSyv;

int nBaseLine;

int nMidLine;

HPENDATA hpendata;

RECT rectBoundInk;

POINT pntEnd;

LPRC lprc;

} RCRESULT;

Members
syg

Symbol graph.

wResultsType

An RCRT_ value.

cSyv

Number of symbol values, not including the NULL terminator.

lpsyv

Null-terminated pointer to the recognizer's best guess.

hSyv

Globally shared handle to the symbol value specified by the lpsyv member.

nBaseLine

Zero or baseline of input writing.

nMidLine

Zero or midline of input writing.

hpendata

Handle to pen data.

rectBoundInk

Bounding rectangle for ink.

pntEnd

Point that terminated recognition.

lprc

Recognition context used.

Comments
When an application calls Recognize, RecognizeData, or ProcessWriting, the WM_RCRESULT message is sent to the appropriate window procedure when the recognizer has a result to return. The wParam parameter of the message contains the reason recognition ended (one of the REC_ codes). It is REC_OK if more results will be sent; otherwise, it is the same value for the last message returned by Recognize or RecognizeData. The lParam parameter is a far pointer to an RCRESULT structure. All of the data in the RCRESULT structure is in tablet coordinates.

The following sections elaborate on the RCRESULT members. All of the members are allocated with GMEM_SHARE so they can be passed between processes.

syg
This member contains the raw results returned by the recognizer. These include the various possible interpretations of the pen input, the mapping of the results to the raw data, and locations of any hot spots if the result is a gesture. The syg.lpsyc member is not valid unless RCP_MAPCHAR was set in the RC structure when Recognize or RecognizeData was called.

wResultsType
This member indicates the type of recognition results, expressed as a bitwise-OR combination of RCRT_ values. The RCRT_ values are not mutually exclusive. Note that the recognizer should never have to set RCRT_GESTURETOKEYS, RCRT_ALREADYPROCESSED, or RCRT_GESTURETRANSLATED. For a list of values, see the entry for RCRT_ values in Chapter 13, "Pen Application Programming Interface Constants."

lpsyv
This member contains the symbols that are recognized. An application should use these values to display the text or gestures recognized. The lpsyv member is the result of any dictionary search on the SYG structure or further postprocessing. It is NULL if the NULL recognizer is used.

hpendata
This member contains the raw data captured during inking.

rectBoundInk
This is the bounding rectangle of the ink drawn during recognition. It is in coordinates of the window that receives the results. If the user attempts to draw ink outside rc.rectbound, the ink will not be displayed. However, rectBoundInk is calculated as though the ink were drawn.

If data is collected outside the bounding rectangle, the rectBound member of PENDATAHEADER reflects this. (Note that rectBound applies only to pen-down points.) This means, however, that a portion of the rectBoundInk rectangle lies outside the rc.rectBound rectangle. The actual ink drawn lies in the intersection of rectBoundInk and the rc.rectBound rectangle. Before calculating the intersection, convert rectBoundInk from tablet to screen coordinates. The bounding rectangle includes the width of the ink drawn.

pntEnd
If recognition ended on a tap outside the bounding rectangle or inside the exclusive rectangle, pntEnd contains the coordinates of those points in display coordinates.

lprc
This is the RC used for recognition. Any default values (RC_WDEFAULT or RC_LDEFAULT) are replaced by the correct default value.