man/XGrabDevice.man

   1 '\" t
   2 .\"     Title: xgrabdevice
   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: 09/23/2011
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "XGRABDEVICE" "libmansuffix" "09/23/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 XGrabDevice, XUngrabDevice \- grab/release the specified extension device
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 int XGrabDevice( Display *display,
  40                  XDevice* device,
  41                  Window grab_window,
  42                  Bool owner_events,
  43                  int event_count,
  44                  XEventClass *event_list,
  45                  int this_device_mode,
  46                  int other_devices_mode,
  47                  Time time);
  48 .fi
  49 .sp
  50 .nf
  51 int XUngrabDevice( Display *display,
  52                    XDevice *device,
  53                    Time time);
  54 .fi
  55 .sp
  56 .nf
  57 display
  58        Specifies the connection to the X server\&.
  59 .fi
  60 .sp
  61 .nf
  62 device
  63        Specifies the device to be grabbed or released\&.
  64 .fi
  65 .sp
  66 .nf
  67 grab_window
  68        Specifies the id of a window to be associated with the
  69        device\&.
  70 .fi
  71 .sp
  72 .nf
  73 owner_events
  74        Specifies a Boolean value that indicates whether
  75        theevents from the deviceare to be reported as usual or
  76        reported with respect to the grab windowif selected by
  77        the event list\&.
  78 .fi
  79 .sp
  80 .nf
  81 event_count
  82        Specifies the number of elements in the event_list
  83        array\&.
  84 .fi
  85 .sp
  86 .nf
  87 event_list
  88        Specifies a pointer to a list of event classes that
  89        indicates which eventsthe client wishes to receive\&.
  90        These event classes must have beenobtained specifying
  91        the device being grabbed\&.
  92 .fi
  93 .sp
  94 .nf
  95 this_device_mode
  96        Specifies further processing of events from this
  97        device\&.You can pass GrabModeSyncor GrabModeAsync\&.
  98 .fi
  99 .sp
 100 .nf
 101 other_devices_mode
 102        Specifies further processing of events from other
 103        devices\&.You can pass GrabModeSyncor GrabModeAsync\&.
 104 .fi
 105 .sp
 106 .nf
 107 time
 108        Specifies the time\&.You can pass either a timestamp or
 109        CurrentTime\&.
 110 .fi
 111 .SH "DESCRIPTION"
 112 .sp
 113 .if n \{\
 114 .RS 4
 115 .\}
 116 .nf
 117 The XGrabDevice request actively grabs control of the device
 118 and generates DeviceFocusIn and DeviceFocusOut events\&. Further
 119 device events are reported only to the grabbing
 120 client\&.XGrabDevice overrides any active device grab by this
 121 client\&. event_list is a pointer to a list of event classes\&.
 122 This list indicates which events the client wishes to receive
 123 while the grab is active\&. If owner_events is False, all
 124 generated device events are reported with respect to
 125 grab_window if selected\&. If owner_events is True and if a
 126 generated device event would normally be reported to this
 127 client, it is reported normally; otherwise, the event is
 128 reported with respect to the grab_window, and is only reported
 129 if specified in the event_list\&.
 130 .fi
 131 .if n \{\
 132 .RE
 133 .\}
 134 .sp
 135 .if n \{\
 136 .RS 4
 137 .\}
 138 .nf
 139 If the this_device_mode argument is GrabModeAsync, device event
 140 processing continues as usual\&. If the device is currently
 141 frozen by this client, then processing of device events is
 142 resumed\&. If the this_device_mode argument is GrabModeSync, the
 143 state of the device (as seen by client applications) appears to
 144 freeze, and the X server generates no further device events
 145 until the grabbing client issues a releasing XAllowDeviceEvents
 146 call or until the device grab is released\&. Actual device
 147 changes are not lost while the device is frozen; they are
 148 simply queued in the server for later processing\&.
 149 .fi
 150 .if n \{\
 151 .RE
 152 .\}
 153 .sp
 154 .if n \{\
 155 .RS 4
 156 .\}
 157 .nf
 158 If other_devices_mode is GrabModeAsync, processing of events
 159 from other devices is unaffected by activation of the grab\&. If
 160 other_devices_mode is GrabModeSync, the state of all devices
 161 except the grabbed device (as seen by client applications)
 162 appears to freeze, and the X server generates no further events
 163 from those devices until the grabbing client issues a releasing
 164 XAllowDeviceEvents call or until the device grab is released\&.
 165 Actual events are not lost while the devices are frozen; they
 166 are simply queued in the server for later processing\&.
 167 .fi
 168 .if n \{\
 169 .RE
 170 .\}
 171 .sp
 172 .if n \{\
 173 .RS 4
 174 .\}
 175 .nf
 176 If the device is actively grabbed by some other client,
 177 XGrabDevice fails and returns AlreadyGrabbed\&. If grab_window is
 178 not viewable, it fails and returns GrabNotViewable\&. If the
 179 device is frozen by an active grab of another client, it fails
 180 and returns GrabFrozen\&. If the specified time is earlier than
 181 the last\-device\-grab time or later than the current X server
 182 time, it fails and returns GrabInvalidTime\&. Otherwise, the
 183 last\-device\-grab time is set to the specified time (
 184 CurrentTime is replaced by the current X server time)\&.
 185 .fi
 186 .if n \{\
 187 .RE
 188 .\}
 189 .sp
 190 .if n \{\
 191 .RS 4
 192 .\}
 193 .nf
 194 If a grabbed device is closed by a client while an active grab
 195 by that client is in effect, the active grab is released\&. If
 196 the device is frozen only by an active grab of the requesting
 197 client, it is thawed\&.
 198 .fi
 199 .if n \{\
 200 .RE
 201 .\}
 202 .sp
 203 .if n \{\
 204 .RS 4
 205 .\}
 206 .nf
 207 XGrabDevice can generate BadClass, BadDevice, BadValue, and
 208 BadWindow errors\&.
 209 .fi
 210 .if n \{\
 211 .RE
 212 .\}
 213 .sp
 214 .if n \{\
 215 .RS 4
 216 .\}
 217 .nf
 218 The XUngrabDevice request releases the device and any queued
 219 events if this client has it actively grabbed from either
 220 XGrabDevice or XGrabDeviceKey\&. If other devices are frozen by
 221 the grab, XUngrabDevice thaws them\&.XUngrabDevice does not
 222 release the device and any queued events if the specified time
 223 is earlier than the last\-device\-grab time or is later than the
 224 current X server time\&. It also generates DeviceFocusIn and
 225 DeviceFocusOut events\&. The X server automatically performs an
 226 UngrabDevice request if the event window for an active device
 227 grab becomes not viewable\&.
 228 .fi
 229 .if n \{\
 230 .RE
 231 .\}
 232 .sp
 233 .if n \{\
 234 .RS 4
 235 .\}
 236 .nf
 237 XUngrabDevice can generate a BadDevice error\&.
 238 .fi
 239 .if n \{\
 240 .RE
 241 .\}
 242 .SH "DIAGNOSTICS"
 243 .sp
 244 .if n \{\
 245 .RS 4
 246 .\}
 247 .nf
 248 BadDevice
 249        An invalid device was specified\&. The specified device
 250        does not exist or has not been opened by this client via
 251        XOpenInputDevice\&. This error may also occur if the
 252        specified device is the X keyboard or X pointer device\&.
 253 .fi
 254 .if n \{\
 255 .RE
 256 .\}
 257 .sp
 258 .if n \{\
 259 .RS 4
 260 .\}
 261 .nf
 262 BadValue
 263        Some numeric value falls outside the range of values
 264        accepted by the request\&. Unless a specific range is
 265        specified for an argument, the full range defined by the
 266        argument\*(Aqs type is accepted\&. Any argument defined as a
 267        set of alternatives can generate this error\&.
 268 .fi
 269 .if n \{\
 270 .RE
 271 .\}
 272 .sp
 273 .if n \{\
 274 .RS 4
 275 .\}
 276 .nf
 277 BadWindow
 278        A value for a Window argument does not name a defined
 279        Window\&.
 280 .fi
 281 .if n \{\
 282 .RE
 283 .\}
 284 .SH "SEE ALSO"
 285 .sp
 286 .if n \{\
 287 .RS 4
 288 .\}
 289 .nf
 290 XAllowDeviceEvents(libmansuffix), XGrabDeviceButton(libmansuffix), XGrabDeviceKey(libmansuffix)
 291 .fi
 292 .if n \{\
 293 .RE
 294 .\}