XGrabButton(3X) XGrabButton(3X)NAME XGrabButton, XUngrabButton - grab pointer buttons SYNOPSIS XGrabButton (display, button-grab, modifiers, grab-window, owner-events, event-mask, pointer-mode, keyboard-mode, confine-to, cursor) Display *display; unsigned int button-grab; unsigned int modifiers; Window grab-window; Bool owner-events; unsigned int event-mask; int pointer-mode, keyboard-mode; Window confine-to; Cursor cursor; XUngrabButton (display, button-ungrab, modifiers, ungrab-window) Display *display; unsigned int button-ungrab; unsigned int modifiers; Window ungrab-window; DESCRIPTION The XGrabButton function establishes a passive grab. In the future, the pointer is actively grabbed (as for XGrab- Pointer), the last-pointer-grab time is set to the time at which the button was pressed (as transmitted in the But- tonPress event), and the ButtonPress event is reported if all of the following conditions are true: The pointer is not grabbed, and the specified button is logically pressed when the specified modifier keys are logically down, and no other buttons or modifier keys are logically down. The grab-window contains the pointer. The confine-to window (if any) is viewable. A passive grab on the same button and key combination does not exist on any ancestor of grab-window. The interpretation of the remaining arguments is as for XGrabPointer. The active grab is terminated automatically when the logical state of the pointer has all buttons released (independent of the state of the logical modifier keys). Note that the logical state of a device (as seen by client applications) may lag the physical state if device event November, 1990 1
XGrabButton(3X) XGrabButton(3X)processing is frozen. This request overrides all previous grabs by the same client on the same button and key combinations on the same window. A modifiers of AnyModifier is equivalent to issuing the grab 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 button of AnyButton is equivalent to issuing the request for all pos- sible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button. If some other client has already issued a XGrabButton with the same button and key combination on the same window, a BadAccess error results. When using AnyModifier or AnyButton, the request fails completely, and a BadAccess er- ror results (no grabs are established) if there is a con- flicting grab for any combination. XGrabButton has no ef- fect on an active grab. The XUngrabButton function releases the passive button and key combination for the specified window if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the ungrab request for all possible modifier combi- nations, including the combination of no modifiers. A but- ton of AnyButton is equivalent to issuing the request for all possible buttons. XUngrabButton has no effect on an ac- tive grab. Arguments These functions accept the following arguments: button-grab Specifies the pointer button that is to be grabbed when the specified modifier keys are down or AnyBut- ton. button-ungrab Specifies the pointer button that is to be released in combination with the modifier keys or None. confine-to Specifies the window in which to confine the pointer or None if it is not to be confined. cursor Specifies the pointer to be displayed during the grab. display Specifies the connection to the X server. event-mask 2 November, 1990
XGrabButton(3X) XGrabButton(3X)Specifies which pointer events are reported to the client. They can be the bitwise inclusive OR of these pointer event mask bits: ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, KeyMapStateMask. grab-window Specifies the window ID of the window to be grabbed. keyboard-mode Specifies further processing of keyboard events. You can pass as a constant either GrabModeSync or GrabModeAsync. modifiers Specifies the set of keymasks or AnyModifier. This mask is the bitwise inclusive OR of these keymask bits: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. owner-events Specifies whether the pointer events are to be re- ported normally (pass TRUE) or with respect to the grab window if selected by the event mask (pass FALSE). pointer-mode Controls further processing of pointer events. You can pass as a constant either GrabModeSync or GrabModeAsync. ungrab-window Specifies the window ID of the window you want to release. ERRORS BadCursor A value for a Cursor argument does not name a de- fined pointer. BadValue A numeric value falls outside the range of values accepted by the request. Unless a range is speci- November, 1990 3
XGrabButton(3X) XGrabButton(3X)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 XGrabButton function can generate BadCursor, BadValue, and BadWindow errors. The XUngrabButton function can generate BadValue and BadWin- dow errors. SEE ALSO XAllowEvents(3X), XGrabPointer(3X), XGrabKey(3X), XGrabKeyboard(3X)Xlib - C Language Interface4 November, 1990