プラグインと RealTimeStylus クラス
RealTimeStylus オブジェクトは、タブレット ペンからデータ ストリームにリアルタイムでアクセスできるように設計されています。 プラグインは、 IStylusSyncPlugin または IStylusAsyncPlugin インターフェイスを実装するオブジェクトを RealTimeStylus オブジェクトに追加できます。 同期プラグインは通常、優先度の高いスレッドの RealTimeStylus オブジェクトによって直接呼び出されますが、非同期プラグインは通常、アプリケーションのユーザー インターフェイス (UI) スレッドで呼び出されます。 データ ストリームへのリアルタイム アクセスを必要とし、パケット フィルター処理などの計算的に管理されていないタスクに対して同期プラグインを作成または使用します。 インク コレクションなど、データ ストリームへのリアルタイム アクセスを必要としないタスクに対して非同期プラグインを作成または使用します。
特定のタスクでは、計算が要求されるが、マルチストローク ジェスチャ認識など、データ ストリームへのリアルタイム アクセスが必要な場合があります。 これらのニーズに対応するために、StylusInput API にはカスケードされた RealTimeStylus モデルが用意されています。このモデルでは、それぞれ独自のスレッドで実行されている 2 つの RealTimeStylus オブジェクトを使用できます。 カスケードされた RealTimeStylus モデルの詳細については、「 カスケードされた RealTimeStylus モデル」を参照してください。
IStylusSyncPlugin インターフェイスと IStylusAsyncPlugin インターフェイスはどちらも同じメソッドを定義します。 これらのメソッドを使用すると、 RealTimeStylus オブジェクトは、非同期プラグインか同期プラグインかに関係なく、各プラグインにペン データを渡すことができます。 Microsoft.StylusInput.IStylusSyncPlugin.DataInterest プロパティと Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest プロパティを使用すると、各プラグインでタブレット ペン データ ストリーム内の特定のデータをサブスクライブできます。 プラグインは、タスクの実行に必要なデータのみをサブスクライブして、パフォーマンスの要求を最小限に抑える必要があります。 スレッド処理と RealTimeStylus クラスの詳細については、「 StylusInput API のスレッド処理に関する考慮事項」を参照してください。
RealTimeStylus オブジェクトは、Microsoft.StylusInput.PluginData 名前空間内のオブジェクトを使用して、ペン データをプラグインに渡します。RealTimeStylus では、プラグインによってスローされた例外もキャッチされます。RealTimeStylus が例外をキャッチすると、IStylusSyncPlugin.Error メソッドまたは IStylusAsyncPlugin.Error メソッドを呼び出してプラグインに通知します。 プラグイン データの使用の詳細については、「プラグイン データ」と「RealTimeStylus クラス」を参照してください。 エラー処理の詳細については、「 StylusInput API のエラー処理に関する考慮事項 」およびプラグイン データと RealTimeStylus クラスの「エラー データ」セクションを参照してください。
Note
RealTimeStylus オブジェクトを有効にするには、少なくとも 1 つのプラグインを RealTimeStylus オブジェクトにアタッチする必要があります。
次のトピックでは、プラグインのいくつかの一般的なカテゴリについて説明します。
特別な考慮事項
RealTimeStylus オブジェクトの複雑な性質上、次の点に注意してください。
プラグインがアタッチ先のプラグイン コレクションを変更した場合、 RealTimeStylus オブジェクトは例外をスローします。 これは、プラグインがそのコレクションのメンバーとして RealTimeStylus オブジェクトによって呼び出されている間にのみ発生します。
次の C# の例は、 RealTimeStylus オブジェクトが例外をスローするコードです。
using Microsoft.Ink;
using Microsoft.StylusInput;
using Microsoft.StylusInput.PluginData;
// ...
public class thePlugin : Microsoft.StylusInput.IStylusAsyncPlugin
{
// ...
// Called when a system gesture occurs.
public void SystemGesture(RealTimeStylus sender, SystemGestureData data)
{
// The following line will cause the realtime stylus that calls this method
// to throw an exception.
sender.Dispose();
}
// ...
}
プラグインが RealTimeStylus オブジェクトの Dispose メソッドを呼び出すと、RealTimeStylus オブジェクトは例外をスローします。 これは、 プラグインが RealTimeStylus オブジェクトによって呼び出されている間にのみ発生します。
次の C# の例は、 RealTimeStylus オブジェクトが例外をスローするコードです。
using Microsoft.Ink;
using Microsoft.StylusInput;
using Microsoft.StylusInput.PluginData;
// ...
public class thePlugin : Microsoft.StylusInput.IStylusAsyncPlugin
{
Microsoft.StylusInput.GestureRecognizer theGestureRecognizer;
// ...
// Called when a system gesture occurs.
public void SystemGesture(RealTimeStylus sender, SystemGestureData data)
{
// The following line will cause the realtime stylus that calls this method
// to throw an exception.
sender.AsyncPluginCollection.Add(this.theGestureRecognizer);
}
// ...
}
プラグイン コレクションは、 RealTimeStylus オブジェクトが有効になっている間に変更できます。ただし、これにより、アプリケーションの動作の予測が困難になる可能性があります。 RealTimeStylus オブジェクトが有効になっているときにプラグインを追加すると、RealTimeStylus オブジェクトはプラグインの IStylusAsyncPlugin.RealTimeStylusEnabled メソッドまたは IStylusSyncPlugin.RealTimeStylusEnabled メソッドを呼び出します。 RealTimeStylus オブジェクトが有効になっているときにプラグインが削除されると、RealTimeStylus オブジェクトは、プラグインの IStylusAsyncPlugin.RealTimeStylusDisabled メソッドまたは IStylusSyncPlugin.RealTimeStylusDisabled メソッドを呼び出します。 これにより、プラグインは RealTimeStylus オブジェクトの Enabled プロパティをチェックすることなく、適切な状態を維持できます。
RealTimeStylus オブジェクトが有効になっている間にプラグインが追加されると、プラグインが受け取るプラグイン データに、初期データのコンテキストを適切に確立するのに十分な情報が含まれていない可能性があります。 たとえば、新しく追加されたプラグインでは、中間ストロークのペンからパケット データの受信を開始できます。 同様に、 RealTimeStylus オブジェクトが有効になっている間にプラグインが削除されると、プラグインが受け取ったプラグイン データが、データの処理を完了するのに不十分な場合があります。
Note
全体的な安定性を確保するために、RealTimeStylusEnabled メソッドまたは RealTimeStylusDisabled メソッドが呼び出されたときに、プラグインの内部状態をリセットします。
関連トピック