書式

int XGrabDevice(display, device, grab_window, owner_events, event_count, event_list,
this_device_mode, other_devices_mode, time)
Display *display;
XDevice *device;
Window grab_window;
Bool owner_events;
int event_count;
XEventClass *event_list;
int this_device_mode, other_devices_mode;
Time time;
XUngrabDevice(display, device, time)
Display *display;
XDevice *device;
Time time;

引き数

display

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

device

グラブあるいは解放されるデバイスを指定する。

grab_window

デバイスに対応するウィンドウのIDを指定する。

owner_events

デバイスからのイベントが通常通り報告させるか、グラブウィンドウについて 報告させるかを示す真偽値を指定する。

event_count

event_list 配列の要素数を指定する。

event_list

クライアントが受信しようとするイベントを指示する、イベントクラスへのリ ストを指定する。これらのイベントクラスは、グラブされるデバイスを指定して取 得していなければならない。

this_device_mode

このデバイスから受け取ったイベントの後処理を指定する。 GrabModeSync あるいは GrabModeAsync を指定する。

other_devices_mode

他のデバイスから受け取ったイベントの後処理を指定する。 GrabModeSync あるいは GrabModeAsync を指定する。

time

時刻を指定する。 タイムスタンプか CurrentTime のいずれかを指定する。

説明

XGrabDevice リクエストは、デバイスの制御をアクティブにグラブし、 DeviceFocusIn イベントと DeviceFocusOut イベントを生成する。 それ以降のデバイスのイベントは、グラブを行ったクライアントのみに報告さ れる。 XGrabDevice は、このクライアントによる全てのアクティブなデバイスのグラブを上書きす る。 event_list はイベントクラスのリストへのポインタである。このリストは、 グラブがアクティブである間にクライアントが受信しようとするイベントを指 定する。 owner_events が False である場合、生成された全てのデバイスイベントは、grab_window が選択して いればこのウィンドウについて報告される。 owner_events が True であり、生成されたデバイスイベントが通常はこのクライアントに報告される ような場合、このイベントは通常通り報告される。そうでない場合は、 grab_window について報告される。さらに、event_list で指定されている場 合は、このイベントだけが報告される。

引き数 this_device_mode が GrabModeAsync ならば、デバイスイベントの処理は通常通り続けられる。 デバイスが現在このクライアントによって凍結されている場合は、その後にデ バイスイベントの処理が再開される。 引き数 this_device_mode が GrabModeSync ならば、デバイスの状態(クライアントアプリケーションから見たもの)は凍結 されていると考えられ、X サーバはそれ以降のデバイスイベントを生成しなく なる。これは、グラブを行っているクライアントが XAllowDeviceEvents の呼び出しによる解放を行うか、デバイスのグラブが解放されるまで続く。 デバイスが凍結されている間も、実際のデバイスの変化は失われない。後で処 理するために、X サーバは単にこれらの変化をキューに入れておく。

other_devices_mode が GrabModeAsync ならば、他のデバイスから受け取ったイベントの処理は、グラブのアクティブ 化による影響を受けない。 other_devices_mode が GrabModeSync ならば、グラブされているデバイスを除く全てのデバイスの状態(クライアン トアプリケーションから見たもの)は凍結されていると考えられ、X サーバは それ以降これらのデバイスからのイベントを生成しなくなる。 これは、グラブを行っているクライアントが XAllowDeviceEvents によって解放を行うか、デバイスのグラブが解放されるまで続く。 デバイスが凍結されている間も、実際のイベントは失われない。後で処理する ために、X サーバは単にこれらの変化をキューに入れておく。

他のクライアントがデバイスをアクティブにグラブしている場合、 XGrabDevice は失敗し、 AlreadyGrabbed を返す。 grab_window が表示可能でない場合もこの関数は失敗し、 GrabNotViewable を返す。 デバイスが他のクライアントのアクティブなグラブによって凍結されている場 合、この関数は失敗し GrabFrozen を返す。 指定された時刻が最終デバイスグラブ時刻よりも早い場合や、X サーバの現在 の時刻よりも遅い場合は、この関数は失敗し、 GrabInvalidTime を返す。 これら以外の場合には、最終デバイスグラブ時刻には指定された時刻がセット される( CurrentTime は X サーバの現在時刻に置き換えられる)。

クライアントによるアクティブがグラブが有効な状態で、このクライアントが このデバイスを閉じた場合、アクティブがグラブは解放される。デバイスが要 求しているクライアントのアクティブなグラブによって凍結されている場合、 凍結は解除される。

XGrabDevice は、エラー BadClass, BadDevice, BadValue, BadWindow を起こすことがある。

XUngrabDevice リクエストは、クライアントが XGrabDevice や XGrabDeviceKey を使ってデバイスをアクティブにグラブしていた場合、このデバイスとキュー に入っているイベントを解放する。 他のデバイスがこのグラブによって凍結されている場合、 XUngrabDevice は凍結を解除する。 指定した時刻が最終デバイスグラブ時刻より早い場合や、X サーバの現在時刻 よりも遅い場合には、 XUngrabDevice はデバイスやキューに入っているイベントを解放しない。 このリクエストは DeviceFocusIn イベントと DeviceFocusOut イベントを生成する。 デバイスのアクティブなグラブに対するイベントウィンドウが表示可能でなく なった場合、X サーバは自動的に UngrabDevice リクエストを出す。

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

返り値

BadDevice

不正なデバイスが指定された。指定されたデバイスが存在しないか、クライア ントの XOpenInputDevice によってオープンされていない。このエラー は、指定されたデバイスが X のキーボードデバイスや X のポインタデバイス である場合にも起こる。

BadValue

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

BadWindow

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