外掛程式資料和 RealTimeStylus 類別
RealTimeStylus類別的外掛程式必須實作IStylusSyncPlugin或IStylusAsyncPlugin介面，或兩者。 雖然您必須實作所有外掛程式介面方法，但外掛程式只會接收外掛程式 Microsoft.StylusInput.IStylusSyncPlugin.DataInterest 或 Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest 屬性中標幟的方法呼叫。
介面上定義的方法會使用 Microsoft.StylusInput.PluginData 命名空間中的 物件，將手寫筆資料傳遞至外掛程式。下表描述通知方法中參數的資料物件，並列出與通知相關聯的 DataInterestMask 值。
| 外掛程式資料 | DataInterestMask 值 | Description |
|---|---|---|
| CustomStylusData | CustomStylusDataAdded | 外掛程式新增的自訂應用程式資料。 |
| ErrorData | 錯誤 |
RealTimeStylus物件在回應其中一個外掛程式中未處理的例外狀況時所新增的錯誤資訊。 |
| InAirPacketsData | InAirPackets | 手寫筆在數位板上方無線時，手寫筆的封包資訊。 |
| PacketsData | 封包 | 手寫筆觸控數位板時的手寫筆動作封包資訊。 |
| RealTimeStylusDisabledData | RealTimeStylusDisabled |
RealTimeStylus物件在停用時所新增的資訊。 |
| RealTimeStylusEnabledData | RealTimeStylusEnabled |
啟用 RealTimeStylus物件時所新增的資訊。 |
| StylusButtonDownData | StylusButtonDown | 正在按下之特定手寫筆按鈕的相關資訊。 |
| StylusButtonUpData | 手寫筆按鈕Up | 正在釋放之特定手寫筆按鈕的相關資訊。 |
| 手寫筆DownData | 手寫筆Down | 手寫筆的封包資訊，因為手寫筆會與數位板連絡。 |
| StylusInRangeData | 手寫筆InRange | 輸入 RealTimeStylus 物件輸入區域的特定手寫筆資訊，或輸入 RealTimeStylus 物件輸入區域上方數位板的偵測範圍。 |
| StylusOutOfRangeData | 手寫筆OutOfRange | 有關離開 RealTimeStylus 物件輸入區域的特定手寫筆資訊，或離開 RealTimeStylus 物件輸入區域上方數位板的偵測範圍。 |
| 手寫筆UpData | 手寫筆Up | 手寫筆的封包資訊，因為手寫筆會從數位板增益。 |
| SystemGestureData | SystemGesture |
RealTimeStylus物件偵測到系統手勢時所新增的資訊。 |
| TabletAddedData | TabletAdded | 正在新增之 Tablet 物件的相關資訊。 |
| TabletRemovedData | TabletRemoved | 正在移除之 Tablet 物件的相關資訊。 |
如需 RealTimeStylus 物件如何處理平板電腦手寫筆資料流程的資訊，請參閱 使用 RealTimeStylus 類別。
資料興趣
當外掛程式新增至RealTimeStylus物件的同步或非同步外掛程式集合時，RealTimeStylus物件會檢查 Microsoft.StylusInput.IStylusInput.IStylusAsyncPlugin.DataInterest 屬性時，外掛程式會檢查Microsoft.StylusInput.IStylusSyncPlugin.DataInterest或Microsoft.StylusInput.DataInterest屬性。 因此，您應該使用 DataInterest 屬性來訂閱此外掛程式實例的所有通知，不過不常使用，但不會訂閱此外掛程式實例永遠不會使用的任何通知。 針對外掛程式只使用偶爾在通知方法中檢查外掛程式狀態的通知，如果外掛程式未在其目前狀態中使用通知，則傳回 。
外掛程式只會接收外掛程式 Microsoft.StylusInput.IStylusSyncPlugin.DataInterest 或 Microsoft.StylusInput.IStylusInput.IStylusAsyncPlugin.DataInterest 屬性中標示的方法呼叫。 如需外掛程式 DataInterest 屬性可能值的詳細資訊，請參閱 DataInterestMask 列舉。
計時
資料會先排入 RealTimeStylus 物件中，再將其傳遞至非同步外掛程式集合中的外掛程式。 下列清單描述在設計非同步外掛程式時可能需要考慮的一些情況。
- 停用 RealTimeStylus 物件時，非同步外掛程式可能會在呼叫 其 RealTimeStylusDisabled 方法之前收到其他佇列通知。 在此情況下，從外掛程式呼叫某些 RealTimeStylus 物件的方法和屬性會擲回例外狀況。 啟用 RealTimeStylus 物件時，應該快取與外掛程式相關的資訊。
- RealTimeStylus物件的ClearStylusQueues方法可能會從輸出佇列中移除資訊。 因此，非同步外掛程式無法依賴接收所有相關通知。
- 移除RealTimeStylus物件的Tablet物件時，非同步外掛程式可能會在呼叫TabletRemoved方法之前，收到平板電腦佇列的手寫筆通知。 在此情況下，呼叫 RealTimeStylus 物件的 GetTabletPropertyDescriptionCollection 方法無法運作。 啟用 RealTimeStylus 物件或新增平板電腦時，應該快取與外掛程式相關的資訊。
視您的應用程式而定，您可以在停用 RealTimeStylus 物件時改善效能。 當 RealTimeStylus 物件的 Enabled 屬性設定為 FALSE時，會處理輸入和輸出佇列上的資料，直到佇列是空的為止。 您可以在停用RealTimeStylus物件之前呼叫RealTimeStylus物件的ClearStylusQueues方法來清除佇列。
已啟用和停用的資料
啟用 RealTimeStylus 物件時，每個外掛程式都會收到其 Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled 或 Microsoft.StylusInput.IStylusAsyncPlugin.RealTimeStylusEnabled 方法的呼叫。 傳入通知的 RealTimeStylusEnabledData 物件包含 啟用 RealTimeStylus 物件時可用平板電腦的內容識別碼集合。
注意
由於 RealTimeStylus 物件非同步外掛程式集合的外掛程式資料已排入佇列，因此非同步外掛程式可能會在收到對 RealTimeStylusDisabled 方法的呼叫之前收到資料，但在停用 RealTimeStylus 物件之後。 請注意，如果停用 RealTimeStylus 物件，某些 RealTimeStylus物件的方法和屬性會擲回例外狀況。
RealTimeStylus物件會在啟用 RealTimeStylus物件的執行緒上呼叫Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled和Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusDisabled方法，
一般而言，停用 RealTimeStylus 物件時新增或移除外掛程式。 如需將外掛程式新增和移除至 RealTimeStylus 物件的詳細資訊，請參閱 外掛程式和 RealTimeStylus 類別。
平板電腦資料
當啟用 RealTimeStylus 物件時，RealTimeStylus物件可以使用的平板電腦新增或移除時，RealTimeStylus物件會通知其外掛程式已新增或移除Tablet物件。 每個 RealTimeStylus 物件都會維護其可與其互動之 Tablet 物件的唯一識別碼清單。 RealTimeStylus物件有兩種方法，可用於在唯一識別碼與 Tablet 物件之間轉譯、GetTabletCoNtextIdFromTablet和GetTabletFromTabletCoNtextId方法。
注意
平板電腦從平板電腦中移除平板電腦之後，無法再從 RealTimeStylus 物件取得平板電腦的相關資訊。
平板電腦手寫筆資料
RealTimeStylus物件會將平板電腦手寫筆的相關資訊傳遞給其外掛程式的一些通知方法。 平板電腦畫筆的相關資訊是由 手寫筆 物件表示。 此物件是收集資料時平板電腦手寫筆狀態的快照集。 因為外掛程式會在平板電腦畫筆資料流程中接收平板電腦畫筆資料，所以外掛程式應該使用手寫筆物件中的資訊，而不是透過 Cursor 類別檢查特定平板電腦手寫筆的目前狀態。
每個 手寫筆 物件都包含產生資料的平板電腦內容識別碼。
系統手勢資料
RealTimeStylus物件會在平板電腦辨識系統手勢時接收系統手勢的相關資料。 下表描述 SystemGestureData 物件相對於其他平板電腦手寫筆資料在平板電腦畫筆資料流程中發生的順序。
| SystemGesture | SystemGestureData物件前面的物件 | SystemGestureData物件之後的物件 |
|---|---|---|
| 點選 |
StylusDownData物件。 |
StylusUpData物件。 |
| DoubleTap |
StylusDownData物件、Tap系統手勢和StylusUpData物件的SystemGestureData物件。 |
第二個 StylusDownData 物件。 |
| RightTap | SystemGesure 列舉之 HoldEnter成員的StylusDownData物件和SystemGestureData物件。 |
StylusUpData物件。 |
| 拖動 |
StylusDownData物件。 |
StylusUpData物件。 |
| RightDrag |
StylusDownData物件。 |
StylusUpData物件。 |
| HoldEnter |
StylusDownData物件。 |
StylusUpData物件。 注意： 如果使用者開始 拖曳 或 RightDrag 系統手勢，則無法辨識此系統手勢。 |
| HoldLeave | 未實作。 |
未實作。 |
| HoverEnter | 數個低平均速度 的 InAirPacketsData 物件。 |
注意： 在收到 HoverEnter 系統手勢之前，可能會有明顯的延遲。
如果 RealTimeStylus物件附加至在系統手勢時直接位於手寫筆底下的視窗或控制項，則 RealTimeStylus物件只會接收此資料。 |
| HoverLeave |
HoverEnter系統手勢的SystemGestureData物件，以及數個InAirPacketsData物件具有足夠的平均速度。 |
注意： 在收到 HoverLeave 系統手勢之前，可能會有明顯的延遲。
如果 RealTimeStylus物件附加至在系統手勢時直接位於手寫筆底下的視窗或控制項，則 RealTimeStylus物件只會接收此資料。 |
自訂手寫筆資料
您可以藉由呼叫AddCustomStylusDataToQueue方法，將自訂手寫筆資料新增至RealTimeStylus物件。 自訂手寫筆資料可以新增至三個位置之一 的 RealTimeStylus 物件的佇列。
- 當 佇列 參數設定為 Output時，自訂資料會在同步外掛程式集合目前處理的資料之後，新增至 RealTimeStylus 物件的輸出佇列。
- 當 queue 參數設定為 OutputImmediate時，自訂資料會在同步外掛程式集合目前處理的資料之前，新增至 RealTimeStylus 物件的輸出佇列。
- 當 佇列 參數設定為 Input時，自訂資料會新增至 RealTimeStylus 物件的輸入佇列，並在從平板電腦手寫筆資料流程的新資料之前傳送至同步外掛程式集合。
在上述每個案例中，後續外掛程式在同步外掛程式集合中新增的資料會在先前外掛程式新增的資料之後新增。
注意
如果從同步外掛程式呼叫 AddCustomStylusDataToQueue 方法，以回應其其中一個 IStylusSyncPlugin 方法的呼叫，則自訂手寫筆資料會以可預測的方式新增至平板電腦手寫筆資料流程;否則，它會新增至佇列中，與 RealTimeStylus 物件正在處理的目前手寫筆資料有關，而不是與非同步外掛程式正在處理的資料有關。 如果 停用 RealTimeStylus 物件，AddCustomStylusDataToQueue 方法會擲回例外狀況。
自訂手寫筆資料會新增至佇列做為 CustomStylusData 物件，而外掛程式會透過其 Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded 或 Microsoft.StylusInput.IStylusAsyncPlugin.CustomStylusDataAdded 方法接收此資料。
DynamicRenderer和GestureRecognizer物件可能會將自訂手寫筆資料新增至佇列。 如需 DynamicRenderer 和 GestureRecognizer 物件的詳細資訊，請參閱動態轉譯 器外掛程式 和 辨識器外掛程式。
RealTimeStylus物件會在接收其 AddCustomStylusDataToQueue方法的執行緒上呼叫Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded方法。
下圖說明將自訂手寫筆資料新增至輸出佇列，並將 佇列 參數設定為 Output。
在此圖表中，以字母為 「A」 和 「B」 的圓形代表已新增至 RealTimeStylus 物件的輸出佇列，且尚未傳送至非同步外掛程式集合的平板電腦手寫筆資料。 字母為 「C」 的圓形代表 RealTimeStylus 物件目前正在處理的平板電腦手寫筆資料。 它會傳送至同步外掛程式集合，並放在輸出佇列上。 編號為 「1」、「2」 和 「3」 的圓形分別代表第一個、第二和第三個同步外掛程式新增至輸出佇列的自訂手寫筆資料，以回應 「C」 所代表的平板電腦手寫筆資料。 外掛程式已新增自訂手寫筆資料，並將 queue 參數設定為 StylusQueues。 空的圓形代表輸出佇列中新增未來平板電腦手寫筆資料的位置。
下圖說明將自訂手寫筆資料新增至輸出佇列，並將 queue 參數設定為 OutputImmediate。
在此圖表中，以字母為 「A」 和 「B」 的圓形代表已新增至 RealTimeStylus 物件的輸出佇列，且尚未傳送至非同步外掛程式集合的平板電腦手寫筆資料。 字母為 「C」 的圓形代表 RealTimeStylus 物件目前正在處理的平板電腦手寫筆資料。 它會傳送至同步外掛程式集合，並放在輸出佇列上。 編號為 「1」、「2」 和 「3」 的圓形分別代表第一個、第二和第三個同步外掛程式新增至輸出佇列的自訂手寫筆資料，以回應 「C」 所代表的平板電腦手寫筆資料。 外掛程式已新增自訂手寫筆資料，並將 佇列 參數設定為 OutputImmediate。 空的圓形代表輸出佇列中新增未來平板電腦手寫筆資料的位置。
下圖說明將自訂手寫筆資料新增至輸入佇列。
在此圖表中，以字母為 「A」 和 「B」 的圓形代表已新增至 RealTimeStylus 物件的輸出佇列，且尚未傳送至非同步外掛程式集合的平板電腦手寫筆資料。 字母為 「C」 的圓形代表 RealTimeStylus 物件目前正在處理的平板電腦手寫筆資料。 它會傳送至同步外掛程式集合，並放在輸出佇列上。 編號為 「1」、「2」 和 「3」 的圓形分別代表由第一個、第二和第三個同步外掛程式新增至輸入佇列的自訂手寫筆資料，以回應 「C」 所代表的平板電腦手寫筆資料。 外掛程式已新增自訂手寫筆資料，並將 佇列 參數設定為 Input。 然後，自訂手寫筆資料編號為 「1」 的自訂手寫筆資料會傳遞至同步外掛程式，然後在自訂手寫筆資料編號為 「2」 和 「3」 的輸出佇列之前，這兩者都會在處理下一個平板電腦手寫筆資料之前進行處理。 空的圓形代表輸出佇列中新增未來平板電腦手寫筆資料的位置。
錯誤資料
當外掛程式擲回例外狀況時，一般資料流程會中斷。 RealTimeStylus物件會產生ErrorData物件並呼叫：
- 擲回例外狀況之外掛程式的 Microsoft.StylusInput.IStylusSyncPlugin.Error 或 Microsoft.StylusInput.IStylusAsyncPlugin.Error 方法。
- 該集合中其餘外掛程式的 Microsoft.StylusInput.IStylusSyncPlugin.Error 或 Microsoft.StylusInput.IStylusAsyncPlugin.Error 方法。
如果擲回例外狀況的外掛程式是同步外掛程式， 則 ErrorData 物件會新增至輸出佇列。 然後 ，RealTimeStylus 物件會繼續正常處理原始資料。
下圖說明將錯誤資料新增至平板電腦手寫筆資料。
在此圖表中，以字母為 「A」 和 「B」 的圓形代表已新增至 RealTimeStylus 物件的輸出佇列，且尚未傳送至非同步外掛程式集合的平板電腦手寫筆資料。 字母為 「C」 的圓形代表 RealTimeStylus 物件目前正在處理的平板電腦手寫筆資料。 以字母為 「e」 的圓形代表當第二個同步外掛程式同步外掛程式 2 時，RealTimeStylus物件所產生的ErrorData物件，會在處理 「C」 時擲回例外狀況。 RealTimeStylus物件接著會暫停其 「C」 的處理，並將 「e」 傳遞至產生例外狀況和所有後續外掛程式的外掛程式。RealTimeStylus物件接著會將 「e」 放在輸出佇列上，並繼續其 「C」 的處理，這會傳遞至同步外掛程式集合中的其餘外掛程式，並在 「e」 之後放在輸出佇列上。 空的圓形代表輸出佇列中新增未來平板電腦手寫筆資料的位置。
如果外掛程式從其 Error 方法擲回例外狀況， 則 RealTimeStylus 物件會攔截例外狀況，但不會產生新的 ErrorData 物件。 這是為了避免遞迴。
錯誤資料會新增至輸出佇列之後，任何在建立錯誤資料例外狀況的例外狀況之前，以及在同步外掛程式集合中後續外掛程式在OutputImmediate位置新增的任何自訂手寫筆資料之前，于OutputImmediate位置新增的自訂手寫筆資料之後。
下圖說明錯誤資料如何新增至輸出佇列，與新增至 OutputImmediate 佇列的自訂資料有關。
在此圖表中，以字母為 「A」 和 「B」 的圓形代表已新增至 RealTimeStylus 物件的輸出佇列，且尚未傳送至非同步外掛程式集合的平板電腦手寫筆資料。 字母為 「C」 的圓形代表 RealTimeStylus 物件目前正在處理的平板電腦手寫筆資料。 編號為 「1」、「2」 和 「3」 的圓圈會分別由第一個、第二和第三個同步外掛程式新增至 OutputImmediate 佇列，以回應以字母為 「C」 的圓形表示的資料。 以字母為 「e」 的圓形代表錯誤資料，以回應第二個外掛程式在第二個外掛程式將自訂資料新增至 OutputImmediate 位置的輸出佇列後，第二個外掛程式擲回的例外狀況。
如果有任何同步外掛程式將自訂手寫筆資料新增至輸入佇列，以回應錯誤資料，則會在錯誤資料之前立即新增資料。 如果任何同步外掛程式將自訂手寫筆資料新增至輸出 佇列中的輸出 佇列，以回應錯誤資料，則會在錯誤資料之後立即新增資料。
RealTimeStylus物件會在擲回例外狀況的執行緒上呼叫Microsoft.StylusInput.IStylusSyncPlugin.Error方法。
相關主題