InkPicture Control Reference
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++.
Note
The InkPicture control is not marked safe for scripting. The InkPicture control should not be used in HTML or ASP.NET pages.
Creating the InkPicture control behind a transparent control (such as a GroupBox with the WS_EX_TRANSPARENT property set) will prevent InkPicture from collecting ink.
Members
| Enumeration | Description |
|---|---|
| InkPictureSizeMode | Defines values that specify how the background picture behaves inside the InkPicture control. |
| Event | Description |
|---|---|
| ChangeUICues | Deprecated. |
| Click | Occurs when a user clicks the InkPicture control. |
| CursorButtonDown Event | Occurs when the InkCollector control detects an IInkCursorButton object that is down. |
| CursorButtonUp Event | Occurs when the InkPicture control detects an IInkCursorButton that is up. |
| CursorDown Event | Occurs when the cursor tip contacts the digitizing tablet surface. |
| CursorInRange Event | Occurs when a cursor enters the physical detection range (proximity) of the tablet context. |
| CursorOutOfRange Event | 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 Event | Occurs when an application gesture is recognized. |
| KeyDown Event [InkPicture Control] | Occurs when a key is pressed and in the down position while the InkPicture control has focus. |
| KeyPress Event[InkPicture Control] | Occurs when a key is pressed while the InkPicture control has focus. |
| KeyUp Event [InkPicture Control] | Occurs when a key is released while the InkPicture control has focus. |
| MouseDown Event [InkPicture Control] | 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 Event [InkPicture Control] | Occurs when the mouse pointer is moved over the InkPicture control. |
| MouseUp Event [InkPicture Control] | 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 Event | Occurs when an in-air packet is seen. |
| NewPackets Event | 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 Event [InkPicture Control] | 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 Width or 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 Event | Occurs when a tablet is added to the system. |
| TabletRemoved Event | Occurs when a tablet is removed from the system. |
| Method | Description |
|---|---|
| GetEventInterest Method | 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 Method | 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 Method | Enables the InkPicture control to collect ink from any tablet attached to the Tablet PC. |
| SetEventInterest Method | Sets a value that indicates whether an InkPicture control has interest in a specified event. |
| SetFocus | Moves the focus to the InkPicture control. |
| SetGestureStatus Method | Sets the interest of the InkPicture object in a specified application gesture. |
| SetSingleTabletIntegratedMode Method | Sets the InkPicture control to collect ink from only one tablet attached to the Tablet PC. Ink from other tablets is ignored. |
| SetWindowInputRectangle Method | 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). |
| Property | Description |
|---|---|
| AutoRedraw Property | 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 Property | 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 Property | 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 Property | Gets or sets the default InkDrawingAttributes collection to use when drawing and displaying ink (run time only). |
| DesiredPacketDescription Property | Gets or sets the packet description of the InkPicture control (run time only). |
| DynamicRendering Property | 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 Property | Gets or sets the x-axis margin around the window rectangle in screen coordinates. |
| MarginY Property | Gets or sets the y-axis margin around the window rectangle in screen coordinates. |
| MouseIcon Property | Gets or sets the current custom mouse icon. |
| MousePointer Property | 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 Property | 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 Property | 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 interfaces (selection bounding box and selection handles) are drawn in high contrast when the system is in High Contrast mode. |
| Tablet Property | 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, any edition of Windows XP other than Windows XP Tablet PC Edition, and any version of Windows Vista. However, you can input ink, accept gestures, or recognize handwriting only under the following conditions:
- Ink can be input and recognized if Windows Vista or XP Tablet PC Edition 2005 is installed.
- Gestures can be recognized as well.
- Handwriting can be recognized as text if the handwriting originated on machines running older versions of Windows as long as recognizers are present.
If you use Windows 2000, Windows Server 2003, any edition of Windows XP other than Windows XP Tablet PC Edition 2005, you can assign values to the ambient properties of the InkPicture control, then copy and paste ink to other applications. However, the value of its InkEnabled property will always be FALSE.
Persisted InkDisp objects can be loaded and displayed on all editions of Windows Vista and XP and on systems that have only the Windows XP Tablet PC Edition Software Development Kit (SDK) installed. InkDisp objects can only be converted to text (recognized), if Windows Vista or the Windows XP Tablet PC Edition 2005 is installed.
If operations on this control do not succeed, a legal HRESULT is returned. If error conditions result, check the returned HRESULT against the error.
For more information about ink controls, see Ink.
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.
Note
When an InkPicture control is overlayed with another control, such as a GroupBox set to transparent, the InkPicture will not collect ink. The InkPicture must be the top-most control in the Z-order or it must be a child of the GroupBox.
COM Implementation
This object implements the IInkPicture COM interface.