書式

XGrabDeviceButton(display, device, button, modifiers, modifier_device, grab_window,
owner_events, event_count, event_list, this_device_mode, other_devices_mode)
Display *display;
XDevice *device;
unsigned int button;
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;
XUngrabDeviceButton(display, device, button, modifiers, modifier_device, grab_window)
Display *display;
XDevice *device;
unsigned int button;
unsigned int modifiers;
XDevice *modifier_device;
Window grab_window;

引き数

display

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

device

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

button

グラブあるいは解放するデバイスのボタンを指定する。 または 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 を指定する。

説明

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

• 指定されたモディファイアデバイス上の指定されたモディファイアキーが論理 的に押されており、他のボタンやモディファイアキーはどれも論理的に押され ていないとき、デバイスがグラブされておらず、指定されたボタンが論理的に 押されている。
• grab_window がフォーカスウィンドウかその祖先ウィンドウである。あるい は、grab_window がフォーカスウィンドウであり、デバイスを含んでいる。
• 同じボタン/モディファイアの組合せにおけるパッシブなグラブが grab_window のどの祖先ウィンドウ上にも存在しない。

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

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

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

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

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

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

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

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

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

返り値

BadDevice

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

BadMatch

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

BadValue

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

BadWindow

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