StylusPlugIn Class
Collapse the table of content
Expand the table of content

StylusPlugIn Class

 

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

Namespace:   System.Windows.Input.StylusPlugIns
Assembly:  PresentationCore (in PresentationCore.dll)

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

public abstract class StylusPlugIn

NameDescription
System_CAPS_protmethodStylusPlugIn()

Initializes a new instance of the StylusPlugIn class.

NameDescription
System_CAPS_pubpropertyElement

Gets the UIElement to which the StylusPlugIn is attached.

System_CAPS_pubpropertyElementBounds

Gets the cached bounds of the element.

System_CAPS_pubpropertyEnabled

Gets or sets whether the StylusPlugIn is active.

System_CAPS_pubpropertyIsActiveForInput

Gets whether the StylusPlugIn is able to accept input.

NameDescription
System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethodOnAdded()

Occurs when the StylusPlugIn is added to an element.

System_CAPS_protmethodOnEnabledChanged()

Occurs when the Enabled property changes.

System_CAPS_protmethodOnIsActiveForInputChanged()

Occurs when the IsActiveForInput property changes.

System_CAPS_protmethodOnRemoved()

Occurs when the StylusPlugIn is removed from an element.

System_CAPS_protmethodOnStylusDown(RawStylusInput)

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

System_CAPS_protmethodOnStylusDownProcessed(Object, Boolean)

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

System_CAPS_protmethodOnStylusEnter(RawStylusInput, Boolean)

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

System_CAPS_protmethodOnStylusLeave(RawStylusInput, Boolean)

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

System_CAPS_protmethodOnStylusMove(RawStylusInput)

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

System_CAPS_protmethodOnStylusMoveProcessed(Object, Boolean)

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

System_CAPS_protmethodOnStylusUp(RawStylusInput)

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

System_CAPS_protmethodOnStylusUpProcessed(Object, Boolean)

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

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

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.

System_CAPS_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.

This class is not typically used in XAML.

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
Available since 3.0

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show:
© 2016 Microsoft