XGrabPointer

Syntax

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; 

Arguments

Description

If the pointer_mode is GrabModeAsync, pointer event processing continues as usual. If the pointer is currently frozen by this client, the processing of events for the pointer is resumed. If the pointer_mode is GrabModeSync, the state of the pointer, as seen by client applications, appears to freeze, and the X server generates no further pointer events until the grabbing client calls XAllowEvents() or until the pointer grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.
the pointer_mode が GrabModeAsync ならば、ポインタイベントの処理は通常通り継続される。 このクライアントがポインタを凍結している場合、 ポインタに関するイベントの処理は再開される。 pointer_mode が GrabModeSync ならば、ポインタの状態 (クライアントアプリケーションが見る) は凍結されていると考えられ、 グラブを行っているクライアントが XAllowEvents() を呼び出すか、 ポインタのグラブが解除されるまでは X サーバはこれ以上のポインタイベントを生成しない。 ポインタの実際の変化はポインタが凍結されている間も失われない。 これらは単にサーバのキューに入れられ、後で処理される。

If the keyboard_mode is GrabModeAsync, keyboard event processing is unaffected by activation of the grab. If the keyboard_mode is GrabModeSync, the state of the keyboard, as seen by client applications, appears to freeze, and the X server generates no further keyboard events until the grabbing client calls XAllowEvents() or until the pointer grab is released. Actual keyboard changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.
keyboard_mode が GrabModeAsync ならばキーボードイベントの処理はグラブのアクティブ化による影響は受けない。 keyboard_mode が GrabModeSync ならばキーボードの状態 (クライアントアプリケーションが見る) は凍結されていると考えられ、 グラブを行っているクライアントが XAllowEvents() を呼び出すか、 ポインタのグラブが解除されるまでは X サーバはこれ以上のキーボードイベントを生成しない。 実際のキーボードイベントの変化はポインタが凍結されている間も失われない。 これらは後で処理するために、 単にサーバのキューに入れられるだけである。

If a cursor is specified, it is displayed regardless of what window the pointer is in. If None is specified, the normal cursor for that window is displayed when the pointer is in grab_window or one of its subwindows; otherwise, the cursor for grab_window is displayed.
cursor が指定された場合、 このカーソルはポインタがどのウィンドウに入っていても表示される。 None が指定された場合は、 ポインタが grab_window やそのサブウィンドウの１つに入った時、 そのウィンドウの通常のカーソルが表示される。 それ以外の場合には grab_window のカーソルが表示される。

If a confine_to window is specified, the pointer is restricted to stay contained in that window. The confine_to window need have no relationship to the grab_window. If the pointer is not initially in the confine_to window, it is warped automatically to the closest edge just before the grab activates and enter/leave events are generated as usual. If the confine_to window is subsequently reconfigured, the pointer is warped automatically, as necessary, to keep it contained in the window.
confine_window が指定された場合は、ポインタはそのウィンドウ内に閉じ込められる。 confine_to は grab_window と関係を持っている必要はない。 最初の状態でポインタが confine_window に入っていない場合は、 グラブがアクティブ化される直前に ポインタがこのウィンドウの最も近い辺へと自動的に移動する。 この時 enter/leave イベントは通常通りに生成される。 その後に confine_to ウィンドウの構成が変えられた場合は、 ポインタはこのウィンドウに含まれたままになるように、 必要に応じて自動的に移動する。

The time argument allows you to avoid certain circumstances that come up if applications take a long time to respond or if there are long network delays. Consider a situation where you have two applications, both of which normally grab the pointer when clicked on. If both applications specify the timestamp from the event, the second application may wake up faster and successfully grab the pointer before the first application. The first application then will get an indication that the other application grabbed the pointer before its request was processed.
引き数 time を利用して、 クライアントはアプリケーションが応答するまでに長い間がかかる場合や、 ネットワークの遅延が大きい場合に生じる不具合を避けることができる。 例として、２つのアプリケーションがあり、 そのいずれもクリックされた時にポインタのグラブを普通に行うという状況を考える。 どちらのアプリケーションもイベントから得たタイムスタンプを指定していれば、 ２番目のアプリケーションは最初のアプリケーションよりも速く立ち上がり、 ポインタをうまくグラブできる。 最初のアプリケーションは、 自分のリクエストが処理される前に他のアプリケーションがポインタを グラブしたことを知らされる。

XGrabPointer() generates EnterNotify and LeaveNotify events.
XGrabPointer() は EnterNotify イベントと LeaveNotify を生成する。

Either if grab_window or confine_to window is not viewable or if the confine_to window lies completely outside the boundaries of the root window, XGrabPointer() fails and returns GrabNotViewable. If the pointer is actively grabbed by some other client, it fails and returns AlreadyGrabbed. If the pointer is frozen by an active grab of another client, it fails and returns GrabFrozen. If the specified time is earlier than the last-pointer-grab time or later than the current X server time, it fails and returns GrabInvalidTime. Otherwise, the last-pointer-grab time is set to the specified time (CurrentTime is replaced by the current X server time).
grab_window ウィンドウか confine_to ウィンドウが表示不可能である場合か、 confine_to ウィンドウがルートウィンドウの境界から完全に外に出ている場合には XGrabPointer() は失敗し、 GrabNotViewable を返す。 他のクライアントがポインタをアクティブにグラブしている場合、 この関数は失敗し、 AlreadyGrabbed を返す。 ポインタが他のクライアントのアクティブなグラブによって凍結されている場合は、 この関数は失敗して GrabFrozen を返す。 指定した時間が最終ポインタグラブ時刻より早い場合や X サーバの現在時刻より遅い場合には、 この関数は失敗して GrabInvalidTime を返す。 これ以外の場合には、 最終ポインタグラブ時刻には指定した時間がセットされる。 (CurrentTime は X サーバの現在時刻に置き換えられる)

XGrabPointer() can generate BadCursor, BadValue, and BadWindow errors.
XGrabPointer() はエラー BadCursor, BadValue, BadWindow を起こすことがある。

Diagnostics

See also