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 .gif)
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 |
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 |
| 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.