man/XIGrabDevice.man

   1 '\" t
   2 .\"     Title: xigrabdevice
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 12/21/2011
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "XIGRABDEVICE" "libmansuffix" "12/21/2011" "[FIXME: source]" "[FIXME: manual]"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 XIGrabDevice, XIUngrabDevice \- grab or ungrab the device\&.
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput2\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 Status XIGrabDevice( Display *display,
  40                      int deviceid,
  41                      Window grab_window,
  42                      Time time,
  43                      Cursor cursor,
  44                      int grab_mode,
  45                      int paired_device_mode,
  46                      Bool owner_events,
  47                      XIEventMask *mask);
  48 .fi
  49 .sp
  50 .nf
  51 Status XIUngrabDevice( Display *display,
  52                        int deviceid,
  53                        Time time);
  54 .fi
  55 .sp
  56 .nf
  57 cursor
  58        Specifies the cursor image to display for the duration
  59        of the grab\&.
  60 .fi
  61 .sp
  62 .nf
  63 display
  64        Specifies the connection to the X server\&.
  65 .fi
  66 .sp
  67 .nf
  68 deviceid
  69        Specifies the device that should be grabbed or
  70        ungrabbed\&.
  71 .fi
  72 .sp
  73 .nf
  74 grab_mode, paired_device_mode
  75        The grab mode for this device and (if applicable) the
  76        paired device\&.
  77 .fi
  78 .sp
  79 .nf
  80 grab_window
  81        The grab window\&.
  82 .fi
  83 .sp
  84 .nf
  85 mask
  86        Event mask\&.
  87 .fi
  88 .sp
  89 .nf
  90 owner_events
  91        True if events are to be reported normally\&.
  92 .fi
  93 .sp
  94 .nf
  95 time
  96        A valid timestamp or CurrentTime\&.
  97 .fi
  98 .SH "DESCRIPTION"
  99 .sp
 100 .if n \{\
 101 .RS 4
 102 .\}
 103 .nf
 104 XIGrabDevice actively grabs control of the device\&. Further
 105 device events are reported only to the grabbing client\&.
 106 XIGrabDevice overrides any active device grab by this client\&.
 107 .fi
 108 .if n \{\
 109 .RE
 110 .\}
 111 .sp
 112 .if n \{\
 113 .RS 4
 114 .\}
 115 .nf
 116 If the device is an attached slave device, the device is
 117 automatically detached from the master device and reattached to
 118 the same master device when client ungrabs the device\&. If the
 119 master device is removed while the device is floating as a
 120 result of a grab, the device remains floating once the grab
 121 deactivates\&.
 122 .fi
 123 .if n \{\
 124 .RE
 125 .\}
 126 .sp
 127 .if n \{\
 128 .RS 4
 129 .\}
 130 .nf
 131 If owner_events is False, all generated device events are
 132 reported with respect to grab_window if selected\&. If
 133 owner_events is True and if a generated device event would
 134 normally be reported to this client, it is reported normally;
 135 otherwise, the event is reported with respect to the
 136 grab_window, and is only reported if specified in the event
 137 mask\&.
 138 .fi
 139 .if n \{\
 140 .RE
 141 .\}
 142 .sp
 143 .if n \{\
 144 .RS 4
 145 .\}
 146 .nf
 147 If the grab_mode argument is XIGrabModeAsync, device event
 148 processing continues as usual\&. If the device is currently
 149 frozen by this client, then processing of device events is
 150 resumed\&. If the grab_mode argument is XIGrabModeSync, the state
 151 of the device (as seen by client applications) appears to
 152 freeze, and the X server generates no further device events
 153 until the grabbing client issues a releasing XIAllowEvents call
 154 or until the device grab is released\&. Actual device changes are
 155 not lost while the device is frozen; they are simply queued in
 156 the server for later processing\&.
 157 .fi
 158 .if n \{\
 159 .RE
 160 .\}
 161 .sp
 162 .if n \{\
 163 .RS 4
 164 .\}
 165 .nf
 166 If paired_device_mode is XIGrabModeAsync, processing of events
 167 from the paired master device is unaffected by activation of
 168 the grab\&. If paired_device_mode is XIGrabModeSync, the state of
 169 the paired master device (as seen by client applications)
 170 appears to freeze, and the X server generates no further events
 171 from this device until the grabbing client issues a releasing
 172 XIAllowEvents call or until the device grab is released\&. Actual
 173 events are not lost while the devices are frozen; they are
 174 simply queued in the server for later processing\&. If the device
 175 is a slave device paired_device_mode is ignored\&.
 176 .fi
 177 .if n \{\
 178 .RE
 179 .\}
 180 .sp
 181 .if n \{\
 182 .RS 4
 183 .\}
 184 .nf
 185 If the device is actively grabbed by some other client,
 186 XIGrabDevice fails and returns AlreadyGrabbed\&. If grab_window
 187 is not viewable, it fails and returns GrabNotViewable\&. If the
 188 device is frozen by an active grab of another client, it fails
 189 and returns GrabFrozen\&. If the specified time is earlier than
 190 the last\-device\-grab time or later than the current X server
 191 time, it fails and returns GrabInvalidTime\&. Otherwise, the
 192 last\-device\-grab time is set to the specified time\&. CurrentTime
 193 is replaced by the current X server time\&.
 194 .fi
 195 .if n \{\
 196 .RE
 197 .\}
 198 .sp
 199 .if n \{\
 200 .RS 4
 201 .\}
 202 .nf
 203 If cursor is not None this cursor is displayed until the client
 204 calls XIUngrabDevice\&.
 205 .fi
 206 .if n \{\
 207 .RE
 208 .\}
 209 .sp
 210 .if n \{\
 211 .RS 4
 212 .\}
 213 .nf
 214 XIGrabDevice can generate BadDevice, BadValue, and BadWindow
 215 errors\&.
 216 .fi
 217 .if n \{\
 218 .RE
 219 .\}
 220 .sp
 221 .if n \{\
 222 .RS 4
 223 .\}
 224 .nf
 225 The XIUngrabDevice request releases the device and any queued
 226 events if this client has it actively grabbed from either
 227 XIGrabDevice or XIGrabKey or XIGrabButton\&. If other devices are
 228 frozen by the grab, XUngrabDevice thaws them\&. XUngrabDevice
 229 does not release the device and any queued events if the
 230 specified time is earlier than the last\-device\-grab time or is
 231 later than the current X server time\&. The X server
 232 automatically performs an XIUngrabDevice request if the event
 233 window for an active device grab becomes not viewable\&.
 234 .fi
 235 .if n \{\
 236 .RE
 237 .\}
 238 .sp
 239 .if n \{\
 240 .RS 4
 241 .\}
 242 .nf
 243 XIUngrabDevice can generate a BadDevice error\&.
 244 .fi
 245 .if n \{\
 246 .RE
 247 .\}
 248 .SH "DIAGNOSTICS"
 249 .sp
 250 .if n \{\
 251 .RS 4
 252 .\}
 253 .nf
 254 BadValue
 255        A value is outside of the permitted range\&.
 256 .fi
 257 .if n \{\
 258 .RE
 259 .\}
 260 .sp
 261 .if n \{\
 262 .RS 4
 263 .\}
 264 .nf
 265 BadDevice
 266        An invalid device was specified\&. The device does not
 267        exist or is not a appropriate for the type of change\&.
 268 .fi
 269 .if n \{\
 270 .RE
 271 .\}
 272 .sp
 273 .if n \{\
 274 .RS 4
 275 .\}
 276 .nf
 277 BadMatch
 278        The window is not viewable\&.
 279 .fi
 280 .if n \{\
 281 .RE
 282 .\}
 283 .sp
 284 .if n \{\
 285 .RS 4
 286 .\}
 287 .nf
 288 BadWindow
 289        A value for a Window argument does not name a defined
 290        Window\&.
 291 .fi
 292 .if n \{\
 293 .RE
 294 .\}
 295 .SH "BUGS"
 296 .sp
 297 .if n \{\
 298 .RS 4
 299 .\}
 300 .nf
 301 The protocol headers for XI 2\&.0 did not provide
 302 XIGrabModeAsync or XIGrabModeSync\&. Use GrabModeSync and
 303 GrabModeAsync instead, respectively\&.
 304 .fi
 305 .if n \{\
 306 .RE
 307 .\}
 308 .SH "SEE ALSO"
 309 .sp
 310 .if n \{\
 311 .RS 4
 312 .\}
 313 .nf
 314 XIAllowEvents(libmansuffix)
 315 .fi
 316 .if n \{\
 317 .RE
 318 .\}