| title | titleSuffix | ms.date | dev_langs | helpviewer_keywords | ms.assetid | description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Digital ink - Windows Forms and COM vs. WPF |
03/30/2017 |
|
|
577835be-b145-4226-8570-1d309e9b3901 |
Learn about the three essential platforms that support digital ink: the Tablet PC Windows Forms platform, the Tablet PC COM platform, and the WPF platform. |
There are essentially three platforms that support digital ink: the Tablet PC Windows Forms platform, the Tablet PC COM platform, and the Windows Presentation Foundation (WPF) platform. The Windows Forms and COM platforms share a similar object model, but the object model for the WPF platform is substantially different. This topic discusses the differences at a high-level so that developers that have worked with one object model can better understand the other.
All three platforms ship objects and controls that enable an application to receive input from a tablet pen. The Windows Forms and COM platforms ship with Microsoft.Ink.InkPicture, Microsoft.Ink.InkEdit, Microsoft.Ink.InkOverlay and Microsoft.Ink.InkCollector classes. Microsoft.Ink.InkPicture and Microsoft.Ink.InkEdit are controls that you can add to an application to collect ink. The Microsoft.Ink.InkOverlay and Microsoft.Ink.InkCollector can be attached to an existing window to ink-enable windows and custom controls.
The WPF platform includes the xref:System.Windows.Controls.InkCanvas control. You can add an xref:System.Windows.Controls.InkCanvas to your application and begin collecting ink immediately. With the xref:System.Windows.Controls.InkCanvas, the user can copy, select, and resize ink. You can add other controls to the xref:System.Windows.Controls.InkCanvas, and the user can handwrite over those controls, too. You can create an ink-enabled custom control by adding an xref:System.Windows.Controls.InkPresenter to it and collecting its stylus points.
The following table lists where to learn more about enabling ink in an application:
| To do this… | On the WPF Platform… | On the Windows Forms/COM Platforms… |
|---|---|---|
| Add an ink-enabled control to an application | See Getting Started with Ink. | See Auto Claims Form Sample |
| Enable ink on a custom control | See Creating an Ink Input Control. | See Ink Clipboard Sample. |
On the Windows Forms and COM platforms, Microsoft.Ink.InkCollector, Microsoft.Ink.InkOverlay, Microsoft.Ink.InkEdit, and Microsoft.Ink.InkPicture each expose a Microsoft.Ink.Ink object. The Microsoft.Ink.Ink object contains the data for one or more Microsoft.Ink.Stroke objects and exposes common methods and properties to manage and manipulate those strokes. The Microsoft.Ink.Ink object manages the lifetime of the strokes it contains; the Microsoft.Ink.Ink object creates and deletes the strokes that it owns. Each Microsoft.Ink.Stroke has an identifier that is unique within its parent Microsoft.Ink.Ink object.
On the WPF platform, the xref:System.Windows.Ink.Stroke?displayProperty=nameWithType class owns and manages its own lifetime. A group of xref:System.Windows.Ink.Stroke objects can be collected together in a xref:System.Windows.Ink.StrokeCollection, which provides methods for common ink data management operations such as hit testing, erasing, transforming, and serializing the ink. A xref:System.Windows.Ink.Stroke can belong to zero, one, or more xref:System.Windows.Ink.StrokeCollection objects at any give time. Instead of having a Microsoft.Ink.Ink object, the xref:System.Windows.Controls.InkCanvas and xref:System.Windows.Controls.InkPresenter contain a xref:System.Windows.Ink.StrokeCollection?displayProperty=nameWithType.
The following pair of illustrations compares the ink data object models. On the Windows Forms and COM platforms, the Microsoft.Ink.Ink object constrains the lifetime of the Microsoft.Ink.Stroke objects, and the stylus packets belong to the individual strokes. Two or more strokes can reference the same Microsoft.Ink.DrawingAttributes object, as shown in the following illustration.
On the WPF, each xref:System.Windows.Ink.Stroke?displayProperty=nameWithType is a common language runtime object that exists as long as something has a reference to it. Each xref:System.Windows.Ink.Stroke references a xref:System.Windows.Input.StylusPointCollection and xref:System.Windows.Ink.DrawingAttributes?displayProperty=nameWithType object, which are also common language runtime objects.
The following table compares how to accomplish some common tasks on the WPF platform and the Windows Forms and COM platforms.
| Task | Windows Presentation Foundation | Windows Forms and COM |
|---|---|---|
| Save Ink | xref:System.Windows.Ink.StrokeCollection.Save%2A | Microsoft.Ink.Ink.Save |
| Load Ink | Create a xref:System.Windows.Ink.StrokeCollection with the xref:System.Windows.Ink.StrokeCollection.%23ctor%2A constructor. | Microsoft.Ink.Ink.Load |
| Hit test | xref:System.Windows.Ink.StrokeCollection.HitTest%2A | Microsoft.Ink.Ink.HitTest |
| Copy Ink | xref:System.Windows.Controls.InkCanvas.CopySelection%2A | Microsoft.Ink.Ink.ClipboardCopy |
| Paste Ink | xref:System.Windows.Controls.InkCanvas.Paste%2A | Microsoft.Ink.Ink.ClipboardPaste |
| Access custom properties on a collection of strokes | xref:System.Windows.Ink.StrokeCollection.AddPropertyData%2A (the properties are stored internally and accessed via xref:System.Windows.Ink.StrokeCollection.AddPropertyData%2A, xref:System.Windows.Ink.StrokeCollection.RemovePropertyData%2A, and xref:System.Windows.Ink.StrokeCollection.ContainsPropertyData%2A) | Use Microsoft.Ink.Ink.ExtendedProperties |
Although the platforms have different object models for the ink data, sharing the data between the platforms is very easy. The following examples save ink from a Windows Forms application and load the ink into a Windows Presentation Foundation application.
[!code-csharpWinFormWPFInk#UsingWinforms]
[!code-vbWinFormWPFInk#UsingWinforms]
[!code-csharpWinFormWPFInk#SaveWinforms]
[!code-vbWinFormWPFInk#SaveWinforms]
[!code-csharpWinFormWPFInk#UsingWPF]
[!code-vbWinFormWPFInk#UsingWPF]
[!code-csharpWinFormWPFInk#LoadWPF]
[!code-vbWinFormWPFInk#LoadWPF]
The following examples save ink from a Windows Presentation Foundation application and load the ink into a Windows Forms application.
[!code-csharpWinFormWPFInk#UsingWPF]
[!code-vbWinFormWPFInk#UsingWPF]
[!code-csharpWinFormWPFInk#SaveWPF]
[!code-vbWinFormWPFInk#SaveWPF]
[!code-csharpWinFormWPFInk#UsingWinforms]
[!code-vbWinFormWPFInk#UsingWinforms]
[!code-csharpWinFormWPFInk#LoadWinforms]
[!code-vbWinFormWPFInk#LoadWinforms]
The Microsoft.Ink.InkOverlay, Microsoft.Ink.InkCollector, and Microsoft.Ink.InkPicture on the Windows Forms and COM platforms receive events when the user inputs pen data. The Microsoft.Ink.InkOverlay or Microsoft.Ink.InkCollector is attached to a window or a control, and can subscribe to the events raised by the tablet input data. The thread on which these events occurs depends on whether the events are raised with a pen, a mouse, or programmatically. For more information about threading in relation to these events, see General Threading Considerations and Threads on Which an Event Can Fire.
On the Windows Presentation Foundation platform, the xref:System.Windows.UIElement class has events for pen input. This means that every control exposes the full set of stylus events. The stylus events have tunneling/bubbling event pairs and always occur on the application thread. For more information, see Routed Events Overview.
The following diagram shows compares the object models for the classes that raise stylus events. The Windows Presentation Foundation object model shows only the bubbling events, not the tunneling event counterparts.
All three platforms provide you with ways to intercept and manipulate the data that comes in from a tablet pen. On the Windows Forms and COM Platforms, this is achieved by creating a Microsoft.StylusInput.RealTimeStylus, attaching a window or control to it, and creating a class that implements the Microsoft.StylusInput.IStylusSyncPlugin or Microsoft.StylusInput.IStylusAsyncPlugin interface. The custom plug-in is then added to the plug-in collection of the Microsoft.StylusInput.RealTimeStylus. For more information about this object model, see Architecture of the StylusInput APIs.
On the WPF platform, the xref:System.Windows.UIElement class exposes a collection of plug-ins, similar in design to the Microsoft.StylusInput.RealTimeStylus. To intercept pen data, create a class that inherits from xref:System.Windows.Input.StylusPlugIns.StylusPlugIn and add the object to the xref:System.Windows.UIElement.StylusPlugIns%2A collection of the xref:System.Windows.UIElement. For more information about this interaction, see Intercepting Input from the Stylus.
On all platforms, a thread pool receives the ink data via stylus events and sends it to the application thread. For more information about threading on the COM and Windows Platforms, see Threading Considerations for the StylusInput APIs. For more information about threading on the Windows Presentation Software, see The Ink Threading Model.
The following illustration compares the object models for the classes that receive pen data on the pen thread pool.
