XGrabPointer()XGrabPointer()NameXGrabPointer – grab the pointer.
Synopsis
int XGrabPointer(display, grab_window, owner_events, event_mask,
pointer_mode, keyboard_mode, confine_to, cursor, time)
Display *display;
Window grab_window;
Bool owner_events;
unsigned int event_mask;
int pointer_mode, keyboard_mode;
Window confine_to;
Cursor cursor;
Time time;
Arguments
display Specifies a connection to an X server; returned from
XOpenDisplay().
grab_window
Specifies the ID of the window that should grab the pointer
input independent of pointer location.
owner_events
Specifies if the pointer events are to be reported normally
within this application (pass True) or only to the grab win‐
dow (pass False).
event_mask
Specifies the event mask symbols that can be ORed together.
Only events selected by this mask will be delivered during
the grab. The valid event masks are: ButtonPressMask, But‐
tonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMo‐
tionMask, PointerMotionHintMask, Button1MotionMask,
Button2MotionMask, Button3MotionMask, Button4MotionMask,
Button5MotionMask, ButtonMotionMask, KeymapStateMask.
pointer_mode
Controls further processing of pointer events. Pass either
GrabModeSync or GrabModeAsync.
keyboard_mode
Controls further processing of keyboard events. Pass either
GrabModeSync or GrabModeAsync.
confine_to
Specifies the ID of the window to confine the pointer. One
option is None, in which case the pointer is not confined to
any window.
cursor Specifies the ID of the cursor that is displayed with the
pointer during the grab. One option is None, which causes
the cursor to keep its current
pattern.
time Specifies the time when the grab request took place. Pass
either a timestamp, expressed in milliseconds (from an
event), or the constant CurrentTime.
Returns
GrabSuccess on success. GrabNotViewable, AlreadyGrabbed, GrabInvalid‐
Time, or GrabFrozen on failure.
DescriptionXGrabPointer() actively grabs control of the pointer. Further pointer
events report only to the grabbing client until XUngrabPointer() is
called. XGrabPointer() overrides any active pointer grab by this
client.
If owner_events is False, all generated pointer events are reported to
grab_window, and are only reported if selected by event_mask. If
owner_events is True, then if a generated pointer event would normally
be reported to this client, it is reported normally; otherwise the
event is reported with respect to the grab_window, and is only reported
if selected by event_mask. For either value of owner_events, unre‐
ported events are discarded.
pointer_mode controls processing of pointer events during the grab, and
keyboard_mode controls further processing of main keyboard events. If
the mode is GrabModeAsync, event processing continues normally. If the
mode is GrabModeSync, events for the device are queued by the server
but not sent to clients until the grabbing client issues a releasing
XAllowEvents() request or an XUngrabPointer() request.
If a cursor is specified, then it is displayed regardless of which win‐
dow the pointer is in. If no cursor is specified, then when the
pointer is in grab_window or one of its subwindows, the normal cursor
for that window is displayed. When the pointer is outside grab_window,
the cursor for grab_window is displayed.
If a confine_to window is specified, then the pointer will be
restricted to that window. The confine_to window need have no rela‐
tionship to the grab_window. If the pointer is not initially in the
confine_to window, then it is warped automatically to the closest edge
(and enter/leave events generated normally) just before the grab acti‐
vates. If the confine_to window is subsequently reconfigured, the
pointer will be warped automatically as necessary to keep it contained
in the window.
The time argument lets you avoid certain circumstances that come up if
applications take a long while to respond or if there are long network
delays. Consider a situation where you have two applications, both of
which normally grab the pointer when clicked on. If both applications
specify the timestamp from the ButtonPress event, the second applica‐
tion will successfully grab the pointer, while the first will get a
return value of AlreadyGrabbed, indicating that the other application
grabbed the pointer before its request was processed. This is the
desired response because the latest user action is most important in
this case.
XGrabPointer() generates EnterNotify and LeaveNotify events.
If the grab is successful, it returns the constant GrabSuccess. The
XGrabPointer() function fails under the following conditions, with the
following return values:
· If grab_window or confine_to window is not viewable, or if the
confine_to window is completely off the screen, GrabNotViewable is
returned.
· If the pointer is actively grabbed by some other client, the con‐
stant AlreadyGrabbed is returned.
· If the pointer is frozen by an active grab of another client,
GrabFrozen is returned.
· If the specified time is earlier than the last-pointer-grab time or
later than the current X server time, GrabInvalidTime is returned.
(If the call succeeds, the last pointer grab time is set to the
specified time, with the constant CurrentTime replaced by the cur‐
rent X server time.)
For more information on grabbing, see Volume One, Chapter 9, The
Keyboard and Pointer.
Errors
BadCursor
BadValue
BadWindow
See AlsoXChangeActivePointerGrab(), XGrabButton(), XGrabKey(), XGrabKeyboard(),
XGrabServer(), XUngrabButton(), XUngrabKey(), XUngrabKeyboard(), XUn‐
grabPointer(), XUngrabServer().
Xlib - Grabbing XGrabPointer()
