Share via


Guide Property

Guide Property

Gets or sets the InkRecognizerGuide to use for ink input.

Declaration

[C++]

[propputref] HRESULT putref_Guide ([in] InkRecognizerGuide* Guide);
[propget] HRESULT get_Guide ([out, retval] InkRecognizerGuide** Guide);

[Microsoft® Visual Basic® 6.0]

Public Property Get Guide() As InkRecognizerGuide
Public Property Let Guide(ByVal theGuide As InkRecognizerGuide)

Property Value

InkRecognizerGuide Gets or sets the InkRecognizerGuide that is used for ink recognition.

This property is read/write.

Return Value

HRESULT value Description
S_OK Success.
E_POINTER The context is invalid or the parameter is an invalid pointer.
TPC_E_OUT_OF_ORDER_CALL This property cannot be assigned after strokes have been added to the Strokes property.
E_OUTOFMEMORY Cannot allocate memory to complete the operation.
E_INK_EXCEPTION An exception occurred inside method.
E_FAIL An unspecified error occurred.
E_INVALIDARG The specified mode is invalid.
E_UNEXPECTED Unexpected parameter or property type.

Remarks

Setting the Guide property succeeds only if the InkStrokes collection is NULL (Nothing in Visual Basic 6.0). You must set the Guide property before you attach the InkStrokes collection to the InkRecognizerContext or you must set the InkStrokes collection to NULL and then set the Guide (and possible reattach the InkStrokes collection).

The InkRecognizerCapabilities enumeration contains the IRC_FreeInput, IRC_LinedInput, and IRC_BoxedInput flags. These flags specify the capabilities of a recognizer, but because they are read only, there is no way to set any of these directly on a IInkRecognizer or InkRecognizerContext object. The only way to put a recognizer into a specific mode is to set the guide using the Guide property. If you do not set the Guide property, the recognizer defaults to FreeInput mode (if the recognizer is capable of this). Another way to set the recognizer into FreeInput mode is to set the Guide property to a InkRecognizerGuide object that has its Columns property set to zero and its Rows property set to zero.

If you set the Guide property to a InkRecognizerGuide object that has its Columns property set to zero and its Rows property set to 1 or more, the recognizer is in IRC_LinedInput mode (if the recognizer is capable of this). The recognizer uses the Rows property to control the number of lines.

If you set the Guide property to a InkRecognizerGuide object that has its Rows property set to zero and its Columns property set to 1 or more, the recognizer is in IRC_LinedInput mode (if the recognizer is capable of this) for vertical writing. The recognizer uses the Columns property to control the number of vertical lines. If the recognizer is capable of this, the IInkRecognizer object's Capabilities property returns either IRC_DownAndLeft or IRC_DownAndRight, or both.

If you set the Guide property to a InkRecognizerGuide object that has its Columns property set to 1 or more and its Rows property set to 1 or more, the recognizer is in IRC_BoxedInput mode (if the recognizer is capable of this).

If you set the mode to one that is not available from this recognizer, an error is returned.

For information about how to query which capabilities, or modes, are available from a specific recognizer, see the Capabilities property of the IInkRecognizer object. In general, Latin language recognizers support free input and horizontal lined input, East Asian language recognizers support free input and boxed input, and the gesture recognizer only supports free input.

Example

[Visual Basic 6.0]

This Visual Basic 6.0 sets the InkRecognizerGuide that is used for recognition to some programmer-specified values.

Dim theRecognizerGuide As New InkRecognizerGuide

theRecognizerGuide.Rows = theRows
theRecognizerGuide.Columns = theColumns
theRecognizerGuide.Midline = theMidline
theRecognizerGuide.WritingBox = rectGuide
theRecognizerGuide.DrawnBox = rectDrawn

Set theRecognizerContext.Guide = theRecognizerGuide

Applies To