297 lines
6.4 KiB
Groff
297 lines
6.4 KiB
Groff
'\" t
|
|
.\" Title: xigrabdevice
|
|
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
|
|
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
|
|
.\" Date: 10/07/2010
|
|
.\" Manual: [FIXME: manual]
|
|
.\" Source: [FIXME: source]
|
|
.\" Language: English
|
|
.\"
|
|
.TH "XIGRABDEVICE" "libmansuffix" "10/07/2010" "[FIXME: source]" "[FIXME: manual]"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
XIGrabDevice, XIUngrabDevice \- grab or ungrab the device\&.
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
.nf
|
|
#include <X11/extensions/XInput2\&.h>
|
|
.fi
|
|
.sp
|
|
.nf
|
|
Status XIGrabDevice( Display *display,
|
|
int deviceid,
|
|
Window grab_window,
|
|
Time time,
|
|
Cursor cursor,
|
|
int grab_mode,
|
|
int paired_device_mode,
|
|
Bool owner_events,
|
|
XIEventMask *mask);
|
|
.fi
|
|
.sp
|
|
.nf
|
|
Status XIUngrabDevice( Display *display,
|
|
int deviceid,
|
|
Time time);
|
|
.fi
|
|
.sp
|
|
.nf
|
|
cursor
|
|
Specifies the cursor image to display for the duration
|
|
of the grab\&.
|
|
.fi
|
|
.sp
|
|
.nf
|
|
display
|
|
Specifies the connection to the X server\&.
|
|
.fi
|
|
.sp
|
|
.nf
|
|
deviceid
|
|
Specifies the device that should be grabbed or
|
|
ungrabbed\&.
|
|
.fi
|
|
.sp
|
|
.nf
|
|
grab_mode, paired_device_mode
|
|
The grab mode for this device and (if applicable) the
|
|
paired device\&.
|
|
.fi
|
|
.sp
|
|
.nf
|
|
grab_window
|
|
The grab window\&.
|
|
.fi
|
|
.sp
|
|
.nf
|
|
mask
|
|
Event mask\&.
|
|
.fi
|
|
.sp
|
|
.nf
|
|
owner_events
|
|
True if events are to be reported normally\&.
|
|
.fi
|
|
.sp
|
|
.nf
|
|
time
|
|
A valid timestamp or CurrentTime\&.
|
|
.fi
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
XIGrabDevice actively grabs control of the device\&. Further
|
|
device events are reported only to the grabbing client\&.
|
|
XIGrabDevice overrides any active device grab by this client\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
If the device is an attached slave device, the device is
|
|
automatically detached from the master device and reattached to
|
|
the same master device when client ungrabs the device\&. If the
|
|
master device is removed while the device is floating as a
|
|
result of a grab, the device remains floating once the grab
|
|
deactivates\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
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
|
|
mask\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
If the grab_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 grab_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 XIAllowEvents 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\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
If paired_device_mode is GrabModeAsync, processing of events
|
|
from the paired master device is unaffected by activation of
|
|
the grab\&. If paired_device_mode is GrabModeSync, the state of
|
|
the paired master device (as seen by client applications)
|
|
appears to freeze, and the X server generates no further events
|
|
from this device until the grabbing client issues a releasing
|
|
XIAllowEvents call or until the device grab is released\&. Actual
|
|
events are not lost while the devices are frozen; they are
|
|
simply queued in the server for later processing\&. If the device
|
|
is a slave device paired_device_mode is ignored\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
If the device is actively grabbed by some other client,
|
|
XIGrabDevice 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\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
If cursor is not None this cursor is displayed until the client
|
|
calls XIUngrabDevice\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
XIGrabDevice can generate BadDevice, BadValue, and BadWindow
|
|
errors\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
The XIUngrabDevice request releases the device and any queued
|
|
events if this client has it actively grabbed from either
|
|
XIGrabDevice or XIGrabKey or XIGrabButton\&. If other devices are
|
|
frozen by the grab, XUngrabDevice thaws them\&. XUngrabDevice
|
|
does not release the device and any queued events if the
|
|
specified time is earlier than the last\-device\-grab time or is
|
|
later than the current X server time\&. The X server
|
|
automatically performs an XIUngrabDevice request if the event
|
|
window for an active device grab becomes not viewable\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
XIUngrabDevice can generate a BadDevice error\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.SH "DIAGNOSTICS"
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
BadValue
|
|
A value is outside of the permitted range\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
BadDevice
|
|
An invalid device was specified\&. The device does not
|
|
exist or is not a appropriate for the type of change\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
BadMatch
|
|
The window is not viewable\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
BadWindow
|
|
A value for a Window argument does not name a defined
|
|
Window\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
XIAllowEvents(libmansuffix)
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|