XGrabDeviceKey(3X11)

名前
 XGrabDeviceKey, XUngrabDeviceKey - 拡張入力デバイス・キーのグラブ/グラブ解放を行なう

書式
XGrabDeviceKey(display, device, Key, modifiers, modifier_device, grab_window, owner_events,
event_count, event_list, this_device_mode, other_devices_mode)
      Display *display;
      XDevice *device;
      unsigned int Key;
      unsigned int modifiers;
      XDevice *modifier_device;
      Window grab_window;
      Bool owner_events;
      unsigned int event_count;
      XEventClass event_list;
      int this_device_mode, other_devices_mode;

XUngrabDeviceKey(display, device, Key, modifiers, modifier_device, grab_window)
      Display *display;
      XDevice *device;
      unsigned int Key;
      unsigned int modifiers;
      XDevice *modifier_device;
      Window grab_window;

引き数

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

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

Key グラブあるいは解放するデバイスのボタンを指定する。 または AnyButton を指定する。

modifiers
    キーマスク値か AnyModifier を指定する。 マスク値は、有効なキーマスクビット値のビットごとの論理和を取ったもので ある。有効なビットは次のものである: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask.

modifier_device
    モディファイアが使用されるデバイスを指定する。modifier_device が NULL の場 合、X のキーボードが modifier_device として使用される。

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

owner_events
    デバイスのイベントを通常通り報告するか、イベントリストで選択されている ならばグラブウィンドウに関して報告するかを示す真偽値を指定する。

event_count
    イベントリストに含まれるイベント数を指定する。

event_list
    クライアントに報告するイベントを指定する。

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

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

説明
XGrabDeviceKey はパッシブなグラブを確立する。 後で以下の条件が全て満たされたならば、デバイスはアクティブにグラブされ (XGrabDevice の場合のように)、最終デバイスグラブ時刻にキーが押さ れた時刻がセットされ(DeviceKeyPress イベントで送られる)、 DeviceKeyPress イベントが報告される。

•   指定されたモディファイアデバイス上の指定されたモディファイアキーが論理 的に押されており、他のキーやモディファイアキーはどれも論理的に押されて いないとき、デバイスがグラブされておらず、指定されたキーが論理的に押さ れている。

•   grab_window がフォーカスウィンドウかその祖先ウィンドウである。あるいは、 grab_window がフォーカスウィンドウであり、このデバイスを含んでいる。

•   confine_window(もしあれば)が表示可能である。

•   同じキー/モディファイアの組合せにおけるパッシブなグラブが、grab_window のどの祖先ウィンドウ上にも存在しない。

残りの引き数の解釈は、XGrabDevice と同じである。 デバイス上の指定されたキーが論理的に離された状態になったとき、アクティ ブなグラブは自動的に終了する。

デバイスのプロセス処理が凍結されている場合、デバイスの論理的な状態(ク ライアントアプリケーションが見る)と物理的な状態の間にはずれがあるかも しれない点に注意すること。

キーが AnyKey でない場合、これは XListInputDevices リクエ ストが返す min_keycode と max_keycode で示される範囲の値でなければなら ない。そうでない場合には、エラー BadValue となる。

このリクエストは、同じクライアントによる同じウィンドウの同じキー/モディ ファイアの組合せに対する以前のグラブを上書きする。 モディファイアに AnyModifier を指定することは、可能なモディファ イアの組合せ全てに対してグラブリクエストを発行すること(モディファイア がない組合せも含む)と等価である。 指定された全てのモディファイアに対して、その時点で KeyCode が割り当て てられている必要は必ずしもない。 キーに AnyKey を指定することは、可能なキー全ての組合せに対してリ クエストを発行することと等価である。 指定されたキーがその時点で物理的なキーに割り当てられている必要はない。

値が NULL である modifier_device は、X のキーボードを modifier_device として使うことを指定する。

他のクライアントが、既に同じウィンドウ上で同じキー/モディファイアの組 合せに対して XGrabDeviceKey を発行していた場合は、エラー BadAccess となる。 AnyModifier あるいは AnyButton を用いた場合、互いに干渉する組合せが1つでもあれば、リクエストは完全に 失敗し、エラー BadAccess となる(いかなるグラブも確立されない)。 XGrabDeviceKey はアクティブなグラブに対しては無効である。

XGrabDeviceKey は、エラー BadAccess, BadClass, BadDevice, BadMatch, BadValue, BadWindow を起こすことがある。この関数はリクエストの正常終了時には Success を返す。

XUngrabDeviceKey リクエストは、指定したウィンドウ上のキー/モディファイアの組合せに対し て、このクライアントがその組合せをパッシブにグラブしていたならば、これ を解放する。 モディファイアに AnyModifier を指定することは、可能であるモディ ファイアの組合せの全てに対してグラブ解放のリクエストを発行することと等 価である。この組合せは、モディファイアがない組合せも含む。 キーに AnyButton を指定することは、可能であるキーの組合せの全て に対してリクエストを送ることと等価である。 XUngrabDeviceKey はアクティブなグラブに対しては無効である。

値が NULL である modifier_device は、modifier_device として X のキーボー ドを使うことを指定する。

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

返り値

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

BadMatch
    このエラーは、キーのないデバイスを指定して XGrabDeviceKey リクエ ストを行った場合や、キーを持たないモディファイアデバイスを指定した場合 に起こる。

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

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

関連項目
XAllowDeviceEvents(3X),
XGrabDevice(3X),
XGrabDeviceButton(3X),
Programming with Xlib