CollectionMode Property

  • Article

CollectionMode Property

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

Declaration

[C++]

[propput] HRESULT put_CollectionMode ([in] InkCollectionMode CollectionMode);
[propget] HRESULT get_CollectionMode ([out, retval] InkCollectionMode*
    CollectionMode);

[Microsoft® Visual Basic® 6.0]

Public Property Get CollectionMode() As InkCollectionMode
Public Property Let CollectionMode( _
    ByVal theCollectionMode As InkCollectionMode)

Property Value

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

The default value is InkOnly, which specifies that only ink is collected.

This property is read/write.

Return Value

HRESULT value Description
S_OK Success.
E_POINTER The CollectionMode parameter is an invalid pointer.
E_INK_EXCEPTION An exception occurred inside the method.
E_INVALIDARG The specified mode is invalid.

Remarks

For a list of the modes that you can use, see the InkCollectionMode enumeration type. However, when using the CollectionMode property on a system that has the Microsoft Windows® XP Tablet PC Edition Software Development Kit (SDK) installed but that doesn't have recognizers installed, the mode cannot be set to GestureOnly or InkAndGesture.

Note: The InkCollector object, the InkOverlay object, or 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.

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 ink collector does not fire the following stroke and packet related events: the CursorDown, Stroke, NewPackets, and NewInAirPackets events.
  • Cursor events fire.
  • Ink is always deleted.

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. To cancel the gesture, set the Cancel parameter to TRUE. Canceling the gesture forces the ink collector to collect the ink.

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

Unwanted behavior might occur when CollectionMode is set to InkAndGesture and an object's/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 ink disappears, even if the gesture is not the top alternate. To prevent the ink from disappearing and cancel collection of the gesture, set the Cancel parameter to TRUE if the event is one that you have no interest in.

When CollectionMode 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 InkAndGesture mode. To prevent the collection of ink while in 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.

Example

[Visual Basic 6.0]

This Visual Basic 6.0 example displays application and system gesture event information in a multiline text edit control, Text1, on the main form window.

Option Explicit
Dim WithEvents theInkCollector As InkCollector

Private Sub Form_Load()
    Set theInkCollector = New InkCollector
    theInkCollector.hWnd = Me.hWnd
    'Set the ink collection mode to collect ink and gestures,
    'and turn off all application gestures except the chevrons.
    theInkCollector.CollectionMode = ICM_InkAndGesture
    theInkCollector.SetGestureStatus IAG_AllGestures, False
    theInkCollector.SetGestureStatus IAG_ChevronUp, True
    theInkCollector.SetGestureStatus IAG_ChevronDown, True
    theInkCollector.SetGestureStatus IAG_ChevronLeft, True
    theInkCollector.SetGestureStatus IAG_ChevronRight, True
    theInkCollector.Enabled = True
    theInkCollector.SetEventInterest ICEI_SystemGesture, True
End Sub

Private Sub theInkCollector_Gesture( _
ByVal Cursor As MSINKAUTLib.IInkCursor, _
ByVal Strokes As MSINKAUTLib.InkStrokes, _
ByVal Gestures As Variant, _
Cancel As Boolean)
    Dim theGesture As Variant
    Dim X As Long
    Dim Y As Long
    Text1.Text = ""
    For Each theGesture In Gestures
        theGesture.GetHotPoint X, Y
        Text1.Text = Text1.Text & "Gesture " & _
        AppGestureName(theGesture.Id) & _
        " at (" & X & "," & Y & ") confidence: " & _
        ConfidenceName(theGesture.Confidence) & vbCrLf
    Next
End Sub

Private Sub theInkCollector_SystemGesture( _
ByVal Cursor As MSINKAUTLib.IInkCursor, _
ByVal Id As MSINKAUTLib.InkSystemGesture, _
ByVal X As Long, ByVal Y As Long, _
ByVal Modifier As Long, _
ByVal Character As String, _
ByVal CursorMode As Long)
    Text1.Text = "SystemGesture " & _
    SystemGestureName(Id) & " (x:" & X & ",y:" & Y & ")"
End Sub

Private Function SystemGestureName(ByVal Id As InkSystemGesture) As String
    Select Case Id
        Case ISG_DoubleTap
            SystemGestureName = "ISG_DoubleTap"
        Case ISG_Drag
            SystemGestureName = "ISG_Drag"
        Case ISG_HoldEnter
            SystemGestureName = "ISG_HoldEnter"
        Case ISG_HoldLeave
            SystemGestureName = "ISG_HoldLeave"
        Case ISG_HoverEnter
            SystemGestureName = "ISG_HoverEnter"
        Case ISG_HoverLeave
            SystemGestureName = "ISG_HoverLeave"
        Case ISG_RightDrag
            SystemGestureName = "ISG_RightDrag"
        Case ISG_RightTap
            SystemGestureName = "ISG_RightTap"
        Case ISG_Tap
            SystemGestureName = "ISG_Tap"
        Case Else
            SystemGestureName = "SystemGesture(" & Id & ")"
    End Select
End Function

Private Function AppGestureName(ByVal Id As InkApplicationGesture) _
As String
    Select Case Id
        Case IAG_AllGestures
            AppGestureName = "IAG_AllGestures"
        Case IAG_NoGesture
            AppGestureName = "IAG_NoGesture"
        Case IAG_ChevronUp
            AppGestureName = "IAG_ChevronUp"
        Case IAG_ChevronDown
            AppGestureName = "IAG_ChevronDown"
        Case IAG_ChevronLeft
            AppGestureName = "IAG_ChevronLeft"
        Case IAG_ChevronRight
            AppGestureName = "IAG_ChevronRight"
        Case Else
            AppGestureName = "AppGesture(" & Id & ")"
    End Select
End Function

Private Function ConfidenceName(ByVal Id As InkRecognitionConfidence) _
As String
    Select Case Id
        Case IRC_Strong
            ConfidenceName = "IRC_Strong"
        Case IRC_Intermediate
            ConfidenceName = "IRC_Intermediate"
        Case IRC_Poor
            ConfidenceName = "IRC_Poor"
        Case Else
            ConfidenceName = "Confidence(" & Id & ")"
    End Select
End Function

Applies To