XGrabButton()XGrabButton()NameXGrabButton – grab a pointer button.
Synopsis
XGrabButton(display, button, modifiers, grab_window, owner_events,
event_mask, pointer_mode, keyboard_mode, confine_to, cursor)
Display *display;
unsigned int button;
unsigned int modifiers;
Window grab_window;
Bool owner_events;
unsigned int event_mask;
int pointer_mode, keyboard_mode;
Window confine_to;
Cursor cursor;
Arguments
display Specifies a connection to an X server; returned from
XOpenDisplay().
button Specifies the mouse button. May be Button1, Button2, But‐
ton3, Button4, Button5, or AnyButton. The constant AnyButton
is equivalent to issuing the grab request for all possible
buttons. The button symbols cannot be ORed.
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).
grab_window
Specifies the ID of the window you want to the grab to occur
in.
owner_events
Specifies a boolean value of either True or False. See the
"Description" section below.
event_mask
Specifies the event mask to take effect during the grab.
This mask is the bitwise OR of one or more of these event
masks: ButtonPressMask, ButtonReleaseMask, EnterWindowMask,
LeaveWindowMask, PointerMotionMask, PointerMotionHintMask,
Button1MotionMask, Button2MotionMask, Button3MotionMask,
Button4MotionMask, Button5MotionMask, ButtonMotionMask,
KeymapStateMask.
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.
confine_to
Specifies the ID of the window to confine the pointer. One
possible value is the constant None, in which case the
pointer is not confined to any window.
cursor Specifies the cursor to be displayed during the grab. One
possible value you can pass is the constant None, in which
case the existing cursor is used.
DescriptionXGrabButton() establishes a passive grab, such that an active grab may
take place when the specified key/button combination is pressed in the
specified window. After this call:
· IF the specified button is pressed when the specified modifier keys
are down (and no other buttons or modifier keys are down),
· AND grab_window contains the pointer,
· AND the confine_to window (if any) is viewable,
· AND these constraints are not satisfied for any ancestor,
· THEN the pointer is actively grabbed as described in XGrabPointer(),
the last pointer grab time is set to the time at which the button
was pressed, and the ButtonPress event is reported.
The interpretation of the remaining arguments is as for XGrabPointer().
The active grab is terminated automatically when all buttons are
released (independent of the state of modifier keys). The ButtonRe‐
lease event which terminates the active button grab is sent to the
grabbing window.
A modifier of AnyModifier is equivalent to issuing the grab request for
all possible modifier combinations (including no modifiers). A button
of AnyButton is equivalent to issuing the request for all possible but‐
tons (but at least one).
XGrabButton() overrides all previous passive grabs by the same client
on the same key/button combination on the same window, but has no
effect on an active grab. The request fails if some other client has
already issued an XGrabButton() with the same button/key combination on
the same window. When using AnyModifier or AnyButton, the request
fails completely (no grabs are established) if there is a conflicting
grab for any combination.
The owner_events argument specifies whether the grab window should
receive all events (False) or whether the grabbing application should
receive all events normally (True).
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
release the events. If either is GrabModeAsync, events for that device
are sent normally.
An automatic grab takes place between a ButtonPress event and the cor‐
responding ButtonRelease event, so this call is not necessary in some
of the most common situations. But this call is necessary for certain
styles of menus.
For more information on grabbing, see Volume One, Chapter 9, The Key‐
board and Pointer.
Errors
BadAccess When using AnyModifier or AnyButton and there is a conflict‐
ing grab by another client. No grabs are established.
Another client has already issued an XGrabButton() request
with the same key/button combination on the same window.
BadCursor
BadValue
BadWindow
See AlsoXChangeActivePointerGrab(), XGrabKey(), XGrabKeyboard(), XGrab‐
Pointer(), XGrabServer(), XUngrabButton(), XUngrabKey(), XUngrabKey‐
board(), XUngrabPointer(), XUngrabServer().
Xlib - Grabbing XGrabButton()
