XtGrabButton() XtGrabButton()
Name
XtGrabButton - passively grab a single pointer button.
Synopsis
void XtGrabButton(widget, button, modifiers, owner_events, event_mask, pointer_mode, keyboard_mode, confine_to, cursor)
Widget widget;
int button;
Modifiers modifiers;
Boolean owner_events;
unsigned int event_mask;
int pointer_mode, keyboard_mode;
Window confine_to;
Cursor cursor;
Inputs
widget Specifies the widget in whose window the button is to be grabbed. Must be of class Core or any subclass thereof.
button Specifies the mouse button which is to be grabbed.
modifiers Specifies the modifiers that must be down to trigger the grab.
owner_events
Specifies whether pointer events generated during the grab are reported normally within the application (True) or only to the
specified widget (False).
event_mask
Specifies the event mask to take effect during the grab.
pointer_mode
Controls processing of pointer events during the grab. Either GrabModeSync or GrabModeAsync.
keyboard_mode
Controls processing of keyboard events during the grab. Either GrabModeSync or GrabModeAsync.
confine_to
Specifies the ID of the window to confine the pointer, or None.
cursor Specifies the cursor to be displayed during the grab, or None.
Description
XtGrabButton() calls XGrabButton() to establish a passive button grab. It specifies the widget's window as the grab_window, and passes its
remaining arguments directly to XGrabButton(). If the widget is not realized, the call to XGrabButton() will be performed when the widget
is realized and its window becomes mapped. If the widget is unrealized and later realized again, the call to XGrabButton() will be per-
formed again.
The button argument may be Button1, Button2, Button3, Button4, Button5, or AnyButton. The constant AnyButton is equivalent to issuing the
grab request for all possible buttons. The button symbols cannot be ORed together.
The modifiers argument 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 combi-
nations (including no modifiers).
See XtGrabPointer() for an explanation of the owner_events, event_mask, pointer_mode, keyboard_mode, confine_to, and cursor arguments.
See the "Background" section below for a description of event handling when a passive button grab is triggered.
Usage
When you passively grab a button/modifiers combination, all events that occur when that button and those modifiers are down will be deliv-
ered to the window you specify or to your application, regardless of the location of the pointer. Button grabs can be used by applications
like xmag and window managers which need to use the pointer to indicate a point on or a region of the screen, regardless of the applica-
tions that are under the pointer.
You should rarely need to use this function. 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. It may be necessary for some styles of menus, however.
Note that XtAddGrab() and spring-loaded popups perform a similar function, but without issuing any X server grabs.
To cancel a passive button grab, use XtUngrabButton().
Background
After making this call, if XtDispatchEvent() is called with a ButtonPress event matching the specified button and modifiers (which may be
AnyButton or AnyModifier, respectively) for the widget's window, the Intrinsics will undo the grab by calling XtUngrabPointer() with the
timestamp from the ButtonPress event if either of the following conditions is true:
o There is a modal cascade and the widget is not in the active subset of the cascade and the pointer was not previously grabbed, or
o XFilterEvent() returns True.
Otherwise, after making this call, the pointer will be actively grabbed (as for XtGrabPointer()), the last-pointer-grab time will be set to
the time at which the button was pressed (as transmitted in the ButtonPress event), and the ButtonPress event will be reported if all of
the following conditions are true:
o 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.
o The grab_window contains the pointer.
o The confine_to window (if any) is viewable.
o A passive grab on the same button/key combination does not exist on any ancestor of grab_window.
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 processing is frozen.
This request overrides all previous grabs by the same client on the same button/key combinations on the same window. A modifiers of Any-
Modifier 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 possible 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/key combination on the same window, a BadAccess error results.
When using AnyModifier or AnyButton, the request fails completely, and a BadAccess error results (no grabs are established) if there is a
conflicting grab for any combination. XGrabButton() has no effect on an active grab.
See Also
XtAddGrab(1), XtGrabKey(1), XtGrabKeyboard(1), XtGrabPointer(1), XtRegisterGrabAction(1), XtUngrabButton(1), XtUngrabKey(1), XtUngrabKey-
board(1), XtUngrabPointer(1).
Xt - Mouse Handling XtGrabButton()