The
XGrabButton function establishes a passive grab. In the future, the pointer
is actively grabbed (as for XGrabPointer), the last-pointer-grab time is
set to the time at which the button was pressed (as transmitted in the
ButtonPress 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/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 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.

XGrabButton
can generate BadCursor, BadValue, and BadWindow errors.

The XUngrabButton
function releases the passive button/key combination on 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 combinations,
including the combination of no modifiers. A button of AnyButton is
equivalent to issuing the request for all possible buttons. XUngrabButton
has no effect on an active grab.

Some numeric value falls outside
the range of values accepted by the request. Unless a specific range is
specified 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.