InkPicture Control

The InkPicture control provides the ability to place an image in an application and enable users to add ink on top of it. It is intended for scenarios in which ink is not recognized as text but is instead stored as ink.

The InkPicture control can be instantiated by calling the CoCreateInstance method in C++ or by using the New keyword in Visual Basic 6.

Note: The InkPicture control is not marked safe for scripting. The InkPicture control should not be used in HTML or ASP.NET pages.

Members

Enumerations

Events

Event	Description
ChangeUICues	Deprecated.
Click	Occurs when a user clicks the InkPicture control.
CursorButtonDown	Occurs when the InkCollector control detects an IInkCursorButton object that is down.
CursorButtonUp	Occurs when the InkPicture control detects an IInkCursorButton 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.
DblClick	Occurs when the InkPicture control is double-clicked. This event method is defined in the _IInkPictureEvents interface. The _IInkPictureEvents interface implements the IDispatch interface with an identifier of DISPID_IPEDblClick.
Gesture	Occurs when an application gesture gesture is recognized.
KeyDown	Occurs when a key is pressed and in the down position while the InkPicture control has focus.
KeyPress	Occurs when a key is pressed while the InkPicture control has focus.
KeyUp	Occurs when a key is released while the InkPicture control has focus.
MouseDown	Occurs when the mouse pointer is over the InkPicture control and a mouse button is pressed.
MouseEnter	Occurs when the mouse pointer enters the InkPicture control.
MouseHover	Occurs when the mouse pointer hovers over the InkPicture control.
MouseLeave	Occurs when the mouse pointer leaves the InkPicture control.
MouseMove	Occurs when the mouse pointer is moved over the InkPicture control.
MouseUp	Occurs when the mouse pointer is over the InkPicture control and a mouse button is released.
MouseWheel	Occurs when the mouse wheel moves while the InkPicture control has focus.
NewInAirPackets	Occurs when an in-air packet is seen.
NewPackets	Occurs when the InkPicture control receives a packet.
Painted	Occurs when the InkPicture control has completed redrawing itself.
Painting	Occurs before the InkPicture control redraws itself.
Resize	Occurs when the InkPicture control is resized.
SelectionChanged	Occurs when the selection of text within the InkPicture 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 text within the InkPicture 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.
SizeChanged	Occurs after the InkPicture control has been resized, specifically, after the InkPicture::Width or InkPicture::Height property value changes.
SizeModeChanged	Occurs after the SizeMode property of the InkPicture control has been changed.
StyleChanged	Not implemented.
Stroke	Occurs when the user draws a new stroke on any tablet.
StrokesDeleted	Occurs after IInkStrokeDisp objects have been deleted from the Ink property.
StrokesDeleting	Occurs before IInkStrokeDisp objects are deleted from the Ink property.
SystemColorsChanged	Occurs after the system colors change.
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.

Methods

Method	Description
GetEventInterest	Returns a value that indicates whether the InkPicture control has interest in a particular event.
GetGestureStatus	Returns a value that indicates whether the InkPicture control has interest in a particular application gesture.
GetWindowInputRectangle	Returns the window rectangle, in pixels, within which ink is drawn.
HitTestSelection	Returns a member of the SelectionHitResult enumeration, which specifies which part of a selection, if any, was hit during a hit test.
SetAllTabletsMode	Enables the InkPicture control to collect ink from any tablet attached to the Tablet PC.
SetEventInterest	Sets a value that indicates whether an InkPicture control has interest in a specified event.
SetFocus	Moves the focus to the InkPicture control.
SetGestureStatus	Sets the interest of the InkPicture object in a specified application gesture.
SetSingleTabletIntegratedMode	Sets the InkPicture control to collect ink from only one tablet attached to the Tablet PC. Ink from other tablets is ignored.
SetWindowInputRectangle	Specifies the window rectangle to set, in window coordinates, within which ink is drawn.
ShowWhatsThis	Displays a selected topic in a Help file using the What's This popup provided by Help in 32-bit Microsoft® Windows® operating systems (design-time only).
ZOrder	Places the control at the front or back of the z-order within its graphical level (design-time only).

Properties

