Share via

RecognitionResult.GetAlternatesFromSelection Method

  • Article

RecognitionResult.GetAlternatesFromSelection Method

Returns the RecognitionAlternates collection from a selection within the best result string of the RecognitionResult object, so that each RecognitionAlternate object in the collection corresponds to only one segment of ink.

Definition

Visual Basic .NET Public Function GetAlternatesFromSelection( _
ByVal selectionStart As Integer, _
ByVal selectionLength As Integer, _
ByVal maximumAlternates As Integer _
) As RecognitionAlternates
C# public RecognitionAlternates GetAlternatesFromSelection(
int selectionStart,
int selectionLength,
int maximumAlternates
);
Managed C++ public: RecognitionAlternates* GetAlternatesFromSelection(
int *selectionStart,
int *selectionLength,
int *maximumAlternates
);

Parameters

selectionStart System.Int32. The start of the text selection from which the RecognitionAlternates collection is returned. The default value is 0 (zero).
selectionLength System.Int32. The length of the text selection from which the RecognitionAlternates collection is returned. The default value is –1, which specifies the text beginning from the start of the selection to the end of the string.
maximumAlternates System.Int32. The maximum number of alternates to return. The default value is 10. Recognizers that cannot compute the number of alternates, because of degree of difficulty or length of time, return an arbitrary number of alternates.

Return Value

Microsoft.Ink.RecognitionAlternates. Returns the RecognitionAlternates collection from a selection within the best result string of the RecognitionResult object, so that each RecognitionAlternate object in the collection corresponds to only one segment of ink.

Remarks

Note: The number of alternates increases exponentially for large ranges and for some languages. Applications should specify the number of alternates rather than query for the maximum number of alternates that the recognizer can return.

A recognizer is likely to divide "how are you" into three segments—depending on the spacing between segments—one for each word. Call the GetAlternatesFromSelection method to return the alternates for only one segment of this selection.

Note: The selectionStart and selectionLength parameters correspond to character indices, not segment indices. To get the alternates from the word "are" in "how are you", for example, call the GetAlternatesFromSelection method with the selectionStart parameter set to 4 and the selectionLength parameter set to 3, because the word "are" starts at the fourth character (zero-based) and is three characters long.

Note the difference between the GetAlternatesFromSelection method and the AlternatesWithConstantPropertyValues, LineAlternates, and ConfidenceAlternates methods of the RecognitionAlternate object. Although the GetAlternatesFromSelection method returns a RecognitionAlternates collection in which each RecognitionAlternate object corresponds to only one segment of ink within a selection, the AlternatesWithConstantPropertyValues, LineAlternates, and ConfidenceAlternates methods return the RecognitionAlternates collection in which the RecognitionAlternate objects correspond to each segment of ink within a selection.

Note: If the selectionLength parameter is set to zero, this method throws an invalid argument exception.

Examples

[C#]

This C# example returns up to five RecognitionAlternate objects for the user selection in a TextBox Leave Site control, theTextBox, which has already been filled with the top result from the RecognitionResult object. The alternates are stored in the RecognitionAlternates collection, theRecognitionAlternates, by using the GetAlternatesFromSelection method. This is a useful way to enable a user to select text that has been recognized and search through the alternates for that text in order to insert a correction.

using Microsoft.Ink;
// . . .
try
{
    if (theTextBox.SelectionLength != 0)
    {
        RecognitionAlternates theRecognitionAlternates =
            theRecognitionResult.GetAlternatesFromSelection(
                theTextBox.SelectionStart, theTextBox.SelectionLength, 5);
        // Do something with theRecognitionAlternates here.
    }
}
catch
{
    // handle exceptions here.
}

[Visual Basic .NET]

This Microsoft® Visual Basic® .NET example returns up to five RecognitionAlternate objects for the user selection in a TextBox Leave Site control, theTextBox, which has already been filled with the top result from the RecognitionResult object. The alternates are stored in the RecognitionAlternates collection, theRecognitionAlternates, by using the GetAlternatesFromSelection method. This is a useful way to enable a user to select text that has been recognized and search through the alternates for that text in order to insert a correction.

Imports Microsoft.Ink
' . . .
Try
    If theTextBox.SelectionLength != 0 Then
        Dim theRecognitionAlternates As RecognitionAlternates
        theRecognitionAlternates = _
            theRecognitionResult.GetAlternatesFromSelection( _
                theTextBox.SelectionStart, _
                theTextBox.SelectionLength, 5)
        'Do something with theRecognitionAlternates here.
    End If
Catch
    'Handle exceptions here.
End Try

See Also