Share via

Working with the RealTimeStylus Class

  • Article

Working with the RealTimeStylus Class

Overview of the RealTimeStylus Class.

The RealTimeStylus class is part of the StylusInput application programming interfaces (APIs). The following sections describe key elements of the RealTimeStylus class and the StylusInput APIs.

Instantiating the RealTimeStylus Class

When you create a RealTimeStylus object, you have the option of attaching it to a window handle or to a control. Attaching the RealTimeStylus object to a window handle requires additional permissions. For more information about these permissions, see Partial Trust Considerations for the StylusInput APIs.

Note: You cannot attach the RealTimeStylus object to a window or control in a different application domain.

You can set the WindowInputRectangle property when you create a RealTimeStylus object or update it later. This property controls where the RealTimeStylus object can begin collecting ink.

If you use the default constructor, you create a RealTimeStylus object that can only accept input from another RealTimeStylus object. For more information about connecting two RealTimeStylus objects, see The Cascaded RealTimeStylus Model.

The RealTimeStylus object implements the IDisposable Leave Site interface.

Extending the RealTimeStylus Class

To allow your plug-ins to interact with the data stream from the tablet pen, the RealTimeStylus object maintains two plug-in collections in its SyncPluginCollection and AsyncPluginCollection properties. You can add a plug-in by calling either the StylusSyncPluginCollection.Add or the StylusAsyncPluginCollection.Add method about the collection in the appropriate property. For more information about creating and using plug-ins, see Plug-ins and the RealTimeStylus Class. For information about deciding whether to create a synchronous or asynchronous plug-in for a particular task, see Threading Considerations for the StylusInput APIs.

Synchronous plug-ins must implement the IStylusSyncPlugin interface, and asynchronous plug-ins must implement the IStylusAsyncPlugin interface. Each plug-in has an IStylusSyncPlugin.DataInterest or IStylusAsyncPlugin.DataInterest property. The RealTimeStylus object calls only the notification methods of the plug-in for methods in which the plug-in has subscribed. For more information about the notification methods, see Plug-in Data and the RealTimeStylus Class.

The RealTimeStylus object implements the IStylusAsyncPlugin interface. The only way to instantiate a RealTimeStylus object that accepts input from another RealTimeStylus object is to use the default constructor and implement the cascaded RealTimeStylus model. For more information about connecting two RealTimeStylus objects, see The Cascaded RealTimeStylus Model.

The RealTimeStylus object has two internal queues to carry the tablet pen data: an input queue and an 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.

  1. The RealTimeStylus object checks for plug-in data objects first on its input queue and then from the tablet pen data stream.
  2. 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.
  3. 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.
  4. The RealTimeStylus object then checks for the next plug-in data object to process.
  5. 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 user interface (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.

For more information about the notification methods, see Plug-in Data and the RealTimeStylus Class.

The following is a minimal scenario for using the RealTimeStylus object on a form that collects ink.

  1. Create a form that implements the IStylusAsyncPlugin interface.
  2. Create a RealTimeStylus object attached to a control on the form.
  3. Set interest in the StylusDown, Packets, and Stylus notifications in the form's DataInterest property.
  4. In the form's IStylusAsyncPlugin.StylusDown, IStylusAsyncPlugin.Packets, and IStylusAsyncPlugin.StylusUp methods, add code to handle the stylus down, packets, and stylus up notifications that are sent from the form's RealTimeStylus object.

For a sample of such an application, see the RealTimeStylus Ink Collection Sample.

Working with Tablet Objects

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.

The TabletPropertyDescription object contains a PacketPropertyId property and a TabletPropertyMetrics structure that describes the range, resolution, and units of the property for a specific Tablet object. The GetTabletPropertyDescriptionCollection method of the RealTimeStylus object takes a unique tablet identifier and returns a collection of TabletPropertyDescription objects supported by that tablet. The RealTimeStylus object's GetDesiredPacketDescription method returns an array of globally unique identifiers (GUIDs) for the packet properties that the RealTimeStylus object forwards to its plug-ins. The set of packet properties that is sent to the plug-ins for a given tablet is the intersection of the set returned by the GetTabletPropertyDescriptionCollection method and the set returned by the GetDesiredPacketDescription method. To modify the set of packet properties the RealTimeStylus object passes to its plug-ins, call the RealTimeStylus object's SetDesiredPacketDescription method.

For a list of the standard packet property GUIDs, see the PacketProperty class.

Special Considerations

The following list describes other points to take into consideration when using the RealTimeStylus object with a Tablet object.

Working with Tablet Pens

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. For information about how tablet pen and tablet pen button data is passed to plug-ins, see Plug-in Data and the RealTimeStylus Class.

To get an array of the Stylus objects that the RealTimeStylus object has encountered since it was last enabled, use the RealTimeStylus object's GetStyluses method.