IRealTimeStylus

デジタイザーからのスタイラスのパケットデータをリアルタイムに処理します。

このインターフェイスは RealTimeStylus Class によって実装されます。

拡張性は同期プラグインモデルと非同期プラグインモデルによって提供され、それぞれ IStylusSyncPlugin インターフェイスと IStylusAsyncPlugin インターフェイスを使用してカスタム処理を行います。計算負荷の高い処理は、パケットストリームをブロックしないように非同期プラグインで実行してください。

CPU 負荷が高く時間のかかる処理には IStylusSyncPlugin インターフェイスの実装を使用しないことをお勧めします。パケットストリームの流れがブロックされるためです。そうした処理は、パケットストリームの流れを維持するスレッドとは別のスレッドで実行される IStylusAsyncPlugin インターフェイスの実装クラスで行ってください。

RealTimeStylus オブジェクトがタブレットペンのデータを収集するかどうかを指定する値を取得または設定します。(Get)

複数の RealTimeStylus オブジェクトを同一のウィンドウ上に存在させることができますが、ウィンドウ入力矩形が重なった状態で有効化されていないことが条件です。入力矩形が重なった状態で有効化された同一ウィンドウ上の RealTimeStylus オブジェクトは、動作が不定になります。

子の RealTimeStylus オブジェクトを有効にするには、接続されている必要があります。

RealTimeStylus オブジェクトはプラグインが 1 つもアタッチされていなくても有効にできますが、実際に役立てるには少なくとも 1 つのプラグインが必要です。

オブジェクトが有効でない場合、イベントは一切受け取れません。

コンテナーコントロールの IRealTimeStylus::Enabled Property を false に設定すると、そこに含まれるすべてのコントロールも無効になります。

RealTimeStylus オブジェクトがタブレットペンのデータを収集するかどうかを指定する値を取得または設定します。(Put)

複数の RealTimeStylus オブジェクトを同一のウィンドウ上に存在させることができますが、ウィンドウ入力矩形が重なった状態で有効化されていないことが条件です。入力矩形が重なった状態で有効化された同一ウィンドウ上の RealTimeStylus オブジェクトは、動作が不定になります。

子の RealTimeStylus オブジェクトを有効にするには、接続されている必要があります。

RealTimeStylus オブジェクトはプラグインが 1 つもアタッチされていなくても有効にできますが、実際に役立てるには少なくとも 1 つのプラグインが必要です。

オブジェクトが有効でない場合、イベントは一切受け取れません。

コンテナーコントロールの IRealTimeStylus::Enabled Property を false に設定すると、そこに含まれるすべてのコントロールも無効になります。

RealTimeStylus オブジェクトが使用するウィンドウに関連付けられたハンドル値を取得または設定します。(Get)

2 つ以上のウィンドウが存在する場合、このプロパティによってどのウィンドウでインクを収集するかを指定できます。

子の RealTimeStylus オブジェクトに対してこのプロパティを設定しようとすると、HRESULT E_INVALIDOPERATION が返されます。

RealTimeStylus オブジェクトが使用するウィンドウに関連付けられたハンドル値を取得または設定します。(Put)

2 つ以上のウィンドウが存在する場合、このプロパティによってどのウィンドウでインクを収集するかを指定できます。

子の RealTimeStylus オブジェクトに対してこのプロパティを設定しようとすると、HRESULT E_INVALIDOPERATION が返されます。

RealTimeStylus Class オブジェクトのウィンドウ入力矩形を取得または設定します。(Get)

各 RealTimeStylus Class オブジェクトは、その RealTimeStylus Class オブジェクトに定義されたウィンドウ入力矩形に基づき、ウィンドウの特定の領域についてタブレットペンのデータを受け取ります。

既定値は空のウィンドウ入力矩形 (IRealTimeStylus::WindowInputRectangle Property の値) です。IRealTimeStylus::WindowInputRectangle Property の値が空 ({0, 0, 0, 0}) の場合、RealTimeStylus Class オブジェクトはウィンドウ全体でペン入力を収集します。これはウィンドウのサイズが変更された後も同様です。

RealTimeStylus Class オブジェクトはいったんペンデータの収集を開始すると、ペンが入力領域の外に移動した場合でも、ペンが持ち上げられるまで収集を継続します。

入力領域外で収集されたペンデータを独自に処理するには、アタッチされた IStylusSyncPlugin オブジェクトまたは IStylusAsyncPlugin オブジェクトを使用します。

子の RealTimeStylus Class オブジェクトに対してこのプロパティを設定しようとすると、E_INVALIDOPERATION HRESULT が返されます。

RealTimeStylus Class オブジェクトのウィンドウ入力矩形を取得または設定します。(Put)

