Share via

Plug-in Data and the RealTimeStylus Class

  • Article

Plug-in Data and the RealTimeStylus Class

Overview of plug-in data.

Plug-ins for the RealTimeStylus class must implement either the IStylusSyncPlugin or IStylusAsyncPlugin interface. While you have to implement all of the plug-in interface methods, your plug-in only receives calls on methods flagged in the plug-in's IStylusSyncPlugin.DataInterest or IStylusAsyncPlugin.DataInterest property.

The methods defined on the interfaces use objects in the Microsoft.StylusInput.PluginData namespace to pass the pen data to the plug-ins. The following table describes the data objects that are parameters in the notification methods and lists the DataInterestMask value associated with the notification.

Plug-in Data DataInterestMask Value Description
CustomStylusData CustomStylusDataAdded Custom application data that a plug-in adds.
ErrorData Error Error information that the RealTimeStylus object adds in response to an unhandled exception in one of its plug-ins.
InAirPacketsData InAirPackets Packet information for stylus motion while the stylus is in-air above the digitizer.
InAirPacketsData Packets Packet information for stylus motion while the stylus is touching the digitizer.
RealTimeStylusDisabledData RealTimeStylusDisabled Information the RealTimeStylus object adds when it is being disabled.
RealTimeStylusEnabledData RealTimeStylusEnabled Information the RealTimeStylus object adds when it is being enabled.
StylusButtonDownData StylusButtonDown Information about the particular stylus button that is being pressed.
StylusButtonUpData StylusButtonUp Information about the particular stylus button that is being released.
StylusDownData StylusDown Packet information for a stylus as the stylus is brought in contact with the digitizer.
StylusInRangeData StylusInRange Information about the particular stylus that is entering the input area of the RealTimeStylus object or entering the detection range of the digitizer above the input area of the RealTimeStylus object.
StylusOutOfRangeData StylusOutOfRange Information about the particular stylus that is leaving the input area of the RealTimeStylus object or leaving the detection range of the digitizer above the input area of the RealTimeStylus object.
StylusUpData StylusUp Packet information for a stylus as the stylus is lifted from the digitizer.
SystemGestureData SystemGesture Information the RealTimeStylus object adds when it detects a system gesture.
TabletAddedData TabletAdded Information about the Tablet object that is being added.
TabletRemovedData TabletRemoved Information about the Tablet object that is being removed.

For information about how the RealTimeStylus object handles the tablet pen data stream, see Extending the RealTimeStylus Class.

Data Interest

The RealTimeStylus object checks the IStylusSyncPlugin.DataInterest or IStylusAsyncPlugin.DataInterest property of a plug-in when the plug-in is added to the RealTimeStylus object's synchronous or asynchronous plug-in collection. Therefore, if you need to update the DataInterest property a plug-in after it has been added to the RealTimeStylus object's plug-in collection, remove the plug-in, update its DataInterest property, and then add the plug-in back to the RealTimeStylus object's plug-in collection.

A plug-in only receives calls on methods flagged in the plug-in's IStylusSyncPlugin.DataInterest or IStylusAsyncPlugin.DataInterest property. For more information about the possible values of a plug-in's DataInterest property, see the DataInterestMask enumeration.

Timing

Data is queued in the RealTimeStylus object before it is passed to the plug-ins in the asynchronous plug-in collection. The following list describes some situations that you may need to account for when designing an asynchronous plug-in.

  • When a Tablet object that is available to the RealTimeStylus object is removed, the plug-in may receive queued stylus notification for the tablet before its TabletRemoved method is called. In this situation, calling the RealTimeStylus object's GetTabletPropertyDescriptionCollection method does not work. Information relevant to your plug-in should be cached when the RealTimeStylus object is enabled or when a new tablet is added.
  • When the RealTimeStylus object is disabled, the plug-in may receive other queued notifications before its RealTimeStylusDisabled method is called. In this situation, calls from the plug-in to some of the RealTimeStylus object's methods and properties throw an exception. Information relevant to your plug-in should be cached when the RealTimeStylus object is enabled.
  • The RealTimeStylus object's ClearStylusQueues method may remove information from the output queue. Therefore, asynchronous plug-ins cannot rely on receiving all relevant notifications.

Enabled and Disabled Data

Generally, add or remove plug-ins while the RealTimeStylus object is disabled. However, plug-in collections can be modified while the RealTimeStylus object is enabled. When a plug-in is added while the RealTimeStylus object is enabled, the RealTimeStylus object calls the plug-in's IStylusSyncPlugin.RealTimeStylusEnabled or IStylusAsyncPlugin.RealTimeStylusEnabled method. When a plug-in is removed while the RealTimeStylus object is enabled, the RealTimeStylus object calls the plug-in's IStylusSyncPlugin.RealTimeStylusDisabled or IStylusAsyncPlugin.RealTimeStylusDisabled method. This enables the plug-in to maintain its proper state without having to poll the RealTimeStylus object.

Note: Because the plug-in data for the RealTimeStylus object's asynchronous plug-in collection is queued, asynchronous plug-ins may receive data prior to the instantiation of a RealTimeStylusDisabledData object but after the RealTimeStylus object is disabled. Also, some of the RealTimeStylus object's methods and properties throw an exception if the RealTimeStylus object is disabled.

When the RealTimeStylus object is enabled, each plug-in receives a call to its IStylusSyncPlugin.RealTimeStylusEnabled or IStylusAsyncPlugin.RealTimeStylusEnabled method. The RealTimeStylusEnabledData object passed in the notification contains a collection of the context identifiers for the available tablets at the time the RealTimeStylus object is enabled.

