Wintab

LINEで送る

本仕様は、複数の大手デジタイザメーカーおよびアプリケーションデベロッパーによるデジタイジングタブレット、3次元位置センサー、およびその他のポインティングデバイスのプログラミングインターフェース標準化のニーズに対応するために作成されました。仕様の機能をサポートするドライバの可用性により、絶対座標入力を組み込み、高度なポインティングデバイスを普及させるWindowsアプリケーションプログラムの開発プロセスが簡略化されます。
本仕様は、オープン標準として開発されました。本書の内容は、補償やライセンスの制限なく自由に使用、複製、配布して構いません。
オリジナル版:copyright c 1991 by LCS/Telegraphics.
改訂版:copyright c 2010 by Wacom Technology Corp.

ご質問やご意見は下記までお送りください。
http://solution.wacom.jp/contact.html

Wacomタブレットの使用に関する一般的な質問は、次のサイトにアクセスしてください。
http://www.wacom.com/jp/ja/contact

INDEX

1 概要
1.1 Wintabとは
1.2 Intuosシリーズ
1.3 アプリケーションの変更点
2 Wintabの初期化とデータ
2.1 プログラムヘッダーでの注意
2.2 Wintabの存在確認
2.3 Wintabの初期化
3 一般的な座標データ入力方法
3.1 メッセージによるデバイス情報の取得
3.2 ポーリングによるデバイス情報の取得
3.3 アクティブ/非アクティブ時の処理
3.4 システムコンテキストとデジタイザコンテキストの併用
4 各種タブレット情報の取得
4.1 パケットの宣言
4.2 パケットの構成
4.3 カーソル情報
4.4 ボタン情報
4.5 座標データ
4.6 筆圧情報
4.7 傾き情報
4.8 回転情報(4Dマウスのホイール情報)
5 その他の情報
5.1 IntuosシリーズにおけるデバイスIDの求め方
5.2 イレーサの識別方法
5.3 データの最大値、最小値の求め方
5.4 タブレット座標データの最大最小と分解能を知る
5.5 使っているタブレットで利用可能なデバイスの種類を知る方法
5.6 Out of Bounds Trackingの設定
5.7 パケットデータキューのサイズを変更する
5.8 Wintabバージョンを識別する
6 関数リファレンス
6.1 基本的な関数
6.1.1. WTInfo
6.1.2. WTOpen
6.1.3. WTClose
6.1.4. WTPacketsGet
6.1.5. WTPacket
6.2 可視化関数
6.2.1. WTEnable
6.2.2. WTOverlap
6.3 コンテキスト編集関数
6.3.1. WTGet
6.3.2. WTSet(1.1変更)
6.3.3. WTExtGet
6.3.4. WTExtSet
6.3.5. WTSave
6.3.6. WTRestore
6.4 高度なパケットおよびキュー関数
6.4.1. WTPacketsPeek
6.4.2. WTDataGet
6.4.3. WTDataPeek
6.4.4. WTQueuePackets(16ビットのみ)
6.4.5. WTQueuePacketsEx
6.4.6. WTQueueSizeGet
6.4.7. TQueueSizeSet
6.5 マネージャーハンドル関数
6.5.1. WTMgrOpen
6.5.2. WTMgrClose
6.6 マネージャーコンテキスト関数
6.6.1. WTMgrContextEnum
6.6.2. WTMgrContextOwner
6.6.3. WTMgrDefContext
6.6.4. WTMgrDefContextEx(1.1変更、1.4変更)
6.7 マネージャーのユーザ設定データ関数(1.4変更)
6.7.1. WTMgrCsrButtonMap
6.7.2. WTMgrCsrPressureBtnMarks(16ビットのみ)
6.7.3. WTMgrCsrPressureBtnMarksEx
6.7.4. WTMgrCsrPressureResponse
7 メッセージリファレンス
7.1 イベントメッセージ
7.1.1. WT_PACKET
7.1.2. WT_CSRCHANGE (1.1)
7.2 コンテキストメッセージ
7.2.1. WT_CTXOPEN
7.2.2. WT_CTXCLOSE
7.2.3. WT_CTXUPDATE
7.2.4. WT_CTXOVERLAP
7.2.5. WT_PROXIMITY
7.3. 情報変更メッセージ
7.3.1. WT_INFOCHANGE(1.4変更)
8 データリファレンス
8.1 一般的なデータ型(1.1変更、1.4変更)
8.2 情報データ構造体
8.2.1. AXIS
8.2.2. 情報カテゴリおよびインデックス(1.1変更)
8.3 コンテキストデータ構造体
8.3.1. LOGCONTEXT(1.1変更)
8.4 イベントデータ構造体
8.4.1. PACKET(1.1変更)
8.4.2. ORIENTATION
8.4.3. ROTATION (1.1)
付録A. PKTDEF.Hの使用
付録B. 拡張定義(1.4変更)
B.1 拡張プログラミング
拡張のプログラミングノート
B.2 OUT OF BOUNDS TRACKING(境界外トラッキング)
OBTプログラミング
情報カテゴリー
OBTのオンまたはオフ
B.5 カーソルマスク
CSRMASKプログラミング
情報カテゴリー
B.7 EXPRESS KEYS(ファンクションキー)拡張(1.4変更)
B.8 TOUCH STRIPS(トラックパッド)およびTOUCH RINGS(タッチホイール)拡張(1.4変更)
B.9 拡張の構造(1.4変更)
EXPKEYSDATA構造体
SLIDERDATA構造体
EXTPROPERTY構造体
付録C. 追加機能(1.4変更)
c.1 消しゴム
c.2 傾き検出
c.3 DUAL TRACK
c.4 UNIQUE ID
c.5 エアブラシ FINGERWHEEL
c.6 4D マウス 回転
c.7 4D マウス サムホイール

詳細

1 概要

この解説書はWintab APIを使ったアプリケーションを開発する場合のガイドとして準備されたものです。
ここでは、ワコムタブレットの特長を生かすためのプログラミングを中心に、最低必要なAPIの使用方法について解説してみました。
この章ではWintab APIを使用するにあたり、どのようなプログラミング変更が必要か、また既にWintabに対応しているアプリケーションがワコムタブレットに対応するにはどのような注意点があるかを記述しています。

1.1 Wintabとは

Wintabとは、Windows上でタブレットを利用するためのAPIで、マウスにはないタブレット独自の機能をサポートできるように設計されたものです。 Windowsでは標準的にはマウスを想定したポインティングデバイスのインターフェースをもっていますが、タブレットのデバイス、例えば電子ペンのようなポインティングだけではない、デバイスに特有な筆圧、傾きなどの情報は、アプリケーションに渡すことができません。
Wintab APIはタブレットの持つ高精度の位置情報はもとより、デバイスの直感的な操作にかかる情報を効率よく伝え、創造的なアプリケーションに生かせるように設計されています。

1.2 Intuosシリーズ

Intuosシリーズは、コンピュータでのより創造的な作業を可能にするために、もっと多くの表現が可能なデバイスを利用できるようにしたタブレットです。
Intuosシリーズでサポートするデバイスには、従来の筆圧ペンやカーソルの他に、エアブラシ、4Dマウスといったものがあります。筆圧の分解能も感度も優れたものになっています。
エアブラシの特長は、ペンのサイドにFingerwheelというホイールが付いていて、ここを回転させることにより筆圧、傾きの他にもう一つの情報がアプリケーションに伝えられます。
4Dマウスは従来のカーソルに似ていますが、これに加えてローテーション情報、ホイール情報が追加されています。ローテーション情報とはタブレット板面に垂直な軸に対する回転角度です。4Dマウスの向きを表わします。ホイール情報とは、4Dマウスのサイドに付いたホイールを前後に親指で回転させることで、この回転の度合いを伝えます。
将来的にはさらに用途にあったデバイスが投入される予定です。Intuosシリーズタブレットは将来的に投入されるデバイスについても対応できるように設計されています。
デバイスにID番号が記憶されている事も特長の一つです。デバイスの種別とデバイスごとに固有な32ビットのシリアル番号の組み合わせでできており、これらは重複することはありません。

1.3 アプリケーションの変更点

従来のWintabを利用してきたアプリケーションにおいては、入手できる情報が増えたことが大きな変更点となります。新しいデバイス用に、Wintabパケットの宣言方法、パケットからのデータ入手方法を追加、改良してご利用頂けます。
以下、新規でWintabに対応される場合を中心に解説します。タブレットの情報を取得するためには、次のようなプログラムの追加が必要になります。
※ []で示した数字は解説している章の番号を示します。

  1. アプリケーション起動時にWintabの初期化を行う

    まず、WTInfo()関数で、タブレットが利用可能か確認します[2.2]。
    同じくWTInfo()関数でタブレットの基本情報を取得、この基本情報を元にWTInfo()関数でアプリケーションに合ったタブレット環境を設定します[2.3]。タブレット情報はマウス情報に比べ情報量が多いのでWintabデータキューがオーバーフローする場合があります。そのためアプリケーションの処理内容にあわせ、適当なキューサイズをWTQueueSizeSet()関数で設定しておくこともできます。[5.6]

  2. イベントハンドラ

    タブレットのデータを取り込むタイミングが重要になります。デバイスの操作をすばやく取り込んでアプリケーションに生かすには、次のイベントメッセージを利用する方法があります。

    • WM_LBUTTONDOWN / WM_LBUTTONUP

      マウスのボタンダウン、アップ、デバイスのスイッチON/OFFでこのメッセージを受け取ることができます。通常、WM_LBUTTONDOWNを受け取ってからWM_LBUTTONUPを受け取るまでずっとペンダウン状態であるとみなして、WTPacketsGet()関数でデータキューにたまっている情報を取り続けるようにすることで描画処理を行うこともできます。
      マウスイベントとWintabパケットは同期していませんので、プログラミングに際しては少し工夫が必要です。例えば、 WM_LBUTTONDOWNを受け取った時、Wintabのデータキューにはまだスイッチが入っていない時の情報が残っていますので、これらを全て整理してスイッチが入った後の情報を使うようにすれば、正確な描画が可能になります。 WM_LBUTTONUPの時も同様な処理が必要になります。

    • WT_PACKET

      アプリケーションがWintab初期化の時に、コンテキストにCXO_MESSAGEオプションをセットしていれば、Wintab Packetが生成されると同時にメッセージがアプリケーションに送られてきます[2.3]。このタイミングでWTPacket()関数を使ってデータを取り込みます。この時、どのくらいのパケットが来ており、後どのくらいのパケットを読み込まねばならないかを調べることで、データを漏らさず取り込むこともできます。WTQueuePackets()関数またはWTQueuePacketsEx()関数にてキューに残っているデータの最も古いシリアル番号と最新のシリアル番号を知ることができます。WTDataGet()関数でこのシリアル番号をパラメータにして、キューに残っている全てのパケットを読み出します。

    • WT_CSRCHANGE(またはWT_PROXIMITY)

      デバイスが入れ替わったり、有効領域にデバイスが入って来たり有効領域外に出たりした時にはWT_PROXIMITYメッセージが送られてきます。違うデバイスが有効領域に入って来た時にはWT_CSRCHANGEが送られてきます。この時点でWTInfo()関数を使ってデバイス固有のIDを読み取り、デバイスに対応した処理をプログラムすることが可能です。[5.1]

  3. Wintabバージョンの識別
    同じWintabを使っていても、ライブラリが古くて新しいIntuosシリーズの機能が使えない場合もあります。Wintabバージョンを識別しておくことをお勧めします。[5.7]

  4. コンテキストの切り替え
    アプリケーション毎にWintabコンテキストを設定することができます。Wintabを使うアプリケーションが同時に開いていた場合、Wintabはそれらのコンテキストがどのようにオーバーラップしているかを見て、最上位にあるコンテキストに従ってパケットを生成して送信します。
    アプリケーションは自分のコンテキストを最上位に持ってくるか下位にするかをWTOverlap()関数で設定することができます。例えば、アプリケーションがWM_ACTIVATEメッセージを受けた時、アクティブになった時は自分のコンテキストを最上位に、アクティブでなくなった時は最下位に設定することで、他のアプリケーションとの混乱を防ぐことができます。[3.3]

2 Wintabの基本的な使い方

2.1 サポートされているバージョン

プログラムヘッダーでの注意
Wintabは最初にパケットの構造を宣言する事から始まります。そのためWintabを利用するためには、決められた手順通りにコーディングする必要があります。
Wintabを利用するためには、関連する3つのヘッダファイルを以下のように、インクルードします。

#include <WINDOWS.H>
.......
#include <MSGPACK.H>
#include <WINTAB.H>
#define PACKETDATA PK_X | PK_Y | PK_BUTTONS
#define PACKETMODE PK_BUTTONS
#include <PKTDEF.H>
.......

注) PACKETDATA/PACKETMODEのdefineは、必ず行ってください。

2.2 Wintabの存在確認

動作中の環境で、Wintab I/Fが使用できるかどうかを確認します。使用中のポインティングデバイスドライバ(タブレットドライバ)で、Wintabが使用できる状態にあるかをチェックします。

IF (!WTInfo(0, 0, NULL)) {
  エラー処理:WINTABが使用できない
}

2.3 Wintabの初期化

Wintabを使用したいモードでオープンします。オープン時のモードの設定は、引き数で渡す LOGCONTEXT構造体で行います。この構造体は、Wintabが持っているデフォルトのLOGCONTEXT構造体を取得し、必要な情報を変更する形で作成します。デフォルトコンテキストはワコムの場合はドライバで設定しています。(入力エリアなど、ドライバの設定を変更することで変わることがあります。)

データの流れを簡単な図で表わすと以下のようになります。
Wintabの初期化

  1. システムカーソルを使用するかどうかの設定

    システムを経由しないで(システムカーソルを表示しない)タブレットから情報を得る場合(これをデジタイジングコンキストと呼びます)と、システムカーソルを動かしながらタブレットの入力も行うモード(システムコンテキストと呼びます)の2種類があります。
    設定方法は、WTInfo 関数でデジタイジングコンテキストか システムコンテキストのどちらを選ぶかを指示します。

    Wintabの初期化を以下に示します。パラメータのカテゴリーにそれぞれ WTI_DEFCONTEXT または WTI_DEFSYSCTX を渡しています。これで得られた LOGCONTEXT のデータテーブルに必要な情報をセットしてWintabを初期化( WTOpen 関数で行います)すると、アプリケーションに固有なWintab設定でタブレットを操作できるようになります。

    ◎ Wintabイベントのメッセージを利用して制御する場合

    WTInfo(WTI_DEFCONTEXT, 0, &lcMine);
    lcMine.lcOption |= CXO_MESSAGES; /* Wintabメッセージが渡されるようにする */
    lcMine.lcMsgBase = WT_DEFBASE;
    lcMine.lcPktData = PACKETDATA;
    lcMine.lcPktMode = PACKETMODE;
    lcMine.lcMoveMask = PACKETDATA;
    lcMine.lcBtnUpMask = lcMine.lcBtnDnMask;
    hTab = WTOpen(hWnd, &lcMine, TRUE); /* 初期化 */
    

    ◎ポーリング形の制御をする場合

    WTInfo(WTI_DEFSYSCTX, 0, &lcMine);
    lcMine.lcMsgBase = WT_DEFBASE;
    lcMine.lcPktData = PACKETDATA;
    lcMine.lcPktMode = PACKETMODE;
    lcMine.lcMoveMask = PACKETDATA;
    lcMine.lcBtnUpMask = lcMine.lcBtnDnMask;
    hTab = WTOpen(hWnd, &lcMine, TRUE);
    
  2. スケーリングの初期化について
    以下のように、LOGCONTEXT の値を初期化する事でスケールの設定を行います。

    ① lcInOrgX,lcInOrgY にタブレットの入力開始座標
    ② lcInExtX,lcInExtY にタブレットの入力最大座標
    ③ lcOutExtX,lcOutExtY にウィンドウの解像度を設定します。
    ④ lcOutOrgX,lcOutOrgY に③で指示した解像度でカウントした場合の原点を指定します。通常0を入れます。

    デフォルトはタブレットドライバが設定している領域が割り当てられています。しかし、タブレット側でどのように有効領域内で操作範囲を設定しているかわからないので、タブレットの最大座標を求めて最大座標に設定することもあります。
    タブレットの最大座標を求めるには次の関数を使います。

    LONG minX,maxX,resX;
    LONG minY,maxY,resY;
    FIX32 axRes;
    WTInfo(WTI_DEVICES, DVC_X, &axis);
    maxX = axis.axMax; /* X方向の最大座標 */
    axResX = axis.axResolution; /* X座標の分解能 単位:line/inch */
    WTInfo(WTI_DEVICES, DVC_Y, &axis);
    maxY = axis.axMax; /* Y方向の最大座標 */
    axResY = axis.axResolution; /* Y座標の分解能 単位:line/inch */
    resX = HIWORD(axResX); /* highワードが分解能の整数部になっています */
    resY = HIWORD(axResY); /* 以上はタブレット情報として持っておくと良いです*/
    WTInfo(WTI_DEFSYSCTX, 0, &lcMine);
    ....... 
    lcMine.lcInOrgX = lcMine.lcInOrgY = 0;
    lcMine.lcInExtX = maxX; /* タブレットの有効範囲全域を操作エリアとします */
    lcMine.lcInExtY = maxY;
    lcMine.lcOutOrgX = lcMine.lcOutOrgY = 0;
    lcMine.lcOutExtX = maxX; /* タブレットの分解能と入力データの分解能を */
    lcMine.lcOutExtY = maxY; /* あわせます */
    hTab = WTOpen(hWnd, &lcMine, TRUE); /* Wintabの初期化 */
    .......
    

    これでタブレットからでてくる生データを取り込むことができるようになります。
    ここで設定した内容はこのアプリケーション独自の設定としてWintabが管理します。

    lcMine.lcOutExtX = lcMine.lcInExtX;
    lcMine.lcOutExtY = lcMine.lcInExtY;
    

    とすれば、タブレットドライバのほうでスケーリングを設定していても、その設定を変えることなくかつタブレット分解能そのものを取り込むことができます。
    上記の①②③④の設定はデフォルト設定(とくに設定を書き込まない)にしておけば、現在のシステムのデフォルト設定でスケーリングが設定されます。
    ワコムのタブレットドライバのほうで設定したスケーリングはそのままデフォルト設定となっています。

    ⑤ lcSysOrgX,lcSysOrgY 及び lcSysExtX,lcSysExtY には表示画面の解像度(ピクセル値)に対してどの範囲でシステムカーソルを動作させるかをピクセル値で設定します。
    例えば、1024*768 の表示分解能であった時に、上記の値をそれぞれ 100,100、1000,700 とすると、タブレットの操作範囲いっぱいに動かしても画面上では設定したピクセルの範囲でしかシステムカーソルは動作しません。

  3. 表示カーソルとの関係

    デジタイジングコンテキストの場合、表示カーソルは動作しません。
    マウスイベントは起こらないので、WT_PACKET のイベントメッセージを待って WTPacket()関数でタブレットデータを取得します。
    システムコンテキストの場合はシステムカーソルがタブレットのデバイスの操作にあわせて移動します。
    注意しなければならないのは、マウスのXY情報はウィンドウの左上が原点となりますが、Wintabの場合は左下が原点となっていることです。
    得られる座標は③④のスケーリングの設定で示した内容になります。例えば③で 10000,10000、④で0,0を設定していると、タブレットの操作範囲の左下が0,0で右上隅が10000,10000という値になって座標値が返ってきます。

3一般的な座標データ入力方法

3.1 メッセージによるデバイス情報の取得

デジタイザのカーソル状態が変化したタイミングで、状態を受け取って制御します。
カーソル状態の取得は、オープン時に指定したトリガで、メッセージ(WT_PACKET )が送られて来るので、そのタイミングで、WTPacket()関数を呼出して行います。このメッセージのパラメータには、WTOpen()関数で設定した時のコンテキストのハンドラとパケットキューのシリアル番号が含まれていますので、WTPacket()関数を利用して情報を取り込みます。

PACKET tPckt;
case WT_PACKET:
IF (WTPacket((HCTX)LOWORD(lParam), wParam, (LPSTR)&tPckt)) {
   Xcoodinate = tPckt.pkX; /* デジタイザ上のX座標 */
   Ycoodinate = tPckt.pkY; /* デジタイザ上のY座標 */
   Buttons = LOWORD(tPckt.pkButtons)); /* ボタン番号 */
}

3.2 ポーリングによるデバイス情報の取得

デジタイザのカーソル状態が変化したタイミングで、状態を受け取って制御します。
カーソル状態の取得は、オープン時に指定したトリガで、メッセージ(WT_PACKET )が送られて来るので、そのタイミングで、WTPacket()関数を呼出して行います。このメッセージのパラメータには、WTOpen()関数で設定した時のコンテキストのハンドラとパケットキューのシリアル番号が含まれていますので、WTPacket()関数を利用して情報を取り込みます。

PACKET tPckt;
case WT_PACKET:
IF (WTPacket((HCTX)LOWORD(lParam), wParam, (LPSTR)&tPckt)) {
   Xcoodinate = tPckt.pkX; /* デジタイザ上のX座標 */
   Ycoodinate = tPckt.pkY; /* デジタイザ上のY座標 */
   Buttons = LOWORD(tPckt.pkButtons)); /* ボタン番号 */
}

