Share via


InkPicture Control

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 Leave Site 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

Enumeration Description
InkApplicationGesture Defines values that set the interest in a set of application-specific gestures.
InkCollectionMode Defines values that determine whether ink, gestures, or ink and gestures are recognized as the user writes.
InkCollectorEventInterest Defines values that are used to specify whether an event has occurred on the InkPicture control and, if so, which event was fired.
InkMouseButton Defines values that specify which mouse button was pressed.
InkMousePointer Defines values that specify the type of mouse pointer to appear.
InkOverlayEditingMode Defines values that specify which editing mode the InkPicture control should use: drawing ink, deleting ink, or editing ink.
InkOverlayEraserMode Defines values that specify the way in which ink is erased when the InkOverlayEditingMode enumeration is set to Delete.
InkPictureSizeMode Defines values that specify how the background picture behaves inside the InkPicture control.
SelectionHitResult Defines values that specify which part of a selection, if any, was hit during a hit test.
InkSystemGesture Defines values that set the interest in a set of operating system–specific gestures.

Events

Event Description
ChangeUICues Deprecated.
Click Leave Site 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 Leave Site Occurs when the InkPicture control is double-clicked.

This event method is defined in the _IInkPictureEvents interface. The _IInkPictureEvents interface implements the IDispatch Leave Site 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 Leave Site 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 Leave Site 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 Leave Site 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 Leave Site 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 Leave Site 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 Leave Site 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 Leave Site 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 Leave Site 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 Leave Site 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.