Arbeiten mit der RealTimeStylus-Klasse
Die RealTimeStylus-Klasse ist Teil der StylusInput-APIs (Application Programming Interfaces). In den folgenden Abschnitten werden wichtige Elemente der RealTimeStylus-Klasse und der StylusInput-APIs beschrieben.
Instanziieren der RealTimeStylus-Klasse
Wenn Sie ein RealTimeStylus-Objekt erstellen, haben Sie die Möglichkeit, es an ein Fensterhandle oder ein Steuerelement anzufügen. Das Anfügen des RealTimeStylus-Objekts an ein Fensterhandle erfordert zusätzliche Berechtigungen. Weitere Informationen zu diesen Berechtigungen finden Sie unter Überlegungen zur teilweisen Vertrauensstellung für die StylusInput-APIs.
Hinweis
Sie können das RealTimeStylus-Objekt nicht in einem anderen Prozess an ein Fenster oder Steuerelement anfügen.
Wenn Sie den Standardkonstruktor verwenden, erstellen Sie ein RealTimeStylus-Objekt , das nur Eingaben von einem anderen RealTimeStylus-Objekt akzeptieren kann. Weitere Informationen zum Verbinden von zwei RealTimeStylus-Objekten finden Sie unter Das kaskadierte RealTimeStylus-Modell.
Das RealTimeStylus-Objekt implementiert die IDisposable-Schnittstelle .
Erweitern der RealTimeStylus-Klasse
Damit Ihre Plug-Ins mit dem Datenstrom des Tablet-Stifts interagieren können, verwaltet das RealTimeStylus-Objekt zwei Plug-In-Auflistungen, auf die über die GetStylusSyncPlugin - und getStylusAsyncPluginPlugin-Methoden in C++ und über die Eigenschaften SyncPluginCollection und AsyncPluginCollection in verwaltetem Code zugegriffen werden kann. Sie können ein Plug-In hinzufügen, indem Sie entweder die AddStylusSyncPlugin - oder die AddStylusAsyncPlugin-Methode der Auflistung innerhalb der entsprechenden Eigenschaft aufrufen. Weitere Informationen zum Erstellen und Verwenden von Plug-Ins finden Sie unter Plug-Ins und die RealTimeStylus-Klasse. Informationen zur Entscheidung, ob ein synchrones oder asynchrones Plug-In für eine bestimmte Aufgabe erstellt werden soll, finden Sie unter Threading Considerations for the StylusInput APIs and Performance Considerations for the StylusInput APIs.
Synchrone Plug-Ins müssen die IStylusSyncPlugin-Schnittstelle implementieren, und asynchrone Plug-Ins müssen die IStylusAsyncPlugin-Schnittstelle implementieren. Jedes Plug-In verfügt über eine IStylusSyncPlugin.DataInterest - oder IStylusAsyncPlugin.DataInterest-Eigenschaft . Das RealTimeStylus-Objekt ruft nur die Benachrichtigungsmethoden des Plug-Ins für Methoden auf, die das Plug-In abonniert hat. Weitere Informationen zu den Benachrichtigungsmethoden finden Sie unter Plug-In-Daten und die RealTimeStylus-Klasse.
Das RealTimeStylus-Objekt implementiert die IStylusAsyncPlugin-Schnittstelle . Die einzige Möglichkeit zum Instanziieren eines RealTimeStylus-Objekts , das Eingaben von einem anderen RealTimeStylus-Objekt akzeptiert, besteht darin, den Standardkonstruktor zu verwenden und das kaskadierte RealTimeStylus-Modell zu implementieren. Weitere Informationen zum Verbinden von zwei RealTimeStylus-Objekten finden Sie unter Das Kaskadierte RealTimeStylus-Modell.
Das RealTimeStylus-Objekt verfügt über zwei interne Warteschlangen, die die Tablet-Stiftdaten enthalten, die Eingabewarteschlange und die Ausgabewarteschlange. Die Stiftdaten werden in Instanzen der Klassen im Microsoft.StylusInput.PluginData-Namespace konvertiert. In der folgenden Liste wird beschrieben, wie das RealTimeStylus-Objekt die Tablet-Stiftdaten verarbeitet.
- Das RealTimeStylus-Objekt sucht zuerst in seiner Eingabewarteschlange und dann aus dem Tablet-Stiftdatenstrom nach Plug-In-Datenobjekten.
- Das RealTimeStylus-Objekt sendet ein Plug-In-Datenobjekt an die Objekte in der synchronen Plug-In-Auflistung. Jedes synchrone Plug-In kann der Eingabe- oder Ausgabewarteschlange Daten hinzufügen.
- Nachdem das Plug-In-Datenobjekt an alle Member der synchronen Plug-In-Auflistung gesendet wurde, wird das Plug-In-Datenobjekt in der Ausgabewarteschlange des RealTimeStylus-Objekts platziert.
- Das RealTimeStylus-Objekt sucht dann nach dem nächsten zu verarbeitenden Plug-In-Datenobjekt.
- Während die Ausgabewarteschlange des RealTimeStylus-Objekts Daten enthält, sendet das RealTimeStylus-Objekt ein Plug-In-Datenobjekt aus seiner Ausgabewarteschlange an die Objekte in seiner asynchronen Plug-In-Auflistung. Jedes asynchrone Plug-In kann Daten entweder der Eingabe- oder Ausgabewarteschlange hinzufügen, aber da die asynchronen Plug-Ins im Benutzeroberflächenthread (UI) ausgeführt werden, werden die Daten der Warteschlange in Bezug auf die aktuellen Stiftdaten hinzugefügt, die vom RealTimeStylus-Objekt verarbeitet werden, und nicht in Bezug auf die Daten, die das asynchrone Plug-In verarbeitet.
Das folgende Diagramm veranschaulicht den Fluss von Tablet-Stiftdaten durch das RealTimeStylus-Objekt und seine Plug-In-Auflistungen.
In diesem Diagramm stellen die Kreise mit den Buchstaben "A" und "B" Tablet-Stiftdaten dar, die bereits der Ausgabewarteschlange des RealTimeStylus-Objekts hinzugefügt wurden und noch nicht an die asynchrone Plug-In-Auflistung gesendet wurden. Der kreisförmige Schriftzug "C" stellt die Daten des Tablet-Stifts dar, die das RealTimeStylus-Objekt derzeit verarbeitet. Sie wird an die synchrone Plug-In-Sammlung gesendet und in der Ausgabewarteschlange platziert. Der leere Kreis stellt die Position in der Ausgabewarteschlange dar, an der zukünftige Tablet-Stiftdaten hinzugefügt werden.
Weitere Informationen dazu, wie der Warteschlange bestimmte Daten hinzugefügt und verarbeitet werden, finden Sie unter Plug-In-Daten und die RealTimeStylus-Klasse.
Es folgt ein minimales Szenario für die Verwendung des RealTimeStylus-Objekts in einem Formular, das Freihandeingaben sammelt.
- Erstellen Sie ein Formular, das die IStylusAsyncPlugin-Schnittstelle implementiert.
- Erstellen Sie ein RealTimeStylus-Objekt , das an ein Steuerelement im Formular angefügt ist.
- Legen Sie das Interesse an den Benachrichtigungen StylusDown, Packets und StylusUp in der IStylusAsyncPlugin.DataInterest-Eigenschaft des Formulars fest.
- Fügen Sie in den Methoden StylusDown, Packets und StylusUp des Formulars Code hinzu, um den Stift nach unten, Pakete und Benachrichtigungen nach oben zu behandeln, die vom RealTimeStylus-Objekt des Formulars gesendet werden.
Ein Beispiel für eine solche Anwendung finden Sie im Beispiel für die RealTimeStylus-Freihandsammlung.
Arbeiten mit Tablet-Objekten
Jedes aktivierte RealTimeStylus-Objekt verwaltet eine Liste eindeutiger Bezeichner für die Tablet-Objekte , mit denen es interagieren kann. Das RealTimeStylus-Objekt macht zwei Methoden für die Übersetzung zwischen dem eindeutigen Bezeichner und dem Tablet-Objekt verfügbar: die Methoden GetTabletContextIdFromTablet und GetTabletFromTabletContextId .
Das TabletPropertyDescription-Objekt (in verwaltetem Code) enthält eine PacketPropertyId-Eigenschaft und eine TabletPropertyMetrics-Struktur , die den Bereich, die Auflösung und die Einheiten der Eigenschaft für ein bestimmtes Tablet-Objekt beschreibt. Die GetDesiredPacketDescription-Methode des RealTimeStylus-Objekts gibt ein Array von GUIDs (Globally Unique Identifiers) für die Paketeigenschaften zurück, die das RealTimeStylus-Objekt an seine Plug-Ins weiterleitet, wenn diese Paketeigenschaften verfügbar sind. Um die Paketeigenschaften zu ändern, die das RealTimeStylus-Objekt an seine Plug-Ins übergibt, rufen Sie die SetDesiredPacketDescription-Methode des RealTimeStylus-Objekts auf. Die GetTabletPropertyDescriptionCollection-Methode (in verwaltetem Code) des RealTimeStylus-Objekts akzeptiert einen eindeutigen Tablet-Bezeichner und gibt eine Auflistung von TabletPropertyDescription-Objekten zurück. Diese Paketeigenschaften stellen die Teilmenge der Eigenschaften dar, die vom Tablet unterstützt werden und von der GetDesiredPacketDescription-Methode zurückgegeben werden.
Eine Liste der STANDARD-GUIDs für die Paketeigenschaft finden Sie in der Klasse PacketPropertyGuids Constants .
Besondere Überlegungen
In der folgenden Liste werden weitere Punkte beschrieben, die bei der Verwendung des RealTimeStylus-Objekts mit einem Tablet-Objekt zu berücksichtigen sind.
- Die SetDesiredPacketDescription-Methode kann nur aufgerufen werden, während das Tablet-Objekt deaktiviert ist. Das RealTimeStylus-Objekt kann die Liste der gewünschten Paketeigenschaften ändern. Rufen Sie daher die GetDesiredPacketDescription-Methode nach dem Aufruf der SetDesiredPacketDescription-Methode auf, um zu bestimmen, welche Paketeigenschaften das RealTimeStylus-Objekt an seine Plug-Ins weiterleiten kann. Ein Tablet unterstützt garantiert nur die Werte X, Y und PacketStatus für PacketProperty. Daher muss Ihr Plug-In-Design möglicherweise berücksichtigen, dass weniger Paketeigenschaften als gewünscht empfangen werden.
- Die GetTabletPropertyDescriptionCollection-Methode (für verwalteten Code) kann nur aufgerufen werden, wenn das RealTimeStylus-Objekt aktiviert ist. Da Benachrichtigungen an die asynchronen Plug-Ins gesendet werden können, nachdem das RealTimeStylus-Objekt deaktiviert wurde, müssen Sie möglicherweise die Informationen für jedes Tablet-Objekt zwischenspeichern. Die GetTabletPropertyDescriptionCollection-Methode gibt eine Liste der gewünschten Paketeigenschaften zurück, die vom angegebenen Tablet unterstützt werden.
- Wenn das RealTimeStylus-Objekt aktiviert ist, empfängt jedes Plug-In einen Aufruf seiner RealTimeStylusEnabled-Methode . Das in der Benachrichtigung übergebene RealTimeStylusEnabledData-Objekt enthält eine Auflistung der Kontextbezeichner für die verfügbaren Tablets zum Zeitpunkt der Aktivierung des RealTimeStylus-Objekts .
- Wenn ein Tablet, das das RealTimeStylus-Objekt verwenden kann, dem Tablet-PC hinzugefügt oder daraus entfernt wird, während das RealTimeStylus-Objekt aktiviert ist, benachrichtigt das RealTimeStylus-Objekt seine Plug-Ins, dass ein Tablet-Objekt hinzugefügt oder entfernt wurde. Weitere Informationen finden Sie unter Plug-In-Daten und die RealTimeStylus-Klasse.
Arbeiten mit Tablet-Stiften
Das RealTimeStylus-Objekt übergibt Informationen über den Tablet-Stift an seine Plug-Ins in einer Reihe der Benachrichtigungsmethoden. Informationen zum Tablet-Stift werden durch ein Stylus-Objekt dargestellt, das über die GetStyluses-Methode abgerufen wird. Dieses Objekt ist eine Darstellung des Tablet-Stifts zum Zeitpunkt der Erfassung der Daten. Da Plug-Ins die Tablet-Stiftdaten als Teil des Tablet-Stiftdatenstroms empfangen, sollten die Plug-Ins die Informationen im Stylus-Objekt verwenden, anstatt den aktuellen Zustand eines bestimmten Tablet-Stifts über die Cursor-Klasse zu überprüfen. Informationen dazu, wie Tablet-Stift- und Tablet-Stift-Schaltflächendaten an Plug-Ins übergeben werden, finden Sie unter Plug-In-Daten und die RealTimeStylus-Klasse.
Verwenden Sie die GetStyluses-Methode des RealTimeStylus-Objekts, um ein Array der Stylus-Objekte abzurufen, die das RealTimeStylus-Objekt seit seiner letzten Aktivierung gefunden hat.
Zugehörige Themen