のように宣言していると、ボタン情報としては、ボタン番号が変化した時以外は0が返ってきます。プログラムの作り方によってはボタンダウン、ボタンアップのデータを取りこぼす場合があります。その時はボタンの状態が見えなくなってしまいますので注意が必要です。[4.4]
これはパケットデータキューのサイズが足りない場合に発生しますので、キューサイズを大きくすることで回避できる場合があります。

3.3 アクティブ化/非アクティブ化時の処理

他のアプリケーションと協調して動作させるためには、非アクティブ化時に、Wintabをディセーブルにして、他のアプリケーションにタブレットを開放する必要があります。また、逆にアクティブ化時には、Wintabをイネーブルにして、タブレットを使用できる状態にしなければなりません。

case WM_ACTIVATE:
IF (wParam) {
  WTOverlap(hTab, TRUE);
}
WTEnable(hTab, wParam);

このコーディングを行うと、自アプリケーションがアクティブの場合は、Wintabを経由して、タブレットの全域or一部を使用し、非アクティブの場合は、マウスエミュレーションで、他のアプリケーションが動作するようにすることができます。
また、Wintabを利用する複数のアプリケーションが動作している場合のコンフリクトを避けることができます。

3.4 システムコンテキストとデジタイザコンテキストの併用

システムカーソルを表示させながら、状況によってはタブレット面に配置したメニューを操作したい、という場合があります。
システムカーソルを有効にさせるためには、system context でWTOpen()しておかねばなりません。また、システムカーソルの操作領域と、タブレット上に置いたメニューからの入力可能領域が違っている場合は、デジタイザコンテキストでもWT_OPENをかけておかねばなりません。そしてこの場合にはWTOverlap()でsystem contextで宣言したほうをアクティブにしておきます。この時、system contextで宣言した領域ではデジタイザコンテキストの情報は渡されません。また、逆にデジタイザコンテキストをアクティブにするとシステムカーソルが表示されなくなります。通常はsystem contextをアクティブにしておき、何等かのトリガーを検出したら、WTOverlap()でdigitizer contextをアクティブにしてパケットを読みだし、システムカーソルを表示させるために再度WTOverlap()でsystem contextを有効にします。

4 各種タブレット情報の取得

ワコムのタブレットは筆圧、傾きが取れる機種があります。また、一本のペンでペン先とテールスイッチの二つの使い方ができるものがあります。
Intuosシリーズでは、イレーサ(テールスイッチ)付きペン、カーソル、エアブラシ、4Dマウス等、UDシリーズに比べ豊富なデバイスが扱えるようになっており、1つのタブレット上で2種類のデバイスが使えるマルチモードをサポートしています。

4.1 パケットの宣言

Wintabのパケットの中で有効にするデータを宣言します。(タブレットが未対応であるデータは0値が返ってきます)

例:UDⅡシリーズの場合
#define PACKETDATA (PK_X | PK_Y | PK_BUTTONS | PK_CURSOR
| PK_STATUS | PK_NORMAL_PRESSURE | PK_ORIENTATION)
例:Intuosシリーズの場合
#define PACKETDATA (PK_X | PK_Y | PK_Z | PK_BUTTONS | PK_CURSOR | PK_STATUS
| PK_NORMAL_PRESSURE | PK_TANGENT_PRESSURE | PK_ORIENTATION)

4.2 パケットの構成

Wintabパケットが扱うことのできる情報には以下のものがあります。

宣言 データタイプ 内容
———— ——– ————-
1 PK_CONTEXT HCTX イベント情報
2 PK_STATUS UINT データの有効/無効、イベントキューのオーバーフロー等
3 PK_TIME DWORD イベントが発生したシステム時間
4 PK_CHANGED WTPKT 前回値と変化があった情報
5 PK_SERIAL_NUMBER UINT Context毎に連続したデータに付けられる番号
6 PK_CURSOR UINT パケットのカーソル毎の種別
7 PK_BUTTONS DWORD ボタン情報
8 PK_X LONG X座標
9 PK_Y LONG Y座標
10 PK_Z LONG Z座標(4Dマウスのホイールデータ)
11 PK_NORMAL_PRESSURE UINT 筆圧情報
12 PK_TANGENT_PRESSURE UINT (エアブラシのホイールデータ)
13 PK_ORIENTATION ORIENTATION 付加情報 以下の構造を持ちます
orAzimuth INT 垂直(Z軸)からみた傾きの方向(0~359度)
orAltitude INT X-Y平面に対する傾き角(90~0度)
oTwist INT 回転角(4Dマウスの回転)

ワコムのドライバが提供している情報は、UDⅡシリーズにおいては2,6,7,8,9,11,13です。Intuosシリーズについては、2,6,7,8,9,10,11,12,13がサポートされます。

4.3 カーソル情報 (PK_CURSOR)

PK_CUROSRにはデバイス種別情報が入ります。カーソルの場合には0、ペンの場合には1、テールスイッチ部は2となります。
Intuosシリーズタブレットでは、1つのタブレット上で任意のデバイスを一度に2つまで使えるマルチモードをサポートしているシリーズがあります。同じ種類のデバイスを使っている場合は、最初に使い始めたデバイスの種別番号は上記の通りですが、2番目に使い始めたデバイスには先の種別番号に3を加えた番号が返ってきます。例えば、ペンを2本使用している場合は最初のデバイスは1の番号を返し、2本目のデバイスには4の番号を返します。このようにして同じデバイスを使った場合にそれぞれのデータを混在して受け取っても、どちらのデバイスのデータかを識別する事が可能です。

4.4 ボタン情報 (PK_BUTTONS)

#define PACKETMODE PK_BUTTONS と宣言してある場合は以下の注意事項があります。
PK_BUTTONSにボタン情報が入ります。ボタンの状態が変化した時だけここにセットされます。
PK_BUTTONSのHighWordにはボタン状態変化が渡されます。ボタンが押された時2となり、ボタンが放された時1となります。状態が変化した時だけこの数値が渡されますが、状態が変化しなければ0となっています。例えばボタンが押された時1度だけ2となりますが、そのままボタンが押され続けると0が返されています。
PK_BUTTONSのLowWordにはボタン番号が入ります。座標指示器(ペンやカーソル)のスイッチ番号が1の時は0、2の時は1、3の時は2、…、16の時は15、というように割り当てられています。同じくボタンが押された時1度だけセットされます。ボタンが押され続けた場合は0が返されるようになります。

(例)WTPacketが送られてきた順にPK_BUTTONSのデータを並べてみたものです。
例

#define PACKETMODE 0 と宣言してある場合は、常にボタンの状態を反映しており、先に述べたようにボタンの変化時だけデータが送られて来るのではなく、ボタンを押している間は押されたボタン番号がパケットのPK_BUTTONSに反映されます。

4.5 座標データの取得 (PK_X、PK_Y、PK_Z)

PK_X、PK_Y からタブレット平面上のデバイスの位置情報を読み取ります。
位置座標としては、2.3 Wintabの初期化の項で述べたように、タブレット入力領域の設定と出力値の設定で決まる数値が、デバイスの位置に従って出力されます。
PK_ZはX-Y平面に対して垂直方向の位置座標を表わすものですが、intuosシリーズタブレットでは4Dマウスのホイール操作で出力される値をこれに充てています。

4.6 筆圧情報の取得 (PK_NORMAL_PRESSURE)

PK_NORMAL_PRESSURE から筆圧値を読み取ります。
(出力される数値の範囲は5.2節を参照してください)

4.7 エアブラシホイール情報の取得 (PK_TANGENT_PRESSURE)

PK_TANGENT_PRESSURE からエアブラシのホイール操作で出力される値を読み取ります。エアブラシのサイドに付いたホイールを回転させることでこの値が変化します。

4.8 傾き情報の取得 (PK_ORIENTATION) (PK_TANGENT_PRESSURE)

PK_ORIENTATION の構成は次のとおりです。

UINT orAzimuth;
UINT orAltitude;
UINT orTwist;
    orAzimuthには傾きの方位が入ります。
    X-Y平面に対して時計回りに360度までの方位であらわされます。
    orAltitudeにはX-Y平面に対しての角度情報が入ります。
    タブレット板面に対し垂直方向は90度、傾くに従い0度まで変化します。
    消しゴムの情報はここでもわかります。ここには符号が付いているのですが、プラス符号なら通常のペン先、マイナス符号なら消しゴム側を示すようになっています。-90度は消しゴム側をタブレット面に垂直に立てた状態を表わし、ペンを傾けるに従い0度に近づきます。

4.9 回転情報の取得 (4Dマウス、アートペンのローテーション情報)

デバイスの回転情報を、先ほどのPK_ORIENTATIONで得たorTwistから取得します。ここの部分に360度にわたる回転(ローテーション)情報が入ります。
UDシリーズタブレットではサポートしていません。
Intuosシリーズでは、デバイスのタブレット面に垂直な軸に対する反時計回りの回転角度がここに入ります。

5 その他の情報

5.1 IntuosシリーズにおけるデバイスIDの求め方

Intuosシリーズで扱うデバイスは固有のIDを持っています。IDは2つの部分で構成され、一つはデバイスの種別を示す12ビットで表わされるID,もう一つはデバイス毎にオリジナルに付けられた32ビットで表わされるシリアル番号です。
Wintabバージョン1.1ではシリアル番号がサポートされ、Wintabバージョン1.2からはデバイス種別の読み取りが可能になります。

// ここでWTPacketから得られたCursorタイプの値に対応してデバイスIDを読み取る事が
// できます。 PK_CURSORで識別されたデバイス#に対応させて以下のように読み取ります。
LONG DevID0, DevID1, DevID3, DevKind0;
WTInfo (WTI_CURSORS, CSR_PHYSID, &DevID0); // デバイス#0のシリアル番号を読み取る
WTInfo (WTI_CURSORS+1, CSR_PHYSID, &DevID1); // デバイス#1のシリアル番号を読み取る
...
WTInfo (WTI_CURSORS+3, CSR_PHYSID, &DevID3); // デバイス#3のシリアル番号を読み取る
// デバイスの種別(12ビット)を読み取ります。12ビットのうち、上位4ビット(bit8~11)と下位側
// の2ビット(bit1~2)でほとんどのデバイスを識別できます。上記同様デバイス#毎に読み取り
// 可能です。(以下の例ではPK_CURSORに対応するデバイス種別を読み取っています)
WTPacketsGet((HCTX)hTab, 1, &pkt); // WTOpenで得られたハンドルをhTabとしています
cursor = pkt.pkCursor;
WTInfo (WTI_CURSOR + cursor, CSR_TYPE, &DevKind0);
// ((DevKind0 & 0x0F06) == 0x0802) : General Pen
// ((DevKind0 & 0x0F06) == 0x0902) : Airbrush Pen
// ((DevKind0 & 0x0F06) == 0x0004) : 4D-Mouse
// ((DevKind0 & 0x0F06) == 0x0006) : 5 button puck

5.2 イレーサの識別方法

以下の3通りの方法で識別できます。

(1) PK_CURSOR で2または5という種別だった時。
(2) PK_ORIENTATION の orAltitude (傾き情報)がマイナスの角度だった時。
(3) PK_STATUS の TPS_INVERT ビットフィールドを見て、このビットがONした時。(V1.1より対応)

傾き情報は、板面に垂直の状態を90度で表わし、傾くに従って0度に近くなって表現されます(実際には30度くらいまで)。先ほどのAltitudeMaxが900だったなら、ペン先ではこの場合 +900~+300で推移する事になります。テールスイッチの時はAltitudeMinを見ます。これが-900ならばテールスイッチを90度から30度まで傾けた時、orAltitudeは -900~-300 という値で推移します。

5.3 データの最大値、最小値の求めかた

タブレットの機種により筆圧レンジが違うものがあります。また傾きデータもorAzimuth(角度)とorAltitude(方位)の2つの値で表現されますが、これもタブレットによって(時にはOSによって)変化するレンジが違う場合があります。アプリケーションはWintabから現在使用しているタブレットに依存するこれらの基本データを取得して、随時得られるデータから最適な変化量を計算しなければなりません。
以下に各種データの推移する範囲(レンジ)を求めるコーディング例を示します。

LONG AzimuthMax, AltitudeMax, TwistMax, PrsMax, WhlMax;
LONG AzimuthMin, AltitudeMin, TwistMin, PrsMin, WhlMin;
AXIS PressAxis, OriAxis[3];
// WTI_DEVICESのDVC_NPRESSUREを取得 (筆圧値の最大、最小)
WTInfo(WTI_DEVICES, DVC_NPRESSURE, &PressAxis);
PrsMax = PressAxis.axMax;
PrsMin = PressAxis.axMin;
// WTI_DEVICESのDVC_TPRESSUREを取得 (エアブラシホイールデータの最大、最小)
WTInfo(WTI_DEVICES, DVC_TPRESSURE, &PressAxis);
WhlMax = PressAxis.axMax;
WhlMin = PressAxis.axMin;
// WTI_DEVICESのDVC_ORIENTATIONを取得
// DVC_ORIENTATIONは、3つの要素(Azimuth,Atitude,Twist)のデータが配列として渡されます
WTInfo(WTI_DEVICES, DVC_ORIENTATION, OriAxis);
// Azimuthのデータ (ペンの傾いた方向-XY平面に投影した角度の最大、最小)
AzimuthMax = OriAxis[0].axMax;
AzimuthMin = OriAxis[0].axMin;
// Altitudeのデータ (XY平面に垂直な角度を最大値とする)
AltitudeMax = OriAxis[1].axMax;
AltitudeMin = OriAxis[1].axMin;
// Twistのデータ (XY平面に垂直な軸を中心とした回転角度の最大、最小)
TwistMax = OriAxis[2].axMax;
TwistMin = OriAxis[2].axMin;
これでデータを読み込んでみると、 例えばIntuos1・2・3シリーズタブレットを使用していた場合には、
PrsMax = 1023 /* 筆圧の最大値 */
PrsMin = 0 /* 筆圧の最小値 */
WhlMax = 1023 /* エアブラシホイールの最大値 */
WhlMin = 0 /* エアブラシホイールの最小値 */
AzimuthMax = 3600 /* 方位の最大値 */
AzimuthMin = 0 /* 方位の最小値 */
AltitudeMax = 900 /* 角度の最大値 */
AltitudeMin = -900 /* 角度の最小値 イレーサを使った時負の数値で傾きを表わします */
TwistMax = 3600 /* 回転角の最大値 */
TwstMin = 0 /* 回転角の最小値 */

となります。
傾き角度の最大、最小の値は、符号無しの時は0からAltitudeMaxまで、符号付きの場合は0からAltitudeMinの絶対値が、それぞれ板面に対して傾き角度0度から90度に対応していると考えてください。

5.4 タブレット座標データの最大最小と分解能を知る

タブレット自身が持つ座標分解能は様々ですが、Wintab経由でこの座標値をアプリケーションに渡す場合、ドライバで分解能を調整して出している事があります。必ずしもカタログ値と一致しているわけではありません。そこで以下のように取得された最大座標の分解能を知ることも必要になります。タブレット面上で実測する必要がある場合には、以下の数値が基準になります。


LONG TabMax_X, TabMin_X, TabRes_X;
UINT TabUni_X;
AXIS axis;
WTInfo(WTI_DEVICES, DVC_X, &axis);
TabMax_X = axis.axMax;
TabMin_X = axis.axMin;
TabUni_X = axis.axUnits;
TabRes_X = HIWORD(axis.axResolution);

ここで、TabMax_XにはX座標の最大値、TabMin_XにはX座標の最小値が入ります。
TabUni_Xには分解能の単位、TabRes_Xには分解能が入ります。
分解能の単位には4つあり、line/inch、line/cm、Circle(deg/radian)、none(単位無し)があります。それぞれWintab.hで定義されている、TU_INCHES、TU_CENTIMETERS、TU_CIRCLE、TU_NONE、で識別します。
例えば、TabMax_Xが38480、TabMin_xが0、TabUni_XがTU_CENTIMETERS、TabRes_Xが1000となっていた場合、分解能は0.01mm(1000line/cm)、有効領域の実寸がX軸方向に384.8mmある、と知ることができます。

5.5 使っているタブレットで利用可能な座標指示器の種類を知る方法

使っているタブレットがどのような座標指示器をサポートしているかを知って、アプリケーションの機能に制限をつけたり、拡張したりすることが必要な場合があります。このような場合は WTInfo関数のInformation Categoriesに WTI_CURSORS を指定することで知ることができます。
簡単な例を示します。以下の例ではイレーサ付きペン(UP-701E:テールスイッチ付き筆圧ペン)が使えるかどうかを調べています。

int i;
char Name[80];
UINT size;
BOOL gSupportsEraser;
gSupportsEraser=FALSE;
for (i = 0; size = WTInfo(WTI_CURSORS + i, CSR_NAME, Name); i++) {
         if(!strcmp("Eraser Stylus",Name)){
                  gSupportsEraser=TRUE;
         }
}

上記のNameのエリアには利用可能な座標指示器の種別として次のような文字列が入ります。
“Standard Stylus” (ノーマルペン) 15文字
“Pressure Stylus“ (筆圧ペン) 15文字
“Eraser Stylus” (テールスイッチ付き筆圧ペン) 15文字
“Puck” (カーソル) 4文字
WTI_CURSORS に+1しながら読んでゆくと、Nameのエリアには上記の文字列が、sizeには文字列+1スペースの文字数が入ります。対応した座標指示器をすべて読み出したらsizeが0で返ってきます。
パケットデータにはデバイス番号が含まれています。pkCursorとして渡される番号で上記のように読めば、現在使用中のデバイスの文字列を取得できます。

WTPacketsGet((HCTX)hTab, 1, &pkt);     // WTOpenで得られたハンドルをhTabとしています
cursor = pkt.pkCursor;
WTInfo(WTI_CURSORS + cursor, CSR_NAME, Name)
...

5.6 Out of Bounds Trackingの設定

タブレットの一部分を入力範囲に定めた時、システムカーソルを表示させたりしていると、その領域以外ではシステムカーソルが張り付いたようになって、タブレットの指示器をどのように動かせば再び操作できるようになるかわからなくなる場合があります。時には画面の端までシステムカーソルが移動してくれなくて、画面の端に位置したメニューバーを操作するのに困る、ということもあるようです。 Out of Bounds Trackingは領域外に指示器を持っていっても、システムカーソルが画面の端でトラッキングし続けてくれるようなモードです。

HMGR hMgr = NULL;
BOOL *ObtBuf;
case WM_CREATE:
         // タブレットマネージャーの作成
         hMgr = WTMgrOpen(hWnd, WT_DEFBASE);
         if(hMgr) {
             // Out of Bounds Tracking のセット
             ObtBuf[0] = 1;
             WTMgrExt(hMgr, WTX_OBT, ObtBuf);
//           WTMgrClose(hMgr); /* ここでクローズしても良い */
         }
case WM_DESTROY:
         // タブレットマネージャーをクローズする
//       hMgr = WTMgrOpen(hWnd, WT_DEFBASE); /* 一度クローズしていたら再度オープン */
         if (hMgr) {
           // Out of Bounds Tracking の解除
           ObtBuf[0] = 0;
           WTMgrExt(hMgr, WTX_OBT, ObtBuf);
           WTMgrClose(hMgr);
         }

5.7 パケットデータキューのサイズを変更する

Wintab.dllからアプリケーションに渡されるパケットは、いったんパケットデータキューのバッファに貯えられます。このバッファはデフォルトで8パケット分あります。タブレットドライバにもよりますが、ワコムのタブレットドライバはUDシリーズ用ドライバ(V2.x)では約15msec間隔で、Intuosシリーズ用ドライバ(intuosドライバV4.x/V6.x)では1つのデバイスで約10msec間隔、さらに2つのデバイスが同時に使用されていると、パケットは交互に5msec間隔で送られてきますから、WTPacketを取りに行く平均的なタイミングがこの時間よりも長い時には、いずれパケットデータキューのバッファがオーバーフローしてデータを失うことになります。アプリケーションの負荷や、システムのパフォーマンスを考えてパケットキューデータのバッファのサイズを設定することも必要です。
パケットデータキューのサイズの変更方法を以下に示します。


HCTX hTab = NULL;
case WM_CREATE:
    hTab = TabletInit(hWnd);
    // パケットデータキューサイズの変更
   WTQueueSizeSet((HCTX)hTab, 16);
....                          ↑
....                        キューのサイズ

オーバーフローしているかどうかはWTQueuePackets()関数を使って知ることができます。パケットには連続した番号がつけられます。(注意:あくまでもアプリケーションに渡される時の連番ですので、オーバーフローして取得できなかったパケットがあるかどうかはわかりません) この番号を見て、常にキューにパケットがいっぱい溜まっている状況であれば、オーバーフローを起こしてデータを失っている可能性があるといえます。これによってアプリケーションの負荷を推測する事もできます。

DWORD Queue;
int QueueSize;
case WT_PACKET:
       if (WTPacket((HCTX)lParam, wParam, &pkt)) {
              ....
              // パケットデータキューについての操作
              Queue = WTQueuePackets((HCTX)lParam);
              QueueSize = WTQueueSizeGet((HCTX)lParam);
              ....
       }
HIWORD(Queue) : 最も新しいパケットのシリアルナンバー (-1であればキューバッファは空です)
LOWORD(Queue) : 最も古いパケットのシリアルナンバー (0であればキューバッファは空です)
QueueSize : パケットデータキューに保持できるパケットの数

5.8 Wintabのバージョンを識別する

筆圧、傾きなどをサポートしたものはV1.0になっています。IntuosシリーズデジタイザのデバイスIDを読み取れるのはV1.1、デバイスの種別を読み取ることができるのはV1.2となっています。

