Plug-ins and the RealTimeStylus Class
Plug-ins and the RealTimeStylus Class |
Overview of the relationship between plug-ins and the RealTimeStylus class.
The RealTimeStylus object is designed to provide real-time access to the data stream from the tablet pen and runs on its own thread. Plug-ins, objects which implement the IStylusSyncPlugin or IStylusAsyncPlugin interface, can be added to a RealTimeStylus object. Synchronous plug-ins generally run on the RealTimeStylus object's thread, while asynchronous plug-ins generally run on the application's user interface (UI) thread. Create or use synchronous plug-ins for tasks that require real-time access to the data stream and are computationally undemanding, such as dynamic rendering. Create or use asynchronous plug-ins for tasks that do not require real-time access to the data stream, such as ink collection.
Certain tasks may be computationally demanding yet still require real-time access to the tablet pen data stream, such as multistroke gesture recognition. The StylusInput application programming interfaces (APIs) provide a cascaded RealTimeStylus model that allows you to use two RealTimeStylus objects, each running on its own thread. For more information about the cascaded RealTimeStylus model, see The Cascaded RealTimeStylus Model.
Both the IStylusSyncPlugin and IStylusAsyncPlugin interfaces define the same methods. These methods allow the RealTimeStylus object to pass the pen data to each plug-in, regardless of whether it is an asynchronous or synchronous plug-in. The IStylusSyncPlugin.DataInterest and IStylusAsyncPlugin.DataInterest properties allow each plug-in to subscribe to specific data in the tablet pen data stream. A plug-in should only subscribe to the data necessary to perform its task, minimizing performance demands. For more information about threading and the RealTimeStylus class, see Threading Considerations for the StylusInput APIs.
The RealTimeStylus object uses objects in the Microsoft.StylusInput.PluginData namespace to pass the pen data to its plug-ins. The RealTimeStylus also catches exceptions thrown by plug-ins. When the RealTimeStylus catches exceptions, it notifies the plug-ins by calling the IStylusSyncPlugin.Error or IStylusAsyncPlugin.Error method. For more information on using plug-in data, see Plug-in Data and the RealTimeStylus Class. For more information on error handling, see Error Handling Considerations for the StylusInput APIs.
Plug-in collections can be modified while the RealTimeStylus object is enabled; however, this can make the behavior of your application harder to predict. 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 allows the plug-in to maintain its proper state without having to poll the RealTimeStylus object.
Note: For overall stability, reset a plug-in's internal state when its RealTimeStylusDisabled method is called.
Note: The RealTimeStylus object throws an exception if any of its plug-ins updates either the RealTimeStylus object's synchronous or asynchronous plug-in collections. The RealTimeStylus object also throws an exception if any of its plug-ins calls the RealTimeStylus object's Dispose method.
The following topics describe some common categories of plug-ins.