XEXTENDEDGRABDEVICE(3) libXi XEXTENDEDGRABDEVICE(3)NAMEXExtendedGrabDevice - actively grab the device.
SYNTAX
#include <X11/extensions/XInput.h>
Status XExtendedGrabDevice(Display *display, XDevice *device,
Window grab_window, int device_mode,
Bool owner_events, Window confine_to,
Cursor cursor, int event_count,
XEventClass *event_list,
int generic_event_count,
XGenericEventMask *generic_events);
ARGUMENTS
confine_to
Specifies the window to confine the pointer in or None.
cursor
Specifies the cursor that is to be displayed during the grab or
None.
display
Specifies the connection to the X server.
device
The device to grab.
device_mode
Specifies further processing of device events. You can pass
GrabModeSync or GrabModeAsync.
event_count
Specifies the number of elements in the event_list array.
event_list
Specifies a pointer to a list of event classes that indicates which
events the client wishes to receive. These event classes must have
been obtained specifying the device being grabbed.
generic_event_count
Specifies the number of elements in the generic_event_list array.
generic_event_list
Specifies a pointer to a list of generic event masks that indicates
which generic events the client wishes to receive.
grab_window
Specifies the grab window.
time
Specifies the time. You can pass either a timestamp or CurrentTime.
owner_events
Specifies a Boolean value that indicates whether the pointer events
are to be reported as usual or reported with respect to the grab
window if selected by the event mask.
DESCRIPTION
The XExtendedGrabDevice request actively grabs control of the device
and generates DeviceFocusIn and DeviceFocusOut events if the device is
a keyboard and DeviceEnterNotify and DeviceLeaveNotify if the device is
a pointer. Further device events are reported only to the grabbing
client. XExtendedGrabDevice overrides any active device grab by this
client.event_list is a pointer to a list of event classes. This list
indicates which events the client wishes to receive while the grab is
active. generic_event_list is a pointer to a list of generic event
masks. These masks indicates which generic events the client wishes to
receive while the grab is active. If owner_events is False, all
generated device events are reported with respect to grab_window if
selected. If owner_events is True and if a generated device 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 specified in the event_list or generic_event_list.
If the device_mode argument is GrabModeAsync, device event processing
continues as usual. If the device is currently frozen by this client,
then processing of device events is resumed. If the device_mode
argument is GrabModeSync, the state of the device (as seen by client
applications) appears to freeze, and the X server generates no further
device events until the grabbing client issues a releasing
XAllowDeviceEvents call or until the device grab is released. Actual
device changes are not lost while the device is frozen; they are simply
queued in the server for later processing.
If a cursor is specified and the device is a master pointer, it is
displayed regardless of what window the device's pointer is in. If None
is specified, the normal cursor for that window is displayed when the
pointer is in grab_window or one of its subwindows; otherwise, the
cursor for grab_window is displayed.
If a confine_to window is specified and the device is a master pointer,
the device's pointer is restricted to stay contained in that window.
The confine_to window need have no relationship to the grab_window. If
the pointer is not initially in the confine_to window, it is warped
automatically to the closest edge just before the grab activates and
enter/leave events are generated as usual. If the confine_to window is
subsequently reconfigured, the pointer is warped automatically, as
necessary, to keep it contained in the window.
The time argument allows you to avoid certain circumstances that come
up if applications take a long time 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 event, the second
application may wake up faster and successfully grab the pointer before
the first application. The first application then will get an
indication that the other application grabbed the pointer before its
request was processed.
If the device is actively grabbed by some other client,
XExtendedGrabDevice fails and returns AlreadyGrabbed. If grab_window is
not viewable, it fails and returns GrabNotViewable. If the device is
frozen by an active grab of another client, it fails and returns
GrabFrozen. If the specified time is earlier than the last-device-grab
time or later than the current X server time, it fails and returns
GrabInvalidTime. Otherwise, the last-device-grab time is set to the
specified time (CurrentTime is replaced by the current X server time).
XExtendedGrabDevice is mostly identical to XGrabPointer and XGrabDevice
but enables a client to register for generic event masks.
XExtendedGrabDevice can generate a BadValue, a BadDevice, and a
BadWindow error.
DIAGNOSIS
BadValue
A value is outside of the permitted range.
BadWindow
A value for a Window argument does not name a defined window.
BadDevice
An invalid device was specified. The device does not exist.
SEE ALSO
XGrabDevice, XUngrabDevice, XGrabPointer
AUTHOR
Peter Hutterer
Specification and implementation.
February 14, 2008 XEXTENDEDGRABDEVICE(3)
