RealTimeStylus クラスの操作
RealTimeStylus クラスは、StylusInput アプリケーション プログラミング インターフェイス (API) の一部です。 以降のセクションでは、 RealTimeStylus クラスと StylusInput API の主要な要素について説明します。
RealTimeStylus クラスのインスタンス化
RealTimeStylus オブジェクトを作成するときは、ウィンドウ ハンドルまたはコントロールにアタッチするオプションがあります。 RealTimeStylus オブジェクトをウィンドウ ハンドルにアタッチするには、追加のアクセス許可が必要です。 これらのアクセス許可の詳細については、「 StylusInput API の部分信頼に関する考慮事項」を参照してください。
Note
RealTimeStylus オブジェクトを別のプロセスのウィンドウまたはコントロールにアタッチすることはできません。
既定のコンストラクターを使用する場合は、 別の RealTimeStylus オブジェクトからの入力のみを受け入れることができる RealTimeStylus オブジェクトを 作成します。 2 つの RealTimeStylus オブジェクトの接続の詳細については、「 カスケードされた RealTimeStylus モデル」を参照してください。
RealTimeStylus オブジェクトは、IDisposable インターフェイスを実装します。
RealTimeStylus クラスの拡張
プラグインがタブレット ペンからデータ ストリームを操作できるように、 RealTimeStylus オブジェクトは 2 つのプラグイン コレクションを保持します。このコレクションは、C++ の GetStylusSyncPlugin メソッドと GetStylusAsyncPlugin メソッド、およびマネージド コードの SyncPluginCollection プロパティと AsyncPluginCollection プロパティからアクセスできます。 プラグインを追加するには、適切なプロパティ内でコレクションの AddStylusSyncPlugin メソッドまたは AddStylusAsyncPlugin メソッドを呼び出します。 プラグインの作成と使用の詳細については、「プラグイン と RealTimeStylus クラス」を参照してください。 特定のタスクに対して同期プラグインと非同期プラグインのどちらを作成するかを決定する方法については、「StylusInput API のスレッド処理に関する考慮事項」および「StylusInput API のパフォーマンスに関する考慮事項」を参照してください。
同期プラグインは IStylusSyncPlugin インターフェイスを実装する必要があり、非同期プラグインは IStylusAsyncPlugin インターフェイスを実装する必要があります。 各プラグインには、 IStylusSyncPlugin.DataInterest または IStylusAsyncPlugin.DataInterest プロパティがあります。 RealTimeStylus オブジェクトは、プラグインがサブスクライブされているメソッドに対して、プラグインの通知メソッドのみを呼び出します。 通知メソッドの詳細については、「 プラグイン データ」と「RealTimeStylus クラス」を参照してください。
RealTimeStylus オブジェクトは、IStylusAsyncPlugin インターフェイスを実装します。 別の RealTimeStylus オブジェクトからの入力を受け入れる RealTimeStylus オブジェクトをインスタンス化する唯一の方法は、既定のコンストラクターを使用し、カスケードされた RealTimeStylus モデルを実装することです。 2 つの RealTimeStylus オブジェクトの接続の詳細については、「 カスケードされた RealTimeStylus モデル」を参照してください。
RealTimeStylus オブジェクトには、タブレット ペン データ、入力キュー、出力キューを保持する 2 つの内部キューがあります。 ペン データは、 Microsoft.StylusInput.PluginData 名前空間のクラスのインスタンスに変換されます。 次の一覧では、 RealTimeStylus オブジェクトがタブレット ペン データを処理する方法について説明します。
- RealTimeStylus オブジェクトは、最初に入力キューでプラグイン データ オブジェクトを調べた後、タブレット ペン データ ストリームからプラグイン データ オブジェクトをチェックします。
- RealTimeStylus オブジェクトは、同期プラグイン コレクション内のオブジェクトに 1 つのプラグイン データ オブジェクトを送信します。 各同期プラグインは、入力キューまたは出力キューにデータを追加できます。
- プラグイン データ オブジェクトが同期プラグイン コレクションのすべてのメンバーに送信されると、プラグイン データ オブジェクトは RealTimeStylus オブジェクトの出力キューに配置されます。
- RealTimeStylus オブジェクトは、処理する次のプラグイン データ オブジェクトを確認します。
- RealTimeStylus オブジェクトの出力キューにはデータが含まれていますが、RealTimeStylus オブジェクトは出力キューから非同期プラグイン コレクション内のオブジェクトに 1 つのプラグイン データ オブジェクトを送信します。 各非同期プラグインは入力キューまたは出力キューにデータを追加できますが、非同期プラグインはユーザー インターフェイス (UI) スレッドで実行されるため、 データは RealTimeStylus オブジェクトが処理している現在のペン データに関連してキューに追加され、非同期プラグインが処理しているデータとは関係ありません。
次の図は、 RealTimeStylus オブジェクトとそのプラグイン コレクションを介したタブレット ペン データのフローを示しています。
この図では、"A" と "B" の丸は、 RealTimeStylus オブジェクトの出力キューに既に追加されており、非同期プラグイン コレクションにまだ送信されていないタブレット ペン データを表しています。 円の文字 "C" は、 RealTimeStylus オブジェクトが現在処理しているタブレット ペン データを表します。 同期プラグイン コレクションに送信され、出力キューに配置されます。 空の円は、将来のタブレット ペン データが追加される出力キュー内の位置を表します。
キューに特定のデータを追加して処理する方法の詳細については、「 プラグイン データと RealTimeStylus クラス」を参照してください。
インクを収集するフォームで RealTimeStylus オブジェクトを使用するための最小限のシナリオを次に示します。
- IStylusAsyncPlugin インターフェイスを実装するフォームを作成します。
- フォーム上のコントロールにアタッチされた RealTimeStylus オブジェクトを作成します。
- フォームの IStylusAsyncPlugin.DataInterest プロパティの StylusDown、Packets、StylusUp 通知に関心を設定します。
- フォームの StylusDown、 Packets、 StylusUp メソッドで、フォームの RealTimeStylus オブジェクトから送信されるスタイラスダウン、パケット、スタイラスアップ通知を処理するコードを追加します。
このようなアプリケーションのサンプルについては、「 RealTimeStylus Ink Collection Sample」を参照してください。
タブレット オブジェクトの操作
有効になっている各 RealTimeStylus オブジェクトは、対話できる Tablet オブジェクトの一意の識別子の一覧を保持します。 RealTimeStylus オブジェクトは、一意の識別子と Tablet オブジェクトの間で変換するための 2 つのメソッド (GetTabletContextIdFromTablet メソッドと GetTabletFromTabletContextId メソッド) を公開します。
TabletPropertyDescription オブジェクト (マネージ コード内) には、PacketPropertyId プロパティと、特定の Tablet オブジェクトの プロパティの範囲、解像度、および単位を記述する TabletPropertyMetrics 構造体が含まれています。 RealTimeStylus オブジェクトの GetDesiredPacketDescription メソッドは、RealTimeStylus オブジェクトが使用可能な場合にプラグインに転送するパケット プロパティのグローバル一意識別子 (GUID) の配列を返します。 RealTimeStylus オブジェクトがプラグインに渡すパケット プロパティのセットを変更するには、RealTimeStylus オブジェクトの SetDesiredPacketDescription メソッドを呼び出します。 RealTimeStylus オブジェクトの GetTabletPropertyDescriptionCollection メソッド (マネージ コード内) は、一意のタブレット識別子を受け取り、TabletPropertyDescription オブジェクトのコレクションを返します。 これらのパケット プロパティは、 GetDesiredPacketDescription メソッドによって返されるタブレットでサポートされるプロパティのサブセットを表します。
標準パケット プロパティ GUID の一覧については、 PacketPropertyGuids Constants クラスを参照してください。
特別な考慮事項
次の一覧では、Tablet オブジェクトで RealTimeStylus オブジェクトを使用する場合に考慮すべきその他の点について説明します。
- SetDesiredPacketDescription メソッドは、Tablet オブジェクトが無効になっている間のみ呼び出すことができます。 RealTimeStylus オブジェクトは、必要なパケット プロパティの一覧を変更できます。そのため、SetDesiredPacketDescription メソッドの呼び出し後に GetDesiredPacketDescription メソッドを呼び出して、RealTimeStylus オブジェクトがプラグインに転送できるパケット プロパティを決定します。タブレットは、PacketProperty の X、Y、PacketStatus 値のみをサポートすることが保証されます。 そのため、プラグインの設計では、必要なパケット プロパティの受信数を減らすために考慮する必要がある場合があります。
- GetTabletPropertyDescriptionCollection メソッド (マネージ コードの場合) は、RealTimeStylus オブジェクトが有効になっている間のみ呼び出すことができます。 RealTimeStylus オブジェクトが無効になった後、非同期プラグインに通知を送信できるため、各 Tablet オブジェクトの情報をキャッシュする必要がある場合があります。 GetTabletPropertyDescriptionCollection メソッドは、指定されたタブレットでサポートされている目的のパケット プロパティの一覧を返します。
- RealTimeStylus オブジェクトが有効になっている場合、各プラグインは RealTimeStylusEnabled メソッドの呼び出しを受け取ります。 通知で渡される RealTimeStylusEnabledData オブジェクトには、 RealTimeStylus オブジェクトが有効になっている時点で使用可能なタブレットのコンテキスト識別子のコレクションが含まれています。
- RealTimeStylus オブジェクトが有効になっている間に RealTimeStylus オブジェクトが使用できるタブレットが Tablet PC に追加または削除されると、RealTimeStylus オブジェクトは Tablet オブジェクトが追加または削除されたことをプラグインに通知します。 詳細については、「 プラグイン データ」と「RealTimeStylus クラス」を参照してください。
タブレット ペンの操作
RealTimeStylus オブジェクトは、タブレット ペンに関する情報を、さまざまな通知方法でプラグインに渡します。 タブレット ペンに関する情報は、GetStyluses メソッドを使用して取得した Stylus オブジェクトによって表されます。 このオブジェクトは、データが収集された時点でのタブレット ペンの表現です。 プラグインはタブレット ペン データ ストリームの一部としてタブレット ペン データを受け取るため、プラグインは Cursor クラスを介して特定のタブレット ペンの現在の状態を確認する代わりに、スタイラス オブジェクトの情報を使用する必要があります。 タブレット ペンとタブレット ペン のボタン データをプラグインに渡す方法については、「 プラグイン データと RealTimeStylus クラス」を参照してください。
RealTimeStylus オブジェクトが最後に有効になった後に検出されたスタイラス オブジェクトの配列を取得するには、RealTimeStylus オブジェクトの GetStyluses メソッドを使用します。
関連トピック