Utilisation de la classe RealTimeStylus
La classe RealTimeStylus fait partie des interfaces de programmation d’applications (API) StylusInput. Les sections suivantes décrivent les éléments clés de la classe RealTimeStylus et des API StylusInput.
Instanciation de la classe RealTimeStylus
Lorsque vous créez un objet RealTimeStylus , vous avez la possibilité de l’attacher à un handle de fenêtre ou à un contrôle. L’attachement de l’objet RealTimeStylus à un handle de fenêtre nécessite des autorisations supplémentaires. Pour plus d’informations sur ces autorisations, consultez Considérations relatives à la confiance partielle pour les API StylusInput.
Notes
Vous ne pouvez pas attacher l’objet RealTimeStylus à une fenêtre ou à un contrôle dans un autre processus.
Si vous utilisez le constructeur par défaut, vous créez un objet RealTimeStylus qui peut uniquement accepter l’entrée d’un autre objet RealTimeStylus . Pour plus d’informations sur la connexion de deux objets RealTimeStylus , consultez Le modèle RealTimeStylus en cascade.
L’objet RealTimeStylus implémente l’interface IDisposable .
Extension de la classe RealTimeStylus
Pour permettre à vos plug-ins d’interagir avec le flux de données à partir du stylet de tablette, l’objet RealTimeStylus gère deux collections de plug-ins, qui sont accessibles par les méthodes GetStylusSyncPlugin et GetStylusAsyncPlugin dans C++ et par les propriétés SyncPluginCollection et AsyncPluginCollection dans le code managé. Vous pouvez ajouter un plug-in en appelant la méthode AddStylusSyncPlugin ou AddStylusAsyncPlugin de la collection dans la propriété appropriée. Pour plus d’informations sur la création et l’utilisation de plug-ins, consultez Plug-ins et la classe RealTimeStylus. Pour plus d’informations sur la création d’un plug-in synchrone ou asynchrone pour une tâche particulière, consultez Considérations relatives au thread pour les API StylusInput et Considérations sur les performances pour les API StylusInput.
Les plug-ins synchrones doivent implémenter l’interface IStylusSyncPlugin , et les plug-ins asynchrones doivent implémenter l’interface IStylusAsyncPlugin . Chaque plug-in a une propriété IStylusSyncPlugin.DataInterest ou IStylusAsyncPlugin.DataInterest . L’objet RealTimeStylus appelle uniquement les méthodes de notification du plug-in pour les méthodes auxquelles le plug-in s’est abonné. Pour plus d’informations sur les méthodes de notification, consultez Plug-in Data and the RealTimeStylus Class.
L’objet RealTimeStylus implémente l’interface IStylusAsyncPlugin . La seule façon d’instancier un objet RealTimeStylus qui accepte l’entrée d’un autre objet RealTimeStylus consiste à utiliser le constructeur par défaut et à implémenter le modèle RealTimeStylus en cascade. Pour plus d’informations sur la connexion de deux objets RealTimeStylus , consultez Le modèle RealTimeStylus en cascade.
L’objet RealTimeStylus a deux files d’attente internes qui transportent les données du stylet de tablette, la file d’attente d’entrée et la file d’attente de sortie. Les données du stylet sont converties en instances des classes dans l’espace de noms Microsoft.StylusInput.PluginData . La liste suivante décrit comment l’objet RealTimeStylus gère les données du stylet de tablette.
- L’objet RealTimeStylus recherche d’abord les objets de données du plug-in dans sa file d’attente d’entrée, puis à partir du flux de données du stylet de tablette.
- L’objet RealTimeStylus envoie un objet de données de plug-in aux objets de sa collection de plug-ins synchrones. Chaque plug-in synchrone peut ajouter des données à la file d’attente d’entrée ou de sortie.
- Une fois que l’objet de données du plug-in a été envoyé à tous les membres de la collection de plug-ins synchrones, l’objet de données de plug-in est placé dans la file d’attente de sortie de l’objet RealTimeStylus .
- L’objet RealTimeStylus recherche ensuite l’objet de données de plug-in suivant à traiter.
- Alors que la file d’attente de sortie de l’objet RealTimeStylus contient des données, l’objet RealTimeStylus envoie un objet de données de plug-in de sa file d’attente de sortie aux objets de sa collection de plug-ins asynchrone. Chaque plug-in asynchrone peut ajouter des données à la file d’attente d’entrée ou de sortie, mais étant donné que les plug-ins asynchrones s’exécutent sur le thread d’interface utilisateur, les données sont ajoutées à la file d’attente par rapport aux données de stylet actuelles traitées par l’objet RealTimeStylus , et non par rapport aux données que le plug-in asynchrone traite.
Le diagramme suivant illustre le flux des données du stylet de tablette via l’objet RealTimeStylus et ses collections de plug-ins.
Dans ce diagramme, les cercles « A » et « B » représentent des données de stylet de tablette qui ont déjà été ajoutées à la file d’attente de sortie de l’objet RealTimeStylus et qui n’ont pas encore été envoyées à la collection de plug-ins asynchrones. Le cercle « C » représente les données du stylet de tablette que l’objet RealTimeStylus traite actuellement. Il est envoyé à la collection de plug-ins synchrones et placé dans la file d’attente de sortie. Le cercle vide représente la position dans la file d’attente de sortie où les données futures du stylet de tablette sont ajoutées.
Pour plus d’informations sur la façon dont des données spécifiques sont ajoutées à la file d’attente et traitées, consultez Plug-in Data and the RealTimeStylus Class.
Voici un scénario minimal d’utilisation de l’objet RealTimeStylus sur un formulaire qui collecte l’entrée manuscrite.
- Créez un formulaire qui implémente l’interface IStylusAsyncPlugin .
- Créez un objet RealTimeStylus attaché à un contrôle sur le formulaire.
- Définissez l’intérêt pour les notifications StylusDown, Packets et StylusUp dans la propriété IStylusAsyncPlugin.DataInterest du formulaire.
- Dans les méthodes StylusDown, Packets et StylusUp du formulaire, ajoutez du code pour gérer les notifications stylus down, packets et stylus up envoyées à partir de l’objet RealTimeStylus du formulaire.
Pour obtenir un exemple d’une telle application, consultez l’exemple de collection d’encres RealTimeStylus.
Utilisation d’objets Tablet
Chaque objet RealTimeStylus activé conserve une liste d’identificateurs uniques pour les objets Tablet avec lesquels il peut interagir. L’objet RealTimeStylus expose deux méthodes de traduction entre l’identificateur unique et l’objet Tablet : les méthodes GetTabletContextIdFromTablet et GetTabletFromTabletContextId .
L’objet TabletPropertyDescription (en code managé) contient une propriété PacketPropertyId et une structure TabletPropertyMetrics qui décrit la plage, la résolution et les unités de la propriété pour un objet Tablet spécifique. La méthode GetDesiredPacketDescription de l’objet RealTimeStylus retourne un tableau d’identificateurs globaux uniques (GUID) pour les propriétés de paquet que l’objet RealTimeStylus transfère à ses plug-ins lorsque ces propriétés de paquet sont disponibles. Pour modifier le jeu de propriétés de paquets que l’objet RealTimeStylus transmet à ses plug-ins, appelez la méthode SetDesiredPacketDescription de l’objet RealTimeStylus. La méthode GetTabletPropertyDescriptionCollection (en code managé) de l’objet RealTimeStylus prend un identificateur de tablette unique et retourne une collection d’objets TabletPropertyDescription . Ces propriétés de paquet représentent le sous-ensemble de propriétés prises en charge par la tablette qui sont retournées par la méthode GetDesiredPacketDescription .
Pour obtenir la liste des GUID de propriété de paquet standard, consultez la classe PacketPropertyGuids Constants .
Points particuliers à prendre en compte
La liste suivante décrit d’autres points à prendre en considération lors de l’utilisation de l’objet RealTimeStylus avec un objet Tablet .
- La méthode SetDesiredPacketDescription ne peut être appelée que lorsque l’objet Tablet est désactivé. L’objet RealTimeStylus peut modifier la liste des propriétés de paquet souhaitées ; Par conséquent, appelez la méthode GetDesiredPacketDescription après l’appel à la méthode SetDesiredPacketDescription pour déterminer les propriétés de paquet que l’objet RealTimeStylus peut transférer à ses plug-ins. Une tablette ne prend en charge que les valeurs X, Y et PacketStatus pour PacketProperty. Par conséquent, votre conception de plug-in peut avoir besoin de prendre en compte la réception de moins de propriétés de paquets que souhaité.
- La méthode GetTabletPropertyDescriptionCollection (pour le code managé) ne peut être appelée que lorsque l’objet RealTimeStylus est activé. Étant donné que la notification peut être envoyée aux plug-ins asynchrones après la désactivation de l’objet RealTimeStylus , vous devrez peut-être mettre en cache les informations de chaque objet Tablet . La méthode GetTabletPropertyDescriptionCollection retourne une liste des propriétés de paquet souhaitées qui sont prises en charge par la tablette spécifiée.
- Lorsque l’objet RealTimeStylus est activé, chaque plug-in reçoit un appel à sa méthode RealTimeStylusEnabled . L’objet RealTimeStylusEnabledData passé dans la notification contient une collection des identificateurs de contexte pour les tablettes disponibles au moment où l’objet RealTimeStylus est activé.
- Lorsqu’une tablette que l’objet RealTimeStylus peut utiliser est ajoutée ou supprimée du Tablet PC alors que l’objet RealTimeStylus est activé, l’objet RealTimeStylus avertit ses plug-ins qu’un objet Tablet a été ajouté ou supprimé. Pour plus d’informations, consultez Plug-in Data and the RealTimeStylus Class.
Utilisation des stylets tablet
L’objet RealTimeStylus transmet des informations sur le stylet de la tablette à ses plug-ins dans un certain nombre de méthodes de notification. Les informations sur le stylet de tablette sont représentées par un objet Stylus , obtenu via la méthode GetStyluses . Cet objet est une représentation du stylet de tablette au moment où les données ont été collectées. Étant donné que les plug-ins reçoivent les données du stylet de tablette dans le cadre du flux de données du stylet de tablette, les plug-ins doivent utiliser les informations de l’objet Stylus au lieu de vérifier l’état actuel d’un stylet de tablette particulier via la classe Cursor . Pour plus d’informations sur la façon dont les données du stylet de tablette et du bouton de stylet de tablette sont transmises aux plug-ins, consultez Plug-in Data and the RealTimeStylus Class.
Pour obtenir un tableau des objets Stylus rencontrés par l’objet RealTimeStylus depuis sa dernière activation, utilisez la méthode GetStyluses de l’objet RealTimeStylus.
Rubriques connexes