各 RealTimeStylus Class オブジェクトは、その RealTimeStylus Class オブジェクトに定義されたウィンドウ入力矩形に基づき、ウィンドウの特定の領域についてタブレットペンのデータを受け取ります。

既定値は空のウィンドウ入力矩形 (IRealTimeStylus::WindowInputRectangle Property の値) です。IRealTimeStylus::WindowInputRectangle Property の値が空 ({0, 0, 0, 0}) の場合、RealTimeStylus Class オブジェクトはウィンドウ全体でペン入力を収集します。これはウィンドウのサイズが変更された後も同様です。

RealTimeStylus Class オブジェクトはいったんペンデータの収集を開始すると、ペンが入力領域の外に移動した場合でも、ペンが持ち上げられるまで収集を継続します。

入力領域外で収集されたペンデータを独自に処理するには、アタッチされた IStylusSyncPlugin オブジェクトまたは IStylusAsyncPlugin オブジェクトを使用します。

子の RealTimeStylus Class オブジェクトに対してこのプロパティを設定しようとすると、E_INVALIDOPERATION HRESULT が返されます。

同期プラグインコレクションの指定したインデックスに IStylusSyncPlugin を追加します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

同期プラグインコレクションにプラグインを動的に追加する場合に使用します。

RealTimeStylus Class オブジェクトの同期および非同期プラグインコレクションは、RealTimeStylus Class オブジェクトを無効化してから再度有効化することなく変更できます。

プラグインはフリースレッドマーシャラーを集約する必要があり、シングルスレッドアパートメントのオブジェクトであってはなりません。

例

次の C++ のコード例は、CheckBox Control (Windows Forms) のイベントハンドラーを実装したものです。m_btnPacketFilter メンバー変数で表されるコントロールのチェック状態に応じて、この関数はグローバル変数 g_pPacketModifier が表すプラグインを追加または削除します。

void CCOMRTSDlg::OnBnClickedCheckPacketFilter()
{
    HRESULT hr;
    IStylusSyncPlugin* pSyncPlugin;

    hr = g_pPacketModifier->QueryInterface(IID_IStylusSyncPlugin, reinterpret_cast<void**>(&pSyncPlugin));

    if (SUCCEEDED(hr))
    {
        if (m_btnPacketFilter.GetCheck())
        {
            // If the checkbox is checked, add the 
            // Packet Modifier plugin to the RealTimeStylus
            hr = g_pRealTimeStylus->AddStylusSyncPlugin(0, pSyncPlugin);
        }
        else
        {
            // If the checkbox is not checked, remove the 
            // Packet Modifier plugin from the RealTimeStylus
            hr = g_pRealTimeStylus->RemoveStylusSyncPlugin(0, &pSyncPlugin);
        }
    }
}

コレクションの指定したインデックスから IStylusSyncPlugin を削除します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

同期プラグインコレクションから特定のプラグインを動的に削除する場合に使用します。

RealTimeStylus Class の同期および非同期プラグインコレクションは、RealTimeStylus Class を無効化してから再度有効化することなく変更できます。

例

次の C++ のコード例は、CheckBox Control (Windows Forms) のイベントハンドラーを実装したものです。m_btnPacketFilter メンバー変数で表されるコントロールのチェック状態に応じて、この関数はグローバル変数 g_pPacketModifier が表すプラグインを追加または削除します。

void CCOMRTSDlg::OnBnClickedCheckPacketFilter()
{
    HRESULT hr;
    IStylusSyncPlugin* pSyncPlugin;

    hr = g_pPacketModifier->QueryInterface(IID_IStylusSyncPlugin, reinterpret_cast<void**>(&pSyncPlugin));

    if (SUCCEEDED(hr))
    {
        if (m_btnPacketFilter.GetCheck())
        {
            // If the checkbox is checked, add the 
            // Packet Modifier plugin to the RealTimeStylus
            hr = g_pRealTimeStylus->AddStylusSyncPlugin(0, pSyncPlugin);
        }
        else
        {
            // If the checkbox is not checked, remove the 
            // Packet Modifier plugin from the RealTimeStylus
            hr = g_pRealTimeStylus->RemoveStylusSyncPlugin(0, &pSyncPlugin);
        }
    }
}

同期プラグインコレクションからすべてのプラグインを削除します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

同期プラグインコレクション内の指定したインデックスにあるプラグインを取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

同期プラグインコレクション内のプラグイン数を取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

非同期プラグインコレクションの指定したインデックスに IStylusAsyncPlugin を追加します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

RealTimeStylus Class オブジェクトが子の RealTimeStylus Class オブジェクトを持っている場合、非同期プラグインを追加することはできません。

例

次の C++ のコード例は、IStylusAsyncPlugin のインスタンスを RealTimeStylus オブジェクトに追加します。この例では、GestureRecognizer プラグイン g_pGestureHandler に対して QueryInterface メソッドを使用して IStylusAsyncPlugin インターフェイスを取得し、続いて IRealTimeStylus::AddStylusAsyncPlugin Method を呼び出しています。

