Uso della classe RealTimeStylus
La classe RealTimeStylus fa parte delle API (Application Programming Interface) stylusInput. Le sezioni seguenti descrivono gli elementi chiave della classe RealTimeStylus e delle API StylusInput.
Creazione di un'istanza della classe RealTimeStylus
Quando si crea un oggetto RealTimeStylus , è possibile collegarlo a un handle di finestra o a un controllo . Il collegamento dell'oggetto RealTimeStylus a un handle di finestra richiede autorizzazioni aggiuntive. Per altre informazioni su queste autorizzazioni, vedere Considerazioni sull'attendibilità parziale per le API StylusInput.
Nota
Non è possibile collegare l'oggetto RealTimeStylus a una finestra o a un controllo in un processo diverso.
Se si usa il costruttore predefinito, si crea un oggetto RealTimeStylus che può accettare solo l'input da un altro oggetto RealTimeStylus . Per altre informazioni sulla connessione di due oggetti RealTimeStylus , vedere Il modello RealTimeStylus cascaded.
L'oggetto RealTimeStylus implementa l'interfaccia IDisposable .
Estensione della classe RealTimeStylus
Per consentire ai plug-in di interagire con il flusso di dati dalla penna del tablet, l'oggetto RealTimeStylus gestisce due raccolte plug-in, accessibili dai metodi GetStylusSyncPlugin e GetStylusAsyncPlugin in C++ e dalle proprietà SyncPluginCollection e AsyncPluginCollection nel codice gestito. È possibile aggiungere un plug-in chiamando il metodo AddStylusSyncPlugin o AddStylusAsyncPlugin dell'insieme all'interno della proprietà appropriata. Per altre informazioni sulla creazione e l'uso di plug-in, vedere Plug-in e la classe RealTimeStylus. Per informazioni su come decidere se creare un plug-in sincrono o asincrono per una determinata attività, vedere Considerazioni sul threading per le API StylusInput e considerazioni sulle prestazioni per le API StylusInput.
I plug-in sincroni devono implementare l'interfaccia IStylusSyncPlugin e i plug-in asincroni devono implementare l'interfaccia IStylusAsyncPlugin . Ogni plug-in ha una proprietà IStylusSyncPlugin.DataInterest o IStylusAsyncPlugin.DataInterest . L'oggetto RealTimeStylus chiama solo i metodi di notifica del plug-in per i metodi in cui è stato sottoscritto il plug-in. Per altre informazioni sui metodi di notifica, vedere Plug-in Data (Dati plug-in) e RealTimeStylus Class (Classe RealTimeStylus).
L'oggetto RealTimeStylus implementa l'interfaccia IStylusAsyncPlugin . L'unico modo per creare un'istanza di un oggetto RealTimeStylus che accetta input da un altro oggetto RealTimeStylus consiste nell'usare il costruttore predefinito e implementare il modello RealTimeStylus a catena. Per altre informazioni sulla connessione di due oggetti RealTimeStylus , vedere Il modello Cascaded RealTimeStylus.
L'oggetto RealTimeStylus ha due code interne che contengono i dati della penna del tablet, la coda di input e la coda di output. I dati della penna vengono convertiti in istanze delle classi nello spazio dei nomi Microsoft.StylusInput.PluginData . L'elenco seguente descrive come l'oggetto RealTimeStylus gestisce i dati della penna del tablet.
- L'oggetto RealTimeStylus verifica innanzitutto la presenza di oggetti dati plug-in nella coda di input e quindi dal flusso di dati della penna del tablet.
- L'oggetto RealTimeStylus invia un oggetto dati plug-in agli oggetti nella raccolta plug-in sincrona. Ogni plug-in sincrono può aggiungere dati alla coda di input o di output.
- Dopo aver inviato l'oggetto dati plug-in a tutti i membri della raccolta plug-in sincrona, l'oggetto dati plug-in viene posizionato nella coda di output dell'oggetto RealTimeStylus .
- L'oggetto RealTimeStylus controlla quindi la presenza dell'oggetto dati plug-in successivo da elaborare.
- Mentre la coda di output dell'oggetto RealTimeStylus contiene dati, l'oggetto RealTimeStylus invia un oggetto dati plug-in dalla coda di output agli oggetti nella raccolta di plug-in asincrona. Ogni plug-in asincrono può aggiungere dati alla coda di input o di output, ma poiché i plug-in asincroni vengono eseguiti nel thread dell'interfaccia utente, i dati vengono aggiunti alla coda in relazione ai dati della penna correnti che l'oggetto RealTimeStylus sta elaborando e non in relazione ai dati elaborati dal plug-in asincrono.
Il diagramma seguente illustra il flusso dei dati della penna del tablet tramite l'oggetto RealTimeStylus e le relative raccolte plug-in.
In questo diagramma i cerchi letterati "A" e "B" rappresentano i dati della penna per tablet già aggiunti alla coda di output dell'oggetto RealTimeStylus e che non sono ancora stati inviati alla raccolta di plug-in asincrona. Il cerchio "C" rappresenta i dati della penna del tablet che l'oggetto RealTimeStylus sta elaborando. Viene inviato alla raccolta di plug-in sincrona e inserita nella coda di output. Il cerchio vuoto rappresenta la posizione nella coda di output in cui vengono aggiunti i dati futuri della penna per tablet.
Per altre informazioni sull'aggiunta di dati specifici alla coda ed elaborati, vedere Plug-in Data (Dati plug-in) e RealTimeStylus Class (Classe RealTimeStylus).
Di seguito è riportato uno scenario minimo per l'utilizzo dell'oggetto RealTimeStylus in un modulo che raccoglie l'input penna.
- Creare un modulo che implementa l'interfaccia IStylusAsyncPlugin .
- Creare un oggetto RealTimeStylus associato a un controllo nel form.
- Impostare l'interesse per le notifiche StylusDown, Packets e StylusUp nella proprietà IStylusAsyncPlugin.DataInterest del modulo.
- Nei metodi StylusDown, Packets e StylusUp del modulo aggiungere codice per gestire lo stilo verso il basso, i pacchetti e le notifiche dello stilo inviate dall'oggetto RealTimeStylus del modulo.
Per un esempio di un'applicazione di questo tipo, vedere l'esempio di raccolta di input penna RealTimeStylus.
Utilizzo di oggetti tablet
Ogni oggetto RealTimeStylus abilitato mantiene un elenco di identificatori univoci per gli oggetti Tablet con cui può interagire. L'oggetto RealTimeStylus espone due metodi per la conversione tra l'identificatore univoco e l'oggetto Tablet : i metodi GetTabletContextIdFromTablet e GetTabletFromTabletContextId .
L'oggetto TabletPropertyDescription (nel codice gestito) contiene una proprietà PacketPropertyId e una struttura TabletPropertyMetrics che descrive l'intervallo, la risoluzione e le unità della proprietà per un oggetto Tablet specifico. Il metodo GetDesiredPacketDescription dell'oggetto RealTimeStylus restituisce una matrice di identificatori univoci globali (GUID) per le proprietà di pacchetto inoltrate dall'oggetto RealTimeStylus ai relativi plug-in quando tali proprietà di pacchetto sono disponibili. Per modificare il set di proprietà del pacchetto, l'oggetto RealTimeStylus passa ai plug-in, chiamare il metodo SetDesiredPacketDescription dell'oggetto RealTimeStylus. Il metodo GetTabletPropertyDescriptionCollection (nel codice gestito) dell'oggetto RealTimeStylus accetta un identificatore di tablet univoco e restituisce una raccolta di oggetti TabletPropertyDescription . Queste proprietà di pacchetto rappresentano il subset di proprietà supportate dal tablet restituito dal metodo GetDesiredPacketDescription .
Per un elenco dei GUID della proprietà del pacchetto standard, vedere la classe Constants PacketPropertyGuids .
Considerazioni speciali
Nell'elenco seguente vengono descritti altri punti da prendere in considerazione quando si usa l'oggetto RealTimeStylus con un oggetto Tablet .
- Il metodo SetDesiredPacketDescription può essere chiamato solo quando l'oggetto Tablet è disabilitato. L'oggetto RealTimeStylus può modificare l'elenco delle proprietà del pacchetto desiderate; Chiamare pertanto il metodo GetDesiredPacketDescription dopo la chiamata al metodo SetDesiredPacketDescription per determinare le proprietà del pacchetto che l'oggetto RealTimeStylus può inoltrare ai plug-in. È garantito che un tablet supporti solo i valori X, Y e PacketStatus per PacketProperty. Pertanto, la progettazione del plug-in potrebbe dover tenere conto della ricezione di un minor numero di proprietà del pacchetto rispetto alle esigenze.
- Il metodo GetTabletPropertyDescriptionCollection (per il codice gestito) può essere chiamato solo quando l'oggetto RealTimeStylus è abilitato. Poiché la notifica può essere inviata ai plug-in asincroni dopo che l'oggetto RealTimeStylus è stato disabilitato, potrebbe essere necessario memorizzare nella cache le informazioni per ogni oggetto Tablet . Il metodo GetTabletPropertyDescriptionCollection restituisce un elenco delle proprietà del pacchetto desiderate supportate dal tablet specificato.
- Quando l'oggetto RealTimeStylus è abilitato, ogni plug-in riceve una chiamata al relativo metodo RealTimeStylusEnabled . L'oggetto RealTimeStylusEnabledData passato nella notifica contiene una raccolta di identificatori di contesto per i tablet disponibili al momento dell'abilitazione dell'oggetto RealTimeStylus .
- Quando un tablet che l'oggetto RealTimeStylus può utilizzare viene aggiunto o rimosso dal Tablet PC mentre l'oggetto RealTimeStylus è abilitato, l'oggetto RealTimeStylus notifica ai plug-in che un oggetto Tablet è stato aggiunto o rimosso. Per altre informazioni, vedere Plug-in Data (Dati plug-in) e RealTimeStylus Class (Classe RealTimeStylus).
Uso delle penne tablet
L'oggetto RealTimeStylus passa informazioni sulla penna del tablet ai relativi plug-in in diversi metodi di notifica. Le informazioni sulla penna del tablet sono rappresentate da un oggetto Stilo ottenuto tramite il metodo GetStyluses . Questo oggetto è una rappresentazione della penna del tablet al momento della raccolta dei dati. Poiché i plug-in ricevono i dati della penna del tablet come parte del flusso di dati della penna del tablet, i plug-in devono usare le informazioni nell'oggetto Stilo invece di verificare lo stato corrente di una particolare penna per tablet tramite la classe Cursor . Per informazioni sul modo in cui i dati della penna e della penna per tablet vengono passati ai plug-in, vedere Dati plug-in e la classe RealTimeStylus.
Per ottenere una matrice degli oggetti Stylus rilevati dall'oggetto RealTimeStylus dopo l'ultima abilitazione, utilizzare il metodo GetStylus dell'oggetto RealTimeStylus.
Argomenti correlati