書式

int XGrabKeyboard(display, grab_window, owner_events, pointer_mode, keyboard_mode, time)

      Display *display;

      Window grab_window;

      Bool owner_events;

      int pointer_mode, keyboard_mode;

      Time time;

XUngrabKeyboard(display, time)

      Display *display;

      Time time;

引き数

display

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

grab_window

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

keyboard_mode

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

owner_events

キーボードイベントを通常通り報告するのかどうかを示す真偽値を指定する。

pointer_mode

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

time

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

説明

関数 XGrabKeyboard はキーボードの制御をアクティブにグラブし、 FocusIn イベントと FocusOut イベントを生成する。 以降のキーイベントはグラブを行っているクライアントにのみに報告される。 XGrabKeyboard はこのクライアントによる全てのアクティブなグラブを上書きする。 owner_events が False ならば、生成された全てのキーイベントは grab_window について報告される。 owner_events が True の場合は、生成されたキーイベントが通常はこのクライアントに報告されるは ずならば、このイベントは通常通りに報告される。そうでないならば、このイ ベントは grab_window について報告される。 KeyPress イベントと KeyRelease イベントのいずれも、クライアントによるイベント選択とは関係なく常に報告 される。

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

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

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

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

関数 XUngrabKeyboard は、このクライアントが XGrabKeyboard や XGrabKey によってアクティブなグラブを行っているならば、キーボードとキューに入っ ているイベントを解放する。 指定した時刻が最終キーボードグラブ時刻より早い場合や X サーバの 現在時刻よりも遅い場合には、 XUngrabKeyboard はキーボードとキューに入っているイベントの解放を行わない。 また、この関数は FocusIn イベントと FocusOut を生成する。 アクティブなキーボードグラブに対するイベントウィンドウが表示不可能にな ると、X サーバは自動的に UngrabKeyboard リクエストを行う。

返り値

BadValue

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

BadWindow

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