int thisVersion;
WTInfo ( WTI_INTERFACE, IFC_SPECVERSION, &thisVersion);

上位バイトにはメジャーバージョン、下位バイトはマイナーバージョンが返されます。V1.0であればメジャーバージョンは1、マイナーバージョンは0です。

参考資料:
各デバイスのデバイスIDを示す。

デバイス名 型番 デバイスID(16進数)
ジェネラルペン GP-300E/XP-300E 822
ジェネラルペン・イレーサー GP-300E/XP-300E 82A
エアブラシ GP-400E/XP-400E 912
エアブラシ・イレーサー GP-400E/XP-400E 91A
イレーサ無しグリップペン GP-501/XP501A 842
グリップペン XP-501E 852
グリップペン・イレーサー XP-501E 85A
インクペン GP-110/XP-110 812
ストロークペン GP-120/XP-120 832
レンズカーソル GC-210/XC-210 096
4Dマウス GC-500/XC-400 094
4Dマウス(左ホイール) GC-500 09C
2Dマウス XC-100 007
グリップペン ZP-501E 823
エアブラシ(21”用) ZP-400E 913
マーカーペン ZP-600 885

6 関数リファレンス

すべてのタブレット関数名には、「WT」というプレフィックスおよびWINAPIと同じ属性があります。アプリケーションは、前のセクションで定義したとおり、標準ファイルおよびモジュール名を持つダイナミックリンクライブラリを介して、タブレットインターフェース機能へのアクセス権を取得します。アプリケーションは、Windows関数LoadLibraryFreeLibrary、およびGetProcAddressを使用して機能にリンクすることも、インポートライブラリを使用することもできます。

32ビットWintab固有の情報:関数WTInfoWTOpenWTGet、およびWTSetには、ANSIバージョンとUnicodeバージョンがあります。いずれも、Win32 APIで使用されている同じANSI/Unicode移植規約を使用しています。移植できない関数WTQueuePacketsWTMgrCsrPressureBtnMarksは、移植可能な新しい関数WTQueuePacketsExWTMgrCsrPressureBtnMarksExに置き換えられています。

表5.1. ダイナミックリンクの関数の序数

ダイナミックリンクの序数を下記の表で定義します。2つの序数エントリが表示されている場合、最初のエントリは、16ビットおよび32ビットANSIバージョンの関数を示します。2番めのエントリは32ビットUnicodeバージョンを示します。

関数名 序列 関数名 序列
WTInfo 20, 1020 WTQueueSizeGet 84
WTOpen 21, 1021 WTQueueSizeSet 85
WTClose 22 WTMgrOpen 100
WTPacketsGet 23 WTMgrClose 100
WTClose 22 WTMgrOpen 100
WTPacketsGet 23 WTMgrClose 101
WTPacket 24 WTMgrContextEnum 120
WTEnable 40 WTMgrContextOwner 121
WTOverlap 41 WTMgrDefContext 122
WTConfig 60 WTMgrDeviceConfig 140
WTGet 61, 1061 WTMgrExt 180
WTSet 62, 1062 WTMgrCsrEnable 181
WTExtGet 63 WTMgrCsrButtonMap 182
WTExtSet 64 WTMgrCsrPressureBtnMarks 183
WTSave 65 WTMgrCsrPressureResponse 184
WTRestore 66 WTMgrCsrExt 185
WTPacketsPeek 80 WTQueuePacketsEx 200
WTDataGet 81 WTMgrCsrPressureBtnMarksEx 201
WTDataPeek 82 WTMgrDefContextEx (1.1) 206
WTQueuePackets 83

6.1. 基本的な関数

次のセクションの関数は、ほとんどのタブレット対応アプリケーションで使用されます。関数には、インターフェースおよびデバイスの情報の取得、コンテキストのオープンとクローズ、ポーリングまたはWindowsメッセージによるパケットの取得が含まれます。

6.1.1. WTInfo

次のセクションの関数は、ほとんどのタブレット対応アプリケーションで使用されます。関数には、インターフェースおよびデバイスの情報の取得、コンテキストのオープンとクローズ、ポーリングまたはWindowsメッセージによるパケットの取得が含まれます。

構文 UINT WTInfo(wCategory, nIndex, lpOutput)
この関数は、アプリケーションが提供したバッファ内のインターフェースに関するグローバル情報を返します。異なるインデックス引数で、異なる種類の情報が指定されます。アプリケーションは、この関数を使用してタブレット座標、物理的な次元、機能、カーソルタイプに関する情報を取得します。
パラメータ 種類/説明
wCategory UINT要求する情報のカテゴリーを指定します。
nIndex UINTカテゴリー内のどの情報が要求するかを指定します。
lpOutput LPVOID 要求された情報を保持するバッファを指定します。
戻り値 戻り値は、返された情報のサイズ(バイト数)を示します。情報がサポートされていない場合、ゼロが返されます。タブレットが物理的に存在しない場合、常にゼロが返されます。
コメント 情報の重要なカテゴリーが、この関数でいくつか取得できます。最初に、この関数は、仕様やソフトウェアバージョン番号、タブレットベンダーおよびモデル情報などの識別情報を提供します。2番目に、次元、分解能、オプション機能、カーソルタイプなどの一般的な機能情報を提供します。3番目に、すべてのタブレットコンテキスト属性のデフォルトを指定できるカテゴリーを提供します。最後に、必要なその他の実装またはベンダー固有の情報カテゴリーを提供することもあります。
この関数で返された情報は、Windowsセッション中に変更の対象となります。アプリケーションはここで返された情報を変更できませんが、タブレットマネージャーアプリケーションまたはハードウェアの変更やエラーは変更できます。アプリケーションは、WT_INFOCHANGEメッセージを処理することで情報の変更に応答できます。メッセージのパラメータは、どの情報が変更されたかを示します。
lpOutput引数がNULLの場合、必要なバッファサイズが返されます。
参照 表7.3から7.9のカテゴリーとインデックス定義、およびセクション6.3.1のWT_INFOCHANGEメッセージ。

6.1.2. WTOpen

構文 HCTX WTOpen(hWnd, lpLogCtx, fEnable)
この関数は、タブレットにアクティブコンテンツを確立します。この関数の実行に成功すると、アプリケーションはメッセージを介してタブレットイベントの受信を開始できます(要求されている場合)。また、コンテキストのポーリングやその他のコンテキスト関連機能を実行するために返されたハンドルを使用できます。
パラメータ 種類/説明
hWnd HWND タブレットコンテキストを所有し、コンテキストからメッセージを受信するウィンドウを指定します。
lpLogCtx LPLOGCONTEXT
fEnable BOOL 新しいコンテキストが入力データの処理をすぐに開始するかどうかを指定します。
戻り値 戻り値は、新しいコンテキストを示します。コンテキストが開かれていない場合は、NULLです。
コメント 新しいコンテキストを開くと、アプリケーションはタブレットの入力を受信したり、システムカーソルやPen Windowsのペンを制御するコンテキストを作成したりできます。所有側のウィンドウ(およびすべてのマネージャーウィンドウ)は、コンテキストが開かれるとすぐにWT_CTXOPENメッセージを受信します。
fEnable引数がゼロの場合、コンテキストが作成されるものの、入力は処理されません。WTEnable関数を使用して、コンテキストを有効にできます。
タブレットイベントメッセージがコンテキストの仕様で要求された場合、所有側のウィンドウがメッセージを受信します。アプリケーションは、LOGCONTEXT構造体のlcMsgBaseフィールドで使用されるメッセージ番号を制御できます。
新しいコンテキストを所有するウィンドウは、イベントメッセージが要求されていない場合でもコンテキストと情報変更メッセージを受信します。多くの場合、これらを処理する必要はありませんが、一部のアプリケーションでは処理を要求するものもあります。
新しく開かれたタブレットコンテキストは、コンテキストの重複順序の一番上に置かれます。
論理コンテキスト構造内の無効な、または範囲外の属性値は、関連する属性値に従って、有効性が確認されるか、開けません。関数からの戻り値が成功すると、lpLogCtxが指すコンテキスト仕様に、有効な値が含まれます。
参照 セクション5.2.1のWTEnable関数、セクション7.3.1のLOGCONTEXTデータ構造体、セクション6.2および6.3のコンテキストおよび情報変更メッセージ。

6.1.3. WTClose

構文 BOOL WTClose(hCtx)
この関数は、タブレットコンテキストオブジェクトを閉じて破棄します。
パラメータ 種類/説明
hCtx HCTX 閉じるコンテキストを指定します。
戻り値 コンテキストが有効であり、正常に破棄された場合、ゼロ以外の値が返されます。それ以外の場合は、ゼロが返されます。
コメント この関数を呼び出すと、渡されたハンドルは無効になります。所有側のウィンドウ(およびすべてのマネージャーウィンドウ)は、コンテキストが閉じられるとWT_CTXCLOSEメッセージを受信します。
参照 セクション5.1.2のWTOpen関数。

6.1.4. WTPacketsGet

構文 int WTPacketsGet(hCtx, cMaxPkts, lpPkts)
この関数は、次のcMaxPkts個のイベントをhCtxのパケットキューからlpPktsバッファにコピーし、キューから削除します。
パラメータ 種類/説明
hCtx HCTX パケットが返されるコンテキストを指定します。
cMaxPkts int 返すパケットの最大数を指定します。
lpPkts LPVOID イベントパケットを受け取るバッファを指定します。
戻り値 戻り値は、バッファ内にコピーされたパケットの数です。
コメント 返されたパケットの正確な構造は、コンテキスを開いたときに要求されたパケット情報によって決まります。
lpPktsによって指定されたバッファは、オーバーフローを防ぐためにcMaxPkts * sizeof(PACKET)バイト長以上なければなりません。
アプリケーションは、NULLのlpPkt引数でこの関数を呼び出すことで、キューからパケットをフラッシュできます。
参照 セクション5.4.1のWTPacketsPeek関数、LOGCONTEXTの説明(セクション7.3.1)、PACKET(セクション7.4.1)データ構造体。

6.1.5. WTPacket

構文 iBOOL WTPacket(hCtx, wSerial, lpPkt)
この関数は、指定したシリアル番号を持つコンテキストイベントパケットを、渡されたlpPktバッファに格納します。返されたパケットと、それよりも古いパケットは、コンテキストの内部キューから削除されます。
パラメータ 種類/説明
hCtx HCTX パケットが返されるコンテキストを指定します。
wSerial UINT 取得するタブレットイベントのシリアル番号。
lpPkts LPVOID イベントパケットを受け取るバッファを指定します。
戻り値 指定したパケットが見つかり、返された場合、戻り値はゼロ以外です。指定したパケットがキュー内に見つからなかった場合は、ゼロです。
コメント 返されたパケットの正確な構造は、コンテキストを開いたときに要求されたパケット情報によって決まります。
lpPktsによって指定されたバッファは、オーバーフローを防ぐためにsizeof(PACKET)バイト長以上なければなりません。
アプリケーションは、NULLのlpPkts引数でこの関数を呼び出すことで、キューからパケットをフラッシュできます。
参照 LOGCONTEXTの説明(セクション7.3.1)およびPACKET(セクション7.4.1)データ構造体。

6.2. 可視化関数

このセクションの関数は、入力を処理しているかどうかに関係なくアプリケーションがコンテキストの可視化および重複順序を制御できるようにするためのものです。

6.2.1. WTEnable

構文 BOOL WTEnable(hCtx, fEnable)
この関数では、パケットの処理を一時的にオンまたはオフにして、タブレットコンテキストを有効化または無効化できます。
パラメータ 種類/説明
hCtx HCTX 有効化または無効化するコンテキストを指定します。
fEnable BOOL ゼロ以外の場合は有効化、ゼロの場合は無効化となります。
戻り値 有効化または無効化要求が満たされた場合はゼロ以外の値、要求が満たされなかった場合はゼロが返されます。
コメント 既に有効化されているコンテキストを有効化したり、既に無効化されているコンテキストを無効化するためにこの関数を呼び出すと、ゼロ以外の値が返されますが、それ以外は何も実行されません。
コンテキストのパケットキューは、無効化の際にフラッシュされます。
アプリケーションは、WTGet関数を使用し、LOGCONTEXT構造体のlcStatusフィールドを確認することで、コンテキストが有効化されているかどうかを判別できます。
参照 セクション5.3.2のWTGet関数およびセクション7.3.1のLOGCONTEXT構造体。

6.2.2. WTOverlap

構文 BOOL WTOverlap(hCtx, fToTop)
この関数は、タブレットコンテキストの重なり順序の一番上か下にタブレットコンテキストを送信します。
パラメータ 種類/説明
hCtx HCTX 重なり順序内で移動するコンテキストを指定します。
fToTop BOOL ゼロ以外の場合は重なり順序の一番上にコンテキストを送信し、ゼロの場合は一番下にコンテキストを送信するよう指定します。
戻り値 成功した場合はゼロ以外、失敗した場合はゼロが返されます。
コメント テーブルコンテキストの入力領域は重複可能です。タブレットインターフェースは、どのコンテキストが所定のイベントを処理するかを判別する際に役立つ重なり重複順序を保持します。入力コンテキストがイベントを包含し、イベントマスクがイベントを選択する重なり重複順序の最も上のコンテキストがイベントを処理します。
この関数は、アプリケーションのコンテキストが他のコンテキストと重複しているときに、入力イベントへのアクセスを取得する場合に役立ちます。
この関数は、コンテキストの引数が無効な場合にのみ失敗します。

6.3. コンテキスト編集関数

この関数のグループでは、アプリケーションはコンテキストを編集、保存、復元できます。

6.3.1. WTEnable

構文 BOOL WTGet(hCtx, lpLogCtx)
この関数は、渡されたハンドルの現在のコンテキスト属性を、渡された構造体に入れます。
パラメータ 種類/説明
hCtx HCTX 属性をコピーするコンテキストを指定します。
lpLogCtx LPLOGCONTEXT コンテキスト属性のコピー先となるLOGCONTEXTデータ構造体のポインタを指定します。
戻り値 データが正常に取得された場合、ゼロ以外の値が返されます。それ以外の場合は、ゼロが返されます。
参照 セクション7.3.1のLOGCONTEXT構造体。

6.3.2. WTSet(1.1変更)

構文 BOOL WTSet(hCtx, lpLogCtx)
この関数では、一部のコンテキストの属性をオンザフライで変更できます。
パラメータ 種類/説明
hCtx HCTX 属性を変更するコンテキストを指定します。
lpLogCtx LPLOGCONTEXT 新しいコンテキスト属性を格納しているLOGCONTEXTデータ構造体のポインタを指定します。
戻り値 渡されたコンテキスト仕様に合わせてコンテキストが変更された場合はゼロ以外、要求された変更のいずれかを実行できなかった場合はゼロが返されます。
コメント コンテキストを所有しているタスクまたはプロセスでこの関数を呼び出した場合、任意のコンテキスト属性を変更できます。それ以外の場合、コンテキストのイベントパケットの形式や意味に影響しない属性、およびコンテキストが開かれたときにロックされるように指定されていない属性を変更できます。コンテキストロック値は、コンテキストの所有者のみが変更できます。
1.1:hCtx引数がWTMgrDef¬ContextまたはWTMgrDefContextExから返されたデフォルトコンテキストハンドルで、lpLogCtx引数がWTP_LPDEFAULTの場合、デフォルトコンテキストは工場出荷時の初期値にリセットされます。
参照 セクション7.3.1のLOGCONTEXT構造体および表7.13のコンテキストロック値。

6.3.3. WTExtGet

構文 BOOL WTExtGet(hCtx, wExt, lpData)
この関数は、拡張用にコンテキスト固有のデータを取得します。
パラメータ 種類/説明
hCtx HCTX 拡張属性を取得するコンテキストを指定します。
wExt UINT 取得する拡張属性のタグを指定します。
lpData LPVOID 取得されたデータを保持するバッファを指定します。
戻り値 データが正常に取得された場合、ゼロ以外の値が返されます。それ以外の場合は、ゼロが返されます。
参照 付録Bの拡張の定義。

6.3.4. WTExtSet

構文 BOOL WTExtSet(hCtx, wExt, lpData)
この関数は、拡張用にコンテキスト固有のデータを設定します。
パラメータ 種類/説明
hCtx HCTX 拡張属性を設定するコンテキストを指定します。
wExt UINT 変更する拡張属性のタグを指定します。
lpData LPVOID 設定するデータのポインタを指定します。
戻り値 データが正常に変更された場合、ゼロ以外の値が返されます。それ以外の場合は、ゼロが返されます。
コメント 拡張は、コンテキストが存在している間、コンテキスト固有のデータの変更を禁止する可能性があります。¬このような拡張の場合、この関数を呼び出すと、必ず失敗します。
コンテキストのロックと同じく、拡張により、所有側ウィンドウのタスクに対してコンテキストデータ編集が制限されることがあります。
参照 付録Bの拡張の定義、セクション7.3.1のLOGCONTEXTデータ構造体、表7.13のコンテキストロック値。

6.3.5. WTSave

構文 BOOL WTSave(hCtx, lpSaveInfo)
この関数は、以降のWindowsセッションで同等のコンテキストを復元するために使用可能なバイナリ保存情報を、渡されたバッファに入れます。
パラメータ 種類/説明
hCtx HCTX 保存するコンテキストを指定します。
lpSaveInfo LPVOID 保存情報を保持するバッファを指定します。
戻り値 保存情報が正常に取得された場合、ゼロ以外の値が返されます。それ以外の場合は、ゼロが返されます。
コメント 保存情報バッファのサイズは、カテゴリーWTI_INTERFACE、インデックスIFC_CTXSAVESIZEでWTInfo関数を呼び出すことで取得することが出来ます。
保存情報は、プライベートバイナリデータ形式で返されます。アプリケーションは、保存情報をWTRestore関数に渡すことによって、未変更の情報を格納し、コンテキストを再作成する必要があります。
WTSaveとWTRestoreを利用することで、アプリケーションはコンテキストにバインドされた拡張データを簡単に保存および復元できます。
参照 セクション5.3.7のWTRestore関数。

6.3.6. WTRestore

構文 HCTX WTRestore(hWnd, lpSaveInfo, fEnable)
この関数は、WTSave関数から返された保存情報からタブレットコンテキストを作成します。
パラメータ 種類/説明
hWnd HWND タブレットコンテキストを所有するウィンドウを示し、コンテキストからメッセージを受信します
lpSaveInfo LPVOID 保存情報を格納しているバッファを指定します。
fEnable BOOL 新しいコンテキストが入力データの処理をすぐに開始するかどうかを指定します。
戻り値 成功した場合、有効なコンテキストハンドルが返されます。保存情報と同じコンテキストを作成できなかった場合、NULLが返されます。
コメント 保存情報はプライベートバイナリデータ形式です。アプリケーションは、WTSave関数から取得された保存情報を渡すだけです。
この関数はWTOpenとよく似ていますが、論理コンテキストではなく保存情報を入力に使用する点が異なります。特に、新しいコンテキストに対してWT_CTXOPENメッセージが生成されます。
参照 セクション5.1.2のWTOpen関数、セクション5.3.6のWTSave関数、セクション6.2.1のWT_CTXOPENメッセージ。

6.4. 高度なパケットおよびキュー関数

これらの関数は、高度なパケット取得およびキュー操作を提供します。パケット取得関数では、アプリケーションはパケット出力バッファを提供する必要があります。オーバーフローを防ぐために、バッファは、指定されたコンテキストから要求されたパケットの数を保持できるだけ大きくなければなりません。(必要に応じてコンテキストを調べて)パケットサイズを判定し、十分大きいバッファを割り当てる作業は、呼び出し側が行います。アプリケーションは、NULLのバッファポインタを渡すことでキューからパケットをフラッシュできます。

6.4.1. WTEnable

構文 int WTPacketsPeek(hCtx, cMaxPkts, lpPkts)
この関数は、コンテキストhCtxのパケットキューから、cMaxPkts個分のパケットを、渡されたlpPktsバッファにコピーします。その際、キューからイベントを削除しません。
パラメータ 種類/説明
hCtx HCTX パケットが読み取られるコンテキストを指定します。
cMaxPkts int 返すパケットの最大数を指定します。
lpPkts LPVOID イベントパケットを受け取る受信するバッファを指定します。
戻り値 戻り値は、バッファ内にコピーされたパケットの数です。
コメント lpPktsによって指定されたバッファは、オーバーフローを防ぐためにcMaxPkts * sizeof(PACKET)バイト長以上なければなりません。
参照 セクション5.1.4のWTPacketsGet関数。

6.4.2. WTDataGet

構文 int WTDataGet(hCtx, wBegin, wEnd, cMaxPkts, lpPkts, lpNPkts)
この関数は、wBegin以上、wEnd以下のシリアル番号を持つすべてのパケットをコンテキストのキューから、渡されたバッファにコピーし、キューから削除します。
パラメータ 種類/説明
hCtx HCTX パケットが返されるコンテキストを指定します。
wBegin UINT 返される最も古いタブレットイベントのシリアル番号。
wEnd UINT 返される最も新しいタブレットイベントのシリアル番号。
戻り値 戻り値は、キュー内で見つかったwBegin以上、wEnd以下のパケットの合計数です。
コメント lpPktsによって指定されたバッファは、オーバーフローを防ぐためにcMaxPkts * sizeof(PACKET)バイト長以上なければなりません。
参照 セクション5.4.3のWTDataPeek関数およびセクション5.4.5のWTQueuePacketsEx関数。