HRESULT CCOMRTSDlg::InitGestureHandler()
{
    // Create an IGestureHandler object
    HRESULT hr = CoCreateInstance(CLSID_GestureHandler, NULL, CLSCTX_INPROC, IID_IGestureHandler, (VOID **)&g_pGestureHandler);

    if (SUCCEEDED(hr))
    {
        // Get a pointer to the IStylusAsyncPlugin interface
        IStylusAsyncPlugin* pAsyncPlugin;
        hr = g_pGestureHandler->QueryInterface(IID_IStylusAsyncPlugin, reinterpret_cast<void**>(&pAsyncPlugin));
        
        if (SUCCEEDED(hr))
        {
            // Get the current count of plugins so we can
            // add this one to the end of the collection
            ULONG nAsyncPluginCount;
            hr = g_pRealTimeStylus->GetStylusAsyncPluginCount(&nAsyncPluginCount);

            if (SUCCEEDED(hr))
            {
                // Add the plugin to the StylusAsyncPlugin collection
                hr = g_pRealTimeStylus->AddStylusAsyncPlugin(nAsyncPluginCount, pAsyncPlugin);

                if (SUCCEEDED(hr))
                {
                    // Pass the Gesture Handler a pointer to the 
                    // status window so it can update the status
                    hr = g_pGestureHandler->SetStatusWindow(&m_staticGestureStatus);
                }
            }
        }
    }
    return hr;
}

非同期プラグインコレクション内の指定したインデックスにある IStylusAsyncPlugin を削除し、必要に応じて返します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

非同期プラグインコレクションからすべてのプラグインを削除します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

特定の非同期プラグインを削除するには、IRealTimeStylus::RemoveStylusAsyncPlugin Method を使用します。

非同期プラグインコレクション内の指定したインデックスにあるプラグインを取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

非同期プラグインコレクション内のプラグイン数を取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

現在の RealTimeStylus オブジェクトの非同期プラグインとして RealTimeStylus オブジェクトを取得または設定します。

子の RTS が存在しない場合、このプロパティを取得すると ppiRTS パラメーターに NULL が設定された状態で S_OK が返されます。子の RTS プロパティに NULL を設定すると、カスケードが解除されます。

子の RealTimeStylus は、さらに別の RealTimeStylus をカスケードした子として持つことはできません。

非同期コレクション内のプラグインは子を持つことができません。

IRealTimeStylus::ChildRealTimeStylusPlugin Property プロパティを使用して RealTimeStylus オブジェクトを子として設定した場合、親の RealTimeStylus には他の非同期プラグインを追加できません。チェーンの深さと幅は、子の RealTimeStylus オブジェクト 1 つに制限されます。子の RealTimeStylus は非同期プラグインを持つことができます。

IRealTimeStylus::GetStylusAsyncPluginCount Method を除き、IRealTimeStylus::AddStylusAsyncPlugin Method などの非同期プラグイン関連のメソッドは、親の RealTimeStylus に対して呼び出すと E_INVALIDOPERATION を返します。

RealTimeStylus Class オブジェクトの指定したキューにカスタムデータを追加します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

データを追加するキューは sq パラメーターで指定します。データは GUID によって識別します。

sq パラメーターはカスタムデータの追加先を指定します。指定できる追加方法は次のいずれかです。

• 入力キューで次に処理されるパケットとして追加する。
• 現在処理中のパケットの前に出力キューへ追加するパケットとして追加する。
• キュー内で現在処理中のパケットの後に出力キューへ追加するパケットとして追加する。

入力キューにデータが追加されると、そのデータは自動的に出力キューにも追加されます。挿入されるデータの順序を制御できるのは出力キューのみで、sq パラメーターに AsyncStylusQueueImmediate を渡すことで制御します。

GUID は、プラグインや real time stylus 以外のオブジェクトがキューにカスタム情報を追加する際にも使用できます。このメソッドは、RealTimeStylus Class オブジェクトへの参照を持つ任意のオブジェクトから呼び出せます。呼び出し元のオブジェクトがプラグインである必要はありません。

IRealTimeStylus::AddCustomStylusDataToQueue Method を使用すると、選択や消去などの機能を追加できます。

RealTimeStylus Class の入力キューと出力キューからデータをクリアします。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

ClearStylusQueues メソッドを使用すると、RealTimeStylus Class のキューを素早くクリアできます。このメソッドはキュー内のすべてのデータをクリアします。

例

次の C++ のコード例は、IRealTimeStylus::ClearStylusQueues Method を呼び出すボタンクリックのイベントハンドラーを示しています。また、DynamicRenderer オブジェクトがインクを描画していたウィンドウを再描画します。

