RecognizerContext.BackgroundRecognize Method (Object)

Article
10/07/2012

Causes the Recognizer object to recognize the associated Strokes collection and raise a Recognition event, with associated application data, when recognition is complete.

Namespace: Microsoft.Ink
Assembly: Microsoft.Ink (in Microsoft.Ink.dll)

Syntax

'Declaration
Public Sub BackgroundRecognize ( _
    customData As Object _
)
'Usage
Dim instance As RecognizerContext 
Dim customData As Object

instance.BackgroundRecognize(customData)

public void BackgroundRecognize(
    Object customData
)

public:
void BackgroundRecognize(
    Object^ customData
)

public function BackgroundRecognize(
    customData : Object
)

Parameters

customData
Type: System.Object

Any application-defined data that is available to the application in the Recognition event. The default value is null (Nothing in Microsoft® Visual Basic® .NET).

Remarks

This method specifies that ink recognition is performed asynchronously. To recognize ink synchronously, call the RecognizerContext.Recognize method.

This method recognizes only the best result string. This method does not create RecognitionAlternate objects. To perform recognition that creates a list of available alternates, call the BackgroundRecognizeWithAlternates method.

The Recognition event is not raised if the recognizer does not recognize anything.

Examples

In this example, each stroke made in an InkOverlay object is automatically recognized and the recognition result displayed.

When the Stroke event fires (in response to the user completing a stroke), the newly created stroke is added to the Strokes collection of the RecognizerContext object, and the BackgroundRecognize method is called, passing the current time to the customData parameter.

Private Sub mInkOverlay_Stroke4(ByVal sender As Object, ByVal e As InkCollectorStrokeEventArgs)
    ' in case background recognition is still occurring, stop it
    mRecognizerContext.StopBackgroundRecognition()
    ' add the stroke, and start recognition
    mRecognizerContext.Strokes.Add(e.Stroke)
    mRecognizerContext.BackgroundRecognize(DateTime.Now)
End Sub

private void mInkOverlay_Stroke4(object sender, InkCollectorStrokeEventArgs e)
{
    // in case background recognition is still occurring, stop it
    mRecognizerContext.StopBackgroundRecognition();
    // add the stroke, and start recognition, passing current time
    mRecognizerContext.Strokes.Add(e.Stroke);
    mRecognizerContext.BackgroundRecognize(DateTime.Now);
}

When background recognition is complete, the Recognition event fires. During handling of this event, the results of the recognition are placed in a list box. In addition, the time that recognition began is retrieved from the CustomData property of the RecognizerContextRecognitionEventArgs object, and used to calculate the total elapsed time required for recognition.

' event fires when recognition results (without alternates) are ready 
Private Sub RecognizerContext_Recognition(ByVal sender As Object, _
            ByVal e As RecognizerContextRecognitionEventArgs)
    ' when updating a control, must use Invoke() since controls are 
    ' not thread safe and recognition occurs on a different thread 
    If Me.InvokeRequired Then 
        ' recursively call this method via Invoke() 
        Me.Invoke( _
            New RecognizerContextRecognitionEventHandler(AddressOf RecognizerContext_Recognition), _
            New Object() {sender, e} _
        )
        Return 
    End If 
    If RecognitionStatus.NoError = e.RecognitionStatus Then
        listBoxRecognitionResults.Items.Add(e.Text)
        ' get the custom data and calculate elapsed time 
        Dim startTime As DateTime = DirectCast(e.CustomData, DateTime)
        Dim endTime As DateTime = DateTime.Now
        Dim span As TimeSpan = New TimeSpan(endTime.Ticks - startTime.Ticks)
        ' display the number of seconds for this recognition to finish
        listBoxRecognitionResults.Items.Add(span.TotalSeconds.ToString())
    End If 
End Sub

// event fires when recognition results (without alternates) are ready 
private void RecognizerContext_Recognition(object sender, RecognizerContextRecognitionEventArgs e)
{
    // when updating a control, must use Invoke() since controls are 
    // not thread safe and recognition occurs on a different thread 
    if (this.InvokeRequired)
    {
        // recursively call this method via Invoke() 
        this.Invoke(
            new RecognizerContextRecognitionEventHandler(RecognizerContext_Recognition),
            new object[] { sender, e }
            );
        return;
    }

    if (RecognitionStatus.NoError == e.RecognitionStatus)
    {
        listBoxRecognitionResults.Items.Add(e.Text);
        // get the custom data and calculate elapsed time
        DateTime startTime = (DateTime)e.CustomData;
        DateTime endTime = DateTime.Now;
        TimeSpan span = new TimeSpan(endTime.Ticks - startTime.Ticks);
        // display the number of seconds for this recognition to finish
        listBoxRecognitionResults.Items.Add(span.TotalSeconds.ToString());
    }
}

Platforms

Windows 7, Windows Vista, Windows Server 2008 R2, Windows Server 2008

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.0

Share via