6.4.3. WTDataPeek

構文 int WTDataPeek(hCtx, wBegin, wEnd, cMaxPkts, lpPkts, lpNPkts)
この関数は、wBegin以上、wEnd以下のシリアル番号を持つすべてのパケットをコンテキストのキューから、渡されたバッファにコピーします、その際、パケットをキューから削除しません。
パラメータ 種類/説明
hCtx HCTX パケットが読み取られるコンテキストを指定します。
wBegin UINT 返される最も古いタブレットイベントのシリアル番号。
wEnd UINT 返される最も新しいタブレットイベントのシリアル番号。
cMaxPkts int 返すパケットの最大数を指定します。
lpPkts LPVOID イベントパケットを受け取るバッファを指定します。
lpNPkts LPINT 実際にコピーされたパケットの数を受け取る変数のポインタを指定します。
戻り値 戻り値は、キュー内で見つかったwBegin以上、wEnd以下のパケットの合計数です。
コメント lpPktsによって指定されたバッファは、オーバーフローを防ぐためにcMaxPkts * sizeof(PACKET)バイト長以上なければなりません。
参照 セクション5.4.2のWTDataGet関数およびセクション5.4.5のWTQueuePacketsEx関数。

6.4.4. WTQueuePackets(16ビットのみ)

構文 DWORD WTQueuePackets(hCtx)
この関数は、現在キュー内にある最も古いパケットと最も新しいパケットのシリアル番号を返します。
パラメータ 種類/説明
hCtx HCTX キューがクエリされるコンテキストを指定します。
戻り値 戻り値の上位ワードには最新のパケットのシリアル番号、下位ワードには最も古いパケットのシリアル番号が含まれています。
コメント この関数は移植不可で、WTQueuePacketsExによって置き換えられます。
参照 セクション5.4.5のWTQueuePacketsEx関数。

6.4.5. WTQueuePacketsEx

構文 BOOL WTQueuePacketsEx(hCtx, lpOld, lpNew)
この関数は、現在キュー内にある最も古いパケットと最も新しいパケットのシリアル番号を返します。
パラメータ 種類/説明
hCtx HCTX キューのコンテキストを指定します。
lpOld UINT FAR * 最も古いパケットのシリアル番号を受信するための符号なし整数のポインタを指定します。
lpNew UINT FAR * 最も新しいパケットのシリアル番号を受信するための符号なし整数のポインタを指定します。
戻り値 成功した場合はゼロ以外、失敗した場合はゼロが返されます。

6.4.6. WTQueueSizeGet

構文 int WTQueueSizeGet(hCtx)
この関数は、コンテキストのキューが保持できるパケットの数を返します。
パラメータ 種類/説明
hCtx HCTX キューサイズが返されるコンテキストを指定します。
戻り値 戻り値は、キューが保持できるパケットの数です。
参照 セクション5.4.7のWTQueueSizeSet関数。

6.4.7. WTQueuePacketsEx

構文 BOOL WTQueueSizeSet(hCtx, nPkts)
この関数は、コンテキストのキューサイズをnPktsで指定した値に変更しようとします。
パラメータ 種類/説明
hCtx HCTX キューサイズを設定するコンテキストを指定します。
nPkts int キューサイズを指定します。
戻り値 キューサイズが正常に変更された場合、戻り値はゼロ以外です。それ以外の場合は、ゼロが返されます。
コメント 戻り値がゼロの場合、関数は新しいキューを作成するまで元のキューを削除するため、コンテキストにはキューがない状態になります。アプリケーションは、関数がゼロ以外の値を返すまで、より小さなキューサイズで関数の呼び出しを続ける必要があります。
参照 セクション5.4.6のWTQueueSizeGet関数。

6.5. 高度なパケットおよびキュー関数

以降のセクションで説明する関数は、タブレットマネージャーアプリケーションで使用するためのものです。このセクションの関数はマネージャーハンドルを作成して破棄します。これらのハンドルを使用すると、インターフェースコードは、強力なマネージャー機能への同時アクセスの程度を制限できます。また、マネージャーハンドルを開くと、アプリケーションはタブレットインターフェースアクティビティに関するメッセージを受信できます。

6.5.1. WTMgrOpen

構文 DHMGR WTMgrOpen(hWnd, wMsgBase)
この関数は、タブレットマネージャーおよび構成アプリケーションで使用するためのタブレットマネージャーハンドルを開きます。このハンドルは、タブレット管理関数を呼び出す必要があります。
パラメータ 種類/説明
hCtx HWND マネージャーハンドルを所有するウィンドウを指定します。
wMsgBase UINT マネージャーウィンドウに通知する際に使用するメッセージベース番号を指定します。
戻り値 正常に実行された場合、マネージャーハンドルが返され、それ以外の場合はNULLが返されます。
コメント マネージャーハンドルが開かれている間、マネージャーウィンドウはすべてのタブレットコンテキストからコンテキストメッセージを受信します。マネージャーウィンドウは、情報変更メッセージも受信します。
使用可能なマネージャーハンドルの数は、インターフェースの実装によって決まります。カテゴリWTI_INTERFACEおよびインデックスIFC_NMANAGERSでWTInfo関数を呼び出すと、この数を判別できます。
参照 セクション5.1.1のWTInfo関数、セクション5.5.2のWTMgrClose関数、セクション6のメッセージベース番号に関する説明、セクション6.2および6.3のコンテキストおよび情報変更メッセージ。

6.5.2. WTMgrClose

構文 BOOL WTMgrClose(hMgr)
この関数はタブレットマネージャーハンドルを閉じます。この関数が元に戻ると、渡されたマネージャーハンドルは無効になります。
パラメータ 種類/説明
hCtx HWND マネージャーハンドルを所有するウィンドウを指定します。
戻り値 ハンドルが有効な場合、ゼロ以外が返され、それ以外の場合はゼロが返されます。

6.6. マネージャーコンテキスト関数

この関数は、開かれているすべてのコンテキストと所有者へのアクセスを提供し、コンテキストのデフォルトを変更できるようにします。タブレットマネージャーのみが、他のアプリケーションに属するタブレットコンテキストを操作できます。

6.6.1. WTMgrContextEnum

構文 BOOL WTMgrContextEnum(hMgr, lpEnumFunc, lParam)
この関数は、lpEnumFuncパラメータによって指定されたコールバック関数に各コンテキストのハンドルを渡すことで、すべてのタブレットコンテキストハンドルを列挙します。
コールバック関数がゼロを返すと、列挙は終了します。
パラメータ 種類/説明
hCtx HWND マネージャーハンドルを所有するウィンドウを指定します。
lpEnumFunc WTENUMPROC コールバック関数のプロシージャインスタンスアドレス。詳細については、次の「コメント」セクションを参照してください。
lParam LPARAM アプリケーションで使用するためにコールバック関数に渡す値を指定します。
戻り値 戻り値は関数の結果を示します。すべてのコンテキストが列挙された場合は、ゼロ以外です。それ以外の場合は、ゼロが返されます。
コメント lpEnumFuncパラメータとして渡されたアドレスは、MakeProcInstance関数を使用して作成する必要があります。
コールバック関数は、WINAPIと同じ属性を保つ必要があります。コールバック関数の形式は次のとおりです。
コールバック BOOL WINAPI EnumFunc(hCtx, lParam)
HCTX hCtx;
LPARAM lParam;
BEnumFuncは、アプリケーション提供の関数名用のプレースホルダーです。実際の名前をエクスポートするには、アプリケーションのモジュール定義ファイルのEXPORTS文に名前を入れます。
パラメータ 種類/説明
hCtx コンテキストを示します。
lParam WTMgrContextEnum関数の32ビット引数を示します。
戻り値 関数は、列挙を続行するにはゼロ以外の値、停止するにはゼロを返す必要があります。

6.6.2. WTMgrContextOwner

構文 HWND WTMgrContextOwner(hMgr, hCtx)
この関数は、タブレットコンテキストを所有するウィンドウのハンドルを返します。
パラメータ 種類/説明
hMgr HMGR 呼び出し元のマネージャーアプリケーションとして示す有効なマネージャーハンドル。
hCtx HCTX 所有者が返されるコンテキストを指定します。
戻り値 渡された引数が有効な場合、コンテキストの所有者のウィンドウハンドルが返されます。それ以外の場合は、NULLが返されます。
コメント この関数を使用すると、タブレットマネージャーはコンテキストを所有するウィンドウの状態にタブレットコンテキスト管理を合わせます。

6.6.3. WTMgrDefContext

構文 HCTX WTMgrDefContext(hMgr, fSystem) (1.4 modified)
この関数は、デフォルトシステムコンテキストかデフォルトデジタイジングコンテキストのコンテキストハンドルを取得します。このコンテキストは読み取り専用です。
パラメータ 種類/説明
hMgr HMGR 呼び出し元のマネージャーアプリケーションとして示す有効なマネージャーハンドル。
fSystem BOOL ゼロ以外の場合はデフォルトシステムコンテキストの取得、ゼロの場合はデフォルトデジタイジングコンテキストの取得を示します。
戻り値 戻り値は、指定したデフォルトコンテキストのコンテキストハンドル、引数が無効な場合はNULLです。
コメント デフォルトデジタイジングコンテキストは、WTInfo関数(WTI_DEFCONTEXTカテゴリ)によって属性が返されるコンテキストです。デフォルトシステムコンテキストは、WTInfo関数(WTI_DEFSYSCTXカテゴリ)によって属性が返されるコンテキストです。
タブレットがシステムに接続されている場合、この関数で返されるHCTX値は、WTGet()で使用していれば、lcDevice = (UINT)(-1)を持つLOGCONTEXTを返します。これは、いわゆる「仮想デバイス」を表します。仮想デバイス(または「仮想タブレット」)は、接続されているタブレットからデータを受け付け、アプリケーションに送信します。
参照 セクション5.1.1のWTInfo関数、セクション5.6.4のWTMgrDefContextEx関数、表7.3から7.9のカテゴリーおよびインデックス定義。

6.6.4. WTMgrDefContextEx(1.1変更、1.4変更)

構文 HCTX WTMgrDefContextEx(hMgr, wDevice, fSystem)
この関数は、指定したデバイスのデフォルトのデジタイジングまたはシステムコンテキストの値を設定できるコンテキストハンドルを取得します。
パラメータ 種類/説明
hMgr HMGR 呼び出し側をマネージャーアプリケーションとして示す有効なマネージャーハンドル。
wDevice BUINT デフォルトコンテキストハンドルが返されるデバイスを指定します。
fSystem BOOL ゼロ以外の場合はデフォルトシステムコンテキストの取得、ゼロの場合はデフォルトデジタイジングコンテキストの取得を示します。
戻り値 戻り値は、指定したデフォルトコンテキストのコンテキストハンドル、引数が無効な場合はNULLです。
コメント デフォルトデジタイジングコンテキストは、WTInfo関数(WTI_DDCTXS多重化カテゴリ)によって属性が返されるコンテキストです。デフォルトシステムコンテキストは、WTInfo関数(WTI_DSCTXS多重化カテゴリ)によって属性が返されるコンテキストです。
wDevice = (UINT)(-1)で、いわゆる「仮想デバイス」を表している場合、この関数で返されるHCTX値は、WTGet()で使用していれば、lcDevice = (UINT)(-1)を持つLOGCONTEXTを返します。仮想デバイス(または「仮想タブレット」)は、接続されているタブレットからデータを受け付け、アプリケーションに送信します。
参照 セクション5.1.1のWTInfo関数、表7.3から7.9のカテゴリーおよびインデックス定義。

6.7. マネージャーのユーザ設定データ関数(1.4変更)

このセクションの関数は、特定のタブレットコンテキストに縛られない、グローバルな人間工学面の設定またはユーザ設定を操作します。

6.7.1. WTMgrCsrButtonMap

構文 BOOL WTMgrCsrButtonMap(hMgr, wCursor, lpLogBtns, lpSysBtns)
この関数では、タブレットマネージャーがカーソルタイプごとのボタンのマッピングを変更できます。各カーソルタイプには、2つのボタンマップがあります。論理ボタンマップは、物理ボタンを論理ボタンに割り当てます(アプリケーションは論理ボタンのみを使用します)。システムカーソルボタンマップは、システムボタン機能を論理ボタンにバインドします。
パラメータ 種類/説明
hMgr HMGR 呼び出し元のマネージャーアプリケーションとして示す有効なマネージャーハンドル。
wCursor UINT ボタンマップが設定されるカーソルタイプのカーソルID(ゼロから始まります)を指定します。
lpLogBtns LPBYTE 論理ボタン番号の32バイト配列を物理ボタンごとに1つずつ指します。WTP_LPDEFAULTという値が指定された場合、関数は論理ボタンマップのデフォルト値をリセットします。
lpSysBtns LPBYTE ボタンアクションコードの32バイト配列を物理ボタンごとに1つずつ指します。WTP_LPDEFAULTという値が指定された場合、関数はシステムボタンマップのデフォルト値をリセットします。
戻り値 新しい設定が有効になった場合、戻り値はゼロ以外です。それ以外の場合は、ゼロが返されます。
コメント この関数では、2つ以上の物理ボタンを1つの論理ボタンに割り当てることができます。同様に、左右のシステムボタンイベントを正しく生成できることは確約されません。論理ボタンマップに適切な制限を適用するかどうか、およびシステムボタンを無効のままにしておくかどうかは、タブレットマネージャーによって決まります。
参照 表7.8のカーソル情報カテゴリーおよび表7.10のシステムボタン割り当てコード。

6.7.2. WTMgrCsrPressureBtnMarks(16ビットのみ)

構文 BOOL WTMgrCsrPressureBtnMarks(hMgr, wCsr, dwNMarks, dwTMarks)
この関数では、タブレットマネージャーは、ボタンイベントへの押圧アクティビティのマッピングを制御する押圧しきい値を変更できます。
パラメータ 種類/説明
hMgr HMGR 呼び出し側をマネージャーアプリケーションとして示す有効なマネージャーハンドル。
wCsr UINT 押圧ボタンマークが設定されるカーソルタイプのカーソルID(ゼロから始まります)を指定します。
dwNMarks DWORD 押圧ボタン用のボタンマークを示します。下位ワードにはリリースマーク、上位ワードには押下マークが含まれます。WTP_DWDEFAULTという値が指定された場合、関数はマークのデフォルト値をリセットします。
戻り値 新しい設定が有効になった場合、戻り値はゼロ以外です。それ以外の場合は、ゼロが返されます。
コメント この関数は移植不可で、WTMgrCsrPressureBtnMarksExによって置き換えられます。
参照 表7.8のカーソル情報カテゴリーおよびセクション5.9.5のWTMgrCsrPres¬sureBtnMarksEx関数。

6.7.3. WTMgrCsrPressureBtnMarksEx

構文 BOOL WTMgrCsrPressureBtnMarksEx(hMgr, wCsr, lpNMarks, lpTMarks)
この関数では、タブレットマネージャーは、ボタンイベントへの押圧アクティビティのマッピングを制御する押圧しきい値を変更できます。
パラメータ 種類/説明
hMgr HMGR 呼び出し側をマネージャーアプリケーションとして示す有効なマネージャーハンドル。
wCsr UINT 押圧ボタンマークが設定されるカーソルタイプのカーソルID(ゼロから始まります)を指定します。
lpNMarks DUINT FAR * 垂直押圧ボタン用のボタンマークを含む2要素配列を指します。最初の符号なし整数にはリリースマーク、2番めの符号なし整数には押下マークが含まれます。WTP_LPDEFAULTという値が指定された場合、関数はマークのデフォルト値をリセットします。
lpTMarks UINT FAR * 接線押圧ボタン用のボタンマークを含む2要素配列を指します。最初の符号なし整数にはリリースマーク、2番めの符号なし整数には押下マークが含まれます。WTP_LPDEFAULTという値が指定された場合、関数はマークのデフォルト値をリセットします。
戻り値 新しい設定が有効になった場合、戻り値はゼロ以外です。それ以外の場合は、ゼロが返されます。
コメント この関数を使用すると、従来のボタンとして押圧ボタンを使用した場合、ボタンの「感覚」をタブレットマネージャーから制御できます。
押圧範囲では、範囲の最小値が押圧をかけていない残りの状態を示し、最大値が完全に押圧をかけた状態を示すように定義します。ボタンマークは、ボタンの押下イベントとリリースイベントが生成される押圧を判定します。ボタンが論理的に上げられているときに押圧が押下マークを超えている場合、ボタン押下イベントが生成されます。反対に、ボタンが論理的に下げられているときに押圧がリリースマークを下回っている場合、ボタンリリースイベントが生成されます。
ボタンが「取り違い」を起こさないようにマークを十分離して設定するとともに、ボタンイベントが簡単に生成されるように範囲の上限と下限を十分に離してください。
ボタンの押下マークがボタンのリリースマークを上回った場合にのみ、マークは有効です。無効な組み合わせにマークを設定すると、ボタンのボタンイベント生成がオフになります。
参照 表7.8のカーソル情報カテゴリー

6.7.4. WTMgrCsrPressureResponse

構文 BOOL WTMgrCsrPressureResponse(hMgr, wCsr, lpNResp, lpTResp)
この関数では、タブレットマネージャーがカーソルタイプごとの押圧反応を調整できます。
パラメータ 種類/説明
hMgr HMGR 呼び出し側をマネージャーアプリケーションとして示す有効なマネージャハンドル。
wCsr UINT 押圧ボタンマークが設定されるカーソルタイプのカーソルID(ゼロから始まります)を指定します。
lpNMarks DUINT FAR * 垂直押圧ボタン用のボタンマークを含む2要素配列を指します。最初の符号なし整数にはリリースマーク、2番めの符号なし整数には押下マークが含まれます。WTP_LPDEFAULTという値が指定された場合、関数はマークのデフォルト値をリセットします。
lpTMarks UINT FAR * 接線押圧ボタン用のボタンマークを含む2要素配列を指します。最初の符号なし整数にはリリースマーク、2番めの符号なし整数には押下マークが含まれます。WTP_LPDEFAULTという値が指定された場合、関数はマークのデフォルト値をリセットします。
戻り値 新しい設定が有効になった場合、戻り値はゼロ以外です。それ以外の場合は、ゼロが返されます。
コメント 押圧反応曲線は、物理押圧値を論理押圧値にマップする転送機能を表します(アプリケーションは論理押圧値のみを参照します)。各配列要素には、一部の物理押圧値に対応する論理押圧値が含まれています。配列インデックスは、入範囲を超えて均等に「伸縮」されます。
配列内のエントリの数は、物理押圧値の範囲によって決まります。物理値か256のうち、どちらか小さい方の数になります。可能な値ごとにエントリがある場合、値は配列へのインデックスとして使用され、対応する配列要素が返されます。配列要素よりも多くの値がある場合、物理値は0~255のスケールにマップされます。結果は、論理押圧値をルックアップするためのインデックスとして使用されます。
参照 表7.8のカーソル情報カテゴリー

7 メッセージリファレンス

このセクションでは、タブレット対応アプリケーションおよびタブレットマネージャーに送信されるメッセージについて説明します。メッセージはWindowsの拡張なので、下記のメッセージ名は、グローバルで固定されているメッセージ番号を表すものではありません。アプリケーションは、WM_USER範囲(WM_USER~16進数8000)でメッセージ番号を選択し、LOGCONTEXT構造体のlcMsgBaseフィールド(セクション7.3.1を参照)、またはWTMgrOpen関数のwMsgBase引数(セクション5.5.1を参照)を介して、メッセージベースをインターフェースにパブリッシュします。アプリケーションは、コンテキストおよびマネージャーハンドルごとに異なる範囲を選択することも、すべてに対して同じ範囲を選択することもできます。

下記のメッセージ名は、実際には、アプリケーション選択ベースからの固定オフセットを表します。インターフェース定義は、将来のメッセージ定義に備えて16のオフセットを保持しています。デフォルトメッセージベースは、16進数7FF0で定義したグローバル定数値WT_DEFBASEです。このデフォルト値は、多くのアプリケーションで妥当で安全なものですが、メッセージ名の競合を防ぐのは、アプリケーションプログラマの責任です。

32ビットWintab固有の情報:ほとんどのメッセージ引数の種類は32ビットWintabではより幅広くなっていますが、wParamからlParam(またはその反対)にジャンプしたメッセージ引数はありません。最も広い引数は現在、これまで未使用または使用不可だったスペースを占めています。WT_INFOCHANGEのカテゴリーおよびインデックス引数は広げられていないので注意してください。いずれも、まだ16ビットです。Wintab Programmer’s KitのヘッダーファイルWINTABX.Hには、16ビットでも32ビットでも使用できる、移植可能な「メッセージクラッカー」マクロが含まれています。

7.1. イベントメッセージ

Windowsメッセージを介してデバイスイベントを受信するWintabアプリケーションは、WT_PACKETメッセージを受信します。

7.1.1. WT_PACKET

説明 BWT_PACKETメッセージは、コンテキストの対してメッセージ要求を行った所有側ウィンドウに送信されます。
パラメータ 種類/説明
wParam メッセージを生成したパケットのシリアル番号が指定されます。
lParam パケットを処理したコンテキストのハンドルが指定されます。
コメント アプリケーションは、このメッセージを受信すると、WTPacket関数または他のパケット取得関数を呼び出す必要があります。
参照 セクション6.1.1のWTPacket関数およびセクション5.4の高度なパケットおよびキュー関数。

7.1.2. WT_PACKET

