InkPicture.CollectionMode Property

  • Article

InkPicture.CollectionMode Property

Gets or sets the collection mode that determines whether ink, gestures, or both are recognized as the user writes.

Definition

Visual Basic .NET Public Property CollectionMode As CollectionMode
C# public CollectionMode CollectionMode { get; set; }
Managed C++ public: __property CollectionMode* get_CollectionMode();
public: __property void set_CollectionMode(CollectionMode*);

Property Value

Microsoft.Ink.CollectionMode. The collection mode that determines whether ink, gestures, or both are recognized as the user writes.

This property is read/write. This property has no default value.

InkOnly0

Collects only ink, creating a stroke.

The InkCollector.Gesture, InkOverlay.Gesture, or InkPicture.Gesture event interest is set to false, meaning that gestures are not collected (all other event interests remain as they were).
GestureOnly1

Collects only gestures and does not create a stroke. Gestures can be either single- or multi-stroke. Multi-stroke gestures are accepted if the strokes are made within the time set by the built-in timer of the recognizer.

All stroke-related and packet-related events do not fire from the InkCollector object, InkOverlay object, or InkPicture control. Cursor events fire, and ink is always deleted.

The InkCollector.Gesture, InkOverlay.Gesture, or InkPicture.Gesture event interest is set to true, meaning that gestures are collected (all other event interests remain as they were).
InkAndGesture2

Accepts only single-stroke gestures. The InkCollector.Gesture, InkOverlay.Gesture, or InkPicture.Gesture event fires first, allowing you to cancel or accept the event. The default is to accept the event, except when NoGesture is the primary gesture. If the gesture is accepted, the ink is deleted. If the gesture is canceled, the stroke is not deleted and a InkCollector.Stroke, InkOverlay.Stroke, or InkPicture.Stroke event fires.

The InkCollector.Gesture, InkOverlay.Gesture, or InkPicture.Gesture event interest is set to true, meaning that gestures are collected (all other event interests remain as they were).

Exceptions

COMException Leave Site:
ObjectDisposedException Leave Site:

Remarks

Note: The InkPicture control generates an error if you try to change the CollectionMode property while ink is being collected. To avoid this conflict, check the CollectingInk property before changing the CollectionMode property.

For a list of the modes that you can use, see the CollectionMode enumeration. However, when using the CollectionMode property on a system that has the Tablet PC SDK installed but that doesn't have recognizers installed, the mode cannot be set to GestureOnly or InkAndGesture.

The following behaviors occur for each of the CollectionMode values.

InkOnly mode

  • Only ink is collected; gestures are not.
  • The Gesture event interest is set to false (all other event interests remain as they were).

GestureOnly mode

  • Only gestures are collected; ink is not. The strokes are deleted after they are sent to the gesture recognizer.
  • The Gesture event interest is set to true (all other event interests remain as they were).
  • The InkPicture control does not fire the following stroke and packet related events: the CursorDown, Stroke, NewPackets, and NewInAirPackets events.
  • Cursor events fire.

InkAndGesture mode

  • Both ink and gestures are collected.
  • Only single-stroke gestures are recognized.
  • The Gesture event interest is set to true (all other event interests remain as they were).
  • The Gesture event fires first, allowing you to accept or cancel the gesture when the InkPicture control's OnGesture event handler is invoked. To cancel the geture, set the inherited Cancel Leave Site property of the InkCollectorGestureEventArgs object to true. Canceling the gesture forces the InkPicture control to collect the ink.

Changing the collection mode does not alter the status of individual gestures.

Unwanted behavior may occur when the CollectionMode property is set to InkAndGesture and an InkPicture control's interest in a known gesture is set (by calling the SetGestureStatus method). If you draw ink that looks something like the known gesture and the known gesture is in the recognizer's list of alternates, the Gesture event fires and the ink disappears, even if the gesture is not the top alternate. To prevent the ink from disappearing when you want to collect the ink instead of the gesture, cancel collection of the gesture and set the inherited Cancel Leave Site property of the InkCollectorGestureEventArgs object to true.

When the CollectionMode property is set to GestureOnly, the timeout between when a user adds a gesture and when the Gesture event occurs is a fixed value that cannot be altered programmatically. Gesture recognition is faster in the InkAndGesture mode. To collect gestures only and prevent the collection of ink while in the InkAndGesture mode, you can:

  1. Set the CollectionMode property to InkAndGesture.
  2. In the Stroke event, delete the stroke.
  3. In the Gesture event, process the gesture.
  4. Set DynamicRendering to false to prevent the flow of ink while gesturing.

Examples

