Wintab
本仕様は、オープン標準として開発されました。本書の内容は、補償やライセンスの制限なく自由に使用、複製、配布して構いません。
オリジナル版:copyright c 1991 by LCS/Telegraphics.
改訂版:copyright c 2010 by Wacom Technology Corp.
ご質問やご意見は下記までお送りください。
https://tablet.wacom.co.jp/business/contact/index.html
INDEX
- 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 概要
ここでは、ワコムタブレットの特長を生かすためのプログラミングを中心に、最低必要なAPIの使用方法について解説してみました。
この章ではWintab APIを使用するにあたり、どのようなプログラミング変更が必要か、また既にWintabに対応しているアプリケーションがワコムタブレットに対応するにはどのような注意点があるかを記述しています。
1.1 Wintabとは
Wintab APIはタブレットの持つ高精度の位置情報はもとより、デバイスの直感的な操作にかかる情報を効率よく伝え、創造的なアプリケーションに生かせるように設計されています。
1.2 Intuosシリーズ
Intuosシリーズでサポートするデバイスには、従来の筆圧ペンやカーソルの他に、エアブラシ、4Dマウスといったものがあります。筆圧の分解能も感度も優れたものになっています。
エアブラシの特長は、ペンのサイドにFingerwheelというホイールが付いていて、ここを回転させることにより筆圧、傾きの他にもう一つの情報がアプリケーションに伝えられます。
4Dマウスは従来のカーソルに似ていますが、これに加えてローテーション情報、ホイール情報が追加されています。ローテーション情報とはタブレット板面に垂直な軸に対する回転角度です。4Dマウスの向きを表わします。ホイール情報とは、4Dマウスのサイドに付いたホイールを前後に親指で回転させることで、この回転の度合いを伝えます。
将来的にはさらに用途にあったデバイスが投入される予定です。Intuosシリーズタブレットは将来的に投入されるデバイスについても対応できるように設計されています。
デバイスにID番号が記憶されている事も特長の一つです。デバイスの種別とデバイスごとに固有な32ビットのシリアル番号の組み合わせでできており、これらは重複することはありません。
1.3 アプリケーションの変更点
以下、新規でWintabに対応される場合を中心に解説します。タブレットの情報を取得するためには、次のようなプログラムの追加が必要になります。
※ []で示した数字は解説している章の番号を示します。
- アプリケーション起動時にWintabの初期化を行う
まず、WTInfo()関数で、タブレットが利用可能か確認します[2.2]。
同じくWTInfo()関数でタブレットの基本情報を取得、この基本情報を元にWTInfo()関数でアプリケーションに合ったタブレット環境を設定します[2.3]。タブレット情報はマウス情報に比べ情報量が多いのでWintabデータキューがオーバーフローする場合があります。そのためアプリケーションの処理内容にあわせ、適当なキューサイズをWTQueueSizeSet()関数で設定しておくこともできます。[5.6] - イベントハンドラ
タブレットのデータを取り込むタイミングが重要になります。デバイスの操作をすばやく取り込んでアプリケーションに生かすには、次のイベントメッセージを利用する方法があります。
- 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]
- WM_LBUTTONDOWN / WM_LBUTTONUP
- Wintabバージョンの識別
同じWintabを使っていても、ライブラリが古くて新しいIntuosシリーズの機能が使えない場合もあります。Wintabバージョンを識別しておくことをお勧めします。[5.7] -
コンテキストの切り替え
アプリケーション毎に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の存在確認
IF (!WTInfo(0, 0, NULL)) { エラー処理:WINTABが使用できない }
2.3 Wintabの初期化
データの流れを簡単な図で表わすと以下のようになります。
- システムカーソルを使用するかどうかの設定
システムを経由しないで(システムカーソルを表示しない)タブレットから情報を得る場合(これをデジタイジングコンキストと呼びます)と、システムカーソルを動かしながらタブレットの入力も行うモード(システムコンテキストと呼びます)の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);
- スケーリングの初期化について
以下のように、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 とすると、タブレットの操作範囲いっぱいに動かしても画面上では設定したピクセルの範囲でしかシステムカーソルは動作しません。 - 表示カーソルとの関係
デジタイジングコンテキストの場合、表示カーソルは動作しません。
マウスイベントは起こらないので、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 アクティブ化/非アクティブ化時の処理
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 パケットの宣言
#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 パケットの構成
———— ——– ————-
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)
Intuosシリーズタブレットでは、1つのタブレット上で任意のデバイスを一度に2つまで使えるマルチモードをサポートしているシリーズがあります。同じ種類のデバイスを使っている場合は、最初に使い始めたデバイスの種別番号は上記の通りですが、2番目に使い始めたデバイスには先の種別番号に3を加えた番号が返ってきます。例えば、ペンを2本使用している場合は最初のデバイスは1の番号を返し、2本目のデバイスには4の番号を返します。このようにして同じデバイスを使った場合にそれぞれのデータを混在して受け取っても、どちらのデバイスのデータかを識別する事が可能です。
4.4 ボタン情報 (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)
位置座標としては、2.3 Wintabの初期化の項で述べたように、タブレット入力領域の設定と出力値の設定で決まる数値が、デバイスの位置に従って出力されます。
PK_ZはX-Y平面に対して垂直方向の位置座標を表わすものですが、intuosシリーズタブレットでは4Dマウスのホイール操作で出力される値をこれに充てています。
4.6 筆圧情報の取得 (PK_NORMAL_PRESSURE)
(出力される数値の範囲は5.2節を参照してください)
4.7 エアブラシホイール情報の取得 (PK_TANGENT_PRESSURE)
4.8 傾き情報の取得 (PK_ORIENTATION) (PK_TANGENT_PRESSURE)
UINT orAzimuth; UINT orAltitude; UINT orTwist;
-
orAzimuthには傾きの方位が入ります。
X-Y平面に対して時計回りに360度までの方位であらわされます。 -
orAltitudeにはX-Y平面に対しての角度情報が入ります。
タブレット板面に対し垂直方向は90度、傾くに従い0度まで変化します。
消しゴムの情報はここでもわかります。ここには符号が付いているのですが、プラス符号なら通常のペン先、マイナス符号なら消しゴム側を示すようになっています。-90度は消しゴム側をタブレット面に垂直に立てた状態を表わし、ペンを傾けるに従い0度に近づきます。
4.9 回転情報の取得 (4Dマウス、アートペンのローテーション情報)
UDシリーズタブレットではサポートしていません。
Intuosシリーズでは、デバイスのタブレット面に垂直な軸に対する反時計回りの回転角度がここに入ります。
5 その他の情報
5.1 IntuosシリーズにおけるデバイスIDの求め方
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 イレーサの識別方法
(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 データの最大値、最小値の求めかた
以下に各種データの推移する範囲(レンジ)を求めるコーディング例を示します。
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 タブレット座標データの最大最小と分解能を知る
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 使っているタブレットで利用可能な座標指示器の種類を知る方法
簡単な例を示します。以下の例ではイレーサ付きペン(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の設定
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 パケットデータキューのサイズを変更する
パケットデータキューのサイズの変更方法を以下に示します。
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のバージョンを識別する
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関数LoadLibrary、FreeLibrary、およびGetProcAddressを使用して機能にリンクすることも、インポートライブラリを使用することもできます。
32ビットWintab固有の情報:関数WTInfo、WTOpen、WTGet、およびWTSetには、ANSIバージョンとUnicodeバージョンがあります。いずれも、Win32 APIで使用されている同じANSI/Unicode移植規約を使用しています。移植できない関数WTQueuePackets、WTMgrCsrPressureBtnMarksは、移植可能な新しい関数WTQueuePacketsEx、WTMgrCsrPressureBtnMarksExに置き換えられています。
表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. 基本的な関数
6.1.1. WTInfo
構文 | 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. 高度なパケットおよびキュー関数
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 メッセージリファレンス
下記のメッセージ名は、実際には、アプリケーション選択ベースからの固定オフセットを表します。インターフェース定義は、将来のメッセージ定義に備えて16のオフセットを保持しています。デフォルトメッセージベースは、16進数7FF0で定義したグローバル定数値WT_DEFBASEです。このデフォルト値は、多くのアプリケーションで妥当で安全なものですが、メッセージ名の競合を防ぐのは、アプリケーションプログラマの責任です。
32ビットWintab固有の情報:ほとんどのメッセージ引数の種類は32ビットWintabではより幅広くなっていますが、wParamからlParam(またはその反対)にジャンプしたメッセージ引数はありません。最も広い引数は現在、これまで未使用または使用不可だったスペースを占めています。WT_INFOCHANGEのカテゴリーおよびインデックス引数は広げられていないので注意してください。いずれも、まだ16ビットです。Wintab Programmer’s KitのヘッダーファイルWINTABX.Hには、16ビットでも32ビットでも使用できる、移植可能な「メッセージクラッカー」マクロが含まれています。
7.1. イベントメッセージ
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 データリファレンス
8.1. 一般的なデータ型(1.1変更、1.4変更)
表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. 情報変更メッセージ
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変更)
表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は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 <wintab.h> #define PACKETNAME MOE #define MOEPACKETDATA PK_X | PK_Y | PK_BUTTONS /* x、y、ボタン */ #define MOEPACKETMODE PK_BUTTONS /* ボタンの相対モード */ #include <pktdef.h> #define PACKETNAME LARRY #define LARRYPACKETDATA PK_Y | PK_Z | PK_BUTTONS /* y、z、ボタン */ #define LARRYPACKETMODE PK_BUTTONS /* ボタンの相対モード */ #include <pktdef.h> #define PACKETNAME CURLY #define CURLYPACKETDATA PK_X | PK_Z | PK_BUTTONS /* x、z、ボタン */ #define CURLYPACKETMODE PK_BUTTONS /* ボタンの相対モード */ #include <pktdef.h> ... 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. 拡張プログラミング
ヘッダーファイルWINTAB.Hには、現在定義されている拡張のタグ定義が含まれます。タグ識別子には、プレフィックス「WTX_」があります。
すべてのWintab実装がすべての拡張をサポートしているわけではないので、アプリケーションは、下記のような関数を使用して、拡張サポートを実行時に検出する必要があります。この関数は拡張のタグを受け取り、WTI_EXTENSIONSから情報カテゴリーオフセットを返します。
UINT ScanExts(UINT wTag) { UINT i; UINT wScanTag; /* wTagの情報カテゴリーをスキャン。*/ for (i = 0; WTInfo(WTI_EXTENSIONS + i, EXT_TAG, &wScanTag); i++) { if (wTag == wScanTag) { /* WTI_EXTENSIONSからカテゴリーオフセットを返す。*/ return i; } } /* エラーコードを返す。*/ return 0xFFFF; }
パケットデータ項目を持つ拡張には、複数の実装で割り当てられている同じWTPKTビットがありません。そのため、拡張パケットデータ項目は、PKTDEF.Hを制御するために、多少異なるスキームを使用します。こうした拡張ごとに、アプリケーションは、PKEXT_ABSOLUTEまたはPKEXT_RELATIVEの値を持つPACKET
拡張のプログラミングノート
拡張イベントが発生すると、拡張パケットが作成され、コンテキストにキューイングされます。アプリケーションがメッセージを要求すると、WT_PACKETEXTメッセージがアプリケーションに送信されます。このメッセージは、キューを除けばWT_PACKETメッセージと同じです。提供されたコンテキストでアプリケーションがWTPacket関数を呼び出すと、PACKETEXTが返されます。このパケットには、EXTENSIONBASEデータ構造体およびPKTDEF.hのインクルード時にアプリケーションが要求したその他の構造体が含まれます。
B.2. Out of Bounds Tracking(境界外トラッキング)
OBTロジックは、要求されていないイベントをいくつかの法則で送信します。モーションイベントを捕捉するコンテキストのみ(つまり、論理コンテキストlcMoveMaskフィールドにPK_X、PK_Y、またはPK_Zビットが設定されている場合にのみ)、境界外イベントを受信できます。権限のあるコンテキストは、イベントを処理すると、現在のOBTコンテキストになります。境界外イベントが発生すると、現在のOBTコンテキスト(存在する場合)がそのイベントを受信します。システム起動時、または、現在のOBTコンテキストが閉じられているか無効化されている場合、現在のOBTコンテキストは存在しません。この場合、境界外イベントは、コンテキストスタッキング順序で権限がある最初のコンテキストに送信されます。
OBTは、CXO_MARGINコンテキストオプションおよびCXO_MGNINSIDEコンテキストオプションで制御されているマージン機能と非常に似ています。実際、アプリケーションにとっては、境界外イベントはマージンイベントと区別が付きません。どちらも、それらのパケットのpkStatusフィールドにTPS_MARGINフラグが設定されます。
OBTプログラミング
情報カテゴリー
表7.14. パケットステータス値
インデックス | 値 |
EXT_NAME | TCHAR[] NULL終端文字列の「Out of Bounds Tracking」(境界外トラッキング) |
EXT_TAG | UINT タグ値ゼロ |
EXT_DEFAULT | BOOL[] 各デバイスに1つのフラグの配列。対応するデバイスでOBTが有効化されている場合はゼロ以外です。 |
OBTのオンまたはオフ
B.5. カーソルマスク
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)を使用して、セッション間のバインディングの安定性を保証します。
情報カテゴリー
インデックス | 値 |
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(拡張ボタンマスク)
XBTNMASKプログラミング
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の呼び出しで返された拡張マスクと論理コンテキストマスクは更新されます。
情報カテゴリー
インデックス | 値 |
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
この拡張を使用するには、次のステップを実行します。
- この拡張をサポートしている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の軸構造。
- EXT_NAME – (TCHAR[])
- インストールされたドライバでExpress Key(ファンクションキー)拡張がサポートされているかどうかを実行時に検出します。これを実行するには、タグがWTX_EXPKEYS2と同じ拡張のWTI_EXTENSIONS情報カテゴリーをスキャンします。見つかったら、拡張がサポートされます。(詳細については、PKTDEF.Hを参照してください)
// Wintab拡張インデックス内を検索 for ( UINT i=0, thisTag = 0; WTInfo(WTI_EXTENSIONS+i, EXT_TAG, &thisTag); i++) { // 指定したタグを検索 if (thisTag == WTX_EXPKEYS2) { // 見つかったタグのインデックスに注目 return i; } } return ERROR(&quot;EXPKEYS2 not supported by this Wintab&quot;);
- PKTDEF.Hをインクルードする前に下記の宣言を追加することで拡張パケット定義にExpress Keys(ファンクションキー)を追加します。
#define PACKETEXPKEYS PKEXT_ABSOLUTE
これにより、EXPKEYSDATA構造体がPACKETEXT構造体定義に含まれます。pkExpKeysとして追加されます。
拡張で要求されたマスクおよびコンテキストのlcPktDataメンバーを持つマスクを取得します。
// ファンクションキーの拡張マスクを取得 WTInfo(WTI_EXTENSIONS + extIndex_ExpKeys, EXT_MASK, &lExpKeys_Mask); ... lcContext.lcPktData = PACKETDATA | lExpKeys_Mask;
これにより、EXPKEYSDATA構造体にデータを入れるようにドライバに指示します。
- WTExtGetコマンドで拡張データを要求することで、存在するキーを判別します。
// バッファを割り当て BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)]; // 拡張プロパティデータ構造にバッファをキャスト EXTPROPERTY *prop = (EXTPROPERTY*)buffer; // データを入力 prop->version = 0; prop->tabletIndex = tablet_I; prop->controlIndex = control_I; prop->functionIndex = function_I; prop->propertyID = TABLET_PROPERTY_AVAILABLE; prop->reserved = 0; prop->dataSize = sizeof(BOOL); // コマンドをWintabに送信 if (WTExtGet(ghCtx, ext_I, prop)) { // 要求データを格納 return *((BOOL*)(&prop->data[0])); }
WTExtGetは、EXTPROPERTY構造体を使用して、拡張に関するデータを受信します。
-
WTExtSetを呼び出してファンクションキーの動作をオーバーライドします。
// バッファを割り当て BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)]; // 拡張プロパティデータ構造にバッファをキャスト EXTPROPERTY *prop = (EXTPROPERTY*)buffer; // データを入力 prop->version = 0; prop->tabletIndex = tablet_I; prop->controlIndex = control_I; prop->functionIndex = function_I; prop->propertyID = TABLET_PROPERTY_OVERRIDE; prop->reserved = 0; prop->dataSize = sizeof(BOOL); *((BOOL*)(&prop->data[0])) = TRUE; // コマンドをWintabに送信 return !WTExtSet(ghCtx, ext_I, prop);
WTExtSetコマンドで、ファンクションキーの名前をオーバーライドすることもできます。(プロパティの完全なリストについては、WINTAB.Hを参照してください)
B.8. Touch Strips(トラックパッド)およびTouch Rings(タッチホイール)拡張(1.4変更)
- この拡張をサポートしている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の軸構造。
- EXT_NAME – (TCHAR[])
- タッチホイール拡張では、下記の情報項目がサポートされます。
- 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の軸構造。
- XT_NAME – (TCHAR[])
- Pインストールされたドライバでこの拡張がサポートされているかどうかを実行時に検出します。これを実行するには、タグがWTX_TOUCHSTRIPおよびWTX_TOUCHRINGと同じ拡張のWTI_EXTENSIONS情報カテゴリーをスキャンします。見つかったら、拡張がサポートされます。(詳細については、PKTDEF.Hを参照してください)
// Wintab拡張インデックス内を検索 for ( UINT i=0, thisTag = 0; WTInfo(WTI_EXTENSIONS+i, EXT_TAG, &thisTag); i++) { // 指定したタグを検索 if (thisTag == WTX_TOUCHSTRIP) { // 見つかったタグのインデックスに注目 return i; } } return ERROR(&quot;TOUCHSTRIP not supported by this Wintab&quot;);
-
PKTDEF.Hをインクルードする前に下記の宣言を追加することで拡張パケット定義にExpress Keys(ファンクションキー)を追加します。
#define PACKETTOUCHSTRIP PKEXT_ABSOLUTE
#define PACKETTOUCHRING PKEXT_ABSOLUTEこれにより、SLIDERDATA構造体がPACKETEXT構造体定義に含まれます。トラックパッド拡張はpkTouchStripを、タッチホイール拡張はpkTouchRingを追加します。
-
拡張で要求されたマスクを取得し、コンテキストのlcPktDataメンバーを持つマスクを追加します。
// タッチストリップの拡張マスクを取得 WTInfo(WTI_EXTENSIONS + extIndex_TouchStrip, EXT_MASK, &lTouchStrip_Mask); // タッチリングの拡張マスクを取得 WTInfo(WTI_EXTENSIONS + extIndex_TouchRing, EXT_MASK, &lTouchRing_Mask); ... lcContext.lcPktData = PACKETDATA | lTouchStrip_Mask | lTouchRing_Mask;
これにより、正しいSLIDERDATA構造体にデータを入れるようにドライバに指示します。
- WTExtGetコマンドで拡張データを要求することで、存在する機能を判別します。
// バッファを割り当て BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)]; // 拡張プロパティデータ構造にバッファをキャスト EXTPROPERTY *prop = (EXTPROPERTY*)buffer; // データを入力 prop->version = 0; prop->tabletIndex = tablet_I; prop->controlIndex = control_I; prop->functionIndex = function_I; prop->propertyID = TABLET_PROPERTY_AVAILABLE; prop->reserved = 0; prop->dataSize = sizeof(BOOL); // コマンドをWintabに送信 if (WTExtGet(ghCtx, ext_I, prop)) { // 要求データを格納 return *((BOOL*)(&prop->data[0])); }
WTExtGetは、EXTPROPERTY構造体を使用して、拡張に関するデータを受信します。
- WTExtSetを呼び出して機能の動作をオーバーライドします。
// バッファを割り当て BYTE *buffer = new BYTE [sizeof(EXTPROPERTY) + sizeof(BOOL)]; // 拡張プロパティデータ構造にバッファをキャスト EXTPROPERTY *prop = (EXTPROPERTY*)buffer; // データを入力 prop->version = 0; prop->tabletIndex = tablet_I; prop->controlIndex = control_I; prop->functionIndex = function_I; prop->propertyID = TABLET_PROPERTY_OVERRIDE; prop->reserved = 0; prop->dataSize = sizeof(BOOL); *((BOOL*)(&prop->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. 消しゴム
消しゴムの使用を検出するには、いくつかの方法があります。
たとえば、パケットの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, &tiltOrient); if (tiltSupport ) { // タブレットは方位角と傾き角をサポートしているか if (tiltOrient[0].axResolution && tiltOrient[1].axResolution) { // 分解能を取得 azimuth = tiltOrient[0].axResolution; altitude = tiltOrient[1].axResolution; } else { tiltSupport = FALSE; } }
傾きデータはpkOrientationパケット内にあります。
C.3. Dual Track
注: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を実装する際に留意すべき事項がいくつかあります。
- 2つの画面カーソルをシステムで自動的に動かすことはできません。動かせるのは1つだけです。そのため、一方のデバイスではトラッキングをオンにし、もう一方ではオフにする(または両方ともオフにする)必要があります。少なくとも1つのデバイスに対して、独自の「画面カーソル」を動かす必要があります。
- メジャーハンドとマイナーハンドがあります。メジャーハンドは通常、利き手側として、より複雑なタスクを実行します。たとえば、メジャーハンドは描画し、マイナーハンドはマスクを持つというようにです。
- 競合を避けてください。アプリケーションは、2台のデバイスを互いに重ねて配置しなくても済むように、その2台のデバイスのオフセットを変更する(つまりタブレットを分割する)必要があります。
ポインティングデバイスには、0から5のインデックスが付けられます。アプリケーションは、パケットのpkCursorデータ項目を確認し、どのデバイスがパケットを生成したかを判別できます。指定可能なインデックス値は次のとおりです。
インデックス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
デバイスの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×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
エアブラシの側面のホイールの値はpkTangentPressure(接線の筆圧)フィールドでレポートされるので、パケットに必ず含めてください。値は0から1023の範囲です。1024をハードコード化しないでください。関数WTInfo(WTI_DEVICES, DVC_TPRESSURE)を使用すると、タブレットでサポートされている接線の筆圧範囲を照会できます。
C.6. 4D マウス回転
4Dマウスの軸回転は、pkOrientation.orTwistフィールドでレポートされます。このフィールドの値は0から3599の範囲です。
初期化のときに、次の方法で回転の有無を確認できます。
// 回転に関する情報を取得 struct tagAXIS tiltOrient[3]; BOOL rotateSupport = FALSE; rotateSupport = WTInfo(WTI_DEVICES, DVC_ORIENTATION, &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, &thumbwheelAxis); if (thumbWheelSupport) { // タブレットはサムホイールをサポートしているか if (!thumbwheelAxis.axResolution) { thumbwheelSupport = FALSE; } }