説明 WT_CSRCHANGEメッセージは、新しいカーソルがコンテキストに入ると、所有側ウィンドウに送信されます。
パラメータ 種類/説明
wParam メッセージを生成したパケットのシリアル番号が指定されます。
lParam パケットを処理したコンテキストのハンドルが指定されます。
コメント CXO_CSRMESSAGESオプションを持つコンテキストのみがこのメッセージを生成します。

7.2. コンテキストメッセージ

このセクションで説明するメッセージは、コンテキストの変更に関する情報を提供します。

7.2.1. WT_CTXOPEN

説明 WT_CTXOPENメッセージは、コンテキストが開かれると、所有側ウィンドウと任意のマネージャーウィンドウに送信されます。
パラメータ 説明
wParam メッセージを生成したパケットのシリアル番号が指定されます。
lParam パケットを処理したコンテキストのハンドルが指定されます。
コメント アプリケーションは、このメッセージを受信すると、WTPacket関数または他のパケット取得関数を呼び出す必要があります。
参照 セクション6.1.1のWTPacket関数およびセクション5.4の高度なパケットおよびキュー関数。

7.2.2. WT_PACKET

説明 WT_CSRCHANGEメッセージは、新しいカーソルがコンテキストに入ると、所有側ウィンドウに送信されます。
パラメータ 説明
wParam メッセージを生成したパケットのシリアル番号が指定されます。
lParam 現在のコンテキストのステータスフラグが指定されます。
コメント タブレットマネージャーアプリケーションは、コンテキストが閉じられ、適切なアクションを取るように注意する必要があります。

7.2.3. WT_CTXUPDATE

説明 WT_CTXUPDATEメッセージは、コンテキストが変更されると、所有側ウィンドウと任意のマネージャーウィンドウに送信されます。
パラメータ 説明
wParam 変更されているコンテキストのコンテキストハンドルが指定されます。
lParam 現在のコンテキストのステータスフラグが指定されます。
コメント アプリケーションは、このメッセージを受信する際に、変更されたコンテキスト属性を検出するために、WTGetまたはWTExtGetを呼び出しても構いません。

7.2.4. WT_CTXOVERLAP

説明 WT_CTXOVERLAPメッセージは、コンテキストが重複順序に移動したときに所有側ウィンドウと任意のマネージャ¬ウィンドウに送信されます。
パラメータ 説明
wParam 再び重複しているコンテキストのコンテキストハンドルが指定されます。
lParam 現在のコンテキストのステータスフラグが指定されます。
コメント タブレットマネージャーは、このメッセージを処理し、アプリケーションによるコンテキスト重複要求を記録します。
アプリケーションは、このメッセージを処理し、コンテキストが別のコンテキストによっていつ隠されたかを検出できます。

7.2.5. WT_PROXIMITY

説明 WT_PROXIMITYメッセージは、カーソルがコンテキストの近接性に入るとき、または近接性から出るときに所有側ウィンドウと任意のマネージャーウィンドウにポストされます。
パラメータ 説明
wParam カーソルが入ろうとしているコンテキストまたは出ようとしているコンテキストのハンドルが指定されます。
lParam カーソルがコンテキストに入ると下位ワードがゼロ以外になり、カーソルがコンテキストから離れるとゼロになります。カーソルがハードウェア近接性から離れるか、近接性に入ると、上位ワードはゼロ以外になります。
コメント タ近接性イベントは、通常のタブレットイベントとは独立して処理されます。アプリケーションは、イベントメッセージを要求していない場合でも近接性メッセージを受信します。

7.3. 情報変更メッセージ

このセクションで説明するメッセージは、情報項目の変更に関する情報を提供します。

7.3.1. WT_INFOCHANGE(1.4変更)

説明 WT_INFOCHANGEメッセージは、接続されているタブレットの数が変更されると、すべてのマネージャーおよびコンテキスト所有側ウィンドウに送信されます。
パラメータ 説明
wParam 情報を変更したタブレットマネージャーのマネージャーハンドルが含まれます。または、ハードウェアを通じて変更がレポートされた場合はゼロになります。
lParam 変更された情報のカテゴリーとインデックス番号が指定されます。下位ワードにはカテゴリー番号、上位ワードにはインデックス番号が指定されます。
コメント アプリケーションは、このメッセージを処理することで機能の変更に応答できます。単純なアプリケーションの場合、閉じて再起動するようにユーザに要求しても構いません。デフォルトコンテキストを使用するごく基本的なアプリケーションは、何も行う必要はないはずです。
タブレットマネージャーは、このメッセージを処理し、ハードウェアの構成変更または他のマネージャーによる変更に応答する必要があります(複数のタブレットマネージャーが可能な実装の場合)。

8 データリファレンス

下記のリストのデータ型は、タブレットインターフェース関数とメッセージに関連するパラメータと戻り値のサイズと意味を定義するキーワードです。下記のリストには、固定小数点数演算型、ポインタ型、ビットフィールド型、ハンドル、コールバック関数プロトタイプが含まれます。固定小数点型名はFIXというプレフィックスから始まります。ポインタ型名はプレフィックスP(ショートポインタの場合)またはLP(ロングポインタの場合)から始まります。ビットフィールド型には、さまざまな条件を指定するために一般的に使用されるビットのセットが含まれます。コールバック関数プロトタイプは、WTプレフィックスとPROCサフィックスを使用し、アプリケーション定義のコールバック関数の属性、引数、戻り型を定義します。ハンドルは、タブレットインターフェース内部で管理されるリソースへのアクセスを提供します。タブレットインターフェースデータ型は、下記のリストで定義されます。

8.1. 一般的なデータ型(1.1変更、1.4変更)

下記のリストのデータ型は、タブレットインターフェース関数とメッセージに関連するパラメータと戻り値のサイズと意味を定義するキーワードです。下記のリストには、固定小数点数演算型、ポインタ型、ビットフィールド型、ハンドル、コールバック関数プロトタイプが含まれます。固定小数点型名はFIXというプレフィックスから始まります。ポインタ型名はプレフィックスP(ショートポインタの場合)またはLP(ロングポインタの場合)から始まります。ビットフィールド型には、さまざまな条件を指定するために一般的に使用されるビットのセットが含まれます。コールバック関数プロトタイプは、WTプレフィックスとPROCサフィックスを使用し、アプリケーション定義のコールバック関数の属性、引数、戻り型を定義します。ハンドルは、タブレットインターフェース内部で管理されるリソースへのアクセスを提供します。タブレットインターフェースデータ型は、下記のリストで定義されます。

表8.1. 一般的なデータ型

種類 定義
FIX32 2つのワードの間に基数点を持つ、32ビット固定小数点数演算型。したがって、この型には、基数点の左に16ビット、右に16ビットがあります。
HMGR タブレットマネージャーのハンドル。アプリケーションによるタブレット管理機能の使用を可能にする値です。複数のマネージャーアプリケーションが許可されている場合、タブレットインターフェースに対するマネージャーも識別します。
HCTX タブレットコンテキストに対するハンドル。タブレットインターフェースのコンテキストテーブルへのインデックスです。
LPLOGCONTEXT LOGCONTEXTデータ構造体へのロングポインタ
WTPKT イベントパケットで使用可能なさまざまなオプションデータ項目を指定するビットフィールド。32ビットフィールドです。ビットOR演算子を使用して、イベントパケットフィールドフラグを組み合わせることができます。WTPKTビットフィールドは、拡張データ項目用に定義されている値に加え、下記の値を格納できます。
意味
PK_CONTEXT レポート用コンテキストのハンドルを示します。
PK_STATUS ステータス情報を示します。
PK_TIME パケットが生成された時間を示します。
PK_CHANGED 最後のパケット以降に変更されたパケットデータ項目を示します。
PK_SERIAL_NUMBER パケットシリアル番号を示します。
PK_CURSOR パケットを生成したカーソルを示します。
PK_BUTTONS パケットボタン情報を示します。
PK_X、PK_Y、PK_Z パケットのx、y、z軸データをそれぞれ指定します。
PK_NORMAL_PRESSURE、PK_TANGENT_PRESSURE ペン先スイッチまたは筆圧データ、およびサイドスイッチまたはエアブラシのホイールデータをそれぞれ指定します。
PK_ORIENTATION カーソル方向情報を示します。
PK_ROTATION (1.1)/td>

カーソル回転情報を示します。
WTENUMPROC コンテキスト列挙コールバックのプロトタイプを示します。

BOOL (WINAPI * WTENUMPROC)(HCTX, LPARAM);

WTPKT コンテキスト構成コールバックのプロトタイプを示します。

BOOL (WINAPI * WTCONFIGPROC)(HCTX, HWND);

8.2. 情報変更メッセージ

このセクションでは、WTInfo関数で返されたデータ形式、および関数の呼び出し時に使用されるカテゴリーとインデックスについて説明します。一部では、共通データ戻り型の形式を最初に説明し、次にすべてのカテゴリーおよびインデックス値のリストを示します。

8.2.1. AXIS

範囲および分解能記述子

説明 AXISデータ構造体は、多くのパケットデータ項目の範囲と分解能を定義します。
typedef struct tagAXIS {
        LONG    axMin;
        LONG    axMax;
        UINT axUnits;
        FIX32     axResolution;
} AXIS;
AXISデータ構造体には、次のフィールドがあります。
フィールド 説明
axMin タブレットのネイティブ座標でデータ項目の最小値を示します。
axMax タブレットのネイティブ座標でデータ項目の最大値を示します。
axUnits データ項目の分解能を計算する際に使用する単位を示します。
axResolution 物理単位ごとに増えていくデータ項目の数値を提供する¬¬固定小数点数値。
コメント この構造体は、WTInfo関数の戻りデータを構築するために使用します。特に、各軸またはパケットデータ項目に関してデバイスの機能を返すためのWTI_DEVICESカテゴリー内で使用します。
セクション5.1.1のWTInfo関数および表7.2の単位指定用の値。

表7.2. 物理単位指定子

TU_NONE 物理単位に対して分解能が提供されないことを示します。
TU_INCHES インチに対して分解能が提供されることを示します。
TU_CENTIMETERS センチメートルに対して分解能が提供されることを示します。
TU_CIRCLE 1回転の弧に対して分解能が提供されることを示します。たとえば、データ項目が角度を返す場合、分解能は360で、単位はTU_CIRCLEとなります。項目がラジアンの場合、分解能は6.28318(FIX32の精度まで)で、単位はTU_CIRCLEとなります。

8.2.2. 情報カテゴリーおよびインデックス(1.1変更)

カテゴリー、インデックス、および戻りデータ形式を次に示します。WTI_DEFCONTEXT、WTI_DEFSYSCTX、WTI_DDCTXS、およびWTI_DSCTXSカテゴリーは、同じ一連のインデックスを共有します。いずれも、デフォルトのデジタイジングおよびシステムコンテキストをそれぞれ参照します。WTI_DEVICES、WTI_CURSORS、およびWTI_EXTENSIONSカテゴリーは多重化されています。つまり、カテゴリー名は、連続する複数のカテゴリーの一番最初のものを実際に参照します。

表7.3. カテゴリーの定義

カテゴリー 説明
WTI_INTERFACE グローバルインターフェースIDおよび機能情報が含まれます。
WTI_STATUS 現在のインターフェースのリソース使用統計が含まれます。
WTI_DEFCONTEXT 現在のデフォルトデジタイジング論理コンテキストが含まれます。
WTI_DEFSYSCTX 現在のデフォルトシステム論理コンテキストが含まれます。
WTI_DEVICES 各デバイスの機能およびステータス情報が含まれます。
WTI_CURSORS 各カーソルタイプの機能およびステータス情報が含まれます。
WTI_EXTENSIONS 各拡張の説明情報およびデフォルトが含まれます。
WTI_DDCTXS(1.1) 対応するデバイスごとの現在のデフォルトデジタイジング論理コンテキストが含まれます。
WTI_DSCTXS(1.1) 対応するデバイスごとの現在のデフォルトシステム論理コンテキストが含まれます。

表7.4. WTI_INTERFACEインデックス定義

インデックス 種類/説明
IFC_WINTABID TCHAR[] ユーザバッファのNULL終端タブレットハードウェアID文字列のコピーを返します。この文字列には、ユーザによる読み取り可能な形式で作成、モデル、および改訂情報が含まれます。
IFC_SPECVERSION WORD 仕様バージョン番号が返されます。上位バイトにはメジャーバージョン番号、下位バイトにはマイナーバージョン番号が含まれます。
IFC_IMPLVERSION WORD 実装バージョン番号を返します。上位バイトにはメジャーバージョン番号、下位バイトにはマイナーバージョン番号が含まれます。
IFC_NDEVICES UINT サポートされているデバイスの数を返します。
IFC_NCURSORS UINT サポートされているカーソルタイプの合計数を返します。
IFC_NCONTEXTS UINT サポートされているコンテキストの数を返します。
IFC_CTXOPTIONS UINT サポートされているコンテキストオプションを示すフラグを返します(表7.11を参照)。
IFC_CTXSAVESIZE UINT WTSaveから返された保存情報のサイズを返します。
IFC_NEXTENSIONS UINT サポートされている拡張データ項目の数を返します。
IFC_NMANAGERS UINT サポートされているマネージャーハンドルの数を返します。

表7.5. WTI_STATUSインデックス定義

インデックス 種類/説明
STA_CONTEXTS UINT 現在開いているコンテキストの数を返します。
STA_SYSCTXS UINT 現在開いているシステムコンテキストの数を返します。
STA_PKTRATE UINT任意のコンテキストが現在受信している最大パケットレポート率(ヘルツ単位)を返します。
STA_PKTDATA WTPKT 1つ以上のコンテキストで要求されたパケットデータ項目を示すマスクを返します。
STA_MANAGERS UINT 現在開いているマネージャーハンドルの数を返します。
STA_SYSTEM BOOL システムポインティングが画面全体で有効な場合はゼロ以外、そうでない場合はゼロを返します。
STA_BUTTONUSE DWORD 1つ以上のコンテキストでイベントが要求された論理ボタンを示すボタンマスクを返します。
STA_SYSBTNUSE DWORD 現在のカーソルのシステムボタンマップによってシステムボタン機能が割り当てられた論理ボタンを示すボタンマスクを返します。

表7.6. WTI_DEFCONTEXT、WTI_DEFSYSCTX、WTI_DDCTXS (1.1)、およびWTI_DSCTXS (1.1)インデックス定義

インデックス 種類/説明
CTX_NAME TCHAR[] デフォルト名を格納する40文字の配列を返します。名前はゼロ文字でも、39文字でも構いません。配列の空白部分にはゼロが入れられます。
CTX_OPTIONS UINT オプションフラグを返します。デフォルトデジタイジングコンテキストの場合、CXO_MARGINとCXO_MGNINSIDEが許可されています。デフォルトシステムコンテキストの場合、CXO_SYSTEMは必須です。CXO_PEN、CXO_MARGIN、CXO_MGNINSIDEが許可されています。詳細については、表7.11を参照してください。
CTX_STATUS UINT ゼロを返します。
CTX_LOCKS UINT ロックされているデフォルトコンテキストの属性を返します。詳細については、表7.13を参照してください。
CTX_MSGBASE UINT 値WT_DEFBASEを返します。セクション6のメッセージの説明を参照してください。
CTX_DEVICE UINT デフォルトデバイスを返します。この値が-1の場合は、「仮想デバイス」としても認識されます。
CTX_PKTRATE UINT デフォルトコンテキストパケットレポート率(ヘルツ単位)を返します。
CTX_PKTDATA WTPKT どのオプションデータ項目がコンテキストから返されたパケット単位になるかを返します。デフォルトデジタイジングコンテキストの場合、このフィールドは、少なくともボタン、x、およびyデータを示す必要があります。
CTX_PKTMODE WTPKT パケットデータ項目が絶対モードで返されるか、相対モードで返されるかを返します。
CTX_MOVEMASK WTPKT どのパケットデータ項目がコンテキストでモーションイベントを生成できるかを返します。
CTX_BTNDNMASK DWORD ボタン押下イベントがコンテキストで処理されるボタンを返します。デフォルトコンテキストは、1つのボタンに対して少なくとも1つのボタン押下イベントを選択する必要があります。
CTX_BTNUPMASK DWORD ボタンリリースイベントがコンテキストで処理されるボタンを返します。
CTX_INORGX、CTX_INORGY、CTX_INORGZ LONG それぞれx、y、z軸に沿ったタブレットのネイティブ座標で、コンテキストの入力領域の原点を返します。
CTX_INEXTX、CTX_INEXTY、CTX_INEXTZ LONG それぞれx、y、zの各軸に沿ったタブレットのネイティブ座標で、コンテキストの入力領域の範囲を返します。
CTX_OUTORGX、CTX_OUTORGY、CTX_OUTORGZ LONG それぞれx、y、zの各軸に沿ったコンテキスト出力座標で、コンテキストの出力座標空間の原点を返します。
CTX_OUTEXTX、CTX_OUTEXTY、CTX_OUTEXTZ LONG それぞれx、y、zの各軸に沿ったコンテキスト出力座標で、コンテキストの出力座標空間の範囲を返します。
CTX_SENSX、CTX_SENSY、CTX_SENSZ FIX32 それぞれx、y、zの各軸に沿った、相対モード感度因子を返します。
CTX_SYSMODE BOOL デフォルトシステムカーソルトラッキングモードを返します。
CTX_SYSORGX、CTX_SYSORGY int 0を返します。
CTX_SYSEXTX、CTX_SYSEXTY int
現在の画面表示サイズ(ピクセル単位)を、それぞれxおよびy方向で返します。
CTX_SYSSENSX、CTX_SYSSENSY FIX32 システムカーソルの相対モード感度因子を、それぞれxおよびy方向で返します。

表7.7. WTI_DEVICESインデックス定義

インデックス 種類/説明
DVC_NAME TCHAR[] デバイス、メーカー、改訂レベルを示す表示可能なNULL終端文字列を返します。
DVC_HARDWARE UINT 下記の定義に従って、ハードウェアおよびドライバ機能を示すフラグを返します。
意味
HWC_INTEGRATED ディスプレイとデジタイザが同じ面を共有していることを示します。
HWC_TOUCH 位置をレポートするために、カーソルが物理的にデバイスに接触している必要があることを示します。
HWC_HARDPROX カーソルが物理検出範囲に入ったとき、およびそこから出たときに、デバイスがイベントを生成できることを示します。
HWC_PHYSID_CURSORS(1.1) デバイスがハードウェアのアクティブなカーソルを一意に識別できることを示します。
DVC_NCSRTYPES UINT サポートされているカーソルタイプの数を返します。
DVC_FIRSTCSR UINT デバイスの最初のカーソルタイプ番号を返します。
DVC_PKTRATE UINT 最大パケットレポート率(ヘルツ単位)を返します。
DVC_PKTDATA WTPKT 常に使用可能なパケットデータ項目を示すビットマスクを返します。
DVC_PKTMODE WTPKT 絶対測定ではなく、物理的な相対的なパケットデータ項目、つまりハードウェアが変更のみをレポートできる項目を示すビットマスクを返します。
DVC_CSRDATA WTPKT 一部のカーソルが接続されているときにのみ使用可能なパケットデータ項目を示すビットマスクを返します。個々のカーソルの説明を調べ、どのカーソルがどのデータを返すかを判別する必要があります。
DVC_XMARGIN、DVC_YMARGIN、DVC_ZMARGIN int タブレットのネイティブ座標のタブレットコンテキストマージンのサイズを、それぞれx、y、z方向で返します。
DVC_X、DVC_Y、DVC_Z AXIS タブレットの範囲と分解能の機能を、それぞれx、y、z軸で返します。
DVC_NPRESSURE、DVC_TPRESSURE AXISそれぞれ筆圧およびエアブラシのホイールの入力に対するタブレットの範囲と分解能の機能を返します。
DVC_ORIENTATION AXISそれぞれ筆圧およびエアブラシのホイールの入力に対するタブレットの範囲と分解能の機能を返します。
DVC_ROTATION(1.1) AXIS[] タブレットの回転の範囲と分解能の機能を示す3要素配列を返します。
DVC_PNPI(1.1) TCHAR[] デバイスのプラグアンドプレイIDを含むNULL終端文字列を返します。

表7.8. WTI_CURSORSインデックス定義

