StylusPlugIn Class

Definition

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

C#
public abstract class StylusPlugIn
Inheritance
StylusPlugIn
Derived

Examples

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

C#
// 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);
        }
    }
}

Remarks

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.

Note

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.

XAML Text Usage

This class is not typically used in XAML.

Constructors

StylusPlugIn()

Initializes a new instance of the StylusPlugIn class.

Properties

Element

Gets the UIElement to which the StylusPlugIn is attached.

ElementBounds

Gets the cached bounds of the element.

Enabled

Gets or sets whether the StylusPlugIn is active.

IsActiveForInput

Gets whether the StylusPlugIn is able to accept input.

Methods

Equals(Object)

Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetHashCode()

Serves as the default hash function.

(Inherited from Object)
GetType()

Gets the Type of the current instance.

(Inherited from Object)
MemberwiseClone()

Creates a shallow copy of the current Object.

(Inherited from Object)
OnAdded()

Occurs when the StylusPlugIn is added to an element.

OnEnabledChanged()

Occurs when the Enabled property changes.

OnIsActiveForInputChanged()

Occurs when the IsActiveForInput property changes.

OnRemoved()

Occurs when the StylusPlugIn is removed from an element.

OnStylusDown(RawStylusInput)

Occurs on a thread in the pen thread pool when the tablet pen touches the digitizer.

OnStylusDownProcessed(Object, Boolean)

Occurs on the application UI (user interface) thread when the tablet pen touches the digitizer.

OnStylusEnter(RawStylusInput, Boolean)

Occurs on a pen thread when the cursor enters the bounds of an element.

OnStylusLeave(RawStylusInput, Boolean)

Occurs on a pen thread when the cursor leaves the bounds of an element.

OnStylusMove(RawStylusInput)

Occurs on a pen thread when the tablet pen moves on the digitizer.

OnStylusMoveProcessed(Object, Boolean)

Occurs on the application UI (user interface) thread when the tablet pen moves on the digitizer.

OnStylusUp(RawStylusInput)

Occurs on a pen thread when the user lifts the tablet pen from the digitizer.

OnStylusUpProcessed(Object, Boolean)

Occurs on the application UI (user interface) thread when the user lifts the tablet pen from the digitizer.

ToString()

Returns a string that represents the current object.

(Inherited from Object)

Applies to

Product Versions
.NET Framework 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
Windows Desktop 3.0, 3.1, 5, 6, 7, 8, 9