XGrabKey()XGrabKey()NameXGrabKey – grab a key.
Synopsis
XGrabKey(display, keycode, modifiers, grab_window, owner_events,
pointer_mode, keyboard_mode)
Display *display;
int keycode;
unsigned int modifiers;
Window grab_window;
Bool owner_events;
int pointer_mode, keyboard_mode;
Arguments
display Specifies a connection to an X server; returned from
XOpenDisplay().
keycode Specifies the keycode to be grabbed. It may be a modifier
key. Specifying AnyKey is equivalent to issuing the request
for all key codes.
modifiers Specifies a set of keymasks. This is a bitwise OR of one or
more of the following symbols: ShiftMask, LockMask, Control‐
Mask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or
AnyModifier. AnyModifier is equivalent to issuing the grab
key request for all possible modifier combinations (including
no modifiers). All specified modifiers do not need to have
currently assigned keycodes.
grab_window
Specifies the window in which the specified key combination
will initiate an active grab.
owner_events
Specifies whether the grab window should receive all events
(False) or whether the grabbing application should receive
all events normally (True).
pointer_mode
Controls processing of pointer events during the grab. Pass
one of these constants: GrabModeSync or GrabModeAsync.
keyboard_mode
Controls processing of keyboard events during the grab. Pass
one of these constants: GrabModeSync or GrabModeAsync.
DescriptionXGrabKey() establishes a passive grab on the specified keys, such that
when the specified key/modifier combination is pressed, the keyboard
may be grabbed, and all keyboard events sent to this application. More
formally, once an XGrabKey() call has been issued on a particular
key/button combination:
· IF the keyboard is not already actively grabbed,
· AND the specified key, which itself can be a modifier key, is logi‐
cally pressed when the specified modifier keys are logically down,
· AND no other keys or modifier keys are logically down,
· AND EITHER the grab window is an ancestor of (or is) the focus win‐
dow OR the grab window is a descendent of the focus window and con‐
tains the pointer,
· AND a passive grab on the same key combination does not exist on any
ancestor of the grab window,
· THEN the keyboard is actively grabbed, as for XGrabKeyboard(), the
last keyboard grab time is set to the time at which the key was
pressed (as transmitted in the KeyPress event), and the KeyPress
event is reported.
The active grab is terminated automatically when the specified key is
released (independent of the state of the modifier keys). The KeyRe‐
lease event which terminates the active grab is sent to the grabbing
window.
The pointer_mode and keyboard_mode control the processing of events
during the grab. If either is GrabModeSync, events for that device are
not sent from the server to Xlib until XAllowEvents() is called to send
the events. If either is GrabModeAsync, events for that device are
sent normally.
For more information on grabbing, see Volume One, Chapter 9, The Key‐
board and Pointer.
Errors
BadAccess When using AnyModifier or AnyKey and another client has
grabbed any overlapping combinations. In this case, no grabs
are established.
Another client has issued XGrabKey() for the same key combi‐
nation in grab_window.
BadValue keycode is not in the range between min_keycode and max_
keycode as returned by XDisplayKeycodes().
BadWindow
See AlsoXChangeActivePointerGrab(), XGrabButton(), XGrabKeyboard(), XGrab‐
Pointer(), XGrabServer(), XUngrabButton(), XUngrabKey(), XUngrabKey‐
board(), XUngrabPointer(), XUngrabServer().
Xlib - Grabbing XGrabKey()
