プラグイン データと RealTimeStylus クラス
RealTimeStylus クラスのプラグインは、IStylusSyncPlugin インターフェイスまたは IStylusAsyncPlugin インターフェイス、またはその両方を実装する必要があります。 すべてのプラグイン インターフェイス メソッドを実装する必要がある場合、プラグインは、プラグイン の Microsoft.StylusInput.IStylusSyncPlugin.DataInterest または Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest プロパティでフラグが設定されたメソッドの呼び出しのみを受け取ります。
インターフェイスで定義されているメソッドは、 Microsoft.StylusInput.PluginData 名前空間内のオブジェクトを使用して、ペン データをプラグインに渡します。次の表では、通知メソッドのパラメーターであるデータ オブジェクトについて説明し、通知に関連付けられている DataInterestMask 値の一覧を示します。
| プラグイン データ | DataInterestMask 値 | 説明 |
|---|---|---|
| CustomStylusData | CustomStylusDataAdded | プラグインが追加するカスタム アプリケーション データ。 |
| ErrorData | エラー |
RealTimeStylus オブジェクトが、いずれかのプラグインでハンドルされない例外に応答して追加するエラー情報。 |
| InAirPacketsData | InAirPackets | スタイラスがデジタイザーの上の空中にある間のスタイラスモーションのパケット情報。 |
| PacketsData | パケット | スタイラスがデジタイザーに触れている間のスタイラスモーションのパケット情報。 |
| RealTimeStylusDisabledData | RealTimeStylusDisabled |
RealTimeStylus オブジェクトが無効になっているときに追加する情報。 |
| RealTimeStylusEnabledData | RealTimeStylusEnabled |
RealTimeStylus オブジェクトが有効になっているときに追加する情報。 |
| StylusButtonDownData | StylusButtonDown | 押されている特定のスタイラス ボタンに関する情報。 |
| StylusButtonUpData | StylusButtonUp | リリースされている特定のスタイラス ボタンに関する情報。 |
| StylusDownData | StylusDown | スタイラスがデジタイザーに接触する際のスタイラスのパケット情報。 |
| StylusInRangeData | StylusInRange | RealTimeStylus オブジェクトの入力領域に入る、または RealTimeStylus オブジェクトの入力領域の上にデジタイザーの検出範囲を入力している特定のスタイラスに 関する情報 。 |
| StylusOutOfRangeData | StylusOutOfRange |
RealTimeStylus オブジェクトの入力領域を離れるか、デジタイザーの検出範囲を RealTimeStylus オブジェクトの入力領域の上に残している特定のスタイラスに関する情報。 |
| StylusUpData | StylusUp | スタイラスがデジタイザーから持ち上げられるときのスタイラスのパケット情報。 |
| SystemGestureData | SystemGesture |
RealTimeStylus オブジェクトがシステム ジェスチャを検出したときに追加する情報。 |
| TabletAddedData | TabletAdded | 追加される Tablet オブジェクトに関する情報。 |
| TabletRemovedData | TabletRemoved | 削除される Tablet オブジェクトに関する情報。 |
RealTimeStylus オブジェクトがタブレット ペン データ ストリームを処理する方法については、「RealTimeStylus クラスの操作」を参照してください。
データの関心
RealTimeStylus オブジェクトは、プラグインが RealTimeStylus オブジェクトの同期または非同期プラグイン コレクションに追加されるときに、プラグインの Microsoft.StylusInput.IStylusSyncPlugin.DataInterest または Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest プロパティをチェックします。 そのため、DataInterest プロパティを使用して、プラグインのこのインスタンスが使用するすべての通知をサブスクライブする必要がありますが、まれに、ただし、プラグインのこのインスタンスが使用しない通知にはサブスクライブしないようにする必要があります。 プラグインがプラグインの状態を通知メソッドで最初にチェックし、その通知がプラグインによって現在の状態で使用されていない場合に戻る場合にのみ使用する通知の場合。
プラグインは、プラグインの Microsoft.StylusInput.IStylusSyncPlugin.DataInterest または Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest プロパティでフラグが設定されたメソッドの呼び出しのみを受け取ります。 プラグインの DataInterest プロパティで使用できる値の詳細については、 DataInterestMask 列挙を参照してください。
タイミング
データは、非同期プラグイン コレクション内のプラグインに渡される前に 、RealTimeStylus オブジェクトにキューに入れられます。 次の一覧では、非同期プラグインを設計するときに考慮する必要がある状況をいくつか示します。
- RealTimeStylus オブジェクトが無効になっている場合、非同期プラグインは、RealTimeStylusDisabled メソッドが呼び出される前に、キューに登録された他の通知を受け取ることがあります。 この状況では、プラグインから RealTimeStylus オブジェクトのメソッドとプロパティの一部を呼び出すと、例外がスローされます。 RealTimeStylus オブジェクトが有効になっている場合は、プラグインに関連する情報をキャッシュする必要があります。
- RealTimeStylus オブジェクトの ClearStylusQueues メソッドは、出力キューから情報を削除できます。 したがって、非同期プラグインは、関連するすべての通知の受信に依存することはできません。
- RealTimeStylus オブジェクトで使用できる Tablet オブジェクトが削除されると、TabletRemoved メソッドが呼び出される前に、非同期プラグインがタブレットのキューに入ったスタイラス通知を受け取ることがあります。 この状況では、 RealTimeStylus オブジェクトの GetTabletPropertyDescriptionCollection メソッドを呼び出しても機能しません。 RealTimeStylus オブジェクトが有効になっている場合、または新しいタブレットが追加されたときに、プラグインに関連する情報をキャッシュする必要があります。
アプリケーションによっては、 RealTimeStylus オブジェクトを無効にするときのパフォーマンスを向上させることができます。 RealTimeStylus オブジェクトの Enabled プロパティが FALSE に設定されている場合、入力キューと出力キューのデータは、キューが空になるまで処理されます。 RealTimeStylus オブジェクトの ClearStylusQueues メソッドを呼び出して、RealTimeStylus オブジェクトを無効にする前にキューをクリアできます。
有効なデータと無効なデータ
RealTimeStylus オブジェクトが有効になっている場合、各プラグインは、その Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled メソッドまたは Microsoft.StylusInput.IStylusAsyncPlugin.RealTimeStylusEnabled メソッドの呼び出しを受け取ります。 通知で渡される RealTimeStylusEnabledData オブジェクトには、 RealTimeStylus オブジェクトが有効になっている時点で使用可能なタブレットのコンテキスト識別子のコレクションが含まれています。
注意
RealTimeStylus オブジェクトの非同期プラグイン コレクションのプラグイン データはキューに登録されているため、非同期プラグインは、RealTimeStylusDisabled メソッドの呼び出しを受信する前に、RealTimeStylus オブジェクトが無効になった後にデータを受信する可能性があります。 RealTimeStylus オブジェクトのメソッドとプロパティの一部では、RealTimeStylus オブジェクトが無効になっている場合に例外がスローされることに注意してください。
RealTimeStylus オブジェクトは、RealTimeStylus オブジェクトが有効になっているスレッドまたは同期プラグインの追加元のスレッドで、Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled メソッドと Microsoft.StylusInput.IStylusSyncPluusDisabled メソッドを呼び出します。
一般に、 RealTimeStylus オブジェクトが無効になっている間にプラグインを追加または削除します。 RealTimeStylus オブジェクトへのプラグインの追加と削除の詳細については、「プラグインと RealTimeStylus クラス」を参照してください。
タブレット データ
RealTimeStylus オブジェクトが有効になっているときに、RealTimeStylus オブジェクトが使用できるタブレットが Tablet PC に追加または削除されると、RealTimeStylus オブジェクトは Tablet オブジェクトが追加または削除されたことをプラグインに通知します。 各 RealTimeStylus オブジェクトは、操作できる Tablet オブジェクトの一意の識別子の一覧を保持します。 RealTimeStylus オブジェクトには、一意識別子と Tablet オブジェクトの間で変換するための 2 つのメソッド、GetTabletContextIdFromTablet メソッドと GetTabletFromTabletContextId メソッドがあります。
注意
タブレットに関する情報は、タブレット PC からタブレットを削除した後、 RealTimeStylus オブジェクトから使用できなくなります。
タブレット ペン データ
RealTimeStylus オブジェクトは、タブレット ペンに関する情報を、さまざまな通知メソッドのプラグインに渡します。 タブレット ペンに関する情報は、 スタイラス オブジェクトによって表されます。 このオブジェクトは、データが収集された時点でのタブレット ペンの状態のスナップショットです。 プラグインはタブレット ペン データ ストリームの一部としてタブレット ペン データを受け取るため、プラグインは Cursor クラスを介して特定のタブレット ペンの現在の状態を確認するのではなく、スタイラス オブジェクトの情報を使用する必要があります。
各 スタイラス オブジェクトには、データを生成したタブレットのタブレット コンテキスト識別子が含まれています。
システム ジェスチャ データ
RealTimeStylus オブジェクトは、タブレット PC で認識されるシステム ジェスチャに関するデータを受け取ります。 次の表では、他のタブレット ペン データに関連して、タブレット ペン データ ストリームで SystemGestureData オブジェクトが発生する順序について説明します。
| SystemGesture | SystemGestureData オブジェクトの前にあるオブジェクト | SystemGestureData オブジェクトの後に来るオブジェクト |
|---|---|---|
| タップ |
StylusDownData オブジェクト。 |
StylusUpData オブジェクト。 |
| DoubleTap |
StylusDownData オブジェクト、Tap システム ジェスチャ用の SystemGestureData オブジェクト、および StylusUpData オブジェクト。 |
2 番目の StylusDownData オブジェクト。 |
| RightTap |
SystemGesure 列挙体の HoldEnter メンバーの StylusDownData オブジェクトと SystemGestureData オブジェクト。 |
StylusUpData オブジェクト。 |
| Drag |
StylusDownData オブジェクト。 |
StylusUpData オブジェクト。 |
| RightDrag |
StylusDownData オブジェクト。 |
StylusUpData オブジェクト。 |
| HoldEnter |
StylusDownData オブジェクト。 |
StylusUpData オブジェクト。 メモ： ユーザーが Drag または RightDrag システム ジェスチャを開始した場合、このシステム ジェスチャは認識されません。 |
| HoldLeave | 実装されていません。 |
実装されていません。 |
| HoverEnter | 平均速度が低い 複数の InAirPacketsData オブジェクト。 |
メモ：HoverEnter システム ジェスチャを受け取る前に、顕著な遅延が発生する可能性があります。
RealTimeStylus オブジェクトは、システム ジェスチャ時にペンのすぐ下にあるウィンドウまたはコントロールに RealTimeStylus オブジェクトがアタッチされている場合にのみ、このデータを受け取ります。 |
| HoverLeave |
HoverEnter システム ジェスチャ用の SystemGestureData オブジェクトと、十分な平均速度を持つ複数の InAirPacketsData オブジェクト。 |
メモ：HoverLeave システム ジェスチャを受け取る前に、顕著な遅延が発生する可能性があります。
RealTimeStylus オブジェクトは、システム ジェスチャ時にペンのすぐ下にあるウィンドウまたはコントロールに RealTimeStylus オブジェクトがアタッチされている場合にのみ、このデータを受け取ります。 |
カスタム スタイラス データ
カスタム スタイラス データを RealTimeStylus オブジェクトに追加するには、 AddCustomStylusDataToQueue メソッドを呼び出します。 カスタム スタイラス データは、3 つの場所のいずれかで RealTimeStylus オブジェクトのキューに追加できます。
- queue パラメーターが Output に設定されている場合、同期プラグイン コレクションによって現在処理されているデータの後に、カスタム データが RealTimeStylus オブジェクトの出力キューに追加されます。
- queue パラメーターが OutputImmediate に設定されている場合、同期プラグイン コレクションによって現在処理されているデータの前に、カスタム データが RealTimeStylus オブジェクトの出力キューに追加されます。
- queue パラメーターが Input に設定されている場合、カスタム データは RealTimeStylus オブジェクトの入力キューに追加され、タブレット ペンのデータ ストリームから新しいデータの前に同期プラグイン コレクションに送信されます。
上記の各ケースでは、同期プラグイン コレクション内の後続のプラグインによって追加されたデータは、前のプラグインによって追加されたデータの後に追加されます。
注意
AddCustomStylusDataToQueue メソッドの呼び出しが、IStylusSyncPlugin メソッドの 1 つへの呼び出しに応じて同期プラグインから行われた場合、カスタム スタイラス データは予測可能な方法でタブレット ペン データ ストリームに追加されます。それ以外の場合は、RealTimeStylus オブジェクトが処理している現在のペン データに関連してキューに追加され、非同期プラグインが処理しているデータとは関係ありません。 RealTimeStylus オブジェクトが無効になっている場合、AddCustomStylusDataToQueue メソッドは例外をスローします。
カスタム スタイラス データは CustomStylusData オブジェクトとしてキューに追加され、プラグインは Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded メソッドまたは Microsoft.StylusInput.IStylusAsyncPlugin.CustomStylusDataAdded メソッドを使用してこのデータを受け取ります。
DynamicRenderer オブジェクトと GestureRecognizer オブジェクトは、カスタム スタイラス データをキューに追加できます。 DynamicRenderer オブジェクトと GestureRecognizer オブジェクトの詳細については、「Dynamic-Renderer プラグイン」と「Recognizer プラグイン」を参照してください。
RealTimeStylus オブジェクトは、AddCustomStylusDataToQueue メソッドの呼び出しを受け取るスレッドで、Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded メソッドを呼び出します。
次の図は、 queue パラメーターが Output に設定されたカスタム スタイラス データを 出力キューに追加する方法を示しています。
この図では、"A" と "B" という文字が付いた円は、 RealTimeStylus オブジェクトの出力キューに既に追加されており、非同期プラグイン コレクションにまだ送信されていないタブレット ペン データを表しています。 "C" という円は、 RealTimeStylus オブジェクトが現在処理しているタブレット ペン データを表します。 同期プラグイン コレクションに送信され、出力キューに配置されます。 "1"、"2"、および "3" の番号が付いた円は、"C" で表されるタブレット ペン データに応じて、それぞれ 1 番目、2 番目、および 3 番目の同期プラグインによって出力キューに追加されたカスタム スタイラス データを表します。 プラグインによって、 queue パラメーターが StylusQueues に設定されたカスタム スタイラス データが追加されました。 空の円は、将来のタブレット ペン データが追加される出力キュー内の位置を表します。
次の図は、 queue パラメーターが OutputImmediate に設定されたカスタム スタイラス データを出力キューに追加する方法を示しています。
この図では、"A" と "B" という文字が付いた円は、 RealTimeStylus オブジェクトの出力キューに既に追加されており、非同期プラグイン コレクションにまだ送信されていないタブレット ペン データを表しています。 "C" という円は、 RealTimeStylus オブジェクトが現在処理しているタブレット ペン データを表します。 同期プラグイン コレクションに送信され、出力キューに配置されます。 "1"、"2"、および "3" の番号が付いた円は、"C" で表されるタブレット ペン データに応じて、それぞれ 1 番目、2 番目、および 3 番目の同期プラグインによって出力キューに追加されたカスタム スタイラス データを表します。 プラグインによって、 queue パラメーターが OutputImmediate に設定されたカスタム スタイラス データが追加されました。 空の円は、将来のタブレット ペン データが追加される出力キュー内の位置を表します。
次の図は、入力キューへのカスタム スタイラス データの追加を示しています。
この図では、"A" と "B" という文字が付いた円は、 RealTimeStylus オブジェクトの出力キューに既に追加されており、非同期プラグイン コレクションにまだ送信されていないタブレット ペン データを表しています。 "C" という円は、 RealTimeStylus オブジェクトが現在処理しているタブレット ペン データを表します。 同期プラグイン コレクションに送信され、出力キューに配置されます。 "1"、"2"、および "3" の番号が付いた円は、"C" で表されるタブレット ペン データに応じて、それぞれ 1 つ目、2 番目、3 番目の同期プラグインによって入力キューに追加されたカスタム スタイラス データを表します。 プラグインによって、 queue パラメーターが 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 番目の同期プラグインである同期プラグイン 2 が "C" の処理中に例外をスローしたときに、RealTimeStylus オブジェクトによって生成された ErrorData オブジェクトを表します。 RealTimeStylus オブジェクトは、"C" の処理を一時停止し、例外とその後のすべてのプラグインを生成したプラグインに "e" を渡します。RealTimeStylus オブジェクトは、出力キューに "e" を配置し、"C" の処理を再開します。この処理は同期プラグイン コレクション内の残りのプラグインに渡され、"e" の後の出力キューに配置されます。 空の円は、将来のタブレット ペン データが追加される出力キュー内の位置を表します。
プラグインが Error メソッドから例外をスローした場合、 RealTimeStylus オブジェクトは例外をキャッチしますが、新しい ErrorData オブジェクトは生成しません。 これは、再帰を防ぐためです。
エラー データは、エラー データを作成した例外の前に OutputImmediate 位置に追加されたカスタム スタイラス データの後、および同期プラグイン コレクション内の後続のプラグインによって OutputImmediate 位置に追加されるカスタム スタイラス データの前に、出力キューに追加されます。
次の図は、 OutputImmediate キューに追加されるカスタム データに関連して、エラー データを出力キューに追加する方法を示しています。
この図では、"A" と "B" という文字が付いた円は、 RealTimeStylus オブジェクトの出力キューに既に追加されており、非同期プラグイン コレクションにまだ送信されていないタブレット ペン データを表しています。 "C" という円は、 RealTimeStylus オブジェクトが現在処理しているタブレット ペン データを表します。 "1"、"2"、および "3" の番号が付いた円は、"C" という円で表されるデータに応じて、 OutputImmediate キューにそれぞれ 1 番目、2 番目、および 3 番目の同期プラグインによって追加されます。 "e" という円は、2 番目のプラグインが OutputImmediate 位置の出力キューにカスタム データを追加した後に 2 番目のプラグインによってスローされた例外に応答して生成されるエラー データを表します。
同期プラグインがエラー データに応答してカスタム スタイラス データを入力キューに追加すると、エラー データの直前にデータが追加されます。 いずれかの同期プラグインが、エラー データに応答して 出力 位置の出力キューにカスタム スタイラス データを追加すると、エラー データの直後にデータが追加されます。
RealTimeStylus オブジェクトは、例外がスローされるスレッドで Microsoft.StylusInput.IStylusSyncPlugin.Error メソッドを呼び出します。
関連トピック