Share via


InkCollector Class

Represents an object that is used to capture ink from available tablet devices.

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

Syntax

'Declaration
<UIPermissionAttribute(SecurityAction.Demand, Window := UIPermissionWindow.SafeTopLevelWindows)> _
<PermissionSetAttribute(SecurityAction.InheritanceDemand, Name := "FullTrust")> _
Public Class InkCollector _
    Implements IDisposable
'Usage
Dim instance As InkCollector
[UIPermissionAttribute(SecurityAction.Demand, Window = UIPermissionWindow.SafeTopLevelWindows)]
[PermissionSetAttribute(SecurityAction.InheritanceDemand, Name = "FullTrust")]
public class InkCollector : IDisposable
[UIPermissionAttribute(SecurityAction::Demand, Window = UIPermissionWindow::SafeTopLevelWindows)]
[PermissionSetAttribute(SecurityAction::InheritanceDemand, Name = L"FullTrust")]
public ref class InkCollector : IDisposable
public class InkCollector implements IDisposable

Remarks

Warning

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 gesture input. The only purpose of the InkCollector is collecting ink from hardware (using, for example, Cursor and Tablet objects) and delivering it to an application. Essentially, it distributes ink into one or many different Ink objects, acting as a container to hold the distributed ink.

To use an InkCollector, create it, set the window that will collect drawn ink, and enable it. After the InkCollector is enabled, it can collect ink in only one of three modes (as 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.

For every movement of a cursor within range of a tablet, the InkCollector 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 may cause the InkCollector object to fire an event.

An InkCollector also manages a list of cursors encountered 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 area, set using the constructor or 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 a 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 noteSecurity Note:

If using under partial trust, this class and all its methods require UIPermissionWindow.SafeTopLevelWindows permission. See Security And Trust for more information.

Inheritance Hierarchy

System.Object
  Microsoft.Ink.InkCollector

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Windows 7, Windows Vista, Windows Server 2008 R2, Windows Server 2008

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.0

See Also

Reference

InkCollector Members

Microsoft.Ink Namespace

Ink

InkOverlay

InkPicture

InkEdit

Other Resources

Ink Collection