[C#]

This C# example displays gesture event information in the status bar of the main form window. Starting with a generic generated application, add a StatusBar Leave Site control, statusBar1, and an InkPicture control, theInkPicture, to the main form and the following code.

//...
using Microsoft.Ink;

namespace CollectionMode_CS
{
    public class CollectionModeForm : System.Windows.Forms.Form
    {
        // ... The generated code will be here.
        //Add this code following the implementation of Main():

        private void CollectionModeForm_Load(object sender, System.EventArgs e)
        {
            // Initialize the InkPicture object.
            theInkPicture.CollectionMode = CollectionMode.InkAndGesture;
            ClearAppGestures();

            // Turn on interest in the ChevronDown application gesture.
            theInkPicture.SetGestureStatus(ApplicationGesture.ChevronDown, true);
            theInkPicture.SetGestureStatus(ApplicationGesture.ChevronUp, true);
            theInkPicture.Gesture += new InkCollectorGestureEventHandler(theInkPicture_Gesture);
            theInkPicture.SystemGesture +=
            new InkCollectorSystemGestureEventHandler(theInkPicture_SystemGesture);
            theInkPicture.Enabled = true;
        }

        private void theInkPicture_Gesture(object sender,
            Microsoft.Ink.InkCollectorGestureEventArgs e)
        {
            Gesture theGesture = e.Gestures[0];
            statusBar1.Text = theGesture.Id.ToString();
            // Cancelling the gesture will cause the ink to remain.
            if (theGesture.Id == ApplicationGesture.ChevronDown)
            e.Cancel = true;
        }

        private void theInkPicture_SystemGesture(object sender,
            Microsoft.Ink.InkCollectorSystemGestureEventArgs e)
        {
            SystemGesture theGesture = e.Id;
            statusBar1.Text = "System: " + theGesture.ToString() +
            " " + e.Point.ToString();
        }

        // Set all of the ApplicationGestures' status
        // to false on the InkCollector object.
        private void ClearAppGestures()
        {
        ApplicationGesture test = ApplicationGesture.NoGesture;
            Array theGestures = System.Enum.GetValues(test.GetType());
            foreach (ApplicationGesture theGesture in theGestures)
            {
               theInkPicture.SetGestureStatus(theGesture, false);
            }
        }
    }
}

[Visual Basic .NET]

This Microsoft® Visual Basic® .NET example displays gesture event information in the status bar of the main form window. Starting with a generic generated application, add a StatusBar Leave Site control, statusBar1, and an InkPicture control, theInkPicture, to the main form and the following code.

Imports Microsoft.Ink

Public Class CollectionModeForm
    Inherits System.Windows.Forms.Form

#Region " Windows Form Designer generated code "
'This contains the standard generated form code, with
'the addition of a Status Bar, StatusBar1, and an InkPicture control, the InkPicture.
#End Region

    Private Sub CollectionModeForm_Load(ByVal sender As System.Object, _
        ByVal e As System.EventArgs) Handles MyBase.Load
        'Set the InkPicture to collect both ink and gestures.
        theInkPicture.CollectionMode = CollectionMode.InkAndGesture
        'Clear interest in all of the application gestures
        ClearAppGestures()
        'Set our interest in only two gestures.
        theInkPicture.SetGestureStatus(ApplicationGesture.ChevronDown, True)
        theInkPicture.SetGestureStatus(ApplicationGesture.ChevronUp, True)
        'Add the handlers for application and system gestures.
        AddHandler theInkPicture.Gesture, AddressOf theInkPicture_Gesture
        AddHandler theInkPicture.SystemGesture, AddressOf theInkPicture_SystemGesture
        theInkPicture.Enabled = True
    End Sub

    Private Sub theInkPicture_Gesture(ByVal sender As Object, _
        ByVal e As InkCollectorGestureEventArgs)
        Dim theGesture As Gesture = e.Gestures(0)
        StatusBar1.Text = theGesture.Id.ToString()
        'Cancelling the gesture will cause the ink to remain.
        If theGesture.Id = ApplicationGesture.ChevronDown Then
            e.Cancel = True
        End If
    End Sub

    Private Sub theInkPicture_SystemGesture( _
        ByVal sender As Object, _
        ByVal e As InkCollectorSystemGestureEventArgs)
        StatusBar1.Text = "System: " + e.Id.ToString() + "   " + e.Point.ToString()
    End Sub

    ' Set all of the ApplicationGestures' status
    ' to false on the InkPicture object.
    Private Sub ClearAppGestures()
        Dim test As ApplicationGesture = ApplicationGesture.NoGesture
        Dim theGestures As Array = System.Enum.GetValues(test.GetType())
        Dim theGesture As ApplicationGesture
        For Each theGesture In theGestures
            theInkPicture.SetGestureStatus(theGesture, False)
        Next
    End Sub
End Class

See Also