void CCOMRTSDlg::OnBnClickedButtonClearTestArea()
{
    // Clear the stylus queues
    if (!SUCCEEDED(g_pRealTimeStylus->ClearStylusQueues()))
    {
        TRACE("Error clearing stylus queues.");
    }

    // Clear the status text
    m_staticGestureStatus.SetWindowTextW(L"");

    // Redraw the window to clear the ink
    this->RedrawWindow();
}

RealTimeStylus Class オブジェクトがすべてのデジタイザーからデータを収集するモードを設定します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

このメソッドを使用すると、RealTimeStylus Class オブジェクトが Tablet PC に接続された任意のタブレットからスタイラスイベントを収集できるようになります。fUseMouseForInput パラメーターは、スタイラスに加えてマウスデバイスも入力に使用できるかどうかを指定します。

最初に IRealTimeStylus::SetSingleTabletMode Method () が呼び出されていて、RealTimeStylus Class オブジェクトが有効になっている場合、この呼び出しは無効となり、TPC_E_INVALID_MODE HRESULT が返されます。

RealTimeStylus Class (RTS) オブジェクトのモードを変更し、Tablet PC に接続されたデジタイザーを表すタブレットオブジェクト 1 つのみから入力を収集するようにします。他のデジタイザーからのスタイラス入力は RealTimeStylus によって無視されます。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

RealTimeStylus Class には、タブレットに関する次の 2 つのモードのいずれかを設定できます。

• すべてのタブレットモード (既定)
• 単一タブレットモード

最初に IRealTimeStylus::SetAllTabletsMode Method () が呼び出されていて、RealTimeStylus が有効になっている場合は、TPC_E_INVALID_MODE HRESULT が返されます。

例

次の C++ のコード例は、IRealTimeStylus オブジェクト g_pRealTimeStylus を単一タブレットモードに設定してタブレットを取得し、そのプラグアンドプレイ識別子を取得します。その後、IRealTimeStylus オブジェクトをすべてのタブレットモードに戻します。

// Must be in single tablet mode for GetTablet to succeed. This call to
// SetSingleTabletMode() would likely happen somewhere else in the app.
if (SUCCEEDED(g_pRealTimeStylus->SetSingleTabletMode(pInkTablet)))
{
    IInkTablet* pTablet = NULL;

    if ((SUCCEEDED(g_pRealTimeStylus->GetTablet(&pTablet))) && (NULL != pTablet))
    {
        BSTR bstrPnPID;

        if (SUCCEEDED(pTablet->get_PlugAndPlayId(&bstrPnPID)))
        {
            TRACE("The tablet's Plug-n-Play ID is: %s\n", bstrPnPID);
        }
    }

    // Restore all tablets mode.
    g_pRealTimeStylus->SetAllTabletsMode(TRUE);
}

IInkTablet Interface オブジェクトを呼び出し元に取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

RealTimeStylus が複数のタブレットからデータを受け取っている場合、このメソッドが返るときに ppiSingleTablet には NULL が格納されます。たとえば、デジタイザーとマウスを備えたコンピューターで IRealTimeStylus::SetAllTabletsMode Method を TRUE の値で呼び出した場合などです。

例

次の C++ のコード例は、IInkTablet Interface オブジェクトへのポインターを取得し、そのポインターを使用してタブレットのプラグアンドプレイ識別子を取得します。

// Must be in single tablet mode for GetTablet to succeed. This call to
// SetSingleTabletMode() would likely happen somewhere else in the app.
if (SUCCEEDED(g_pRealTimeStylus->SetSingleTabletMode(pInkTablet)))
{
    IInkTablet* pTablet = NULL;

    if ((SUCCEEDED(g_pRealTimeStylus->GetTablet(&pTablet))) && (NULL != pTablet))
    {
        BSTR bstrPnPID;

        if (SUCCEEDED(pTablet->get_PlugAndPlayId(&bstrPnPID)))
        {
            TRACE("The tablet's Plug-n-Play ID is: %s\n", bstrPnPID);
        }
    }

    // Restore all tablets mode.
    g_pRealTimeStylus->SetAllTabletsMode(TRUE);
}

指定したタブレットデジタイザーオブジェクトに関連付けられた TabletContextId プロパティを取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

デジタイザーのコンテキスト識別子は RealTimeStylus Class オブジェクトごとに固有です。2 つの RealTimeStylus Class オブジェクトが、同じデジタイザーオブジェクトに対して異なるコンテキスト識別子を持つ場合があります。タブレットコンテキスト識別子が有効なのは、RealTimeStylus Class オブジェクトが有効になっている間だけです。RealTimeStylus Class オブジェクトを無効化してから再度有効化した場合、各デジタイザーオブジェクトの TCID は、RealTimeStylus Class オブジェクトを最初に有効化したときとは異なる値になることがあります。

