Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
71 lines (49 sloc) 7.07 KB
title ms.date dev_langs helpviewer_keywords ms.assetid
Intercepting Input from the Stylus
03/30/2017
csharp
vb
architecture [WPF],
,
,
,
791bb2f0-4e5c-4569-ac3c-211996808d44

Intercepting Input from the Stylus

The xref:System.Windows.Input.StylusPlugIns architecture provides a mechanism for implementing low-level control over xref:System.Windows.Input.Stylus input and the creation of digital ink xref:System.Windows.Ink.Stroke objects. The xref:System.Windows.Input.StylusPlugIns.StylusPlugIn class provides a mechanism for you to implement custom behavior and apply it to the stream of data coming from the stylus device for the optimal performance.

This topic contains the following subsections:

Architecture

The xref:System.Windows.Input.StylusPlugIns.StylusPlugIn is the evolution of the StylusInput APIs, described in Accessing and Manipulating Pen Input, in the Microsoft Windows XP Tablet PC Edition Software Development Kit 1.7.

Each xref:System.Windows.UIElement has a xref:System.Windows.UIElement.StylusPlugIns%2A property that is a xref:System.Windows.Input.StylusPlugIns.StylusPlugInCollection. You can add a xref:System.Windows.Input.StylusPlugIns.StylusPlugIn to an element's xref:System.Windows.UIElement.StylusPlugIns%2A property to manipulate xref:System.Windows.Input.StylusPoint data as it is generated. xref:System.Windows.Input.StylusPoint data consists of all the properties supported by the system digitizer, including the xref:System.Windows.Input.StylusPoint.X%2A and xref:System.Windows.Input.StylusPoint.Y%2A point data, as well as xref:System.Windows.Input.StylusPoint.PressureFactor%2A data.

Your xref:System.Windows.Input.StylusPlugIns.StylusPlugIn objects are inserted directly into the stream of data coming from the xref:System.Windows.Input.Stylus device when you add the xref:System.Windows.Input.StylusPlugIns.StylusPlugIn to the xref:System.Windows.UIElement.StylusPlugIns%2A property. The order in which plug-ins are added to the xref:System.Windows.UIElement.StylusPlugIns%2A collection dictates the order in which they will receive xref:System.Windows.Input.StylusPoint data. For example, if you add a filter plug-in that restricts input to a particular region, and then add a plug-in that recognizes gestures as they are written, the plug-in that recognizes gestures will receive filtered xref:System.Windows.Input.StylusPoint data.

Implementing Stylus Plug-ins

To implement a plug-in, derive a class from xref:System.Windows.Input.StylusPlugIns.StylusPlugIn. This class is applied o the stream of data as it comes in from the xref:System.Windows.Input.Stylus. In this class you can modify the values of the xref:System.Windows.Input.StylusPoint data.

[!CAUTION] If a xref:System.Windows.Input.StylusPlugIns.StylusPlugIn throws or causes an exception, the application will close. You should thoroughly test controls that consume a xref:System.Windows.Input.StylusPlugIns.StylusPlugIn and only use a control if you are certain the xref:System.Windows.Input.StylusPlugIns.StylusPlugIn will not throw an exception.

The following example demonstrates a plug-in that restricts the stylus input by modifying the xref:System.Windows.Input.StylusPoint.X%2A and xref:System.Windows.Input.StylusPoint.Y%2A values in the xref:System.Windows.Input.StylusPoint data as it comes in from the xref:System.Windows.Input.Stylus device.

[!code-csharpAdvancedInkTopicsSamples#19] [!code-vbAdvancedInkTopicsSamples#19]
[!code-csharpAdvancedInkTopicsSamples#3] [!code-vbAdvancedInkTopicsSamples#3]

Adding Your Plug-in to an InkCanvas

The easiest way to use your custom plug-in is to implement a class that derives from InkCanvas and add it to the xref:System.Windows.UIElement.StylusPlugIns%2A property.

The following example demonstrates a custom xref:System.Windows.Controls.InkCanvas that filters the ink.

[!code-csharpAdvancedInkTopicsSamples#4]

If you add a FilterInkCanvas to your application and run it, you will notice that the ink isn't restricted to a region until after the user completes a stroke. This is because the xref:System.Windows.Controls.InkCanvas has a xref:System.Windows.Controls.InkCanvas.DynamicRenderer%2A property, which is a xref:System.Windows.Input.StylusPlugIns.StylusPlugIn and is already a member of the xref:System.Windows.UIElement.StylusPlugIns%2A collection. The custom xref:System.Windows.Input.StylusPlugIns.StylusPlugIn you added to the xref:System.Windows.UIElement.StylusPlugIns%2A collection receives the xref:System.Windows.Input.StylusPoint data after xref:System.Windows.Input.StylusPlugIns.DynamicRenderer receives data. As a result, the xref:System.Windows.Input.StylusPoint data will not be filtered until after the user lifts the pen to end a stroke. To filter the ink as the user draws it, you must insert the FilterPlugin before the xref:System.Windows.Input.StylusPlugIns.DynamicRenderer.

The following C# code demonstrates a custom xref:System.Windows.Controls.InkCanvas that filters the ink as it is drawn.

[!code-csharpAdvancedInkTopicsSamples#5]

Conclusion

By deriving your own xref:System.Windows.Input.StylusPlugIns.StylusPlugIn classes and inserting them into xref:System.Windows.Input.StylusPlugIns.StylusPlugInCollection collections, you can greatly enhance the behavior of your digital ink. You have access to the xref:System.Windows.Input.StylusPoint data as it is generated, giving you the opportunity to customize the xref:System.Windows.Input.Stylus input. Because you have such low-level access to the xref:System.Windows.Input.StylusPoint data, you can implement ink collection and rendering with optimal performance for your application.

See also

You can’t perform that action at this time.