Edit

Share via

IInkOverlay::put_CollectionMode method (msinkaut.h)

  • Article

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

This property is read/write.

Syntax

HRESULT put_CollectionMode(
  InkCollectionMode Mode
);

Parameters

Mode

Return value

None

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 recognizer 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.

Requirements

Requirement Value
Minimum supported client Windows XP Tablet PC Edition [desktop apps only]
Minimum supported server None supported
Target Platform Windows
Header msinkaut.h
Library InkObj.dll

See also

CollectingInk Property

Enabled Property

IInkOverlay

InkCollectionMode Enumeration

InkOverlay Class