Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

StylusPlugIn Class

Represents a plug-in that can be added to a control's StylusPlugIns property.

System.Object
  System.Windows.Input.StylusPlugIns.StylusPlugIn
    System.Windows.Input.StylusPlugIns.DynamicRenderer

Namespace:  System.Windows.Input.StylusPlugIns
Assembly:  PresentationCore (in PresentationCore.dll)
XMLNS for XAML: Not mapped to an xmlns.
public abstract class StylusPlugIn
This class is not typically used in XAML.

The StylusPlugIn type exposes the following members.

  NameDescription
Protected methodStylusPlugInInitializes a new instance of the StylusPlugIn class.
Top
  NameDescription
Public propertyElementGets the UIElement to which the StylusPlugIn is attached.
Public propertyElementBoundsGets the cached bounds of the element.
Public propertyEnabledGets or sets whether the StylusPlugIn is active.
Public propertyIsActiveForInputGets whether the StylusPlugIn is able to accept input.
Top
  NameDescription
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnAddedOccurs when the StylusPlugIn is added to an element.
Protected methodOnEnabledChangedOccurs when the Enabled property changes.
Protected methodOnIsActiveForInputChangedOccurs when the IsActiveForInput property changes.
Protected methodOnRemovedOccurs when the StylusPlugIn is removed from an element.
Protected methodOnStylusDownOccurs on a thread in the pen thread pool when the tablet pen touches the digitizer.
Protected methodOnStylusDownProcessedOccurs on the application UI (user interface) thread when the tablet pen touches the digitizer.
Protected methodOnStylusEnterOccurs on a pen thread when the cursor enters the bounds of an element.
Protected methodOnStylusLeaveOccurs on a pen thread when the cursor leaves the bounds of an element.
Protected methodOnStylusMoveOccurs on a pen thread when the tablet pen moves on the digitizer.
Protected methodOnStylusMoveProcessedOccurs on the application UI (user interface) thread when the tablet pen moves on the digitizer.
Protected methodOnStylusUpOccurs on a pen thread when the user lifts the tablet pen from the digitizer.
Protected methodOnStylusUpProcessedOccurs on the application UI (user interface) thread when the user lifts the tablet pen from the digitizer.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

The StylusPlugIn allows you to manipulate StylusPoint objects on separate threads. Separate threads are used so that the ink still renders as the tablet pen inputs data even if the application is doing something else.

To intercept stylus points from the hardware, create a class that inherits from the StylusPlugIn class. The StylusPlugIn class has the following methods that you can override to manipulate StylusPoint objects on a thread in the pen thread pool.

The pen's input is routed to an element's StylusPlugIn on the pen thread. Since accurate hit-testing cannot be performed on the pen thread, some elements might occasionally receive stylus input intended for other elements. If you need to make sure the input was routed correctly before performing an operation, subscribe to and perform the operation in the OnStylusDownProcessed, OnStylusMoveProcessed, or OnStylusUpProcessed method. These methods are invoked by the main application thread after accurate hit-testing has been performed. To subscribe to these methods, call the NotifyWhenProcessed method in the method that occurs on the pen thread. For example, if you call NotifyWhenProcessed in OnStylusMove, the OnStylusMoveProcessed occurs.

NoteNote

If you use a StylusPlugIn inside a control, you should test the plug-in and control extensively to make sure they do not throw any unintended exceptions.

The following example creates a custom StylusPlugIn that constrains the ink to a certain area on the control.

// EventArgs for the StrokeRendered event. 
public class StrokeRenderedEventArgs : EventArgs
{
    StylusPointCollection strokePoints;

    public StrokeRenderedEventArgs(StylusPointCollection points)
    {
        strokePoints = points;
    }

    public StylusPointCollection StrokePoints
    {
        get
        {
            return strokePoints;
        }
    }
}

// EventHandler for the StrokeRendered event. 
public delegate void StrokeRenderedEventHandler(object sender, StrokeRenderedEventArgs e);

// A StylusPlugin that restricts the input area 
class FilterPlugin : StylusPlugIn
{
    StylusPointCollection collectedPoints;
    int currentStylus = -1;
    public event StrokeRenderedEventHandler StrokeRendered;

    protected override void OnStylusDown(RawStylusInput rawStylusInput)
    {
        // Run the base class before modifying the data 
        base.OnStylusDown(rawStylusInput);

        if (currentStylus == -1)
        {
            StylusPointCollection pointsFromEvent = rawStylusInput.GetStylusPoints();

            // Create an emtpy StylusPointCollection to contain the filtered 
            // points.
            collectedPoints = new StylusPointCollection(pointsFromEvent.Description);

            // Restrict the stylus input and add the filtered  
            // points to collectedPoints. 
            StylusPointCollection points = FilterPackets(pointsFromEvent);
            rawStylusInput.SetStylusPoints(points);
            collectedPoints.Add(points);

            currentStylus = rawStylusInput.StylusDeviceId;
        }
    }

    protected override void OnStylusMove(RawStylusInput rawStylusInput)
    {
        // Run the base class before modifying the data 
        base.OnStylusMove(rawStylusInput);

        if (currentStylus == rawStylusInput.StylusDeviceId)
        {
            StylusPointCollection pointsFromEvent = rawStylusInput.GetStylusPoints();

            // Restrict the stylus input and add the filtered  
            // points to collectedPoints. 
            StylusPointCollection points = FilterPackets(pointsFromEvent);
            rawStylusInput.SetStylusPoints(points);
            collectedPoints.Add(points);
        }
    }

    protected override void OnStylusUp(RawStylusInput rawStylusInput)
    {
        // Run the base class before modifying the data 
        base.OnStylusUp(rawStylusInput);

        if (currentStylus == rawStylusInput.StylusDeviceId)
        {
            StylusPointCollection pointsFromEvent = rawStylusInput.GetStylusPoints();

            // Restrict the stylus input and add the filtered  
            // points to collectedPoints. 
            StylusPointCollection points = FilterPackets(pointsFromEvent);
            rawStylusInput.SetStylusPoints(points);
            collectedPoints.Add(points);

            // Subscribe to the OnStylusUpProcessed method.
            rawStylusInput.NotifyWhenProcessed(collectedPoints);

            currentStylus = -1;
        }
    }

    private StylusPointCollection FilterPackets(StylusPointCollection stylusPoints)
    {
        // Modify the (X,Y) data to move the points  
        // inside the acceptable input area, if necessary 
        for (int i = 0; i < stylusPoints.Count; i++)
        {
            StylusPoint sp = stylusPoints[i];
            if (sp.X < 50) sp.X = 50;
            if (sp.X > 250) sp.X = 250;
            if (sp.Y < 50) sp.Y = 50;
            if (sp.Y > 250) sp.Y = 250;
            stylusPoints[i] = sp;
        }

        // Return the modified StylusPoints. 
        return stylusPoints;
    }

    // This is called on the application thread.   
    protected override void OnStylusUpProcessed(object callbackData, bool targetVerified)
    {
        // Check that the element actually receive the OnStylusUp input. 
        if (targetVerified)
        {
            StylusPointCollection strokePoints = callbackData as StylusPointCollection;

            if (strokePoints == null)
            {
                return;
            }

            // Raise the StrokeRendered event so the consumer of the plugin can 
            // add the filtered stroke to its StrokeCollection.
            StrokeRenderedEventArgs e = new StrokeRenderedEventArgs(strokePoints);
            OnStrokeRendered(e);
        }

    }

    protected virtual void OnStrokeRendered(StrokeRenderedEventArgs e)
    {
        if (StrokeRendered != null)
        {
            StrokeRendered(this, e);
        }
    }
}

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.