Arbeiten mit der RealTimeStylus-Klasse

Die RealTimeStylus-Klasse ist Teil der StylusInput-Anwendungsprogrammierschnittstellen (Application Programming Interfaces, APIs). 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, können Sie es an ein Fensterhandle oder ein Steuerelement anfügen. Zum Anfügen des RealTimeStylus-Objekts an ein Fensterhandle sind zusätzliche Berechtigungen erforderlich. Weitere Informationen zu diesen Berechtigungen finden Sie unter Überlegungen zur teilweisen Vertrauenswürdigkeit für die StylusInput-APIs.

Hinweis

Sie können das RealTimeStylus-Objekt nicht an ein Fenster oder Steuerelement in einem anderen Prozess 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 aus dem Tablettstift interagieren können, verwaltet das RealTimeStylus-Objekt zwei Plug-In-Sammlungen, auf die über die Methoden GetStylusSyncPlugin und GetStylusAsyncPlugin in C++ sowie über die SyncPluginCollection- und AsyncPluginCollection-Eigenschaften in verwaltetem Code zugegriffen werden kann. Sie können ein Plug-In hinzufügen, indem Sie entweder die AddStylusSyncPlugin-Methode 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 (Threadingüberlegungen für die StylusInput-APIs) und Performance Considerations for the StylusInput APIs (Überlegungen zur Leistung der 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 die IStylusSyncPlugin.DataInterest- oder IStylusAsyncPlugin.DataInterest-Eigenschaft. Das RealTimeStylus-Objekt ruft nur die Benachrichtigungsmethoden des Plug-Ins für Methoden auf, in denen das Plug-In abonniert wurde. Weitere Informationen zu den Benachrichtigungsmethoden finden Sie unter Plug-In-Daten und 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 Tablettstiftdaten enthalten: die Eingabewarteschlange und die Ausgabewarteschlange. Die Stiftdaten werden in Instanzen der Klassen im Namespace Microsoft.StylusInput.PluginData konvertiert. In der folgenden Liste wird beschrieben, wie das RealTimeStylus-Objekt die Tablettstiftdaten behandelt.

  1. Das RealTimeStylus-Objekt sucht zuerst in der Eingabewarteschlange und dann aus dem Tablettstiftdatenstrom nach Plug-In-Datenobjekten.
  2. Das RealTimeStylus-Objekt sendet ein Plug-In-Datenobjekt an die Objekte in seiner synchronen Plug-In-Auflistung. Jedes synchrone Plug-In kann der Eingabe- oder Ausgabewarteschlange Daten hinzufügen.
  3. Nachdem das Plug-In-Datenobjekt an alle Member der synchronen Plug-In-Sammlung gesendet wurde, wird das Plug-In-Datenobjekt in der Ausgabewarteschlange des RealTimeStylus-Objekts platziert.
  4. Das RealTimeStylus-Objekt sucht dann nach dem nächsten zu verarbeitenden Plug-In-Datenobjekt.
  5. 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-Sammlung. Jedes asynchrone Plug-In kann der Eingabe- oder Ausgabewarteschlange Daten hinzufügen. Da die asynchronen Plug-Ins jedoch im Benutzeroberflächenthread ausgeführt werden, werden die Daten der Warteschlange in Bezug auf die aktuellen Stiftdaten hinzugefügt, die das RealTimeStylus-Objekt verarbeitet, und nicht in Bezug auf die Daten, die das asynchrone Plug-In verarbeitet.

Das folgende Diagramm veranschaulicht den Fluss von Tablettstiftdaten durch das RealTimeStylus-Objekt und seine Plug-In-Sammlungen.

illustratiom mit Tablett-PC-Stiftdatenfluss

In diesem Diagramm stellen die Kreise mit den Buchstaben "A" und "B" Tablettstiftdaten dar, die der Ausgabewarteschlange des RealTimeStylus-Objekts bereits hinzugefügt und noch nicht an die asynchrone Plug-In-Sammlung gesendet wurden. Der Kreis mit dem Buchstaben "C" stellt die Tablettstiftdaten 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 Tablettstiftdaten hinzugefügt werden.

Weitere Informationen dazu, wie bestimmte Daten der Warteschlange hinzugefügt und verarbeitet werden, finden Sie unter Plug-In-Daten und der RealTimeStylus-Klasse.

Im Folgenden wird ein minimales Szenario für die Verwendung des RealTimeStylus-Objekts in einem Formular dargestellt, das Ink sammelt.

  1. Erstellen Sie ein Formular, das die IStylusAsyncPlugin-Schnittstelle implementiert.
  2. Erstellen Sie ein RealTimeStylus-Objekt, das an ein Steuerelement im Formular angefügt ist.
  3. Legen Sie das Interesse an den Benachrichtigungen StylusDown, Packets und StylusUp in der IStylusAsyncPlugin.DataInterest-Eigenschaft des Formulars fest.
  4. Fügen Sie in den StylusDown-, Packets-und StylusUp-Methoden des Formulars Code hinzu, um die Benachrichtigungen für Denkstift, Pakete und Stifte nach oben zu behandeln, die vom RealTimeStylus-Objekt des Formulars gesendet werden.

Ein Beispiel für eine solche Anwendung finden Sie unter RealTimeStylus Ink Collection Sample.

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 den Satz von 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 verwendet 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-Paketeigenschafts-GUIDs finden Sie in der PacketPropertyGuids Constants-Klasse.

Besondere Überlegungen

In der folgenden Liste werden andere 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 nur die X-, Y- und PacketStatus-Werte für PacketProperty. Daher muss Ihr Plug-In-Entwurf möglicherweise berücksichtigen, dass weniger Paketeigenschaften als gewünscht empfangen werden.
  • Die GetTabletPropertyDescriptionCollection-Methode (für verwalteten Code) kann nur aufgerufen werden, während 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 vom RealTimeStylus-Objekt verwendet werden 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 realTimeStylus-Klasse.

Arbeiten mit Tablettstiften

Das RealTimeStylus-Objekt übergibt Informationen über den Tablettstift an seine Plug-Ins in einer Reihe von Benachrichtigungsmethoden. Informationen zum Tablettstift werden durch ein Tablettstiftobjekt dargestellt, das über die GetStyluses-Methode erfasst wird. Dieses Objekt ist eine Darstellung des Tablettstifts zum Zeitpunkt der Datensammelung. Da Plug-Ins die Tablettstiftdaten als Teil des Tablettstiftdatenstroms empfangen, sollten die Plug-Ins die Informationen im Tablettstiftobjekt verwenden, anstatt den aktuellen Zustand eines bestimmten Tablettstifts über die Cursor-Klasse zu überprüfen. Informationen dazu, wie Tablettstift- und Tablettstift-Schaltflächendaten an Plug-Ins übergeben werden, finden Sie unter Plug-In-Daten und realTimeStylus-Klasse.

Verwenden Sie die GetStyluses-Methode des RealTimeStylus-Objekts, um ein Array der Stiftobjekte abzurufen, auf die das RealTimeStylus-Objekt seit seiner letzten Aktivierung gestoßen ist.

Microsoft.Ink.Tablet

Microsoft.StylusInput.RealTimeStylus

Das kaskadierte RealTimeStylus-Modell

Überlegungen zur teilweisen Vertrauenswürdigkeit für die StylusInput-APIs

Plug-In-Daten und die RealTimeStylus-Klasse

Threadingüberlegungen für die StylusInput-APIs