XGrabKey(3) XLIB FUNCTIONS XGrabKey(3)

# [NAME](#NAME)

XGrabKey, XUngrabKey - grab keyboard keys

# [SYNTAX](#SYNTAX)

int XGrabKey(Display \**display*, int *keycode*, unsigned int *modifiers*, Window *grab\_window*, Bool *owner\_events*, int *pointer\_mode*, int *keyboard\_mode*);

int XUngrabKey(Display \**display*, int *keycode*, unsigned int *modifiers*, Window *grab\_window*);

# [ARGUMENTS](#ARGUMENTS)

[*display*](#display)

Specifies the connection to the X server.

[*grab\_window*](#grab_window)

Specifies the grab window.

[*keyboard\_mode*](#keyboard_mode)

Specifies further processing of keyboard events. You can pass **GrabModeSync** or **GrabModeAsync**.

[*keycode*](#keycode)

Specifies the KeyCode or **AnyKey**.

[*modifiers*](#modifiers)

Specifies the set of keymasks or **AnyModifier**. The mask is the bitwise inclusive OR of the valid keymask bits.

[*owner\_events*](#owner_events)

Specifies a Boolean value that indicates whether the keyboard events are to be reported as usual.

[*pointer\_mode*](#pointer_mode)

Specifies further processing of pointer events. You can pass **GrabModeSync** or **GrabModeAsync**.

# [DESCRIPTION](#DESCRIPTION)

The **XGrabKey** function establishes a passive grab on the keyboard. In the future, 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 if all of the following conditions are true:

- The keyboard is not grabbed and the specified key (which can itself be a modifier key) is logically pressed when the specified modifier keys are logically down, and no other modifier keys are logically down.
- Either the grab\_window is an ancestor of (or is) the focus window, or the grab\_window is a descendant of the focus window and contains the pointer.
- A passive grab on the same key combination does not exist on any ancestor of grab\_window.

The interpretation of the remaining arguments is as for **XGrabKeyboard**. The active grab is terminated automatically when the logical state of the keyboard has the specified key released (independent of the logical state of the modifier keys), at which point a **KeyRelease** event is reported to the grabbing window.

Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.

A modifiers argument of **AnyModifier** is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A keycode argument of **AnyKey** is equivalent to issuing the request for all possible KeyCodes. Otherwise, the specified keycode must be in the range specified by min\_keycode and max\_keycode in the connection setup, or a **BadValue** error results.

If some other client has issued a **XGrabKey** with the same key combination on the same window, a **BadAccess** error results. When using **AnyModifier** or **AnyKey**, the request fails completely, and a **BadAccess** error results (no grabs are established) if there is a conflicting grab for any combination.

**XGrabKey** can generate **BadAccess**, **BadValue**, and **BadWindow** errors.

The **XUngrabKey** function releases the key combination on the specified window if it was grabbed by this client. It has no effect on an active grab. A modifiers of **AnyModifier** is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A keycode argument of **AnyKey** is equivalent to issuing the request for all possible key codes.

**XUngrabKey** can generate **BadValue** and **BadWindow** error.

# [DIAGNOSTICS](#DIAGNOSTICS)

[**BadAccess**](#BadAccess)

A client attempted to grab a key/button combination already grabbed by another client.

[**BadValue**](#BadValue)

Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

[**BadWindow**](#BadWindow)

A value for a Window argument does not name a defined Window.

# [SEE ALSO](#SEE_ALSO)

[**XAllowEvents**(3)](/man/os/libx11/XAllowEvents.3), [**XGrabButton**(3)](/man/os/libx11/XGrabButton.3), [**XGrabKeyboard**(3)](/man/os/libx11/XGrabKeyboard.3), [**XGrabPointer**(3)](/man/os/libx11/XGrabPointer.3)  
*Xlib - C Language X Interface*

libX11 1.8.14 X Version 11

---

Document: XGrabKey(3) from libx11 1.8.14-r2 (Chainguard OS)
Source: https://gitlab.freedesktop.org/xorg/lib/libx11.git