このメソッドは、RealTimeStylus Class オブジェクトが有効でない場合でも、RealTimeStylus Class がキュー内のデータの処理を完了していない限り呼び出せます。最後の非同期プラグインが IStylusPlugin::RealTimeStylusDisabled Method を受け取るまで、このメソッドを呼び出すことができます。

例

次の C++ のコード例は、IInkTablet オブジェクトへのポインターを取得し、それを使用してタブレットコンテキスト識別子を取得します。その後、システムに接続されているすべてのタブレットの名前をデバッグ出力ウィンドウに表示します。

TABLET_CONTEXT_ID* pTcids = NULL;
TABLET_CONTEXT_ID tcid = 0;
ULONG ulTcidCount = 0;
IInkTablet* pInkTablet = NULL;

if (SUCCEEDED(g_pRealTimeStylus->GetAllTabletContextIds(&ulTcidCount, &pTcids)))
{
    TRACE("Got the tablet context ID array.\n");

    // Loop through all the tablets on the system
    for (ULONG i = 0; i < ulTcidCount; i++)
    {
        // Get the tablet from the context ID
        if (SUCCEEDED(g_pRealTimeStylus->GetTabletFromTabletContextId(pTcids[i], &pInkTablet)))
        {
            // Display the name of the tablet in debug output
            BSTR bstrName;
            if (SUCCEEDED(pInkTablet->get_Name(&bstrName)))
            {
                TRACE("The name of tablet %d is %s.\n", i, bstrName);
            }
        }
    }

    // Get the context ID from the tablet
    if (SUCCEEDED(g_pRealTimeStylus->GetTabletContextIdFromTablet(pInkTablet, &tcid)))
    {
        TRACE("The context ID of the tablet is %d\n", tcid);
    }
}

指定したタブレットコンテキストに対応する IInkTablet Interface を取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

タブレットコンテキスト識別子は RealTimeStylus Class オブジェクトごとに固有です。2 つの RealTimeStylus Class オブジェクトが、同じタブレットオブジェクトに対して異なるコンテキスト識別子を持つ場合があります。タブレットコンテキスト識別子が有効なのは、RealTimeStylus Class オブジェクトが有効になっている間だけです。RealTimeStylus Class オブジェクトを無効化してから再度有効化した場合、各タブレットオブジェクトのタブレットコンテキスト識別子は、RealTimeStylus Class オブジェクトを最初に有効化したときとは異なる値になることがあります。

このメソッドは、IRealTimeStylus::Enabled Property が false を返す場合でも、IStylusPlugin::RealTimeStylusDisabled Method がキュー内のデータの処理を完了していない限り呼び出せます。最後の非同期プラグインが IStylusPlugin::RealTimeStylusDisabled Method を受け取るまで、このメソッドを呼び出すことができます。

例

次の C++ のコード例は、タブレットコンテキスト識別子を使用して IInkTablet Interface オブジェクトへのポインターを取得します。

TABLET_CONTEXT_ID* pTcids = NULL;
TABLET_CONTEXT_ID tcid = 0;
ULONG ulTcidCount = 0;
IInkTablet* pInkTablet = NULL;

if (SUCCEEDED(g_pRealTimeStylus->GetAllTabletContextIds(&ulTcidCount, &pTcids)))
{
    TRACE("Got the tablet context ID array.\n");

    // Loop through all the tablets on the system
    for (ULONG i = 0; i < ulTcidCount; i++)
    {
        // Get the tablet from the context ID
        if (SUCCEEDED(g_pRealTimeStylus->GetTabletFromTabletContextId(pTcids[i], &pInkTablet)))
        {
            // Display the name of the tablet in debug output
            BSTR bstrName;
            if (SUCCEEDED(pInkTablet->get_Name(&bstrName)))
            {
                TRACE("The name of tablet %d is %s.\n", i, bstrName);
            }
        }
    }

    // Get the context ID from the tablet
    if (SUCCEEDED(g_pRealTimeStylus->GetTabletContextIdFromTablet(pInkTablet, &tcid)))
    {
        TRACE("The context ID of the tablet is %d\n", tcid);
    }
}

現在アクティブなすべてのタブレットコンテキスト識別子を含む配列を取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

IRealTimeStylus::GetAllTabletContextIds Method メソッドは、現在アクティブなすべてのタブレットコンテキスト識別子へのアクセスを提供します。このメソッドを使用すると、IStylusPlugin::RealTimeStylusEnabled Method の通知からデータをキャッシュする代わりに、これらの識別子を直接取得できます。

TabletContextID プロパティの適用範囲は、RealTimeStylus Class の特定のインスタンスに限定されます。Tablet オブジェクトは、RealTimeStylus Class のインスタンスごとに異なる一意の識別子を持つ場合があります。