インデックス 種類/説明
CSR_NAME TCHAR[] カーソルの名前を含む表示可能なゼロ終端文字列を返します。
CSR_ACTIVE BOOL カーソルが現在接続されているかどうかを返します。
CSR_PKTDATA WTPKT 現在のカーソルが接続されているときにサポートされるパケットデータ項目を示すビットマスクを返します。
CSR_BUTTONS BYTE 現在のカーソルのボタンの数を返します。
CSR_BUTTONBITS BYTE ハードウェアによって返される未処理ボタンデータのビットの数を返します。
CSR_BTNNAMES TCHAR[] カーソルのボタンの名前を含むゼロ終端文字列のリストを返します。リスト内の名前の数は、カーソルのボタンの数と同じです。それぞれの名前は1つのゼロ文字で区切られ、リストの終端には2つのゼロ文字が付けられます。
CSR_BUTTONMAP BYTE[] 論理ボタン番号の32バイト配列を物理ボタンごとに1つずつ返します。
CSR_SYSBTNMAP BYTE[]ボタンアクションコードの32バイト配列を物理ボタンごとに1つずつ返します。
CSR_NPBUTTON BYTE 筆圧によって制御されるボタンの物理ボタン番号を返します。
CSR_NPBTNMARKS UINT[] 筆圧ボタン用のボタンマークを指定する2つのUINTの配列を返します。最初のUINTにはリリースマーク、2番めのUINTには押下マークが含まれます。
CSR_NPRESPONSE UINT[] 筆圧の押圧反応曲線を示すUINTの配列を返します。
CSR_TPBUTTON BYTE エアブラシのホイールによって制御されるボタンの物理ボタン番号を返します。
CSR_TPBTNMARKS UINT[] エアブラシのホイール用のボタンマークを指定する2つのUINTの配列を返します。最初のUINTにはリリースマーク、2番めのUINTには押下マークが含まれます。
CSR_TPRESPONSE UINT[] エアブラシのホイールの押圧反応曲線を示すUINTの配列を返します。
CSR_PHYSID(1.1) DWORD カーソルに対するメーカー固有の物理IDを返します。この値は、物理カーソルを同じデバイスにある他のカーソルから区別します。カテゴリー番号が変更されたものの、それ以外の情報は同じ物理カーソルが複数ある場合でも、この物理IDを使用すれば、アプリケーションは特定の物理カーソルに機能をバインドさせることができます。
CSR_MODE(1.1) UINT 現在のカーソルタイプのカーソルモード番号を返します(現在のカーソルタイプにCRC_MULTIMODE機能がある場合)。
CSR_MINPKTDATA(1.1) UINT 現在のカーソルタイプの物理カーソルで利用可能な最小データセットを返します(現在のカーソルタイプにCRC_AGGREGATE機能がある場合)。
CSR_MINBUTTONS(1.1) UINT カーソルタイプの物理カーソルの最小ボタン数を返します(現在のカーソルタイプにCRC_AGGREGATE機能がある場合)。
CSR_CAPABILITIES UINT 下記の定義に従って、カーソル機能を示すフラグを返します。
意味
CRC_MULTIMODE 現在のカーソルタイプが1つの物理カーソルで複数のモードのいずれかを表していることを示します。連続カーソルタイプカテゴリーはモードを示します。CSR_MODEデータ項目は、カーソルタイプごとのモード番号を提供します。
CRC_AGGREGATE 現在のカーソルタイプが、ソフトウェアでは区別できない複数の物理カーソルを表していることを示します。
CRC_INVERT 現在のカーソルタイプが、反転された方向で物理カーソルを表していることを示します。以前の連続カーソルタイプカテゴリーは、通常の方向を表します。

表7.9. WTI_EXTENSIONSインデックス定義

インデックス 種類/説明
EXT_NAME TCHAR[] 拡張を示す一意のNULL終端文字列を返します。
EXT_TAG UINT 拡張の一意の識別子を返します。
EXT_MASK WTPKT 拡張を選択するためにWTPKT型の変数でビットOR化できるマスクを返します。
EXT_SIZE UINT[] パケット内の拡張のサイズ(バイト単位)を指定する2つのUINTの配列を返します。最初の配列は絶対モード用、2番目の配列は相対モード用です。
EXT_AXES AXIS[] 拡張で必要とされている、軸の記述の配列を返します。
EXT_DEFAULT BYTE[] 拡張で必要とされている、現在のグローバルデフォルトデータを返します。このデータは、WTMgrExt関数を介して変更されます。
EXT_DEFCONTEXT、EXT_DEFSYSCTX BYTE[] 拡張で必要とされている、現在のデフォルトコンテキスト固有データを返します。インデックスは、デジタイジングコンテキストおよびシステムコンテキストのデフォルトをそれぞれ識別します。
EXT_CURSORS BYTE[] 1つまたは複数の連続インデックスの最初のインデックスです。各カーソルタイプに1つずつ存在します。拡張で必要とされている、現在のデフォルトカーソル固有データを返します。このデータは、WTMgrCsrExt関数を介して変更されます。

表7.10. システムボタン割り当て値

下記で定義されている値は、マウスボタンアクションの列挙を示します。クリック、ダブルクリック、ドラッグという3種類のアクションが、マウスボタンごとに定義されています。クリックは、対応するマウスボタンと同じ処理をボタンが行うことを示します。ダブルクリックは、ボタンを1回押すと、マウスボタンのダブルクリックをエミュレートすることを示します。ドラッグは、ボタンを押すと、エミュレートされたマウスボタンの状態が切り替わることを示します。1回クリックで押し、もう1回クリックで離します。

意味
SBN_NONE システムボタンアクションはありません。
SBN_LCLICK、SBN_LDBLCLICK、SBN_LDRAG それぞれ左ボタンクリック、ダブルクリック、ドラッグを示します。
SBN_RCLICK、SBN_RDBLCLICK、SBN_RDRAG それぞれ真ん中ボタンクリック、ダブルクリック、ドラッグを示します。

Pen Windowsをサポートしている実装では、下記で定義されている値は、ペン-ボタンアクションをタブレットカーソルボタンに割り当てます。単体でも使用できますし、(ビットOR演算子を使用して)上記の値のいずれかと組み合わせて使用することもできます。

意味
SBN_PTCLICK、SBN_PTDBLCLICK、SBN_PTDRAG それぞれペン先クリック(タップ)、ダブルクリック(ダブルタップ)、ドラッグ(ストローク)を示します。
SBN_PNCLICK、SBN_PNDBLCLICK、SBN_PNDRAG それぞれ反転ペン先クリック、ダブルクリック、ドラッグを示します。
SBN_P1CLICK、SBN_P1DBLCLICK、SBN_P1DRAG それぞれサイドスイッチ1クリック、ダブルクリック、ドラッグを示します。
SBN_P2CLICK、SBN_P2DBLCLICK、SBN_P2DRAG それぞれサイドスイッチ2クリック、ダブルクリック、ドラッグを示します。
SBN_P3CLICK、SBN_P3DBLCLICK、SBN_P3DRAG それぞれサイドスイッチ3クリック、ダブルクリック、ドラッグを示します。

8.3. コンテキストデータ構造体

このセクションでは、コンテキストを開いて操作する際に使用されるLOGCONTEXTデータ構造体について説明します。この構造体には、アプリケーションとタブレットマネージャーがコンテキストについて認識する必要があるすべての情報が含まれています。コンテキストの操作を簡便化するために、アプリケーションは、WTInfo関数から使用できるデフォルトコンテキスト仕様を利用できます。

8.3.1.  LOGCONTEXT(1.1変更)

LOGCONTEXTデータ構造体には、タブレットコンテキストの指定に必要な属性が含まれています。

#define LC_NAMELEN 40
typedef struct tagLOGCONTEXT {
TCHAR  lcName[LC_NAMELEN];
        UINT   lcOptions;
       UINT   lcStatus;
       UINT   lcLocks;
       UINT   lcMsgBase;
       UINT   lcDevice;
       UINT   lcPktRate;
       WTPKT  lcPktData;
       WTPKT  lcPktMode;
       WTPKT  lcMoveMask;
       DWORD  lcBtnDnMask;
       DWORD  lcBtnUpMask;
       LONG   lcInOrgX;
       LONG   lcInOrgY;
       LONG   lcInOrgZ;
       LONG   lcInExtX;
       LONG   lcInExtY;
       LONG   lcInExtZ;
       LONG   lcOutOrgX;
       LONG   lcOutOrgY;
       LONG   lcOutOrgZ;
       LONG   lcOutExtX;
       LONG   lcOutExtY;
       LONG   lcOutExtZ;
       FIX32  lcSensX;
       FIX32  lcSensY;
       FIX32  lcSensZ;
       BOOL   lcSysMode;
       int    lcSysOrgX;
       int    lcSysOrgY;
       int    lcSysExtX;
       int    lcSysExtY;
       FIX32  lcSysSensX;
       FIX32  lcSysSensY;
} LOGCONTEXT;

説明 LOGCONTEXTデータ構造体には、次のフィールドがあります。
フィールド 説明
lcName ゼロ終端コンテキスト名文字列が含まれています。
lcOptions コンテキストのオプションを示します。このオプションは、ビットOR演算子を使用して組み合わせることができます。lcOptionsフィールドには、表7.11で定義されている値の任意の組み合わせを使用できます。特定の実装でサポートされていないオプションを指定すると、WTOpenが失敗します。
lcStatus コンテキストの現在のステータス条件を示します。この条件は、ビットOR演算子を使用して組み合わせることができます。lcStatusフィールドには、表7.12で定義されている値の任意の組み合わせを使用できます。
lcLocks アプリケーションがロックを希望するコンテキストの属性を示します。ロック条件は、コンテキストをいったん開くと変更できなくなるコンテキストの属性を示します(WTConfigを呼び出しても、ロックされた属性には影響しません)。ロック条件は、ビットOR演算子を使用して組み合わせることができます。lcLocksフィールドには、表7.13で定義されている値の任意の組み合わせを使用できます。ロックは、そのコンテキストを所有しているタスクまたはプロセスによってのみ変更できます。
lcMsgBase コンテキストのアクティビティをレポートするために使用されるメッセージ番号の範囲を示します。セクション6のメッセージの説明を参照してください。
lcDevice コンテキストが処理する入力が行われたデバイスを示します。
lcPktRate 目的のパケットレポート率(ヘルツ単位)を示します。コンテキストが開かれると、このフィールドには実際のレポート率が含まれます。
lcPktData どのオプションデータ項目がコンテキストから返されたパケット単位になるかを示します。サポートされていないデータ項目を要求すると、WTOpenが失敗します。
lcPktMode パケットデータ項目が絶対モードで返されるか、相対モードで返されるかを示します。項目のビットがこのフィールドで設定された場合、相対モードで項目が返されます。lcPktDataフィールドで選択されていない項目に対するこのフィールドのビットは無視されます。一方のモードのみが有効なデータ項目(シリアル番号など)のビットも無視されます。
lcMoveMask どのパケットデータ項目がコンテキストで移動イベントを生成できるかを示します。lcPktDataフィールドのパケット定義の一部ではない項目のビットは無視されます。ボタン、タイムスタンプ、シリアル番号のビットも無視されます。重複するコンテキストの場合、このフィールドで選択されていないデータ項目の移動イベントは、基底
コンテキストで処理される可能性があります。
lcBtnDnMask ボタン押下イベントがコンテキストで処理されるボタンを示します。重複するコンテキストの場合、このフィールドで選択されていないボタンのボタン押下イベントは、基底コンテキストで処理される可能性があります。
lcBtnUpMask ボタンリリースイベントがコンテキストで処理されるボタンを示します。重複するコンテキストの場合、このフィールドで選択されていないボタンのボタンリリースイベントは、基底コンテキストで処理される可能性があります。
押下イベントとリリースイベントの両方がボタン用に選択されている場合(上記のlcBtnDnMaskフィールドを参照)、ボタンを押している間、インターフェースによって、コンテキストが暗黙的にすべてのタブレットイベントを捕捉します。この場合、コンテキスト外部で発生したイベントは、コンテキストにつなげられ、コンテキスト内で発生した場合と同様に処理されます。ボタンを離すと、コンテキストはボタンリリースイベントを受信し、イベント処理が通常に戻ります。
lcInOrgX、lcInOrgY、lcInOrgZ それぞれx、y、z軸に沿ったタブレットのネイティブ座標で、コンテキストの入力領域の原点を示します。コンテキストが開かれるか、変更されると、いずれもタブレットのネイティブ座標空間につなげられます。
lcInExtX、lcInExtY、lcInExtZ それぞれx、y、z軸に沿ったタブレットのネイティブ座標で、コンテキストの入力領域の範囲を示します。コンテキストが開かれるか、変更されると、いずれもタブレットのネイティブ座標空間につなげられます。
lcOutOrgX、lcOutOrgY、lcOutOrgZ それぞれx、y、z軸に沿ったコンテキストの出力座標で、コンテキストの出力領域の原点を示します。いずれも、絶対モードでのみ座標スケーリングに使用されます。
lcOutExtX、lcOutExtY、lcOutExtZ それぞれx、y、z軸に沿ったコンテキストの出力座標で、コンテキストの出力領域の範囲を示します。いずれも、絶対モードでのみ座標スケーリングに使用されます。
lcSensX、lcSensY、lcSensZ それぞれx、y、zの各軸に対する相対モード感度因子を示します。
lcSysMode システムカーソルトラッキングモードを示します。ゼロは絶対モード、ゼロ以外は相対モードを示します。
lcSysOrgX、lcSysOrgY システムカーソルトラッキング用の画面マッピング領域の原点を画面の座標で指定します。
lcSysExtX、lcSysExtY システムカーソルトラッキング用の画面マッピング領域の範囲を画面の座標で指定します。
lcSysSensX、lcSysSensY それぞれx、y、zの各軸に対するシステムカーソルの相対モード感度因子を示します。
コメント LOGCONTEXT構造体は、アプリケーションがどのイベントを取得するか、イベントがどのように処理されるか、イベントがどのようにアプリケーションまたはWindows自体に配信されるかを判別します。
タブレットコンテキストは、入力データのアプリケーションコントロールとワークステーションエルゴノミクスのユーザーコントロールとの間の緊張を反映したものです。コンテキストの一部の属性はユーザ、その他はアプリケーションによって制御されます。ロックの概念により、通常はユーザによって制御されている属性の一部をアプリケーションで制御できるようになります。ユーザは、タブレットコンテキストの入力領域(タブレットの物理的な場所)の原点を常に制御できます。ロック可能な属性は、アプリケーションの任意で、ユーザまたはアプリケーションのどちらかで制御されます。それ以外は、アプリケーションで制御されます。この処置により、プログラマはアプリケーションの複雑さを制御できます。これにより、ユーザは快適で効率的な方法でワークステーションを配置できます。
タブレットコンテキストは、入力ポイントのスケーリングを制御します。スケーリングは、WindowsのGDIインターフェースで提供されるスケーリング機能と同等の方法で機能します。タブレット入力領域は、GDIのMM_ANISOTROPICスケーリングモード用の式と同様の変換式を使用して、出力座標空間にマップされますつまり、入力コンテキスト全体が出力コンテキスト全体にマップされます。スケーリング変換は、GDIスケーリングと同様に、返された座標のユニットサイズ、原点、オフセット、軸の方向を変更できます。
システムカーソルスケーリングとトラッキングは、タブレットパケットスケーリングとトラッキングとは独立して制御できます。そのため、システムコンテキストは、ポーリングを使用し、補助タブレットデータを任意の形式で受信できます。絶対モードシステムカーソルコンテキストを、アプリケーション描画ウィンドウなど、画面のサブコンテキストにマップできます。この機能を使用すると、既存の変更されていないアプリケーションで絶対モードデータエントリおよび描画のスケーリングを利用できます。
軸ごとの正確なスケーリング式は次のとおりです。

Let:
 
In = 軸の入力値
Out = 軸の出力値
InOrg = 軸の入力原点(lcInOrgXなど)
InExt = 軸の入力範囲(lcInExtXなど)
OutOrg = 軸の出力原点(lcOutOrgXまたはlcSysOrgX など)
OutExt = 軸の出力範囲(lcOutExtXまたはlcSysExtX など)
入力値が0以上の場合、sign() は1を返し、
  それ以外の場合は-1を返します。
abs()は入力の絶対値を返します。
 
if sign(OutExt) == sign(InExt)
  Out = ((In - InOrg) * abs(OutExt) / abs(InExt)) + OutOrg
else
  Out = ((abs(InExt) - (In - InOrg)) * abs(OutExt) /
    abs(InExt)) + OutOrg
 
移動マスクおよびボタンマスクは、コンテキストによって処理されるイベントの種類を決定します。
参照 表7.11のコンテキストオプション値、表7.12のコンテキストステータス値、表7.13のコンテキストロック値。

表7.11.コンテキストオプション

意味
CXO_SYSTEM コンテキストがシステムカーソルコンテキストであることを示します。
CXO_PEN コンテキストがPen Windowsコンテキストであることを示します(Pen Windowsがインストールされている場合)。コンテキストもシステムカーソルコンテキストです。つまり、CXO_PENを指定すると、暗黙的にCXO_SYSTEMを指定したことになります。
CXO_MESSAGES コンテキストがWT_PACKETメッセージを所有者に返すことを示します。
CXO_MARGIN タブレットの入力コンテキストにマージンがあることを示します。マージンとは、指定されている入力領域外の領域です。イベントは、入力領域の端にマップされます。この機能により、コンテキストの端でポイントを入力しやすくなります。
CXO_MGNINSIDE CXO_MARGINビットがオンの場合、指定したコンテキスト内にマージンが来ることを示します。そのため、指定した入力コンテキストよりもやや小さなコンテキストから出力座標空間へのスケーリングが発生します。
CXO_CSRMESSAGES (1.1) コンテキストがWT_CSRCHANGEメッセージを所有者に返すことを示します。

表7.12. コンテキストステータス値

意味
CXS_DISABLED WTEnable関数を使用してコンテキストが無効化されていることを示します。
CXS_OBSCURED コンテキスト重複順序内で上にある重複コンテキストによって、少なくとも部分的にコンテキストが隠されていることを示します。
CXS_ONTOP コンテキストが、コンテキスト重複順序内で最上位のコンテキストであることを示します。

表7.13. コンテキストロック条件値

意味
CXL_INSIZE コンテキストの入力サイズを変更できないことを示します。この値を指定しなかった場合、コンテキストの入力範囲x、y、zを変更できます。注:コンテキストの原点x、y、zは常に変更できます。
CXL_INASPECT コンテキストの入力アスペクト比を変更できないことを示します。この値が指定された場合、コンテキストのサイズを変更できますが、x、y、z範囲の間の比率は可能な限り一定に保たれます。
CXL_MARGIN コンテキストのマージンオプションを変更できないことを示します。この値は、CXO_MARGINおよびCXO_MGNINSIDEオプション値のロックを制御します。
CXL_SENSITIVITY x、y、zに対するコンテキストの感度設定を変更できないことを示します。
CXL_SYSOUT コンテキストがシステムカーソルコンテキストの場合、値は、コンテキストのシステムポインティング制御変数を変更できないことを示します。

8.4. イベントデータ構造体

このセクションでは、イベントを返すために使用されるデータ構造体について説明します。定義には、パケット用の変数データ構造体、関連する構造体、および定数のファミリーが含まれます。

8.4.1. PACKET(1.1変更)

イベントパケットデータ構造体

説明 PACKETデータ構造体は、タブレットイベント情報を格納する柔軟な構造体です。各フィールドはオプションです。構造体は、パケットを生成したコンテキストのlcPktDataフィールドで選択されたデータ項目の連鎖で構成されています。データ項目の順序は、フィールド内の対応する設定ビットの順序と同じです。
pkButtonsデータ項目は、絶対モードと相対モードで異なる形式を持っています。これは、コンテキストのlcPktModeフィールドのPK_BUTTONSビットで決定されています。
下記のサンプル構造体は、lcPktDataフィールドの全定義ビットが設定され、lcPktModeフィールドが明らかになっている(すべての項目が絶対モードである)場合を示しています。
typedef struct tagPACKET {
        HCTX   pkContext;
        UINT   pkStatus;
        LONG   pkTime;
        WTPKT  pkChanged;
        UINT   pkSerialNumber;
        UINT   pkCursor;
        DWORD  pkButtons;
        DWORD  pkX;
        DWORD  pkY;
        DWORD  pkZ;
        UINT   pkNormalPressure;
        UINT   pkTangentPressure;
        ORIENTATION pkOrientation;
        ROTATION    pkRotation;  /* 1.1 */
} PACKET;
PACKETデータ構造体には、次の定義済みフィールドがあります。
フィールド 説明
pkContext イベントを生成したコンテキストを示します。
pkStatus さまざまなステータスとエラー条件を示します。この条件は、ビットOR演算子を使用して組み合わせることができます。pkStatusフィールドには、表7.14で定義されている値の任意の組み合わせを使用できます。
pkTime 絶対モードでは、イベントがポストされたシステム時間を示します。相対モードでは、最後のパケット以後の経過時間をミリ秒で指定します。
pkChanged 含まれているパケットデータ項目のうち、前回ポストされたイベント以降、どれが変更されたかを示します。
pkSerialNumber コンテキストによってパケットに割り当てられたシリアル番号が含まれます。連続パケットには、連続シリアル番号があります。
pkCursor パケットを生成したカーソルタイプを示します。
pkButtons 絶対モードでは、現在のボタンの状態を格納したDWORDです。相対モードでは、下位ワードにボタン番号、上位ワードに次のコードのいずれかを格納したDWORDです。
意味
TBN_NONE ボタンの状態に変化がありません。
TBN_UP ボタンを離しました。
TBN_DOWN ボタンを押しました。
pkX、pkY、pkZ 絶対モードでは、それぞれx、y、zの各軸に沿ってスケールされているカーソル位置を格納したDWORDです。相対モードでは、カーソル位置でスケールされている変更内容を格納したLONGです。
pkNormalPressure、pkTangentPressure 絶対モードでは、それぞれ筆圧およびエアブラシのホイールの調整済み状態を格納したUINTです。相対モードでは、調整済み押圧状態の変更内容を格納したintです。
pkOrientation 更新されたカーソル方向情報が含まれます。詳細については、セクション7.4.2のORIENTATIONデータ構造体の説明を参照してください。
pkRotation (1.1) 更新されたカーソル回転情報が含まれます。詳細については、セクション7.4.3のROTATIONデータ構造体の説明を参照してください。
コメント 拡張データ項目は、実装でサポートされている場合、PACKETデータ構造体に連結され、lcPktDataコンテキストフィールドの適切なマスクを使用して選択されます。拡張項目は、(符号なし比較を使用して)一意のタグの順序を増やしながら標準データ項目の後で連結されます。実装内では、拡張マスクがタグ順序で割り当てられます。拡張マスクの値は複数の実装で確実に同じにはならないものの、拡張のタグ(したがってPACKET構造体の中の拡張の順序)は必ず同じになります。
参照 参照 表7.14のパケットステータス値、セクション7.4.2のORIENTATION構造体、セクション7.4.3のROTATION構造体、セクション5.1.2のWTOpen関数、セクション7.3.1のLOGCONTEXTデータ構造体、表7.9の情報カテゴリーのWTI_EXTENSIONSグループ。

