InkOverlay class

Represents an object that is useful for annotation scenarios where users are not concerned with performing recognition on ink but instead are interested in the size, shape, color, and position of the ink.

Creating the InkOverlay control behind a transparent control (such as a GroupBox with the WS_EX_TRANSPARENT property set) will prevent InkOverlay from collecting ink.

InkOverlay has these types of members:

Events

The InkOverlay class has these events.

EventDescription
CursorButtonDown

Occurs when the InkOverlay detects a cursor button that is down.

CursorButtonUp

Occurs when the InkOverlay 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 InkOverlay object is double-clicked.

Gesture

Occurs when an application-specific gesture is recognized.

MouseDown

Occurs when the mouse pointer is over the InkOverlay object and a mouse button is pressed.

MouseMove

Occurs when the mouse pointer is moved over the InkOverlay object.

MouseUp

Occurs when the mouse pointer is over the InkOverlay object and a mouse button is released.

MouseWheel

Occurs when the mouse wheel moves while the InkOverlay 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 InkOverlay object's window or the user moves a mouse within the InkOverlay object object's associated window.

NewPackets

Occurs when the InkOverlay object receives packets.

Painted

Occurs when the InkOverlay object has completed redrawing itself.

Painting

Occurs before the InkOverlay object redraws itself.

SelectionChanged

Occurs when the selection of ink within the control has changed, such as through alterations to the user interface, cut-and-paste procedures, or the Selection property.

SelectionChanging

Occurs when the selection of ink within the control is about to change, such as through alterations to the user interface, cut-and-paste procedures, or the Selection property.

SelectionMoved

Occurs when the position of the current selection has changed, such as through alterations to the user interface, cut-and-paste procedures, or the Selection property.

SelectionMoving

Occurs when the position of the current selection is about to change, such as through alterations to the user interface, cut-and-paste procedures, or the Selection property.

SelectionResized

Occurs when the size of the current selection has changed, such as through alterations to the user interface, cut-and-paste procedures, or the Selection property.

SelectionResizing

Occurs when the size of the current selection is about to change, such as through alterations to the user interface, cut-and-paste procedures, or the Selection property.

Stroke

Occurs when the user finishes drawing a new stroke on any tablet.

StrokesDeleted

Occurs after strokes have been deleted from the Ink property.

StrokesDeleting

Occurs before strokes are deleted from the Ink property.

SystemGesture

Occurs when a system gesture is recognized.

TabletAdded

Occurs when an IInkTablet is added to the system.

TabletRemoved

Occurs when a Tablet is removed from the system.

 

Interfaces

The InkOverlay class defines these interfaces.

InterfaceDescription
IInkOverlay

This object implements the IInkOverlay COM interface.

 

Methods

The InkOverlay class has these methods.

MethodDescription
Draw

Sets a rectangle in which to redraw the ink within the InkOverlay object.

GetEventInterest

Returns the current state of a particular InkOverlay object event, that is, whether the event is being listened for or used.

GetGestureStatus

Returns whether the InkOverlay object is interested in a particular gesture.

GetWindowInputRectangle

Retrieves the window rectangle, in pixels, within which ink is drawn.

HitTestSelection

Determines what portion of the selection was hit during a hit test.

SetAllTabletsMode

This mode allows the InkOverlay object to collect ink from any tablet attached to the Tablet PC.

SetEventInterest

Sets whether a specific event should be listened for or used.

SetGestureStatus

Sets the interest of the InkOverlay object in a known gesture.

SetSingleTabletIntegratedMode

This mode allows the InkOverlay object to collect ink from only one tablet. Ink from other tablets is ignored by the InkOverlay object.

SetWindowInputRectangle

Sets the window rectangle, in pixels, to use to map drawn ink to the window.

 

Properties

The InkOverlay class has these properties.

PropertyAccess typeDescription

AttachMode

Read/write

Gets or sets the value that specifies whether the InkOverlay object is attached behind or in front of the known window.

AutoRedraw

Read/write