例

次の C++ のコード例は、すべてのタブレットコンテキスト識別子を取得し、最初のタブレットコンテキスト識別子を使用して IInkTablet Interface オブジェクトへのポインターを取得します。

TABLET_CONTEXT_ID* pTcids = NULL;
TABLET_CONTEXT_ID tcid = 0;
ULONG ulTcidCount = 0;
IInkTablet* pInkTablet = NULL;

if (SUCCEEDED(g_pRealTimeStylus->GetAllTabletContextIds(&ulTcidCount, &pTcids)))
{
    TRACE("Got the tablet context ID array.\n");

    // Loop through all the tablets on the system
    for (ULONG i = 0; i < ulTcidCount; i++)
    {
        // Get the tablet from the context ID
        if (SUCCEEDED(g_pRealTimeStylus->GetTabletFromTabletContextId(pTcids[i], &pInkTablet)))
        {
            // Display the name of the tablet in debug output
            BSTR bstrName;
            if (SUCCEEDED(pInkTablet->get_Name(&bstrName)))
            {
                TRACE("The name of tablet %d is %s.\n", i, bstrName);
            }
        }
    }

    // Get the context ID from the tablet
    if (SUCCEEDED(g_pRealTimeStylus->GetTabletContextIdFromTablet(pInkTablet, &tcid)))
    {
        TRACE("The context ID of the tablet is %d\n", tcid);
    }
}

RealTimeStylus Class オブジェクトが検出したスタイラスのコレクションを取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

RealTimeStylus Class のコレクションには、タブレットコンテキストが作成されたスタイラスが含まれます。このスタイラスコレクションには、システムで利用可能なすべてのスタイラスが含まれるわけではありません。

RealTimeStylus Class オブジェクトに関連付けられたタブレットオブジェクトでスタイラスオブジェクトが検出されていない場合、このメソッドは空の配列を返します。

このメソッドは、RealTimeStylus Class オブジェクトが接続され、かつ有効になっていなければ呼び出せません。

例

次の C++ のコード例は、RealTimeStylus Class オブジェクトが最後に有効化されて以降に検出した Stylus オブジェクトの配列を取得します。その後、配列を反復処理して各スタイラスの ID をデバッグ出力に表示します。

IInkCursors *piInkCursors;

if (SUCCEEDED(g_pRealTimeStylus->GetStyluses(&piInkCursors)))
{
    long lCursorCount;
    
    if (SUCCEEDED(piInkCursors->get_Count(&lCursorCount)))
    {
        for (long l = 0; l < lCursorCount; l++)
        {
            LONG sid;
            IInkCursor *piInkCursor;
            IInkCursor *piInkCursorForId;

            piInkCursors->Item(l, &piInkCursor);
            piInkCursor->get_Id(&sid);

            if (SUCCEEDED(g_pRealTimeStylus->GetStylusForId((STYLUS_ID)sid, &piInkCursorForId)))
            {
                TRACE("Got stylus with ID %d\n", sid);
            }
        }
    }
}

指定したスタイラス識別子に対応するスタイラスを取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

パケットストリームに含めるプロパティを要求します。

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

イベントは実際のパケットプロパティを次の順序で受け取ります。

パケットの順序	説明
1 番目	DesiredPacketDescription Property で X が指定されているかどうかにかかわらず、そのプロパティの x 座標データが格納されます。
2 番目	DesiredPacketDescription Property で Y が指定されているかどうかにかかわらず、そのプロパティの y 座標データが格納されます。
最後	DesiredPacketDescription Property にパケットステータスが含まれている場合、パケットステータスが格納されます。

指定したパケットプロパティがタブレットデバイスでサポートされていない場合、そのプロパティのデータは返されず、パケットデータ配列にも含まれません。packetDescription 引数に同じ GUID が複数回現れる場合、最初の 1 つだけが保持され、以降のものはすべて除外されます。IRealTimeStylus::SetDesiredPacketDescription Method メソッドは、RealTimeStylus Class オブジェクトが無効になっている間にのみ呼び出せます。

cProperties に 0 を、pPropertyGuids に NULL を渡そうとすると E_INVALIDARG が返されます。

IRealTimeStylus::SetDesiredPacketDescription Method メソッドの呼び出しは、IRealTimeStylus::GetDesiredPacketDescription Method メソッドの戻り値に即座に反映されます。

例

次の C++ のコード例は、パケットストリームに含めるよう要求するプロパティを設定します。

GUID guidDesiredPacketDescription[] = { GUID_PACKETPROPERTY_GUID_X, 
                                        GUID_PACKETPROPERTY_GUID_Y, 
                                        GUID_PACKETPROPERTY_GUID_NORMAL_PRESSURE,
                                        GUID_PACKETPROPERTY_GUID_TANGENT_PRESSURE };