表7.14. パケットステータス値

意味
TPS_PROXIMITY カーソルがコンテキスト外にあることを示します。
TPS_QUEUE_ERR コンテキストのイベントキューがオーバーフローしたことを示します。
TPS_MARGIN カーソルがコンテキストのマージン内にあることを示します。
TTPS_GRAB カーソルがコンテキスト外にあるものの、ボタンリリースイベントを待機している間にコンテキストが入力を捕捉したことを示します。
TPS_INVERT (1.1) カーソルが反転状態にあることを示します。

8.4.2. ORIENTATION

カーソル方向記述子

説明 ORIENTATIONデータ構造体は、タブレットを基準にしたカーソルの方向を指定します¬。

typedef struct tagORIENTATION {
        int   orAzimuth;
        iint   orAltitude;
        iint   orTwist;
} ORIENTATION;

ORIENTATIONデータ構造体には、次のフィールドがあります。

フィールド 説明
orAzimuth z軸の周囲を時計回り方向にカーソルが完全な円を描いて回転することを示します。
orTwist 符号付き半円¬範囲でx-y平面との角度を示します。正の値はz軸の正(上)の方向の角度、負の値はz軸の負(下)の方向の角度を示します。
orTwist 独自の主軸の周囲を時計回り方向にカーソルが回転することを示します。
コメント 各カーソルタイプは、物理特性に基づいて、そのカーソルタイプ用に定義された主軸と「垂直方向」を持ちます。
参照 セクション7.4.1のPACKETデータ構造体定義。

8.4.3. ROTATION (1.1)

カーソル回転記述子

説明 ROTATIONデータ構造体は、タブレットを基準にしたカーソルの回転を指定します。

typedef struct tagROTATION {
        iint   roPitch;
        iint   roRoll;
        iint   roYaw;
} ROTATION;

ROTATIONデータ構造体には、次のフィールドがあります。

フィールド 説明
roPitch カーソルのピッチを示します。
roRoll カーソルのロールを示します。
roYaw カーソルの方位を示します。
コメント 各カーソルタイプは、物理特性に基づいて、そのカーソルタイプ用に定義された回転動作を持ちます。
参照 セクション7.4.1のPACKETデータ構造体定義。

付録A. PKTDEF.Hの使用

この付録では、ヘッダーファイルPKTDEF.HをC言語プログラムで使用する方法について説明します。

PKTDEF.HはWINTAB.Hの定義よって決まるので、プログラムは最初にWINTAB.Hをインクルードする必要があります。

プログラムが1つのパケット形式のみを使用する場合、PKTDEF.Hをインクルードする前に次の手順が必要になります。プログラムは、どのパケットデータ項目をインクルードするかを指定するためにPACKETDATA定数を定義し、どのパケットデータ項目を相対モードにするかを指定するためにPACKETMODE定数を定義する必要があります。どちらの定数も、ビットOR演算子と合わせたWTPKTビット(PK_*識別子)の組み合わせにする必要があります。生成された構造体typedefはPACKETと呼ばれます。PACKETDATA定数とPACKETMODE定数を使用し、LOGCONTEXT構造体のlcPktDataフィールドとlcPktModeフィールドに値を入力します。次の例#1を参照してください。

例#1.– 単一パケット形式

#include <wintab.h>
#define PACKETDATA   PK_X | PK_Y | PK_BUTTONS   /* x、y、ボタン */
#define PACKETMODE   PK_BUTTONS       /* ボタンの相対モード */
#include <pktdef.h>
...
  lc.lcPktData = PACKETDATA;
  lc.lcPktMode = PACKETMODE;

プログラムが複数のパケット形式を使用している場合、PKTDEF.Hは、異なる名前、データ項目、モードを持つ複数のパケット構造を生成できます。プログラムは、各パケット構造で1回ずつPKTDEF.Hをインクルードします。各PKTDEF.Hのインクルードの前に、定数PACKETNAMEを定義します。そのテキスト値は、このパケットのパラメータと名前のプレフィックスになります。次に、<name>PACKETDATAと<name>PACKETMODEを定義します。<name>は定義済みPACKETNAME定数の値です。最後に、PKTDEF.Hをインクルードし、<name>PACKETという構造体を定義します。次の例#2を参照してください。

例#2.– 複数の形式

#include &lt;wintab.h&gt;
#define PACKETNAME    MOE
#define MOEPACKETDATA   PK_X | PK_Y | PK_BUTTONS   /* x、y、ボタン */
#define MOEPACKETMODE   PK_BUTTONS       /* ボタンの相対モード */
#include &lt;pktdef.h&gt;
#define PACKETNAME    LARRY
#define LARRYPACKETDATA    PK_Y | PK_Z | PK_BUTTONS   /* y、z、ボタン */
#define LARRYPACKETMODE    PK_BUTTONS       /* ボタンの相対モード */
#include &lt;pktdef.h&gt;
#define PACKETNAME    CURLY
#define CURLYPACKETDATA    PK_X | PK_Z | PK_BUTTONS   /* x、z、ボタン */
#define CURLYPACKETMODE    PK_BUTTONS       /* ボタンの相対モード */
#include &lt;pktdef.h&gt;
...
  lcMOE.lcPktData = MOEPACKETDATA;
  lcMOE.lcPktMode = MOEPACKETMODE;
...
  lcLARRY.lcPktData = LARRYPACKETDATA;
  lcLARRY.lcPktMode = LARRYPACKETMODE;
...
  lcCURLY.lcPktData = CURLYPACKETDATA;
  lcCURLY.lcPktMode = CURLYPACKETMODE;

付録B. 拡張定義(1.4変更)

この付録では、拡張のプログラミングインターフェースの詳細について説明します。現在定義されているすべての拡張の定義が含まれます。

名前 タグ定数シンボル タグ定数値
Out of Bounds Tracking(境界外トラッキング) WTX_OBT 0
Cursor Mask(カーソルマスク) WTX_CSRMASK 3
Extended Button Masks(拡張ボタンマスク) WTX_XBTNMASK 4
Touch Strips(トラックパッド) WTX_TOUCHSTRIP 6
Touch Rings(タッチホイール) WTX_TOUCHRING 7
Express Keys(ファンクションキー) WTX_EXPKEYS2 8

注(1.4変更) – WTX_*値が表B.1に含まれていない場合は、サポートされていません。

B.1. 拡張プログラミング

各拡張には、そのインターフェースに対して複数の部位があり、タグと呼ばれる一意の識別番号があります。また、WTI_EXTENSIONS下で多重化された情報カテゴリーを備えています。また、パケットデータ項目を定義したり、WTExtGet, WTExtSet、WTMgrExt、WTMgrCsrExt関数のいずれか1つまたは複数に応答したりすることも可能です。

ヘッダーファイルWINTAB.Hには、現在定義されている拡張のタグ定義が含まれます。タグ識別子には、プレフィックス「WTX_」があります。

すべてのWintab実装がすべての拡張をサポートしているわけではないので、アプリケーションは、下記のような関数を使用して、拡張サポートを実行時に検出する必要があります。この関数は拡張のタグを受け取り、WTI_EXTENSIONSから情報カテゴリーオフセットを返します。

UINT ScanExts(UINT wTag)
{
  UINT i;
  UINT wScanTag;
 
  /* wTagの情報カテゴリーをスキャン。*/
  for (i = 0; WTInfo(WTI_EXTENSIONS + i, EXT_TAG, &amp;wScanTag); i++) {
     if (wTag == wScanTag) {
      /* WTI_EXTENSIONSからカテゴリーオフセットを返す。*/
      return i;
    }
  }
  /* エラーコードを返す。*/
  return 0xFFFF;
}

パケットデータ項目を持つ拡張には、複数の実装で割り当てられている同じWTPKTビットがありません。そのため、拡張パケットデータ項目は、PKTDEF.Hを制御するために、多少異なるスキームを使用します。こうした拡張ごとに、アプリケーションは、PKEXT_ABSOLUTEまたはPKEXT_RELATIVEの値を持つPACKETという定数を定義します。次の例では、アプリケーションは拡張「XFOO」のパケットデータ項目を追加します。

拡張のプログラミングノート

注:アプリケーションのメインウィンドウが非アクティブになったときに、アプリケーションがオーバーライドを削除することを推奨します(WM_ACTIVEを使用)。拡張のオーバーライドは、システム全体で有効になります。アプリケーションがオーバーライドをそのままにしておくと、別のアプリケーションで制御が正しく機能しません。
拡張イベントが発生すると、拡張パケットが作成され、コンテキストにキューイングされます。アプリケーションがメッセージを要求すると、WT_PACKETEXTメッセージがアプリケーションに送信されます。このメッセージは、キューを除けばWT_PACKETメッセージと同じです。提供されたコンテキストでアプリケーションがWTPacket関数を呼び出すと、PACKETEXTが返されます。このパケットには、EXTENSIONBASEデータ構造体およびPKTDEF.hのインクルード時にアプリケーションが要求したその他の構造体が含まれます。

B.2. Out of Bounds Tracking(境界外トラッキング)

WintabのOut of Bounds Tracking(OBT)拡張では、アクティブなタブレットコンテキストでカバーされていないエリアでカーソルトラッキングが可能です。通常、カーソルがアクティブな全コンテキストの外に移動すると、カーソルが再びコンテキストに入るまで、Wintabイベントアクティビティは停止します。Wintabは、こうした境界外イベントを単純に破棄します。OBTが有効になると、Wintabは境界外イベントを一部のコンテキスト(通常はカーソルが最後に離れたコンテキスト)に配信します。受信コンテキストは、イベントを座標範囲に留めます。通常、マウスのユーザが画面の縁から画面のカーソルを出そうとする場合と同じように、画面やウィンドウの縁に沿ってカーソルが動きます。

OBTロジックは、要求されていないイベントをいくつかの法則で送信します。モーションイベントを捕捉するコンテキストのみ(つまり、論理コンテキストlcMoveMaskフィールドにPK_X、PK_Y、またはPK_Zビットが設定されている場合にのみ)、境界外イベントを受信できます。権限のあるコンテキストは、イベントを処理すると、現在のOBTコンテキストになります。境界外イベントが発生すると、現在のOBTコンテキスト(存在する場合)がそのイベントを受信します。システム起動時、または、現在のOBTコンテキストが閉じられているか無効化されている場合、現在のOBTコンテキストは存在しません。この場合、境界外イベントは、コンテキストスタッキング順序で権限がある最初のコンテキストに送信されます。

OBTは、CXO_MARGINコンテキストオプションおよびCXO_MGNINSIDEコンテキストオプションで制御されているマージン機能と非常に似ています。実際、アプリケーションにとっては、境界外イベントはマージンイベントと区別が付きません。どちらも、それらのパケットのpkStatusフィールドにTPS_MARGINフラグが設定されます。

OBTプログラミング

OBT拡張では、デバイスごとにOBTの動作を有効化または無効化できます。Wintab対応プログラムは、OBTサポートを検出し、その現在の状態を読み取ることができます。Wintabマネージャープログラムは、任意のデバイスまたはすべてのデバイスに対してOBTをオンまたはオフにできます。OBTは、拡張タグ値ゼロを使用します。WINTAB.Hの更新バージョンは、定数WTX_OBTをゼロとして定義します。

情報カテゴリー

OBT情報カテゴリーはEXT_NAME、EXT_TAG、およびEXT_DEFAULTインデックスのみを実装します。カテゴリー内の他のインデックスを使用すると、WTInfoがゼロを返します。EXT_DEFAULTデータのサイズは、現在インストールされているWintabデバイスの数によって決まります。アプリケーションは、WTInfo関数のEXT_DEFAULTに対する戻り値、またはIFC_NDEVICES情報項目で指定されているデバイスの数を使用して、適切なバッファサイズを判定します。

表7.14. パケットステータス値

インデックス
EXT_NAME TCHAR[] NULL終端文字列の「Out of Bounds Tracking」(境界外トラッキング)
EXT_TAG UINT タグ値ゼロ
EXT_DEFAULT BOOL[] 各デバイスに1つのフラグの配列。対応するデバイスでOBTが有効化されている場合はゼロ以外です。

OBTのオンまたはオフ

Wintabマネージャープログラムは、WTMgrExt関数を使用してOBTをオンまたはオフにできます。渡されたデータバッファには、EXT_DEFAULT情報項目と同じ形式があります。

B.5. カーソルマスク

Wintab Cursor Mask(CSRMASK)拡張では、コンテキストがカーソルタイプに基づいて入力を選択できるようにします。この選択により、特に複数のアクティブカーソルをサポートするデバイスで、特定のカーソルに簡単に機能を割り当てられるようになります。

CSRMASKプログラミング

CSRMASKを使用する際の手順は、主に次の3つに分かれています。それらは、実行時のCSRMASKサポートの検出、コンテキストの作成、関数WTExtGetおよびWTExtSetを使用したコンテキストのカーソルマークの変更です。CSRMASKをサポートするアプリケーションは、タグ定数WTX_CSRMASK(3で定義)を持つWINTAB.Hの更新バージョンを使用する必要があります。Wintab Programmer’s KitのサンプルプログラムCSRMASKを参照してください。

CSRMASKを検出するには、WTI_EXTENSIONS情報カテゴリーをスキャンし、WTX_CSRMASKタグを持つものを探します。見つからなかった場合、CSRMASK拡張はサポートされていないので、アプリケーションはCSRMASKを使用しないはずです。CSRMASKがサポートされている場合、アプリケーションは、enableフラグの引数をFALSEに設定したWTOpen関数を使用し、WTExtSet関数で目的のCSRMASK値を設定し、最後にWTEnableでコンテキストを有効化する必要があります。

カーソルマスクデータは16バイトビットマップです。各ビットは対応するカーソルIDの入力選択を制御します。バイト0のビット0から7はカーソルIDの0から7に対応します。同様に、バイト1のビット0から7はカーソルIDの8から15に対応する、というように続いていきます。ビットの値1は、コンテキストがカーソルの入力を処理することを示します。値0は、コンテキストがそのカーソルを無視することを示します。

複数デバイス構成では、当該デバイスのカーソルIDはゼロから始まらない場合もあります。所定のデバイスの最初のカーソルIDは、デバイス情報カテゴリーのDVC_FIRSTCSR項目から使用可能になります。また、他のデバイスやカーソルタイプがインストールまたは削除されている場合、カーソルIDはセッション間で同一性を必ず保つわけではないので注意してください。カーソルタイプの永続機能バインディングは、デバイス名(DVC_NAME)と物理カーソルID(CSR_PHYSID)を使用して、セッション間のバインディングの安定性を保証します。

情報カテゴリー

CSRMASK情報カテゴリーは、下記の項目のみを実装します。

インデックス
EXT_NAME TCHAR[] NULL終端文字列「Cursor Mask」(カーソルマスク)
EXT_TAG UINT タグ値3。
EXT_DEFCONTEXT BYTE[16] デフォルトカーソルマスク。ビットはすべて1に設定されます。
EXT_DEFSYSCTX BYTE[16] デフォルトカーソルマスク。ビットはすべて1に設定されます。

B.6. Extended Button Masks(拡張ボタンマスク)

Wintab Extended Button Mask(XBTNMASK)拡張では、コンテキストが最大で256個のボタンの入力を完全に選択できるようにします。これは、多くのボタンを備えたロケータデバイスにも対応します。

XBTNMASKプログラミング

XBTNMASKを使用する際の手順は、主に次の3つに分かれています。それらは、実行時のXBTNMASKサポートの検出、コンテキストの作成、関数WTExtGetおよびWTExtSetを使用したコンテキストのカーソルマークの変更です。XBTNMASKをサポートするアプリケーションは、タグ定数WTX_XBTNMASK(4で定義)を持つWINTAB.Hの更新バージョンを使用する必要があります。

XBTNMASKを検出するには、WTI_EXTENSIONS情報カテゴリーをスキャンし、WTX_XBTNMASKタグを持つものを探します。見つからなかった場合、XBTNMASK拡張はサポートされていないので、アプリケーションはXBTNMASKを使用しないはずです。XBTNMASKがサポートされている場合、アプリケーションは、enableフラグの引数をFALSEに設定したWTOpen関数を使用し、WTExtSet関数で目的のXBTNMASK値を設定し、最後にWTEnableでコンテキストを有効化する必要があります。

ボタンマスクデータ構造体は、2つの32バイトビットマップで構成されています。各ビットは、対応するボタンの入力選択を制御します。バイト0のビット0から7はボタン0から7に対応します。同様に、バイト1のビット0から7はボタン8から15に対応する、というように続いていきます。ビットの値1は、コンテキストがボタンの入力を処理することを示します。値0は、コンテキストがそのボタンを無視することを示します。最初の32バイトマップはボタン押下イベントを、2番めの32バイトマップはボタンリリースイベントを制御します。ボタンマスクデータ構造体定義を次に示します。

typedef struct tagXBTNMASK {
  BYTE xBtnDnMask[32];
  BYTE xBtnUpMask[32];
} XBTNMASK;

これらの拡張ボタンマスクは、論理コンテキスト構造でボタンマスクを拡張しますが、それ以外の動作はlcBtnDnMaskおよびlcBtnUpMaskで説明したものと同じです。論理コンテキストマスクの値と拡張マスクの間の競合は、ビットAND演算でマスクの下位4バイトを組み合わせることで解決されます。以降のWTGetの呼び出しで返された拡張マスクと論理コンテキストマスクは更新されます。

情報カテゴリー

XBTNMASK情報カテゴリーは、下記の項目のみを実装します。

インデックス
EXT_NAME TCHAR[] NULL終端文字列「Extended Button Mask」(拡張ボタンマスク)
EXT_TAG UINT タグ値4
EXT_DEFCONTEXT XBTNMASK デフォルトマスク。ビットはすべて1に設定されます。
EXT_DEFSYSCTX XBTNMASK デフォルトマスク。ビットはすべて1に設定されます。
EXT_CURSORS BYTE[512] カーソルタイプごとのシステムおよび論理ボタンマップ。最初の256バイトはシステムボタンマップを、2番めの256バイトは論理ボタンマップを格納します。

B.7. Express Keys(ファンクションキー)拡張(1.4変更)

一部のタブレットは、タブレット面に物理キーを備えています。これらのキーをアプリケーションにエクスポーズし、キーを押したときに、アプリケーションがタスクを実行できるようにしてほしいという要望を受けました。
この拡張では、アプリケーションがファンクションキーイベント通知を受信し、ファンクションキーの通常のシステム全体の動作をオーバーライドできるようにします。実施例については、次のWindowsサンプルコードのTabletControlsSampleデモを参照してください。

http://wdnet.jp/library/windows
この拡張を使用するには、次のステップを実行します。

  1. この拡張をサポートしているWINTAB.HとPKTDEF.Hのバージョン(1.4以降)を持っていることを確認します。
    この拡張で下記の情報項目がサポートされます。

    • EXT_NAME – (TCHAR[])
      NULL終端文字列「ExpressKeys」
    • EXT_TAG – (UINT)
      タグ値WTX_EXPKEYS2
    • EXT_MASK – (WTPKT)
      拡張をアクティブ化するためにコンテキストを作成する際に使用されるマスク。
    • EXT_SIZE – (UINT[2])
      拡張パケットのデータ構造体のサイズ。
    • EXT_AXES – (AXIS[1])
      axMinが0、axMaxがすべてのボタンを押した場合に返される値、axResolutionが1、axUnitsがTU_NONEの軸構造。
  2. インストールされたドライバでExpress Key(ファンクションキー)拡張がサポートされているかどうかを実行時に検出します。これを実行するには、タグがWTX_EXPKEYS2と同じ拡張のWTI_EXTENSIONS情報カテゴリーをスキャンします。見つかったら、拡張がサポートされます。(詳細については、PKTDEF.Hを参照してください)
    // Wintab拡張インデックス内を検索
    for ( UINT i=0, thisTag = 0;
     WTInfo(WTI_EXTENSIONS+i, EXT_TAG, &amp;thisTag);
     i++)
    {
        // 指定したタグを検索
        if (thisTag == WTX_EXPKEYS2)
        {
       // 見つかったタグのインデックスに注目
       return i;
        }
    }
    return ERROR(&amp;quot;EXPKEYS2 not supported by this Wintab&amp;quot;);
    
    
  3. PKTDEF.Hをインクルードする前に下記の宣言を追加することで拡張パケット定義にExpress Keys(ファンクションキー)を追加します。
    #define PACKETEXPKEYS PKEXT_ABSOLUTE

    これにより、EXPKEYSDATA構造体がPACKETEXT構造体定義に含まれます。pkExpKeysとして追加されます。

    拡張で要求されたマスクおよびコンテキストのlcPktDataメンバーを持つマスクを取得します。

    // ファンクションキーの拡張マスクを取得
    WTInfo(WTI_EXTENSIONS + extIndex_ExpKeys, EXT_MASK, &amp;lExpKeys_Mask);
     
    ...
     
    lcContext.lcPktData = PACKETDATA | lExpKeys_Mask;
    

    これにより、EXPKEYSDATA構造体にデータを入れるようにドライバに指示します。

  4. WTExtGetコマンドで拡張データを要求することで、存在するキーを判別します。
    // バッファを割り当て
    BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)];
    // 拡張プロパティデータ構造にバッファをキャスト
    EXTPROPERTY *prop = (EXTPROPERTY*)buffer;
     
    // データを入力
    prop-&gt;version = 0;
    prop-&gt;tabletIndex = tablet_I;
    prop-&gt;controlIndex = control_I;
    prop-&gt;functionIndex = function_I;
    prop-&gt;propertyID = TABLET_PROPERTY_AVAILABLE;
    prop-&gt;reserved = 0;
    prop-&gt;dataSize = sizeof(BOOL);
     
    // コマンドをWintabに送信
    if (WTExtGet(ghCtx, ext_I, prop))
    {
        // 要求データを格納
        return *((BOOL*)(&amp;prop-&gt;data[0]));
    }
    
    

    WTExtGetは、EXTPROPERTY構造体を使用して、拡張に関するデータを受信します。

  5. WTExtSetを呼び出してファンクションキーの動作をオーバーライドします。

    // バッファを割り当て
    BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)];
    // 拡張プロパティデータ構造にバッファをキャスト
    EXTPROPERTY *prop = (EXTPROPERTY*)buffer;
     
    // データを入力
    prop-&gt;version = 0;
    prop-&gt;tabletIndex = tablet_I;
    prop-&gt;controlIndex = control_I;
    prop-&gt;functionIndex = function_I;
    prop-&gt;propertyID = TABLET_PROPERTY_OVERRIDE;
    prop-&gt;reserved = 0;
    prop-&gt;dataSize = sizeof(BOOL);
    *((BOOL*)(&amp;prop-&gt;data[0])) = TRUE;
     
    // コマンドをWintabに送信
    return !WTExtSet(ghCtx, ext_I, prop);
    
    

    WTExtSetコマンドで、ファンクションキーの名前をオーバーライドすることもできます。(プロパティの完全なリストについては、WINTAB.Hを参照してください)