The RealTimeStylus object calls the IStylusSyncPlugin.RealTimeStylusEnabled and IStylusSyncPlugin.RealTimeStylusDisabled methods on the thread from which the RealTimeStylus object is enabled or from which the synchronous plug-in is added.

Tablet Data

When a tablet that the RealTimeStylus object can use is added to or removed from the Tablet PC while the RealTimeStylus object is enabled, the RealTimeStylus object notifies its plug-ins that a Tablet object has been added or removed. Each RealTimeStylus object maintains a list of unique identifiers for the Tablet objects it can interact with. The RealTimeStylus object has two methods for translating between the unique identifier and the Tablet object, the GetTabletContextIDFromTablet and GetTabletFromTabletContextID methods.

Note: Information about a tablet is no longer available from the RealTimeStylus object after the tablet is removed from the Tablet PC.

Tablet Pen Data

The RealTimeStylus object passes information about the tablet pen to its plug-ins in a number of the notification methods. Information about the tablet pen is represented by a Stylus object. This object is a snapshot of the state of the tablet pen at the time the data was gathered. Because plug-ins receive the tablet pen data as part of the tablet pen data stream, the plug-ins should use the information in the Stylus object instead of checking for the current state of a particular tablet pen through the Cursor class.

Each Stylus object contains the tablet context identifier for the tablet that generated the data.

System Gesture Data

The RealTimeStylus object receives data about system gestures as they are recognized by the Tablet PC. The following table describes the order in which the SystemGestureData objects occur in the tablet pen data stream in relation to other tablet pen data.

SystemGesture Objects that precede the SystemGestureData object Objects that come after the SystemGestureData object
Tap The StylusDownData object. The StylusUpData object.
DoubleTap The StylusDownData object, the SystemGestureData object for the Tap system gesture, and the StylusUpData object. The second StylusDownData object.
RightTap The StylusDownData object and the SystemGestureData object for the HoldEnter system gesture. The StylusUpData object.
Drag The StylusDownData object. The StylusUpData object.
RightDrag The StylusDownData object. The StylusUpData object.
HoldEnter The StylusDownData object. The StylusUpData object.
Note: This system gesture isn't recognized if the user begins a Drag or RightDrag system gesture.
HoldLeave Not implemented. Not implemented.
HoverEnter Several InAirPacketsData objects of low average velocity.
Note: There may be noticeable delay before receiving the HoverEnter system gesture. The RealTimeStylus object only receives this data if the RealTimeStylus object is attached to the window or control that is directly under the pen at the time of the system gesture.
HoverLeave The SystemGestureData object for the HoverEnter system gesture and several InAirPacketsData objects of sufficient average velocity.
Note: There may be noticeable delay before receiving the HoverLeave system gesture. The RealTimeStylus object only receives this data if the RealTimeStylus object is attached to the window or control that is directly under the pen at the time of the system gesture.

Custom Stylus Data

Custom stylus data can be added to the RealTimeStylus object by calling the AddCustomStylusDataToQueue method. If the call to the AddCustomStylusDataToQueue method is made from a synchronous plug-in in response to a call to one of its IStylusSyncPlugin methods, then the custom stylus data is added to the tablet pen data stream in a predictable manner; otherwise, it is added in an unpredictable manner. The AddCustomStylusDataToQueue method throws an exception if the RealTimeStylus object is disabled.

Custom stylus data can be added to the RealTimeStylus object's queues in one of three places.

  • When the queue parameter is set to Input, the custom data is added to the RealTimeStylus object's input queue and is sent to the synchronous plug-in collection before new data from the tablet pen's data stream.
  • When the queue parameter is set to Output, the custom data is added to the RealTimeStylus object's output queue after the data currently being processed by the synchronous plug-in collection.
  • When the queue parameter is set to OutputImmediate, the custom data is added to the RealTimeStylus object's output queue before the data currently being processed by the synchronous plug-in collection.

In each of the previous cases, data added by subsequent plug-ins in the synchronous plug-in collection is added after data added by preceding plug-ins.

Custom stylus data is added to the queue as a CustomStylusData object and plug-ins receive this data through their IStylusSyncPlugin.CustomStylusDataAdded or IStylusAsyncPlugin.CustomStylusDataAdded method.

The DynamicRenderer and the GestureRecognizer objects may add custom stylus data to the queue. For more information about the DynamicRenderer and the GestureRecognizer objects, see Dynamic-Renderer Plug-ins and Recognizer Plug-ins.

The RealTimeStylus object calls the IStylusSyncPlugin.CustomStylusDataAdded method on the thread from which it receives the call to its AddCustomStylusDataToQueue method.

Error Data

When a plug-in throws an exception, the normal flow of data is interrupted. The RealTimeStylus object generates an ErrorData object and calls:

If the plug-in that threw the exception is a synchronous plug-in, the ErrorData object is added to the output queue. Then RealTimeStylus object resumes normal processing of the original data.

If a plug-in throws an exception from its Error method, the RealTimeStylus object catches the exception but does not generate a new ErrorData object.

The error data is added to the output queue after any custom stylus data that is added to the OutputImmediate queue prior to the exception that created the error data and before any custom stylus data that is added to the OutputImmediate queue by subsequent plug-ins in the synchronous plug-in collection. If any of the synchronous plug-ins adds custom stylus data to the OutputImmediate queue in response to the error data, the data is added immediately before the error data. If any of the synchronous plug-ins adds custom stylus data to the Output queue in response to the error data, the data is added immediately after the error data.

The RealTimeStylus object calls the IStylusSyncPlugin.Error method on the thread from which the exception is thrown.