Export (0) Print
Expand All
Expand Minimize

InkOverlay.CollectionMode property

Applies to: desktop apps only

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(
  [in]           InkCollectionMode Mode
);

HRESULT get_CollectionMode(
  [out, retval]  InkCollectionMode *Mode
);

Property value

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.

Error codes

NameMeaning
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 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

Minimum supported client

Windows XP Tablet PC Edition

Minimum supported server

None supported

Header

Msinkaut.h (also requires Msinkaut_i.c)

Library

InkObj.dll

See also

InkOverlay Class
Enabled Property
CollectingInk Property
InkCollectionMode Enumeration

 

 

Send comments about this topic to Microsoft

Build date: 3/6/2012

Community Additions

ADD
Show:
© 2014 Microsoft