CollectionMode Enumeration

Defines values that determine whether ink, gestures, or ink and gestures are recognized as the user writes.

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

Syntax

'Declaration
Public Enumeration CollectionMode
'Usage
Dim instance As CollectionMode

public enum CollectionMode

public enum class CollectionMode

public enum CollectionMode

public enum CollectionMode

Members

	Member name	Description
	GestureOnly	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).
	InkAndGesture	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 the NoGesture value from ApplicationGesture, 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).
	InkOnly	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).

Remarks

If a user attempts a right-click and moves the pen when in the InkOnly or InkAndGesture mode, ink flows from the pen tip. When handling the InkCollector.Stroke, InkOverlay.Stroke, or InkPicture.Stroke event, erase the ink that flowed as a result of the pen movement.

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

• Set the collection mode to InkAndGesture.

• Delete the stroke in the handler for the InkCollector.Stroke, InkOverlay.Stroke, or InkPicture.Stroke.

• Process the gesture in the handler for the gesture event.

• Set the InkCollector.DynamicRendering, InkOverlay.DynamicRendering, or InkPicture.DynamicRendering property to false.

When using this enumeration with the InkPicture control, or the InkCollector or InkOverlay objects, on a system that has the Microsoft® Windows® XP Tablet PC Edition Software Development Kit (SDK) installed but that does not have recognizers installed, the mode cannot be set to GestureOnly or InkAndGesture.

Typical scenarios for each collection mode follow.

Note

If the cursor does not move out of range of the collection object between strokes, the cursor in range and the cursor out of range events do not fire.

• InkOnly

  Step	InkCollector object	InkOverlay object	InkPicture control
  1	An CursorInRange event fires.	An CursorInRange event fires.	An CursorInRange event fires.
  2	An NewInAirPackets event fires.	An NewInAirPackets event fires.	An NewInAirPackets event fires.
  3	An CursorDown event fires.	An CursorDown event fires.	An CursorDown event fires.
  4	An NewPackets event fires.	An NewPackets event fires.	An NewPackets event fires.
  5	A Stroke object is created.	A Stroke object is created.	A Stroke object is created.
  6	An CursorOutOfRange event fires.	An CursorOutOfRange event fires.	An CursorOutOfRange event fires.

• GestureOnly

  Step	InkCollector object	InkOverlay object	InkPicture control
  1	An CursorInRange event fires.	An CursorInRange event fires.	An CursorInRange event fires.
  2	An NewInAirPackets event fires.	An NewInAirPackets event fires.	An NewInAirPackets event fires.
  3	An CursorDown event fires.	An CursorDown event fires.	An CursorDown event fires.
  4	An NewPackets event fires.	An NewPackets event fires.	An NewPackets event fires.
  5	Either a Gesture object is created or, if the cursor movement does not represent a gesture, nothing happens.	Either a Gesture object is created or, if the cursor movement does not represent a gesture, nothing happens.	Either a Gesture object is created or, if the cursor movement does not represent a gesture, nothing happens.
  6	An CursorOutOfRange event fires.	An CursorOutOfRange event fires.	An CursorOutOfRange event fires.

  Note

  Either single- or multi-stroke gestures are accepted in this mode.

• InkAndGesture

  Step	InkCollector object	InkOverlay object	InkPicture control
  1	An CursorInRange event fires.	An CursorInRange event fires.	An CursorInRange event fires.
  2	An NewInAirPackets event fires.	An NewInAirPackets event fires.	An NewInAirPackets event fires.
  3	An CursorDown event fires.	An CursorDown event fires.	An CursorDown event fires.
  4	An NewPackets event fires.	An NewPackets event fires.	An NewPackets event fires.
  5	Either a Gesture object or a Stroke object is created.	Either a Gesture object or a Stroke object is created.	Either a Gesture object or a Stroke object is created.
  6	An CursorOutOfRange event fires.	An CursorOutOfRange event fires.	An CursorOutOfRange event fires.

  Note

  Only single-stroke gestures are accepted in this mode.

Unwanted behavior might occur when the InkCollector.CollectionMode, InkOverlay.CollectionMode, or InkPicture.CollectionMode property is set to and the interest of an object or control in a known gesture is set (by calling the InkCollector.SetGestureStatus, InkOverlay.SetGestureStatus, or InkPicture.SetGestureStatus method). If a user draws ink that resembles a gesture that 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 to cancel collection of the gesture, set the inherited Cancel property of the InkCollectorGestureEventArgs to true if you do not want the recognizer to respond to that event.

Platforms

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

Version Information

.NET Framework

Supported in: 3.0

See Also

Reference

Microsoft.Ink Namespace
InkCollector.CollectionMode
InkOverlay.CollectionMode
InkPicture.CollectionMode