書式

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

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

cursor

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

display

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

event_mask

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

grab_window

グラブウィンドウを指定する。

keyboard_mode

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

owner_events

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

pointer_mode

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

time

時刻を指定する。 タイムスタンプか CurrentTime を指定できる。

説明

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

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

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

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

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

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

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

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

XGrabPointer はエラー BadCursor, BadValue, BadWindow を起こすことがある。

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

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

XChangeActivePointerGrab はエラー BadCursor, BadValue を起こすことがある。

返り値

BadCursor

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

BadValue

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

BadWindow

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