// Number of properties in the array
ULONG ulProperties = sizeof(guidDesiredPacketDescription) / sizeof(GUID);

// Set the packet information we'd like to get
if (SUCCEEDED(g_pRealTimeStylus->SetDesiredPacketDescription(ulProperties, guidDesiredPacketDescription)))
{
    TRACE("Set the desired packet description successfully.\n");
}

GUID* pGuids = NULL;

// See if setting the properties was successful
if (SUCCEEDED(g_pRealTimeStylus->GetDesiredPacketDescription(&ulProperties, &pGuids)))
{
    TRACE("The RealTimeStylus supports %d properties.\n", ulProperties);

    // Display the values of the GUIDs in debug output
    for (int i = 0; i < ulProperties; i++)
    {
        TRACE("GUID #%d == %d\n", i, pGuids[i]);
    }
}

パケットストリームに含めるよう要求されたプロパティの一覧を取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

このメソッドを使用すると、IRealTimeStylus::SetDesiredPacketDescription Method の呼び出しによって IRealTimeStylus オブジェクトが購読したパケットプロパティの配列を取得できます。パケットプロパティはグローバル一意識別子 (GUID) の配列で表されます。メトリックを取得できるプロパティの完全な一覧については、PacketPropertyGuids Constants を参照してください。

既定値は、X、Y、および法線方向の筆圧の GUID を含む GUID 配列です。

IRealTimeStylus::GetDesiredPacketDescription Method は、GUID 用の領域を確保するために CoTaskMemAlloc を使用します。呼び出し元は、配列が不要になった時点で CoTaskMemFree を呼び出す必要があります。

子の IRealTimeStylus オブジェクト (カスケード構成) に対して呼び出され、接続されている場合、このメソッドは親のパケット記述を返します。接続されていない場合は、既定値 (X、Y、筆圧)、または以前の IRealTimeStylus::SetDesiredPacketDescription Method の呼び出しで設定されたプロパティを返します。

IRealTimeStylus オブジェクトによるパケットプロパティ GUID の並び順は次のとおりです。

• 既定では、IRealTimeStylus::GetDesiredPacketDescription Method メソッドは GUID_X、GUID_Y、GUID_NORMAL_PRESSURE を返します。
• X と Y の GUID は、以前の IRealTimeStylus::SetDesiredPacketDescription Method メソッドの呼び出しで指定されたかどうかにかかわらず、IRealTimeStylus::GetDesiredPacketDescription Method メソッドによって常に配列の先頭 2 つの位置に返されます。
• IRealTimeStylus::SetDesiredPacketDescription Method メソッドの呼び出しで GUID_PACKET_STATUS が指定された場合、GUID_PACKET_STATUS は IRealTimeStylus::GetDesiredPacketDescription Method メソッドによって常に配列の最後の位置に返されます。
• IRealTimeStylus::SetDesiredPacketDescription Method メソッドの呼び出しで同じ GUID が複数回指定された場合でも、各 GUID は IRealTimeStylus::GetDesiredPacketDescription Method メソッドが返す配列内に 1 回だけ現れます。

例

次の C++ のコード例は、パケットストリームに含まれるプロパティの一覧を取得します。

GUID guidDesiredPacketDescription[] = { GUID_PACKETPROPERTY_GUID_X, 
                                        GUID_PACKETPROPERTY_GUID_Y, 
                                        GUID_PACKETPROPERTY_GUID_NORMAL_PRESSURE,
                                        GUID_PACKETPROPERTY_GUID_TANGENT_PRESSURE };

// Number of properties in the array
ULONG ulProperties = sizeof(guidDesiredPacketDescription) / sizeof(GUID);

// Set the packet information we'd like to get
if (SUCCEEDED(g_pRealTimeStylus->SetDesiredPacketDescription(ulProperties, guidDesiredPacketDescription)))
{
    TRACE("Set the desired packet description successfully.\n");
}

GUID* pGuids = NULL;

// See if setting the properties was successful
if (SUCCEEDED(g_pRealTimeStylus->GetDesiredPacketDescription(&ulProperties, &pGuids)))
{
    TRACE("The RealTimeStylus supports %d properties.\n", ulProperties);

    // Display the values of the GUIDs in debug output
    for (int i = 0; i < ulProperties; i++)
    {
        TRACE("GUID #%d == %d\n", i, pGuids[i]);
    }
}

パケットプロパティとスケーリング係数を取得します。

戻り値の説明については、RealTimeStylus Classes and Interfaces を参照してください。

スケーリングのパラメーターが不要な場合は NULL を渡すことができます。

IRealTimeStylus::GetPacketDescriptionData Method は、ppPacketProperties 用の領域を確保するために CoTaskMemAlloc を使用します。呼び出し元は、配列が不要になった時点で CoTaskMemFree を呼び出す必要があります。

