InkCollector Class
InkCollector Class |
Represents an object that is used to capture ink from available tablet devices.
Definition
Visual Basic .NET Public Class InkCollector
Inherits Object
Implements IDisposableC# public class InkCollector : Object,
IDisposableManaged C++ public __gc class InkCollector : public Object,
IDisposable
Members Table
The following table lists the members exposed by the object.
Events
Event Description CursorButtonDown Occurs when the InkCollector detects a cursor button that is down. CursorButtonUp Occurs when the InkCollector detects a cursor button that is up. CursorDown Occurs when the cursor tip contacts the digitizing tablet surface. CursorInRange Occurs when a cursor enters the physical detection range (proximity) of the tablet context. CursorOutOfRange Occurs when a cursor leaves the physical detection range (proximity) of the tablet context. DoubleClick Occurs when the InkCollector object is double-clicked. Gesture Occurs when an application-specific gesture is recognized. MouseDown Occurs when the mouse pointer is over the InkCollector and a mouse button is pressed. MouseMove Occurs when the mouse pointer is moved over the InkCollector. MouseUp Occurs when the mouse pointer is over the InkCollector and a mouse button is released. MouseWheel Occurs when the mouse wheel moves while the InkCollector object has focus. NewInAirPackets Occurs when an in-air packet is seen, which happens when a user moves a pen near the tablet and the cursor is within the InkCollector object's window or the user moves a mouse within the InkCollector object's associated window. NewPackets Occurs when the InkCollector receives packets. Stroke Occurs when the user finishes drawing a new stroke on any tablet. SystemGesture Occurs when a system gesture is recognized. TabletAdded Occurs when a Tablet is added to the system. TabletRemoved Occurs when a Tablet is removed from the system. Fields
Field Description ClipInkToMargin Not implemented. DefaultMargin Returns the default margin used by the MarginX and MarginY properties. Methods
Method Description Dispose Releases resources used by the InkCollector object. Equals Determines whether two Object instances are equal. Inherited from Object
Finalize Frees the resources of the current InkCollector object before it is reclaimed by the garbage collector. GetGestureStatus Returns a value that indicates whether the InkCollector object has interest in a particular application gesture. GetHashCode Serves as a hash function for a particular type, suitable for use in hashing algorithms and data structures like a hash table. Inherited from Object GetType Gets the Type GetWindowInputRectangle Gets the window rectangle, in pixels, within which ink is drawn. InkCollector Initializes a new instance of the InkCollector class. MemberwiseClone Creates a shallow copy of the current Object OnCursorButtonDown Allows derived classes to modify the default behavior of the CursorButtonDown event. OnCursorButtonUp Allows derived classes to modify the default behavior of the CursorButtonUp event. OnCursorDown Allows derived classes to modify the default behavior of the CursorDown event. OnCursorInRange Allows derived classes to modify the default behavior of the CursorInRange event. OnCursorOutOfRange Allows derived classes to modify the default behavior of the CursorOutOfRange event. OnDoubleClick Allows derived classes to modify the default behavior of the DoubleClick event. OnGesture Allows derived classes to modify the default behavior of the Gesture event. OnMouseDown Allows derived classes to modify the default behavior of the MouseDown event. OnMouseMove Allows derived classes to modify the default behavior of the MouseMove event. OnMouseUp Allows derived classes to modify the default behavior of the MouseUp event. OnMouseWheel Allows derived classes to modify the default behavior of the MouseWheel event. OnNewInAirPackets Allows derived classes to modify the default behavior of the NewInAirPackets event. OnNewPackets Allows derived classes to modify the default behavior of the NewPackets event. OnStroke Allows derived classes to modify the default behavior of the Stroke event. OnSystemGesture Allows derived classes to modify the default behavior of the SystemGesture event. OnTabletAdded Allows derived classes to modify the default behavior of the TabletAdded event. OnTabletRemoved Allows derived classes to modify the default behavior of the TabletRemoved event. ReferenceEquals
Determines whether the specified Object SetAllTabletsMode Sets the InkCollector object to collect ink from any tablet attached to the Tablet PC. SetGestureStatus Sets whether or not the InkCollector object has interest in a known application gesture. SetSingleTabletIntegratedMode Sets the InkCollector object to collect ink from only one tablet attached to the Tablet PC. Ink from other tablets is ignored by the InkCollector object. SetWindowInputRectangle Sets the window rectangle, in pixels, within which ink is drawn. ToString Returns a String Properties
Property Description AttachedControl Gets or sets the control to which the InkCollector object is attached. AutoRedraw Gets or sets a value that specifies whether the InkCollector object repaints the ink when the window is invalidated. CollectingInk Gets a value that specifies whether ink is currently being drawn on an InkCollector object. CollectionMode Gets or sets the collection mode that determines whether ink, gestures, or both are recognized as the user writes. Cursor Gets or sets the cursor that appears when the mouse pointer is over the InkPicture control. Cursors Gets the Cursors collection that is available for use in the inking region. DefaultDrawingAttributes Gets or sets the default DrawingAttributes object, which specifies the drawing attributes that are used when drawing and displaying ink. DesiredPacketDescription Gets or sets interest in aspects of the packets associated with ink drawn on the InkCollector object. DynamicRendering Gets or sets a value that indicates whether ink is rendered as it is drawn. Enabled Gets or sets a value that specifies whether the InkCollector object collects pen input. Handle Gets or sets the handle of the window to which the InkCollector object is attached. Ink Gets or sets the Ink object that is associated with the InkCollector object. MarginX Gets or sets the margins along the x-axis, in pixels. MarginY Gets or sets the margins along the y-axis, in pixels. Renderer Gets or sets the Renderer object that is used to draw ink. SupportHighContrastInk Gets or sets a value that specifies whether ink is rendered as just one color when the system is in High Contrast mode. Tablet Gets the tablet device that the InkCollector object is currently using to collect input.
Inheritance Hierarchy
InkCollector
Remarks
Caution: To avoid a memory leak you must explicitly call the Dispose method on any InkCollector object to which an event handler has been attached before the object goes out of scope.
The InkCollector object collects only ink and gestures that are input into the specific window with which it is associated. The only purpose of the InkCollector is to collect ink from the hardware (for example, through a Cursor and Tablet object) and deliver it to an application. It essentially acts as the source that distributes ink into one or many different Ink objects, which act as a container that holds the distributed ink.
To use an InkCollector, create it, set which window to collect drawn ink, and enable it. After the InkCollector is enabled, it can be set to collect in only one of three modes (the mode is specified in the CollectionMode enumeration):
- InkOnly, in which a Stroke object is created.
- GestureOnly, in which a Gesture object is created.
- InkAndGesture, in which a stroke, a gesture, or potentially both are created, depending on how the application handles events.
This means for every movement of a cursor that is within range of a tablet, the InkCollector always collects either a stroke or a gesture and sometimes both. Gesture support is built in using the Microsoft gesture recognizer.
An InkCollector handles tablet input. Ink can be collected from all attached tablets (including the mouse) simultaneously. Changes in the Cursor and CursorButton objects can cause the InkCollector object to fire an event.
An InkCollector also manages the list of cursors that it encounters during its existence. When the InkCollector encounters a new cursor, the CursorInRange event fires with the NewCursor property of the InkCollectorCursorInRangeEventArgs object set to true. Applications use the InkCollector to manage new cursors.
More than one InkCollector can be associated with a particular window handle, even if their collection areas, set in the constructor or with the SetWindowInputRectangle method, overlap. However, the only way this scenario works is if each InkCollector calls SetSingleTabletIntegratedMode and uses a unique tablet. This behavior makes it easy to store ink in a separate object for each tablet.
An error occurs if the window input rectangle of one enabled InkCollector object (set with the Enabled property) overlaps the window input rectangle of another enabled InkCollector.
Note: Overlap can occur without an error as long as only one of the input rectangles is enabled at any known time.
The MouseDown, MouseMove, MouseUp, and MouseWheel events return x- and y-coordinates in pixels, and not the HIMETRIC units that are associated with the ink space. This is because these events replace the mouse events of pen-unaware applications and these applications understand only pixels.
The InkCollector behaves differently in applications created by using Microsoft® Visual Basic® than those created by using the Microsoft Foundation Classes (MFC). For more information about these behaviors, see Ink Collection.
Note: The InkCollector object cannot be safely released on a non-user interface (UI) thread.
To improve your application's performance, manually dispose of an InkCollector object when it is no longer needed.
Security Alert: If using under partial trust, this class and all its methods require UIPermissionWindow.SafeTopLevelWindows
Class Information
Namespace Microsoft.Ink Assembly Microsoft.Ink (microsoft.ink.dll) Strong Name Microsoft.Ink, Version=1.7.4009.0, Culture=neutral, PublicKeyToken=a2870d9cc4d021c8
See Also