GetAlternatesFromSelection Method
GetAlternatesFromSelection Method |
Returns the alternates collection from a selection within the best result string of the recognition result so that each alternate corresponds to only one segment of ink.
Declaration
[C++]
HRESULT AlternatesFromSelection (
[in, optional, defaultvalue(0)] long selectionStart,
[in, optional, defaultvalue(-1)] long selectionLength,
[in, optional, defaultvalue(10)] long maximumAlternates,
[out, retval] IInkRecognitionAlternates** AlternatesFromSelection
);
[Microsoft® Visual Basic® 6.0]
Public Function AlternatesFromSelection( _
[selectionStart As Long], _
[selectionLength As Long = -1], _
[maximumAlternates As Long = 10] _
) As IInkRecognitionAlternates
Parameters
selectionStart
[in] The start of the text selection from which the collection of alternates is returned. The default value is 0 in the overloaded methods without this parameter.
selectionLength
[in] The length of the text selection from which the collection of alternates is returned. The default value is -1, which specifies the text beginning from selectionStart to the end of the string, in the overloaded methods without this parameter.
maximumAlternates
[in, optional] 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.
Note: The number of alternates increases exponentially for large ranges and for some languages, so applications should specify the number of alternates rather than query for the maximum number of alternates that the recognizer can return.
AlternatesFromSelection
[out, retval] Returns the IInkRecognitionAlternates collection of alternates from a selection within the best result string of the recognition result.
Return Value
| HRESULT value | Description |
|---|---|
| S_OK | Success. |
| E_INVALIDARG | The recognition range is invalid. |
| E_INK_EXCEPTION | An exception occurred while processing. |
| E_POINTER | A parameter contained an invalid pointer. |
| E_OUTOFMEMORY | Cannot allocate memory to complete the operation. |
Remarks
The selection "how are you" is probably broken into three segments (depending on the spacing between segments), one for each word. Call GetAlternatesFromSelection to return the alternates for only one segment of this selection. Note that the selectionStart and selectionLength indices correspond to the character index, not a segment index. So to get the alternates from the word "are", call GetAlternatesFromSelection with the parameters of selectionStart = 4 and selectionLength = 3, since the word "are" starts at the 4th character (beginning at 0) and is 3 characters long.
Note the difference between this GetAlternatesFromSelection method and the AlternatesWithConstantPropertyValues, LineAlternates, and ConfidenceAlternates methods of the IInkRecognitionAlternate object. Although GetAlternatesFromSelection returns a collection of alternates in which each alternate corresponds to only one segment of ink within a selection, AlternatesWithConstantPropertyValues, LineAlternates, and ConfidenceAlternates return the collection of alternates in which the alternates correspond to each segment of ink within a selection.
Note: This method throws an invalid argument exception if the selectionLength is zero.
Example
[Visual Basic 6.0]
This Visual Basic 6.0 example shows how to get up to five alternates for the users selection in a TextBox control (Text1), which has already been filled with the top result from the IInkRecognitionResult. The alternates are stored in the IInkRecognitionAlternates collection theRecognitionAlternates using the GetAlternatesFromSelection method.
Dim theRecognitionAlternates As IInkRecognitionAlternates
If Text1.SelLength <> 0 Then
On Error Resume Next
Set theRecognitionAlternates = _
theRecognitionResult.AlternatesFromSelection( _
Text1.SelStart, Text1.SelLength, 5)
If Err = 0 Then
'Do something with theRecognitionAlternates here.
Else
'Handle exceptions here.
End If
End If