XGrabButton() XGrabButton()
Name
XGrabButton - 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, Button3, Button4, Button5, or AnyButton. The constant AnyButton is equiva-
lent 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, ControlMask,
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: But-
tonPressMask, 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.
Description
XGrabButton() 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:
o IF the specified button is pressed when the specified modifier keys are down (and no other buttons or modifier keys are down),
o AND grab_window contains the pointer,
o AND the confine_to window (if any) is viewable,
o AND these constraints are not satisfied for any ancestor,
o 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 ButtonRelease event which terminates the active button grab is sent to the grab-
bing 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 buttons (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 corresponding 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 Keyboard and Pointer.
Errors
BadAccess When using AnyModifier or AnyButton and there is a conflicting 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 Also
XChangeActivePointerGrab(), XGrabKey(), XGrabKeyboard(), XGrabPointer(), XGrabServer(), XUngrabButton(), XUngrabKey(), XUngrabKeyboard(),
XUngrabPointer(), XUngrabServer().
Xlib - Grabbing XGrabButton()