XGrabPointer(3X11)

名前
XGrabPointer, XUngrabPointer, XChangeActivePointerGrab - ポインタのグラブ

書式
int XGrabPointer(display, grab_window, owner_events, event_mask, pointer_mode,
               keyboard_mode, confine_to, cursor, time)
      Display *display;
      Window grab_window;
      Bool owner_events;
      unsigned int event_mask;
      int pointer_mode, keyboard_mode;
      Window confine_to;
      Cursor cursor;
      Time time;

XUngrabPointer(display, time)
      Display *display;
      Time time;

XChangeActivePointerGrab(display, event_mask, cursor, time)
      Display *display;
      unsigned int event_mask;
      Cursor cursor;
      Time time;

引き数

confine_to
    ポインタを閉じ込めるウィンドウか を指定。

cursor
    グラブの間に表示されるカーソルか を指定。

display
    X サーバへの接続を指定。

event_mask
    どのポインタイベントをクライアントに通知するか指定。 マスク値は正しいポインタイベントのマスクビット値のビットごとの論理和を 取ったものである。

grab_window
    グラブウィンドウを指定。

keyboard_mode
    キーボードイベントの後処理を指定。 あるいは を指定する。

owner_events
    イベントマスクで選択している場合、ポインタイベントを通常通り通知するか、 グラブウィンドウに関して通知するかを示す真偽値を指定。

pointer_mode
    ポインタイベントの後処理を指定。 あるいは を指定する。

time
    時刻を指定。 タイムスタンプか を指定。

説明
関数 はポインタの制御をアクティブにグラブし、これに成功した場合に を返す。 以降のポインタイベントはグラブを行ったクライアントに対してのみ通知され る。 はこのクライアントによる全てのアクティブなポインタのグラブを無視する。 owner_events が ならば、生成された全てのポインタイベントは、イベントマスクによって選択 されている場合に限り、grab_window に関して通知される。 owner_events が であり、ポインタイベントが通常はこのクライアントに通知されるはずならば、 このイベントは通常通り通知される。 そうでない場合は、このイベントはイベントマスクによって選択されている場 合に限って grab_window に関して通知される。 owner_events のそれぞれの値について、通知されなかったイベントは破棄さ れる。

the pointer_mode が ならば、ポインタイベント処理は通常通り継続される。 ポインタがこのクライアントによって凍結されている場合、ポインタに関する イベントの処理は再開される。 pointer_mode が ならば、ポインタの状態(クライアントアプリケーションが見る)は凍結されて いると考えられ、グラブを行っているクライアントが を呼び出すか、ポインタのグラブが解放されるまでは X サーバはこれ以上の ポインタイベントを生成しない。 実際のポインタの変化はポインタが凍結されている間も失われない。これらは 単にサーバのキューに入れられ、後で処理される。

keyboard_mode が ならば、キーボードイベントの処理はグラブのアクティブ化による影響は受け ない。 keyboard_mode が ならば、キーボードの状態(クライアントアプリケーションが見る)は凍結され ていると考えられ、グラブを行っているクライアントが を呼び出すか、ポインタのグラブが解放されるまでは X サーバはこれ以上の キーボードイベントを生成しない。 実際のキーボードイベントの変化はポインタが凍結されている間も失われない。 これらは後で処理するために、単にサーバのキューに入れられるだけである。

cursor が指定された場合、このカーソルはポインタがどのウィンドウに入っ ていても表示される。 が指定された場合は、ポインタが grab_window やそのサブウィンドウの1つに 入った時にはそのウィンドウの通常のカーソルが表示される。 それ以外の場合には、grab_window のカーソルが表示される。

confine_window が指定された場合は、ポインタはそのウィンドウ内に閉じ込 められる。 confine_to は grab_window と関係を持っている必要はない。 ポインタが最初から confine_window に入っていない場合は、 グラブがアクティブ化され、enter/leave イベントが通常通りに生成される直 前に、ポインタはこのウィンドウの最も近い辺へと自動的に移動する。 その後に confine_to ウィンドウの構成が変えられた場合は、ポインタはこの ウィンドウに含まれたままになるように、必要に応じて自動的に移動する。

引き数 time を利用して、クライアントはアプリケーションが応答するまでに長 い間がかかる場合や、ネットワークの遅延が大きい場合に生じる不具合を避け ることができる。 例として、2つのアプリケーションがあり、そのいずれもクリックされた時に ポインタのグラブを普通に行うという状況を考える。 どちらのアプリケーションもイベントから得たタイムスタンプを指定していれ ば、2番目のアプリケーションは最初のアプリケーションよりも速く立ち上が り、ポインタのグラブに成功することができる。 最初のアプリケーションは、自分のリクエストが処理される前に他のアプリケー ションがポインタをグラブしたことを知らされることができる。

は イベントと を生成する。

grab_window ウィンドウか confine_to ウィンドウが表示不可能である場合か、 confine_to ウィンドウがルートウィンドウの境界の完全な外側にある場合に は は失敗し、 を返す。 ポインタが他のクライアントによってアクティブにグラブされている場合、こ の関数は失敗し、 を返す。 ポインタが他のクライアントのアクティブなグラブによって凍結されている場 合は、この関数は失敗し、 を返す。 指定した時間が最終ポインタグラブ時刻より早い場合やXサーバの現在時刻よ り遅い場合には、この関数は失敗し、 を返す。 これ以外の場合には、最終ポインタグラブ時刻には指定した時間がセットされ る は X サーバの現在時刻に置き換えられる)。

はエラー を起こすことがある。

関数 は、このクライアントが 関数の呼び出しや普通にボタンを押したことでポインタをアクティブにグラブ している場合、ポインタとキューに入っているイベントを解放する。 指定した時刻が最終ポインタグラブ時刻より早い場合や、Xサーバの現在時刻 よりも遅い場合には、 はポインタの解放を行わない。 この関数は イベントと イベントを生成する。 アクティブなグラブに対するイベントウィンドウや confine_to ウィンドウが 表示不能になった場合や、ウィンドウの構成の変化によって confine_to ウィ ンドウがルートウィンドウの境界の完全な外側になった場合は、X サーバは リクエストを自動的に実行する。

関数 は、クライアントがポインタがアクティブにグラブしていて、指定した時刻が 最終ポインタグラブ時刻よりも早くなく、Xサーバの現在時刻よりも遅くない 場合に、指定した動的なパラメータを変更する。 この関数は のパッシブなパラメータに対しては無効である。 引き数 event_mask と cursor の解釈は での説明と同じである。

はエラー を起こすことがある。

返り値

引き数 Cursor の値が、定義されている Cursor を指していない。

指定された数値に、リクエストの許容範囲を越えているものがある。引き数に対
    して特定の範囲が指定されていなければ、引き数の型で定義されている全ての範 囲が許される。選択肢として定義されている引き数はこのエラーを起こすことが ある。

引き数 Window の値が、定義されている Window を指していない。

関連項目
XAllowEvents(3X11), XGrabButton(3X11), XGrabKey(3X11), XGrabKeyboard(3X11)
Xlib - C Language X Interface