curs_mouse(3X) | curs_mouse(3X) |
名称
getmouse, ungetmouse, mousemask, wenclose, mouse_trafo, wmouse_trafo, mouseinterval - curses を介したマウスインタフェース書式
#include <curses.h>
typedef unsigned long mmask_t;
typedef struct
{
short id; /* 複数のデバイスを区別する ID */
int x, y, z; /* イベント座標 */
mmask_t bstate; /* ボタン状態ビット */
}
MEVENT;
int getmouse(MEVENT *event);
int ungetmouse(MEVENT *event);
mmask_t mousemask(mmask_t newmask, mmask_t *oldmask);
bool wenclose(const WINDOW *win, int y, int x);
bool mouse_trafo(int* pY, int* pX, bool to_screen);
bool wmouse_trafo(const WINDOW* win, int* pY, int* pX,
bool to_screen);
int mouseinterval(int erval);
解説
これらの関数は ncurses(3X) からのマウスイベントのインタフェースを提供します。マウスイベントは wgetch 入力ストリームで KEY_MOUSE 疑似キー値によって表わされます。マウスイベントを目に見えるようにするためには、 mousemask 関数を使用します。これはマウスイベントを報告させます。デフォルトでは、マウスイベントは報告されません。関数は、指定されたマウスイベントのどれを報告できるかを示すマスクを返します。完全な失敗の場合、0 を返します。 oldmask が NULL でない場合、この関数は、与えられたウィンドウのマウスイベントマスクの前の値で示された位置を入れます。
副作用として、0 の mousemask の設定はマウスポインタをオフにできます。 0 でないマスクの設定はそれをオンにできます。これが起こるかどうかは装置依存です。
次は、定義されるマウスイベントタイプマスクです:
名前 | 説明 |
BUTTON1_PRESSED | マウスボタン 1 ダウン |
BUTTON1_RELEASED | マウスボタン 1 アップ |
BUTTON1_CLICKED | マウスボタン 1 クリック |
BUTTON1_DOUBLE_CLICKED | マウスボタン 1 ダブルクリック |
BUTTON1_TRIPLE_CLICKED | マウスボタン 1 トリプルクリック |
BUTTON2_PRESSED | マウスボタン 2 ダウン |
BUTTON2_RELEASED | マウスボタン 2 アップ |
BUTTON2_CLICKED | マウスボタン 2 クリック |
BUTTON2_DOUBLE_CLICKED | マウスボタン 2 ダブルクリック |
BUTTON2_TRIPLE_CLICKED | マウスボタン 2 トリプルクリック |
BUTTON3_PRESSED | マウスボタン 3 ダウン |
BUTTON3_RELEASED | マウスボタン 3 アップ |
BUTTON3_CLICKED | マウスボタン 3 クリック |
BUTTON3_DOUBLE_CLICKED | マウスボタン 3 ダブルクリック |
BUTTON3_TRIPLE_CLICKED | マウスボタン 3 トリプルクリック |
BUTTON4_PRESSED | マウスボタン 4 ダウン |
BUTTON4_RELEASED | マウスボタン 4 アップ |
BUTTON4_CLICKED | マウスボタン 4 クリック |
BUTTON4_DOUBLE_CLICKED | マウスボタン 4 ダブルクリック |
BUTTON4_TRIPLE_CLICKED | マウスボタン 4 トリプルクリック |
BUTTON_SHIFT | ボタン状態変更中に shift はダウン |
BUTTON_CTRL | ボタン状態変更中に control (ctrl) はダウン |
BUTTON_ALT | ボタン状態変更中に alt はダウン |
ALL_MOUSE_EVENTS | ボタン状態変更をすべて報告 |
REPORT_MOUSE_POSITION | マウス移動を報告 |
一旦マウスイベントのクラスがウィンドウで目に見えるようになったならば、マウスイベントのインジケータとして KEY_MOUSE を返すことができるウィンドウで wgetch 関数の呼び出しはキューに入れられます。イベントデータを読み込み、かつキューからイベントをポップするためには、 getmouse を呼びます。この関数は、マウスイベントが与えられたウィンドウで実際に目に見える場合、 OK を返し、そうでなければ、 ERR を返します。 getmouse が OK を返す時、イベント構造体の座標で y と x として保管されたデータは、画面相対の文字セル座標になるでしょう。返された状態マスクは、イベントタイプを示すためにちょうど 1 ビット設定されます。
ungetmouse 関数は、 ungetch と同じように振る舞います。それは KEY_MOUSE イベントを入力キューにプッシュして、そのイベントと与えられた状態データおよび画面相対の文字セル座標を関連づけます。
wenclose 関数は、与えられた一組の画面相対の文字セル座標が、与えられたウィンドウで囲まれているかどうかをテストします。そうであれば TRUE を返し、そうでなければ FALSE を返します。それは、画面ウィンドウのサブセットがマウスイベントの位置を囲むかどうかを決定するのに役立ちます。
wmouse_trafo 関数は、stdscr-相対の座標から与えられたウィンドウ相対の座標へ、またはその逆に与えられた座標の組を変換します。 stdscr-相対の座標は、他の目的のために画面の最上部と最下部の行を保存するメカニズムのためにウィンドウ相対の座標と常に同じではないことを、思い出してください (例えば、 ripoffline() と slk_init 呼び出しを参照)。パラメータ to_screen が TRUE である場合、ポインタ pY、pX は、ウィンドウ win の内部の位置の座標を参照しなければなりません。それらは、ウィンドウ相対の座標に変換され、ポインタを通して返されます。変換が成功した場合、関数は TRUE を返します。パラメータの 1 つが NULL か、位置がウィンドウの内部でない場合、 FALSE が返されます。 to_screen が FALSE であるなら、ポインタ pY、pX はウィンドウ相対の座標を参照しなければなりません。ウィンドウ win がこの点 (ポイント) を囲む場合、それらは stdscr-相対の座標に変換されます。この場合、関数は TRUE を返します。パラメータの 1 つが NULL か、点 (ポイント) がウィンドウの内部でない場合、 FALSE が返されます。注意してください、変換が成功した場合、参照された座標は、変換された座標と取り替えられるだけです。
mouse_trafo 関数は、 win に stdscr を使用して、 wmouse_trafo と同じ変換を実行します。
mouseinterval 関数は、それらがクリックと認識されるために押して離す (press and release) イベント間に経過することができる mouseinterval(0) を使用して、クリックの分解能を無効にします。この関数は前のインターバル値を返します。それを変更することなしに、インターバルを得るためには mouseinterval(-1) を使用します。デフォルトは 6 分の 1 秒です。
入力が cooked モードである時マウスイベントが無視され、 cooked モードが、入力ループ終了のためのラインフィードを予期する getstr のような関数よってウィンドウでシミュレートされている時エラービープ音をもたらすことに注意してください。
戻り値
getmouse と ungetmouse は、失敗すると整数 ERR を返し、成功して終了すれば OK を返します。- getmouse
- マウスドライバが初期化されなかったか、またはマスクパラメータが 0 であるなら、エラーを返します。
- ungetmouse
- FIFO が満杯であるなら、エラーを返します。
mousemask は、報告可能なイベントのマスクを返します。
mouseinterval 端末が初期化されていないなら、前のインターバル値を返します。その場合には、最大のインターバル値 (166) を返します。
wenclose と wmouse_trafo はそれらの検査結果に依存して TRUE あるいは FALSE を返すブール関数です。
移植性
これらの呼び出しは ncurses(3X) のために設計されており、SVr4 curses、 4.4BSD curses または他の前のバージョンの curses には見つかりません。プリプロセッサがこれらの特徴が存在するかどうかをテストするために使用することができるように、目玉のマクロ NCURSES_MOUSE_VERSION は提供されます。インタフェースが変更される場合、 NCURSES_MOUSE_VERSION の値が増加させられます。 NCURSES_MOUSE_VERSION のためのこれらの値は、ncurses を設定するとき、指定されます:
- 1
- 予約されたイベントのための定義があります。マスクは 28 ビットを使用します。
- 2
- ボタン 5 のために定義を加えて、予約されたイベントのために定義を取り除きます。マスクは 29 ビットを使用します。
MEVENT 構造体メンバの順序は保証されません。追加のフィールドが構造体に今後加えられるかもしれません。
ncurses(3X) の下では、これらの呼び出しは xterm のビルトインのマウス追跡 API または次を含むプラットフォーム特有のドライバのいずれかを使用して実装されます。
利用者がサポートされない設定を使用していなら、マウスイベントは ncurses(3X) で目に見えるようになりません (そして mousemask 関数は、常に 0 を返します)。
terminfo エントリが XM 文字列を含んでいるなら、これは、端末がマウス操作のために初期化される方法を制御するために xterm マウスドライバで使用されます。 XM が見つけられないなら、デフォルトは、xterm のプライベートモード 1000 に対応しています:
イベント構造体中の z メンバは現在使用されません。それは、タッチ画面 (それらは感圧性かもしれません)、あるいは "3D-マウス/トラックボール/パワー"グローブで使用のために意図されます。
バグ
それらが mousemask によって利用可能になったなら、xterm の下のマウスイベントは cooked モードの間に実際は無視されないでしょう。代わりに、xterm マウス報告書シーケンスは文字列の読み込みに現われるでしょう。それらが様々なファンクションキーとして解釈されるので、xterm の下のマウスイベントはそのキーパッドビットオフのウィンドウで正確に検知されないでしょう。利用者の terminfo 記述は、 kmous を "\E[M" (マウスクリックのための xterm からの応答の始め) に設定するべきです。 kmous のための他の値は、許可されますが、同じ前提 (assumption) の下でです、すなわち、それは応答の始まりです。
xterm マウスプロトコルをサポートする端末を識別するのに役立つ、標準端末の応答がないので、利用者の $TERM 環境変数が "xterm"を含んでいるか、 kmous が端末 (terminal) 記述 (訳注: terminfo 記述の間違いか?) に定義される場合、端末はマウスイベントを送れることを ncurses は仮定します。