名称

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ポインタを拘束するウィンドウまたは None を指定します。

cursorグラブ中に表示されるカーソルまたは None を指定します。

displayX サーバへのコネクションを指定します。

event_maskクライアントにどのポインタイベントを通知するかを指定します。 マスクは、有効なポインタイベントのマスクビットの論理和です。

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

keyboard_mode
キーボードイベントの以後の処理を指定します。 GrabModeSync または GrabModeAsync を渡すことができます。

owner_events
イベントマスクで選ばれた場合にポインタイベントを通常どおりに 通知するか、またはグラブウィンドウに関して通知するかを示すブール値を 指定します。

pointer_mode
ポインタイベントの以後の処理を指定します。 GrabModeSync または GrabModeAsync を渡せます。

time時間を指定します。 タイムスタンプまたは CurrentTime を渡すことができます。

解説

XGrabPointer 関数は、ポインタの制御をアクティブにグラブし、グラブに成功したら GrabSuccess を返します。 それ以降のポインタイベントは、グラブしたクライアントだけに 通知されます。 XGrabPointer は、このクライアントによるアクティブなポインタグラブを無視します。 owner_events が False であれば、 すべてのポインタイベントは grab_window に関して通知され、 event_mask で選ばれた場合にだけ通知されます。 owner_events が True の場合、またポインタイベントが通常、このクライアントに通知される場合、 通常どおりに通知されます。 さもなければ、イベントは grab_window に関して通知され、 event_mask で選ばれた場合にだけ通知されます。 owner_events のどちらの値についても、通知されないイベントは 捨てられます。 pointer_mode が GrabModeAsync であれば、 ポインタイベント処理は通常どおり続行します。 ポインタが現在このクライアントによってフリーズされている場合、 ポインタのイベント処理は再開されます。 pointer_mode が GrabModeSync であれば、 ポインタの状態 (クライアントアプリケーションからみた) はフリーズし、 グラブしているクライアントが XAllowEvents をコールするまで、またはポインタグラブが解除されるまで、 X サーバはそれ以降いかなるポインタイベントも発生しません。 ポインタがフリーズされている間、 実際のポインタの変化は失われません。 これらは、後に処理するようサーバのキューに入れられるにすぎません。 keyboard_mode が GrabModeAsync であれば、 キーボードイベントの処理はグラブの動作に影響されません。 keyboard_mode が GrabModeSync であれば、 キーボードの状態 (クライアントアプリケーションからみた) は フリーズし、グラブするクライアントが XAllowEvents をコールするまで、またはポインタグラブが解除されるまで、 X サーバはそれ以降いかなるキーボードイベントも発生しません。 ポインタがフリーズされている間、実際のキーボードの変化は失われません。 これらは、後に処理するようサーバのキューに入れられるにすぎません。 cursor が指定された場合、どのウィンドウにポインタがあるかに関係なく、 指定されたカーソルが表示されます。 None が指定された場合、 ポインタが grab_window かまたはそのサブウィンドウのどれかにあるとき、 そのウィンドウの通常のカーソルが表示されます。 さもなければ、grab_window のカーソルが表示されます。 confine_to ウィンドウが指定された場合、 ポインタはそのウィンドウから外に出ないよう制限されます。 confine_to ウィンドウは、grab_window と関係がなくてもかまいません。 ポインタが最初 confine_to ウィンドウになければ、 グラブが動作する直前の最も近いエッジに自動的にワープされ、 enter/leave イベントは通常どおりに発生します。 confine_to ウィンドウがその後再構成される場合、 ポインタをウィンドウに入れておくため必要に応じてポインタは自動的に ワープされます。 time 引数により、アプリケーションが応答するのに時間がかかる場合 またはネットワーク遅延が長い場合に生ずるある種の状況を避けることが できます。 2 つのアプリケーションがあり、クリックオンされた場合に両方とも 通常ポインタをグラブする場合を考えてみます。 両方のアプリケーションがイベントからタイムスタンプを指定した場合、 2 番目のアプリケーションが最初のアプリケーションより前に起動し、 ポインタをグラブすることがあります。 次に、最初のアプリケーションは、リクエストが処理される前に 他のアプリケーションがポインタをグラブしたという情報を得ます。 XGrabPointer は、 EnterNotify および LeaveNotify イベントを発生します。 grab_window または confine_to ウィンドウが表示不可能な場合、 または confine_to ウィンドウが完全にルートウィンドウのボーダ外にある場合、 XGrabPointer は失敗し、 GrabNotViewable を返します。 ポインタが他のあるクライアントによってアクティブにグラブされた場合、 XGrabPointer は失敗し、 AlreadyGrabbed を返します。 別のクライアントのアクティブなグラブによってポインタがフリーズされた 場合、 XGrabPointer は失敗し、 GrabFrozen を返します。 指定された時間が最後のポインタグラブ時間より前かまたは 現在の X サーバの時間より後であれば、 XGrabPointer は失敗し、 GrabInvalidTime を返します。 さもなければ、最後のポインタグラブ時間は指定された時間に設定されます (CurrentTime は、現在の X サーバの時間に置換されます)。 XGrabPointer は、 BadCursor、 BadValue、 および BadWindow エラーを生じることがあります。 XUngrabPointer 関数は、このクライアントが XGrabPointer、 XGrabButton からまたは通常のボタンを押すことでポインタをアクティブにグラブした 場合、ポインタおよびキューに入れられたイベントを解除します。 指定された時間が最後のポインタグラブ時間の前か、または現在の X サーバの 時間より後であれば、 XUngrabPointer はポインタを解除しません。 また、 EnterNotify および LeaveNotify イベントを発生します。 アクティブなポインタグラブのイベントウィンドウまたは confine_to ウィンドウが viewable でなくなるか、 またはウィンドウ再構成によって confine_to ウィンドウが完全にルート ウィンドウのボーダ外にくると、X サーバは自動的に UngrabPointer リクエストを出します。 XChangeActivePointerGrab 関数は、ポインタがクライアントによってアクティブにグラブされた場合や 指定された時間が最後のポインタグラブ時間の後で、現在の X サーバの時間の 前の場合、指定された動的パラメータを変更します。 この関数は、 XGrabButton のパッシブパラメータに影響を与えません。 event_mask とカーソルの解釈は、 XGrabPointer で説明したのと同じです。 XChangeActivePointerGrab は、 BadCursor および BadValue エラーを生ずることがあります。

診断

BadCursor Cursor 引数の値が定義された Cursor を指さない。

BadValue ある数値が許容範囲を超えた。 引数の値の範囲が明示されない限り、引数のタイプによって決まる最大の 範囲まで指定可能です。 選択形式の引数も、このエラーを生じることがあります。

BadWindow
Window 引数の値が定義された Window を指しません。

関連事項

XAllowEvents(3X11), XGrabButton(3X11), XGrabKey(3X11), XGrabKeyboard(3X11)
Xlib − C Language X Interface

NEWS-OSRelease 4.2.1R