プラグインに送られるデータストリーム内のプロパティの順序は、IRealTimeStylus::GetPacketDescriptionData Method が返すプロパティの順序と同じです。このメソッドを使用すると、IRealTimeStylus::SetDesiredPacketDescription Method の呼び出しで要求した内容に対して、ハードウェアが実際に報告している内容を確認できます。

例

次の C++ のコード例は、IRealTimeStylus::GetPacketDescriptionData Method メソッドを使用してインクのパケットデータに関する情報を取得します。

STDMETHODIMP CCustomRenderer::StylusUp( 
            /* [in] */ IRealTimeStylus *piRtsSrc,
            /* [in] */ const StylusInfo *pStylusInfo,
            /* [in] */ ULONG cPropCountPerPkt,
            /* [size_is][in] */ LONG *pPacket,
            /* [out][in] */ LONG **ppInOutPkt)
{
TABLET_CONTEXT_ID *pTcids;
ULONG ulTcidCount;
TABLET_CONTEXT_ID tcid;
FLOAT fInkToDeviceScaleX;
FLOAT fInkToDeviceScaleY;
ULONG ulPacketProperties;
PACKET_PROPERTY *pPacketProperties;

// Get all the tablet context identifiers
HRESULT hr = piRtsSrc->GetAllTabletContextIds(&ulTcidCount, &pTcids);

// Use the first tablet context identifier in the array
tcid = *pTcids;

// Get the packet description data
hr = piRtsSrc->GetPacketDescriptionData(tcid, &fInkToDeviceScaleX, 
                                        &fInkToDeviceScaleY, &ulPacketProperties,
                                        &pPacketProperties);

// Use the packet description data to do things like scale the ink 
// to the physical display device when rendering your own strokes

    return S_OK;
}

#define global IID_IRealTimeStylus "{A8BB5D22-3144-4A7B-93CD-F34A16BE513A}"
#usecom global IRealTimeStylus IID_IRealTimeStylus "{E26B366D-F998-43CE-836F-CB6D904432B0}"
#comfunc global IRealTimeStylus_get_Enabled                       3 var
#comfunc global IRealTimeStylus_put_Enabled                       4 int
#comfunc global IRealTimeStylus_get_HWND                          5 var
#comfunc global IRealTimeStylus_put_HWND                          6 sptr
#comfunc global IRealTimeStylus_get_WindowInputRectangle          7 var
#comfunc global IRealTimeStylus_put_WindowInputRectangle          8 var
#comfunc global IRealTimeStylus_AddStylusSyncPlugin               9 int,sptr
#comfunc global IRealTimeStylus_RemoveStylusSyncPlugin            10 int,sptr
#comfunc global IRealTimeStylus_RemoveAllStylusSyncPlugins        11
#comfunc global IRealTimeStylus_GetStylusSyncPlugin               12 int,sptr
#comfunc global IRealTimeStylus_GetStylusSyncPluginCount          13 var
#comfunc global IRealTimeStylus_AddStylusAsyncPlugin              14 int,sptr
#comfunc global IRealTimeStylus_RemoveStylusAsyncPlugin           15 int,sptr
#comfunc global IRealTimeStylus_RemoveAllStylusAsyncPlugins       16
#comfunc global IRealTimeStylus_GetStylusAsyncPlugin              17 int,sptr
#comfunc global IRealTimeStylus_GetStylusAsyncPluginCount         18 var
#comfunc global IRealTimeStylus_get_ChildRealTimeStylusPlugin     19 sptr
#comfunc global IRealTimeStylus_putref_ChildRealTimeStylusPlugin  20 sptr
#comfunc global IRealTimeStylus_AddCustomStylusDataToQueue        21 int,var,int,var
#comfunc global IRealTimeStylus_ClearStylusQueues                 22
#comfunc global IRealTimeStylus_SetAllTabletsMode                 23 int
#comfunc global IRealTimeStylus_SetSingleTabletMode               24 sptr
#comfunc global IRealTimeStylus_GetTablet                         25 sptr
#comfunc global IRealTimeStylus_GetTabletContextIdFromTablet      26 sptr,var
#comfunc global IRealTimeStylus_GetTabletFromTabletContextId      27 int,sptr
#comfunc global IRealTimeStylus_GetAllTabletContextIds            28 var,var
#comfunc global IRealTimeStylus_GetStyluses                       29 sptr
#comfunc global IRealTimeStylus_GetStylusForId                    30 int,sptr
#comfunc global IRealTimeStylus_SetDesiredPacketDescription       31 int,var
#comfunc global IRealTimeStylus_GetDesiredPacketDescription       32 var,var
#comfunc global IRealTimeStylus_GetPacketDescriptionData          33 int,var,var,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。