XtGrbButton(3X) — DeltaWindows 1.3.3 Release 4 Version 4.3

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

widgetSpecifies the widget in whose window the button is to be grabbed. Must be of class Core or any subclass thereof.

buttonSpecifies the mouse button which is to be grabbed.

modifiersSpecifies 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.

cursorSpecifies 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 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 equivalent to issuing the grab key request for all possible modifier combinations (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 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:

•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 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/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 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 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.