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