Property	Description
AutoRedraw	Gets or sets a value that specifies whether the InkPicture control repaints when the window is invalidated (whether the InkDisp object currently associated with InkPicture control is automatically redrawn when the window associated with the InkPicture receives a WM_PAINT message).
BackColor	Gets or sets the background color for the InkPicture control. The default background color is the system window background color, which is typically white.
CollectingInk	Gets the value that specifies whether the InkPicture control is collecting ink (run time only).
CollectionMode	Gets or sets the collection mode that determines whether ink, gestures, or ink and gestures are recognized as the user writes.
Cursors	Gets the IInkCursors collection available for use in the InkPicture control's inking region.
CustomStrokes	Gets the IInkCustomStrokes collection to be persisted with the ink (design-time only).
DefaultDrawingAttributes	Gets or sets the default InkDrawingAttributes collection to use when drawing and displaying ink (run time only).
DesiredPacketDescription	Gets or sets the packet description of the InkPicture control (run time only).
DynamicRendering	Gets or sets the value that specifies whether the InkPicture control dynamically renders the ink as it is collected.
EditingMode	Gets or sets a value that specifies whether the InkPicture control is in ink mode, deletion mode, or selecting/editing mode.
Enabled	Gets or sets a value that determines whether the InkPicture control can respond to user-generated events. Note: This property is equivalent to the InkEnabled property.
EraserMode	Gets or sets the value that specifies whether ink is erased by stroke or by point.
EraserWidth	Gets or sets the value that specifies the width of the eraser pen tip.
hWnd	Gets the window handle to which the InkPicture control is bound. (run time only)
Ink	Gets or sets the InkDisp object that is associated with the InkPicture control (run time only).
InkEnabled	Gets or sets a value that specifies whether the InkPicture control collects pen input (in-air packets, cursor in range events, and so on).
MarginX	Gets or sets the x-axis margin around the window rectangle in screen coordinates.
MarginY	Gets or sets the y-axis margin around the window rectangle in screen coordinates.
MouseIcon	Gets or sets the current custom mouse icon.
MousePointer	Gets or sets a value that indicates the type of mouse pointer that appears when the mouse is over a particular part of the InkPicture control.
Picture	Gets the graphics file to appear on the InkPicture control.
Renderer	Gets or sets the InkRenderer object that is used to draw ink on the InkPicture control (run time only).
Selection	Gets the InkStrokes collection currently selected inside the InkPicture control (run time only).
SizeMode	Gets or sets how the control handles image placement and sizing.
SupportHighContrastInk	Gets a value that specifies whether ink is rendered as just one color, Color = COLOR_WINDOWTEXT (from the GetSystemMetrics call) when the system is in High Contrast mode.
SupportHighContrastSelectionUI	Gets or sets a value that specifies whether all selection user interface (selection bounding box and selection handles) are drawn in high contrast when the system is in High Contrast mode.
Tablet	Gets the IInkTablet object that the InkPicture control is currently using to collect input.

Remarks

The run time user interface for the InkPicture control is a window with an opaque background (single color, picture background, or both) that contains opaque ink.

You can use the InkPicture control to render ink in Microsoft® Windows® 2000, Windows Server 2003, and any edition of Windows XP other than Windows XP Tablet PC Edition. However, you can input ink, accept gestures, or recognize handwriting only under the following conditions:

• Ink can be input and recognized if Windows XP Tablet PC Edition is installed.
• Gestures can be recognized if Windows XP Tablet PC Edition is installed.
• Handwriting can be recognized as text if the handwriting originated elsewhere and if recognizers are present.

If you use Windows 2000, Windows Server 2003, or any edition of Windows XP other than Windows XP Tablet PC Edition, you can assign values to the ambient properties of the InkPicture control and copy and paste ink to other applications, but the value of its InkEnabled property is always False.

Persisted InkDisp objects can be loaded and displayed on all editions of Windows XP (including the Windows XP Tablet PC Edition) and on systems that have only the Windows XP Tablet PC Edition Software Development Kit (SDK) installed. However, the InkDisp objects can be converted to text (recognized) only if Windows XP Tablet PC Edition is installed.

If operations on this control do not succeed the returned error is a legal HRESULT from either the Microsoft Platform Software Development Kit (SDK) or the Tablet PC SDK Automation API. If error conditions are returned, check the returned HRESULT against both.

For more information about ink controls, see Ink Controls.

For information about which threads raise particular events, see Threads on Which an Event Can Fire.

To improve your application's performance, manually dispose of an InkPicture control when it is no longer needed.

COM Implementation

This object implements the IInkPicture COM interface.

Related Topics

• InkEdit Control (Automation Library Reference)
• InkOverlay Object (Automation Library Reference)