Architecture of the StylusInput APIs
Architecture of the StylusInput APIs |
Description of the architecture of the StylusInput application programming interfaces (APIs).
The StylusInput APIs allow you to interact with the tablet pen data stream. To interact with the data stream, add a RealTimeStylus object to your application, and add plug-ins to the RealTimeStylus object. Two plug-ins are provided in the StylusInput APIs: the GestureRecognizer and DynamicRenderer classes.
Definitions
The following terms are used in the sections describing the StylusInput APIs.
- Synchronous plug-in
A class that implements the IStylusSyncPlugin interface. - Asynchronous plug-in
A class that implements the IStylusAsyncPlugin interface. - Synchronous plug-in collection
A StylusSyncPluginCollection collection, which is an ordered collection of IStylusSyncPlugin objects. A synchronous plug-in collection usually refers to the collection assigned to the SyncPluginCollection property of a RealTimeStylus object. Only synchronous plug-ins may be added to a synchronous plug-in collection. - Asynchronous plug-in collection
A StylusAsyncPluginCollection collection, which is an ordered collection of IStylusAsyncPlugin objects. An asynchronous plug-in collection usually refers to the collection assigned to the AsyncPluginCollection property of a RealTimeStylus object. Only asynchronous plug-ins may be added to an asynchronous plug-in collection.
Synchronous and Asynchronous Plug-ins
The RealTimeStylus object is designed to provide real-time access to the data stream from a tablet pen. The RealTimeStylus object runs on its own thread. 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 for dynamic rendering. Create or use asynchronous plug-ins for tasks that do not require real-time access to the data stream, such as for ink collection.
Certain tasks may be computationally demanding yet require real-time access to the data stream, such as multistroke gesture recognition. To address these needs, the StylusInput 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.
For more information about using and creating plug-ins, see Working with the StylusInput APIs.
The Tablet Pen Data Stream
The RealTimeStylus object has two internal queues that carry the tablet pen data, the input queue and the output queue. The pen data is represented by the classes in the Microsoft.StylusInput.PluginData namespace. The following list describes how the RealTimeStylus object handles the tablet pen data.
- The RealTimeStylus object checks for plug-in data objects first on its input queue and then from the tablet pen data stream.
- The RealTimeStylus object sends one plug-in data object to the objects in its synchronous plug-in collection. Each synchronous plug-in can add data to either the input or output queue.
- Once the plug-in data object has been sent to all members of the synchronous plug-in collection, the plug-in data object is placed on the RealTimeStylus object's output queue.
- The RealTimeStylus object then checks for the next plug-in data object to process.
- While the RealTimeStylus object's output queue contains data, the RealTimeStylus object sends one plug-in data object from its output queue to the objects in its asynchronous plug-in collection. Each asynchronous plug-in can add data to either the input or output queue, but since the asynchronous plug-ins run on the UI thread, the data added to the queue does not have a set relationship to the rest of the data in the tablet pen data stream or to the RealTimeStylus object's input and output queues.
The StylusInput APIs
The StylusInput APIs reside primarily in the Microsoft.StylusInput and Microsoft.StylusInput.PluginData namespaces. However, the StylusInput APIs also reference some classes in the Microsoft.Ink namespace, such as the Tablet class, the TabletPropertyDescriptionCollection collection, and the ApplicationGesture and SystemGesture enumerations.