---
name: "XGrabKeyboard"
section: "3x"
platform: "linux"
package: "libx11-dev"
version: "4.3.0.dfsg.1-14sarge7"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/XGrabKeyboard/3x"
---

# XGrabKeyboard(3x)

grab the keyboard

## NAME

XGrabKeyboard, XUngrabKeyboard - grab the keyboard

## SYNTAX

int XGrabKeyboard(Display \**display*, Window *grab\_window*, Bool *owner\_events*, int *pointer\_mode*, int *keyboard\_mode*, Time *time*);

int XUngrabKeyboard(Display \**display*, Time *time*);

## ARGUMENTS

- *display*

  Specifies the connection to the X server.

- *grab\_window*

  Specifies the grab window.

- *keyboard\_mode*

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

- *owner\_events*

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

- *pointer\_mode*

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

- *time*

  Specifies the time. You can pass either a timestamp or *CurrentTime*.

## DESCRIPTION

The *XGrabKeyboard* function actively grabs control of the keyboard and generates *FocusIn* and *FocusOut* events. Further key events are reported only to the grabbing client. *XGrabKeyboard* overrides any active keyboard grab by this client. If owner\_events is  *False*, all generated key events are reported with respect to grab\_window.   If owner\_events is  *True* and if a generated key event would normally be reported to this client, it is reported normally; otherwise, the event is reported with respect to the grab\_window.   Both  *KeyPress* and  *KeyRelease* events are always reported, independent of any event selection made by the client.

If the keyboard\_mode argument is  *GrabModeAsync*, keyboard event processing continues as usual.  If the keyboard is currently frozen by this client,  then processing of keyboard events is resumed. If the keyboard\_mode  argument is *GrabModeSync*, the state of the keyboard (as seen by client applications) appears to freeze, and the X server generates no further keyboard events until the grabbing client issues a releasing  *XAllowEvents* call or until the keyboard grab is released. Actual keyboard changes are not lost while the keyboard is frozen;  they are simply queued in the server for later processing.

If pointer\_mode is  *GrabModeAsync*, pointer event processing is unaffected by activation of the grab.   If pointer\_mode is  *GrabModeSync*, the state of the pointer (as seen by client applications) appears to freeze,  and the X server generates no further pointer events  until the grabbing client issues a releasing  *XAllowEvents* call or until the keyboard grab is released. Actual pointer changes are not lost while the pointer is frozen;  they are simply queued in the server for later processing.

If the keyboard is actively grabbed by some other client, *XGrabKeyboard* fails and returns *AlreadyGrabbed*. If grab\_window is not viewable, it fails and returns *GrabNotViewable*. If the keyboard is frozen by an active grab of another client, it fails and returns *GrabFrozen*. If the specified time is earlier than the last-keyboard-grab time  or later than the current X server time, it fails and returns *GrabInvalidTime*. Otherwise, the last-keyboard-grab time is set to the specified time (*CurrentTime* is replaced by the current X server time).

*XGrabKeyboard* can generate *BadValue* and *BadWindow* errors.

The *XUngrabKeyboard* function releases the keyboard and any queued events if this client has it actively grabbed from either *XGrabKeyboard* or *XGrabKey*. *XUngrabKeyboard* does not release the keyboard and any queued events if the specified time is earlier than the last-keyboard-grab time or is later than the current X server time. It also generates *FocusIn* and  *FocusOut* events. The X server automatically performs an  *UngrabKeyboard* request if the event window for an active keyboard grab becomes not viewable.

## DIAGNOSTICS

- *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*

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

## SEE ALSO

XAllowEvents(3X11), XGrabButton(3X11), XGrabKey(3X11), XGrabPointer(3X11)\
 *Xlib - C Language X Interface*