AlternatesWithConstantPropertyValues Method

AlternatesWithConstantPropertyValues Method

Returns a IInkRecognitionAlternates collection, which are a division of the IInkRecognitionAlternate object on which this method is called.

Declaration

[C++]

HRESULT AlternatesWithConstantPropertyValues (
    [in] BSTR propertyType,
    [out, retval] IInkRecognitionAlternates** RecognitionAlternates
);

[Microsoft® Visual Basic® 6.0]

Public Function AlternatesWithConstantPropertyValues( _
    propertyType As String _
) As IInkRecognitionAlternates

Parameters

propertyType

[in] Specifies a string value that identifies the property. For a list of the properties that can be used, see RecognitionProperty.

For more information about the BSTR data type, see Using the Automation Library.

IInkRecognitionAlternates

[out, retval] Returns a IInkRecognitionAlternates collection which is made up of a division of the alternate on which this method is called. Each IInkRecognitionAlternate object in the collection contains adjacent recognition segments which have the same property value for the propertyType parameter.

Return Value

HRESULT value Description
S_OK Success.
E_POINTER A parameter contained an invalid pointer.
E_INVALIDARG The recognition range is invalid.
E_INK_EXCEPTION An exception occurred while processing.
E_OUTOFMEMORY Cannot allocate memory to complete the operation.

Remarks

Each alternate in the collection contains adjacent recognition segments which have the same property value for the property passed into the method.

For example, you can return alternates that divide the original alternate by:

  • Level of confidence boundaries—strong, intermediate, or poor—in the recognition result.
  • Line boundaries.
  • Segment boundaries.

For a complete list of property types, see RecognitionProperty.

Note: The recognizer determines the segmentation of strokes into the recognition segments. Some recognition segments, such as spaces, may correspond to an empty InkStrokes collection.

Note: The recognizer determines the ordering of the recognition segments. Therefore, adjacent recognition segments may be based on the order in which the ink was drawn or based on location, such as whether it is positioned left-to-right, positioned top-to-bottom, and so on.

The ConfidenceAlternates property is an alternative to the AlternatesWithConstantPropertyValues method, where ConfidenceLevel is the RecognitionProperty that separates the alternates in the returned recognition alternates collection.

The LineAlternates property is an alternative to the AlternatesWithConstantPropertyValues method, where LineNumber is the RecognitionProperty that separates the alternates in the returned recognition alternates collection.

Note: The AlternatesWithConstantPropertyValues method, the LineAlternates property, and the ConfidenceAlternates property of the IInkRecognitionAlternate object function differently than the GetAlternatesFromSelection method of the IInkRecognitionResult object. GetAlternatesFromSelection returns a collection of alternates for the requested segments of the recognition result.

Example

[Visual Basic 6.0]

This Visual Basic 6.0 example calls AlternatesWithConstantPropertyValues with a property type of ConfidenceLevel, defined in the SDK module InkConstants.bas, to display the alternates within the top alternate divided by confidence level boundaries for the recognized ink.

Option Explicit
Dim WithEvents theInkCollector As InkCollector
Dim WithEvents theRecognizerContext As InkRecognizerContext
Dim theStrokes As InkStrokes

Private Sub Form_Load()
    'Initialize the InkCollector
    Set theInkCollector = New InkCollector
    theInkCollector.hWnd = Me.hWnd
    theInkCollector.Enabled = True
    'Create new RecognizerContext
    Dim theRecognizers As New InkRecognizers
    Dim theRecognizer As IInkRecognizer
    Set theRecognizer = theRecognizers.GetDefaultRecognizer
    Set theRecognizerContext = theRecognizer.CreateRecognizerContext
    'Initialize the recognizer's strokes
    'and assign them to the RecognizerContext
    Set theStrokes = theInkCollector.Ink.Strokes
    Set theRecognizerContext.Strokes = theStrokes
End Sub

Private Sub theRecognizerContext_RecognitionWithAlternates( _
ByVal RecognitionResult As MSINKAUTLib.IInkRecognitionResult, _
ByVal CustomData As Variant, _
ByVal RecognitionStatus As MSINKAUTLib.InkRecognitionStatus)
    'Clear the list box
    List1.Clear
    'Get the set of alternates which are divided by
    'confidence level boundaries
    Dim theTopRecognitionAlternate As IInkRecognitionAlternate
    Set theTopRecognitionAlternate = RecognitionResult.TopAlternate
    Dim recoConstAlts As IInkRecognitionAlternates
    Set recoConstAlts = theTopRecognitionAlternate. _
        AlternatesWithConstantPropertyValues(ConfidenceLevel)
    'Update the list box with the alternates
    Dim theRecognitionAlternate As IInkRecognitionAlternate
    For Each theRecognitionAlternate In recoConstAlts
        List1.AddItem (theRecognitionAlternate.String)
    Next
    'Save the recognition results with the strokes
    RecognitionResult.SetResultOnStrokes
End Sub

Private Sub theInkCollector_Stroke( _
ByVal Cursor As MSINKAUTLib.IInkCursor, _
ByVal Stroke As MSINKAUTLib.IInkStrokeDisp, _
Cancel As Boolean)
    'When a new stroke is collected, add it to
    'the RecognizerContext's strokes collection
    theStrokes.Add Stroke
    'Tell the RecognizerContext to recognize
    theRecognizerContext.BackgroundRecognizeWithAlternates
End Sub

Applies To