Gets or sets a value that specifies whether the InkOverlay repaints the ink when the window is invalidated.

CollectingInk

Read-only

Gets a value that specifies whether ink is currently being drawn on an InkOverlay object.

CollectionMode

Read/write

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/write

Gets or sets the default InkDrawingAttributes object, which specifies the drawing attributes that are used when drawing and displaying ink.

DesiredPacketDescription

Read/write

Gets or sets interest in aspects of the packet associated with ink drawn on the InkOverlay object.

DynamicRendering

Read/write

Gets or sets a value that indicates whether ink is rendered as it is drawn.

EditingMode

Read/write

Gets or sets a value that indicates whether the InkOverlay is in ink mode, deletion mode, or selecting/editing mode.

Enabled

Read/write

Gets or sets a value that specifies whether the InkOverlay object collects pen input.

EraserMode

Read/write

Gets or sets a value that indicates whether ink is erased by stroke or by point.

EraserWidth

Read/write

Gets or sets a value that specifies the width of the eraser pen tip.

Handle

Read/write

Gets or sets the handle of the window to which the InkOverlay object is attached.

Ink

Read/write

Gets or sets the InkDisp object that is associated with the InkOverlay object.

MarginX

Read/write

Gets or sets the margins along the x-axis, in pixels.

MarginY

Read/write

Gets or sets the margins along the y-axis, in pixels.

MouseIcon

Read/write

Gets or sets the current custom mouse icon.

MousePointer

Read/write

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/write

Gets or sets the InkRenderer object that is used to draw ink.

Selection

Read/write

Gets or sets the InkStrokes collection that is currently selected inside the InkOverlay control.

SupportHighContrastInk

Read/write

Gets or sets a value that specifies whether ink is rendered as just one color when the system is in High Contrast mode.

SupportHighContrastSelectionUI

Read/write

Gets or sets a value that specifies whether all selection UI is drawn in high contrast when the system is in High Contrast mode.

Tablet

Read-only

Gets the tablet device that the InkOverlay object is currently using to collect input.

 

MFC Implementation Notes

If you attached the InkOverlay object to a CView object, release the InkOverlay object in response to the WM_DESTROY message as shown in the following example:


BOOL CRecognitionAlternatesSampleCppView::OnWndMsg(UINT msg, WPARAM wp, PARAM lp, LRESULT *pLR)
{
    if(WM_DESTROY == msg)
        m_spInkOverlay.Release();
    return CView::OnWndMsg(msg, wp, lp, pLR);
}

Remarks

This object can be instantiated by calling the CoCreateInstance method in C++.

The InkOverlay object is well suited for note taking and basic scribbling. The primary intended use of this object is to display ink as ink.

In general, the run-time user interface for this object is a transparent window with opaque ink.

The MouseDown, MouseMove, MouseUp, and MouseWheel events return x-coordinates 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.

Caution  If you are setting the InkOverlay object's AttachMode property to InFront then create the InkOverlay object in the thread in which the form is running. Your application may stop responding if the InkOverlay object is created in a different thread and its AttachMode property is set to InFront.
 
Note  The InkOverlay object cannot be safely released on a non-UI thread.
 

To improve your application's performance, dispose your InkOverlay object when it is no longer needed.

If you attached the InkOverlay object to a CView object, release the InkOverlay object in response to the WM_DESTROY message as shown in the following example:


BOOL CRecognitionAlternatesSampleCppView::OnWndMsg(UINT msg, WPARAM wp, PARAM lp, LRESULT *pLR)
{
    if(WM_DESTROY == msg)
        m_spInkOverlay.Release();
    return CView::OnWndMsg(msg, wp, lp, pLR);
}

Requirements

Minimum supported client

Windows XP Tablet PC Edition [desktop apps only]

Minimum supported server

None supported

Header

Msinkaut.h (also requires Msinkaut_i.c)

Library

InkObj.dll

See also

InkCollector Class
InkPicture Control Reference
InkEdit Control Reference

 

 

Show: