XGrabKeyboard(3X)                               XGrabKeyboard(3X)



NAME
     XGrabKeyboard,  XUngrabKeyboard  -  grab  and   ungrab   the
     keyboard

SYNOPSIS
     int XGrabKeyboard (display, grab-window,
     owner-events, pointer-mode, keyboard-mode, time)
     Display *display;
     Window grab-window;
     Bool owner-events;
     int pointer-mode, keyboard-mode;
     Time time;

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

DESCRIPTION
     The XGrabKeyboard function actively grabs control of the
     main 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, indepen-
     dent of any event selection made by the client.

     If keyboard-mode is GrabModeAsync, keyboard event processing
     continues as usual. If the keyboard is currently frozen by
     this client, processing of keyboard events is resumed.  If
     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 pro-
     cessing.




November, 1990                                                  1

XGrabKeyboard(3X)                               XGrabKeyboard(3X)



     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).

     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.

   Arguments
     These functions accept the following arguments:

     display Specifies the connection to the X server.

     grab-window
             Specifies the window ID of the window associated
             with the keyboard to be grabbed.

     keyboard-mode
             Controls further processing of keyboard events.  You
             can pass one of the following constants:
             GrabModeSync or GrabModeAsync.

     owner-events
             Specifies a Boolean value of either TRUE or FALSE
             that indicates whether keyboard events are to be re-
             ported as usual.

     pointer-mode
             Specifies further processing of pointer events.  You
             can pass one of the following constants:  GrabMo-
             deSync or GrabModeAsync.

     time    Specifies the time.  You can pass either a times-
             tamp, expressed in milliseconds, or CurrentTime.






2                                                  November, 1990

XGrabKeyboard(3X)                               XGrabKeyboard(3X)



ERRORS
     BadValue
             A numeric value falls outside the range of values
             accepted by the request.  Unless a range is speci-
             fied 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 de-
             fined window.

     The XGrabKeyboard function can generate BadValue and BadWin-
     dow errors.

SEE ALSO
     XAllowEvents(3X), XGrabButton(3X), XGrabKey(3X),
     XGrabPointer(3X)

     Xlib - C Language Interface




































November, 1990                                                  3