XtGrabButton()XtGrabButton()NameXtGrabButton - 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.
DescriptionXtGrabButton() 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 performed
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 equiva‐
lent to issuing the grab key request for all possible modifier combina‐
tions (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 delivered
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 applications 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 situa‐
tions. It may be necessary for some styles of menus, however.
Note that XtAddGrab() and spring-loaded popups perform a similar func‐
tion, 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 Button‐
Press 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 condi‐
tions is true:
· 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
· 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 fol‐
lowing 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/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 applica‐
tions) 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 spec‐
ified 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 con‐
flicting grab for any combination. XGrabButton() has no effect on an
active grab.
See AlsoXtAddGrab(1), XtGrabKey(1), XtGrabKeyboard(1), XtGrabPointer(1), XtReg‐
isterGrabAction(1), XtUngrabButton(1), XtUngrabKey(1), XtUngrabKey‐
board(1), XtUngrabPointer(1).
Xt - Mouse Handling XtGrabButton()
