InkCollector class
Represents the object that is used to capture ink from available tablet devices.
Creating the InkCollector control behind a transparent control (such as a GroupBox with the WS_EX_TRANSPARENT property set) will prevent InkCollector from collecting ink.
InkCollector has these types of members:
Events
The InkCollector class has these 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 the 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 object and a mouse button is pressed. |
| MouseMove | Occurs when the mouse pointer is moved over the InkCollector object. |
| MouseUp | Occurs when the mouse pointer is over the InkCollector object 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 object's associated window. |
| NewPackets | Occurs when the InkCollector object 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. |
Interfaces
The InkCollector class defines these interfaces.
| Interface | Description |
|---|---|
| IInkCollector | This object implements the IInkCollector COM interface. |
Methods
The InkCollector class has these methods.
| Method | Description |
|---|---|
| GetEventInterest | Retrieves the current state of a particular InkCollector object event, that is, whether the event is being listened for or used. |
| GetGestureStatus | Retrieves whether the InkCollector object is interested in a particular gesture. |
| GetWindowInputRectangle | Retrieves the window rectangle, in pixels, within which ink is drawn. |
| SetAllTabletsMode | This mode allows the InkCollector object to collect ink from any tablet attached to the Tablet PC. |
| SetEventInterest | Modifies a value that indicates whether a specific event should be listened for or used. |
| SetGestureStatus | Modifies the interest of the InkCollector object in a known gesture. |
| SetSingleTabletIntegratedMode | This mode allows the InkCollector object to collect ink from only one tablet. Ink from other tablets is ignored by the InkCollector object. |
| SetWindowInputRectangle | Modifies the window rectangle, in pixels, to use to map drawn ink to the window. |
Properties
The InkCollector class has these properties.
| Property | Access type | Description |
|---|---|---|
| AutoRedraw |
Read-only |
Gets or sets a value that specifies whether the InkCollector repaints the ink when the window is invalidated. |
| CollectingInk |
Read-only |
Gets a value that specifies whether ink is currently being drawn on an InkCollector object. |
| CollectionMode |
Read-only |
Gets or sets the collection mode that determines whether ink, gestures, or both are recognized as the user writes. |
| Cursors |
Read-only |
Gets the Cursors collection that is available for use in the inking region. |
| DefaultDrawingAttributes |
Read-only |
Gets or sets the default InkDrawingAttributes object, which specifies the drawing attributes that are used when drawing and displaying ink. |
| DesiredPacketDescription |
Read-only |
Gets or sets interest in aspects of the packet associated with ink drawn on the InkCollector object. |
| DynamicRendering |
Read-only |
Gets or sets a value that indicates whether ink is rendered as it is drawn. |
| Enabled |
Read-only |
Gets or sets a value that specifies whether the InkCollector object collects pen input. |
| Handle |
Read-only |
Gets or sets the handle of the window to which the InkCollector object is attached. |
| Ink |
Read-only |
Gets or sets the InkDisp object that is associated with the InkCollector object. |
| MarginX |
Read-only |
Gets or sets the margins along the x-axis, in pixels. |
| MarginY |
Read-only |
Gets or sets the margins along the y-axis, in pixels. |
| MouseIcon |
Read-only |
Gets or sets the current custom mouse icon. |
| MousePointer |
Read-only |
Gets or sets a value that indicates the type of mouse pointer that appears when the mouse is over a particular part of the object. |
| Renderer |
Read-only |
Gets or sets the InkRenderer object that is used to draw ink. |
| SupportHighContrastInk |
Read-only |
Gets or sets a value that specifies whether ink is rendered as just one color when the system is in High Contrast mode. |
| Tablet |
Read-only |
Gets the tablet device that the InkCollector object is currently using to collect input. |
Remarks
This object can be instantiated by calling the CoCreateInstance method in C++.
The InkCollector object collects only ink and gestures that are input into the specific window with which it is associated. The sole purpose of the InkCollector is to collect ink from the hardware (for example, through an IInkCursor and IInkTablet object) and deliver it to an application. It essentially acts as the source that distributes ink into one or many different InkDisp objects, which act as container that hold the distributed ink.
To use an InkCollector, you create it, tell it on which window to collect drawn ink, and enable it. After it is enabled, it can be set to collect in only one of three modes (the mode is specified in the InkCollectionMode enumeration):
- InkOnly, in which an IInkStrokeDisp object is created.
- GestureOnly, in which an IInkGesture object is created.
- InkAndGesture, in which a stroke, a gesture, or potentially both are created, depending on how the application handles events.
This means that, 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 all tablet input. Ink can be collected from all attached tablets (including the mouse) simultaneously. Changes in the IInkCursor and IInkCursorButton objects can cause 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 parameter set to VARIANT_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 InkCollectors (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.
Note
The InkCollector object cannot be safely released on a non-UI thread.
To improve your application's performance, dispose of your InkCollector object when it is no longer needed.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows XP Tablet PC Edition [desktop apps only] |
| Minimum supported server |
None supported |
| Header |
|
| Library |
|