B.8. Touch Strips(トラックパッド)およびTouch Rings(タッチホイール)拡張(1.4変更)

これらの拡張では、アプリケーションがトラックパッドおよびタッチホイールイベント通知を受信し、トラックパッドおよびタッチホイールの通常のシステム全体の動作をオーバーライドできるようにします。この拡張を使用するには、次のステップを実行します。

  1. この拡張をサポートしているWINTAB.HとPKTDEF.Hのバージョン(1.4以降)を持っていることを確認します。

    トラックパッド拡張では、下記の情報項目がサポートされます。

    • EXT_NAME – (TCHAR[])
      NULL終端文字列「TouchStrips」
    • EXT_TAG – (UINT)
      タグ値WTX_TOUCHSTRIP
    • EXT_MASK – (WTPKT)
      拡張をアクティブ化するためにコンテキストを作成する際に使用されるマスク。
    • EXT_SIZE – (UINT[2])
      拡張パケットのデータ構造体のサイズ。
    • XT_AXES – (AXIS[1])
      axMinが0、axMaxがすべてのボタンを押した場合に返される値、axResolutionが1、axUnitsがTU_NONEの軸構造。
  2. タッチホイール拡張では、下記の情報項目がサポートされます。
    • XT_NAME – (TCHAR[])
      NULL終端文字列「TouchRings」
    • EXT_TAG – (UINT)
      タグ値WTX_TOUCHRING
    • EXT_MASK – (WTPKT)
      拡張をアクティブ化するためにコンテキストを作成する際に使用されるマスク。
    • EXT_SIZE – (UINT[2])
      拡張パケットのデータ構造体のサイズ。
    • EXT_AXES – (AXIS[1])
      axMinが0、axMaxがタッチホイールのゾーンの数、axResolutionが1/axMax、axUnitsがTU_CIRCLEの軸構造。
  3. Pインストールされたドライバでこの拡張がサポートされているかどうかを実行時に検出します。これを実行するには、タグがWTX_TOUCHSTRIPおよびWTX_TOUCHRINGと同じ拡張のWTI_EXTENSIONS情報カテゴリーをスキャンします。見つかったら、拡張がサポートされます。(詳細については、PKTDEF.Hを参照してください)
    // Wintab拡張インデックス内を検索
    for ( UINT i=0, thisTag = 0;
     WTInfo(WTI_EXTENSIONS+i, EXT_TAG, &amp;thisTag);
     i++)
    {
        // 指定したタグを検索
        if (thisTag == WTX_TOUCHSTRIP)
        {
       // 見つかったタグのインデックスに注目
       return i;
        }
    }
    return ERROR(&amp;quot;TOUCHSTRIP not supported by this Wintab&amp;quot;);
    
  4. PKTDEF.Hをインクルードする前に下記の宣言を追加することで拡張パケット定義にExpress Keys(ファンクションキー)を追加します。

    #define PACKETTOUCHSTRIP PKEXT_ABSOLUTE
    #define PACKETTOUCHRING PKEXT_ABSOLUTE

    これにより、SLIDERDATA構造体がPACKETEXT構造体定義に含まれます。トラックパッド拡張はpkTouchStripを、タッチホイール拡張はpkTouchRingを追加します。

  5. 拡張で要求されたマスクを取得し、コンテキストのlcPktDataメンバーを持つマスクを追加します。

    // タッチストリップの拡張マスクを取得
    WTInfo(WTI_EXTENSIONS + extIndex_TouchStrip, EXT_MASK, &amp;lTouchStrip_Mask);
     
    // タッチリングの拡張マスクを取得
    WTInfo(WTI_EXTENSIONS + extIndex_TouchRing, EXT_MASK, &amp;lTouchRing_Mask);
     
    ...
     
    lcContext.lcPktData = PACKETDATA | lTouchStrip_Mask | lTouchRing_Mask;
    
    

    これにより、正しいSLIDERDATA構造体にデータを入れるようにドライバに指示します。

  6. WTExtGetコマンドで拡張データを要求することで、存在する機能を判別します。
    // バッファを割り当て
    BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)];
    // 拡張プロパティデータ構造にバッファをキャスト
    EXTPROPERTY *prop = (EXTPROPERTY*)buffer;
     
    // データを入力
    prop-&gt;version = 0;
    prop-&gt;tabletIndex = tablet_I;
    prop-&gt;controlIndex = control_I;
    prop-&gt;functionIndex = function_I;
    prop-&gt;propertyID = TABLET_PROPERTY_AVAILABLE;
    prop-&gt;reserved = 0;
    prop-&gt;dataSize = sizeof(BOOL);
     
    // コマンドをWintabに送信
    if (WTExtGet(ghCtx, ext_I, prop))
    {
        // 要求データを格納
        return *((BOOL*)(&amp;prop-&gt;data[0]));
    }
    
    

    WTExtGetは、EXTPROPERTY構造体を使用して、拡張に関するデータを受信します。

  7. WTExtSetを呼び出して機能の動作をオーバーライドします。
    // バッファを割り当て
    BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)];
    // 拡張プロパティデータ構造にバッファをキャスト
    EXTPROPERTY *prop = (EXTPROPERTY*)buffer;
     
    // データを入力
    prop-&gt;version = 0;
    prop-&gt;tabletIndex = tablet_I;
    prop-&gt;controlIndex = control_I;
    prop-&gt;functionIndex = function_I;
    prop-&gt;propertyID = TABLET_PROPERTY_OVERRIDE;
    prop-&gt;reserved = 0;
    prop-&gt;dataSize = sizeof(BOOL);
    *((BOOL*)(&amp;prop-&gt;data[0])) = TRUE;
     
    // コマンドをWintabに送信
    return !WTExtSet(ghCtx, ext_I, prop);
    
    

    WTExtSetコマンドで、機能の名前をオーバーライドすることもできます。(プロパティの完全なリストについては、WINTAB.Hを参照してください)

B.9. 拡張の構造(1.4変更)

EXPKEYSDATA構造体

typedef struct tagEXPKEYSDATA { /* 1.4 */
    BYTE    nTablet;    // タブレットのインデックス
    BYTE    nControl;   // コントロールの位置インデックス
    BYTE    nLocation;  // コントロールの位置
    BYTE    nReserved;  //
    DWORD   nState;     // コントロールの状態(1 - 押下、0 - リリース)
} EXPKEYSDATA;

この構造体はPACKETEXT構造体の一部として返されます。

SLIDERDATA構造体

typedef struct tagSLIDERDATA { /* 1.4 */
    BYTE    nTablet;    // タブレットのインデックス
    BYTE    nControl;   // コントロールの位置インデックス
    BYTE    nFunction;  // 制御関数インデックス
    BYTE    nReserved;  //
    DWORD   nPosition;  // コントロール上の指の位置(タッチがない場合はゼロ)
} SLIDERDATA;

この構造体はPACKETEXT構造体の一部として返されます。

EXTPROPERTY構造体

typedef struct tagEXTPROPERTY { /* 1.4 */
    BYTE    version;   // 構造体バージョン、現在は0
    BYTE    tabletIndex;    // 0から始まるタブレットのインデックス
    BYTE    controlIndex;   // 0から始まるコントロールのインデックス 
    BYTE    functionIndex;  // 0から始まるコントロールのサブ関数のインデックス
    WORD    propertyID;     // プロパティID
    WORD    reserved;  // DWORDアラインメントフィルタ
    DWORD   dataSize;  // data[]バッファのバイト数
    BYTE    data[1];   // 未処理データ
} EXTPROPERTY;

この構造体は、WTExtGetおよびWTExtSetに使用されます。
この構造体は可変サイズです。構造体の合計サイズはsizeof(EXTPROPERTY) + dataSizeです。この構造体を使用する前に、必ず適切なサイズのメモリを割り当ててください。

付録C. 追加機能(1.4変更))

C.1. 消しゴム

消しゴムの最も分かりやすい用途は、消去ツールとして使用することです。ただし、より高度なタスクを実行するように消しゴムの機能を変更できます。ペン先を消しゴムと組み合わせると、ドッジ(覆い焼き)とバーン(焼き込み)、インクとブリーチなど、と2つの相反する機能を簡単に実行できます。また、アプリケーションで選択したツールとして、独立して機能させることもできます。

消しゴムの使用を検出するには、いくつかの方法があります。

たとえば、パケットのpkOrientationデータで負のorAltitude値を探すというやり方があります。この方法を用いた場合は、傾斜値が(Wintab仕様で符号付きと指定されていても)符号なしで定義されているので注意してください。そのため、処理を適切に行うには、割り当てられた傾斜値をキャストする必要があります。

消しゴムを検出するもう1つの方法としては、カーソル番号2を探し、Dual Track(後で説明)の開発で、カーソル番号5も確認します。カーソル番号を確認するのは、デバイスが近接したとき1回です。WT_CSRCHANGEメッセージにより、新しいデバイスがいつ近接するかを検出できます。下位互換性のために、WT_PROXIMITYメッセージを処理する場合もあります。データパケットのカーソル番号(pkCursorフィールド)を必ず含めてください。この方法を使用する場合、デバイスごとのカーソルの数(WTInfo(WTI_INTERFACE, IFC_NCURSORS, &data)およびテストを実行するためのpkCursorフィールドによる係数をWintabに問い合わせます。

アプリケーションが消しゴムを検出できる3番目の方法は、パケットのpkStatusデータ項目のTPS_INVERTビットフィールドを参照することです。このフィールドは、Wintab 1.1仕様で追加されたものです。

C.2. 傾き検出

スタイラスの傾き検出にはいくつかの用途がありますが、最も明らかなのはブラシ形状の変化です。また、オブジェクトの回転に使用することも、ジョイスティックとして用いることもできます。
初期化のときに、次の方法で傾きの有無を確認できます。

// 傾きに関する情報を取得
struct tagAXIS tiltOrient[3];
BOOL tiltSupport = FALSE;
tiltSupport = WTInfo(WTI_DEVICES, DVC_ORIENTATION, &amp;tiltOrient);
if (tiltSupport )
{
    // タブレットは方位角と傾き角をサポートしているか 
    if (tiltOrient[0].axResolution &amp;&amp; tiltOrient[1].axResolution)
    {
   // 分解能を取得
   azimuth = tiltOrient[0].axResolution;
   altitude = tiltOrient[1].axResolution;
    }
    else
    {
   tiltSupport = FALSE;
    }
} 

傾きデータはpkOrientationパケット内にあります。

C.3. Dual Track

Dual Track(別名「マルチモード」)では、2台のデバイスを同時に追跡できます。UDIIシリーズ12 x 12以上では、スタイラスとパックを同時に追跡できます。サポートされている一部のIntuosタブレットでは、任意のデバイス2つを追跡できます。
注:Dual Trackは、UDII 12×12、Intuos、Intuos IIのみでサポートされているので注意してください。Intuos III以降はDual Trackをサポートしていません。
同時に2つのツールを操作すると、ユニークかつ多様な方法で、能力をより幅広く活用できます。両側から線を延長したり、片方の手でマスクを動かしながら、もう片方の手でその周囲にエアブラシを吹き付けたりするなどの作業が可能です。また、片手で拡大鏡を動かしながら、もう片方の手で拡大または非拡大画像を描画することもできます。Bier、Eric A.、Stone、Maureen C.、Pier、Ken、Buxton、William著による論文を参照してください。「Toolglass and Magic Lenses:The See-Through Interface」(ツールグラスとマジックレンズ:シースルー形式のインターフェース)Computer Graphics, (1993), 73-80またはビデオによる提案:A GUI Paradigm Using Tablets, Two Hands and Transparency(タブレットによるGUIパラダイム、2本の手と透過性)George Fitzmaurice、Thomas Baudel、Gordon KurtenbachおよびBill Buxton著、ACMによるCHI 97ビデオプログラム。
Dual Trackを実装する際に留意すべき事項がいくつかあります。

  1. 2つの画面カーソルをシステムで自動的に動かすことはできません。動かせるのは1つだけです。そのため、一方のデバイスではトラッキングをオンにし、もう一方ではオフにする(または両方ともオフにする)必要があります。少なくとも1つのデバイスに対して、独自の「画面カーソル」を動かす必要があります。
  2. メジャーハンドとマイナーハンドがあります。メジャーハンドは通常、利き手側として、より複雑なタスクを実行します。たとえば、メジャーハンドは描画し、マイナーハンドはマスクを持つというようにです。
  3. 競合を避けてください。アプリケーションは、2台のデバイスを互いに重ねて配置しなくても済むように、その2台のデバイスのオフセットを変更する(つまりタブレットを分割する)必要があります。

ポインティングデバイスには、0から5のインデックスが付けられます。アプリケーションは、パケットのpkCursorデータ項目を確認し、どのデバイスがパケットを生成したかを判別できます。指定可能なインデックス値は次のとおりです。

インデックス0 – パック形式のデバイス#1
インデックス1 – スタイラス形式のデバイス#1
インデックス2 – 反転スタイラス形式のデバイス#1
インデックス3 – パック形式のデバイス#2
インデックス4 – スタイラス形式のデバイス#2
インデックス5 – 反転スタイラス形式のデバイス#2

インデックスは、実際のポインティングデバイスのプレースホルダです。たとえば、初めてコンテキストに近接したとき、デバイスインデックス2は反転エアブラシの場合があります。デバイスインデックス2がコンテキストの近くにある限り、デバイスインデックス2は、この物理デバイスを同じ反転エアブラシとして一意に識別します。ただし、デバイス2が離れた後で、インデックス2のポインティングデバイスが近接したところをコンテキストが次に見つけると、インデックス2は反転ペンなど、別のデバイスを識別する可能性があります。

デフォルトでは、最初のデバイスに対してトラッキングがオンになります(pkCursor = 0、1、または2)。これは、近接する最初のデバイスです。近接する2番めのデバイスに対してトラッキングがオフになります(pkCursor = 3、4、または5)。そのため、デュアルトラッキングをサポートしないアプリケーションは、オフにした2番めのデバイスを仮想的に持つことになります。両方ともオンにされた場合、画面カーソルはそれらの間を行き来します。どのデバイスがどちらの手にあるかに基づき、場合によってはオンザフライで(WT_CSRCHANGEメッセージで)これを反転する必要があります。

データパケットのカーソル番号(pkCursorフィールド)を使用し、パケットストリームを2つ(0-2および3-5)に分割し、各デバイスに1つのストリームが割り当てられます。

C.4. Unique ID

Intuosシリーズにはもう1つ、Unique IDという新機能があります。一意の番号を持つチップが各スタイラスデバイス内にあるので、すべてのデバイスを一意に識別できます。Unique IDを使用すると、特定の描画ツールを特定のポインティングデバイスに割り当てることができます。または、このIDを使用して文書に「署名」することもできます。ドキュメントレイヤーへのアクセスを特定のデバイスに制限し、他のマシンへのデバイスに従う設定にすることができます。
デバイスのIDコードは2つのセクションに分かれています。この2つの組み合わせによって、確実に一意のデータになります。最初のセクションCSR_TYPEは、各デバイスタイプに固有の、一意のコードです。もう1つのセクションCSR_PHYSIDは、デバイスタイプ内の一意の32ビット番号です。CSR_PHYSIDは、デバイスタイプ内ではなく、デバイスタイプ間で反復可能です。

CSR_TYPEは符号化ビットフィールドです。一部のビットはハードウェアに対して特別な意味を持っていますが、開発者にとって意味のあるものではありません。
開発者にとって意味があるのは、次のとおりです。

合計で12ビットあります。

ビット1、2、8、9、10、11はデバイスを識別します。真ん中の4つのビット(4、5、6、7)は、色が異なる一般的なスタイラスなど、電気的に似ているものの、物理的には別のデバイスを区別するために使用します。そのため、特定のデバイスタイプを判別するために、0x0F06でマスクします。たとえば、0×0812は黒いスタイラス、0×0802はボックスに含まれた標準スタイラス、0×0832は1つのサイドスイッチを備えたスタイラスの場合があります。ビット0、3は内部で使用されるので、無視されます。
現在サポートされているタイプは次のとおりです。

一般的なスタイラス:(CSR_TYPE & 0x0F06) == 0×0802
エアブラシ:(CSR_TYPE & 0x0F06) == 0×0902
アートペン:(CSR_TYPE & 0x0F06) == 0×0804
4Dマウス:(CSR_TYPE & 0x0F06) == 0×0004
5ボタンカーソル:(CSR_TYPE & 0x0F06) == 0×0006

一意のIDを作成するには、CSR_TYPE(0x0F06によるマスキングなし)とCSR_PHYSIDを連結し、48ビット(おそらく64ビットを使用することになります)のシリアル番号を作成します。

C.5. エアブラシ Fingerwheel

Intuosシリーズタブレットには、エアブラシに近いデバイスがあります。このデバイスは、ペン先の筆圧をサポートしながら、側面のホイールで2番めの値を同時に変化させることができます。たとえば、ホイールでインクの濃さを変え、筆圧で線の太さを変えるなどの操作が可能になります。
エアブラシの側面のホイールの値はpkTangentPressure(接線の筆圧)フィールドでレポートされるので、パケットに必ず含めてください。値は0から1023の範囲です。1024をハードコード化しないでください。関数WTInfo(WTI_DEVICES, DVC_TPRESSURE)を使用すると、タブレットでサポートされている接線の筆圧範囲を照会できます。

C.6. 4D マウス回転

Intuosシリーズタブレットには、マウスに近いデバイスがあります。通常のマウスパラメータに加え、このマウスは軸回転と側面のサムホイールをサポートしています。たとえば、4Dマウス 回転では、用紙やオブジェクトを回転させ、サムホイールでズームできます。

4Dマウスの軸回転は、pkOrientation.orTwistフィールドでレポートされます。このフィールドの値は0から3599の範囲です。

初期化のときに、次の方法で回転の有無を確認できます。

// 回転に関する情報を取得
struct tagAXIS tiltOrient[3];
BOOL rotateSupport = FALSE;
rotateSupport = WTInfo(WTI_DEVICES, DVC_ORIENTATION, &amp;tiltOrient);
if (rotateSupport)
{
    // タブレットは湾曲をサポートしているか
    if (!tiltOrient[2].axResolution)
    {
   rotateSupport = FALSE;
    }
} 
同じデータ構造体にあるので、おそらく傾斜の確認と同時にこれを確認することになるでしょう。

C.7. 4D マウスサムホイール

4Dマウス サムホイールの使用には、ズームと3Dナビゲーションが含まれます。サムホイールの値は、pkZフィールドでレポートされます。サムホイールはpkZ = 1023からpkZ = -1023の範囲で変化し、ホイールを離すと、スナップして真ん中に戻ります。中心は0で、合計範囲はaxMinからaxMaxです。(レガシータブレットなど)タブレットが4D Mouseをサポートしていない場合、値axResolutionは0です。サムホイールは、どの用途に対しても十分に広い範囲があるわけではありません。範囲を広げる方法については、演習問題として残しておきます。
初期化のときに、次の方法でサムホイールの有無を確認できます。

// サムホイールに関する情報を取得
struct tagAXIS thumbwheelAxis;
BOOL thumbwheelSupport = FALSE;
thumbwheelSupport = WTInfo(WTI_DEVICES, DVC_Z, &amp;thumbwheelAxis);
if (thumbWheelSupport)
{
    // タブレットはサムホイールをサポートしているか
    if (!thumbwheelAxis.axResolution)
    {
   thumbwheelSupport = FALSE;
    }
}
Top