man/XIGrabButton.man

   1 '\" t
   2 .\"     Title: xigrabbutton
   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/22/2011
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "XIGRABBUTTON" "libmansuffix" "12/22/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 XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode \- grab/ungrab buttons or keys
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput2\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 int XIGrabButton( Display *display,
  40                   int deviceid,
  41                   int button,
  42                   Window grab_window,
  43                   Cursor cursor,
  44                   int grab_mode,
  45                   int paired_device_mode,
  46                   Bool owner_events,
  47                   XIEventMask *mask,
  48                   int num_modifiers,
  49                   XIGrabModifiers *modifiers_inout);
  50 .fi
  51 .sp
  52 .nf
  53 int XIUngrabButton( Display *display,
  54                     int deviceid,
  55                     int button,
  56                     Window grab_window,
  57                     int num_modifiers,
  58                     XIGrabModifiers *modifiers);
  59 .fi
  60 .sp
  61 .nf
  62 int XIGrabKeycode( Display *display,
  63                    int deviceid,
  64                    int keycode,
  65                    Window grab_window,
  66                    int grab_mode,
  67                    int paired_device_mode,
  68                    Bool owner_events,
  69                    XIEventMask *mask,
  70                    int num_modifiers,
  71                    XIGrabModifiers *modifiers_inout);
  72 .fi
  73 .sp
  74 .nf
  75 int XIUngrabKeycode( Display *display,
  76                      int deviceid,
  77                      int keycode,
  78                      Window grab_window,
  79                      int num_modifiers,
  80                      XIGrabModifiers *modifiers);
  81 .fi
  82 .sp
  83 .nf
  84 int XIGrabTouchBegin( Display *display,
  85                       int deviceid,
  86                       Window grab_window,
  87                       Bool owner_events,
  88                       XIEventMask *mask,
  89                       int num_modifiers,
  90                       XIGrabModifiers *modifiers_inout);
  91 .fi
  92 .sp
  93 .nf
  94 int XIUngrabTouchBegin( Display *display,
  95                         int deviceid,
  96                         Window grab_window,
  97                         int num_modifiers,
  98                         XIGrabModifiers *modifiers);
  99 .fi
 100 .sp
 101 .nf
 102 display
 103        Specifies the connection to the X server\&.
 104 .fi
 105 .sp
 106 .nf
 107 device
 108        Specifies the device that is to be grabbed or released
 109 .fi
 110 .sp
 111 .nf
 112 button
 113        Specifies the device button that is to be grabbed or
 114        released or XIAnyButton\&.
 115 .fi
 116 .sp
 117 .nf
 118 keycode
 119        Specifies the keycode that is to be grabbed or released
 120        or XIAnyKeycode\&.
 121 .fi
 122 .sp
 123 .nf
 124 num_modifiers
 125        Number of elements in modifiers or modifiers_inout\&.
 126 .fi
 127 .sp
 128 .nf
 129 modifiers
 130        Specifies the set of latched and base modifiers or
 131        XIAnyModifier to ungrab\&. The data type is for
 132        consistency with the respective grab request and the
 133        status code of the XIGrabModifiers struct is ignored\&.
 134 .fi
 135 .sp
 136 .nf
 137 modifiers_inout
 138        Specifies the set of latched and base modifiers or
 139        XIAnyModifier to grab\&. Returns the modifiers that could
 140        not be grabbed and their error code\&.
 141 .fi
 142 .sp
 143 .nf
 144 grab_window
 145        Specifies the grab window\&.
 146 .fi
 147 .sp
 148 .nf
 149 owner_events
 150        Specifies a Boolean value that indicates whether the are
 151        to be reported as usual or reported with respect to the
 152        grab window\&.
 153 .fi
 154 .sp
 155 .nf
 156 mask
 157        Specifies the event mask\&.
 158 .fi
 159 .sp
 160 .nf
 161 grab_mode
 162        Specifies further processing of events from this device\&.
 163        You can pass XIGrabModeSync or XIGrabModeAsync\&.
 164 .fi
 165 .sp
 166 .nf
 167 paired_device_mode
 168        Specifies further processing of events from the paired
 169        master device\&. You can pass XIGrabModeSync or
 170        XIGrabModeAsync\&. If deviceid specifies a floating slave
 171        device, this parameter is ignored\&.
 172 .fi
 173 .SH "DESCRIPTION"
 174 .sp
 175 .if n \{\
 176 .RS 4
 177 .\}
 178 .nf
 179 XIGrabButton, XIGrabKeycode and XIGrabTouchBegin establish a passive
 180 grab\&. The modifier device for a button grab is the paired master device
 181 if deviceid specifies a master pointer\&. Otherwise, the modifier
 182 device is the device specified with deviceid\&. In the future,
 183 the device is actively grabbed (as for XIGrabDevice, the
 184 last\-grab time is set to the time at which the button or keycode
 185 was pressed and the XI_ButtonPress or XI_KeyPress event is
 186 reported if all of the following conditions are true:
 187   * The device is not grabbed, and the specified button or
 188     keycode is logically pressed or a touch event occurs when the
 189     specified modifier keys are logically down on the modifier device
 190     and no other buttons or modifier keys are logically down\&.
 191   * Either the grab window is an ancestor of (or is) the focus
 192     window, OR the grab window is a descendent of the focus
 193     window and contains the device\&.
 194   * A passive grab on the same button/modifier combination does
 195     not exist on any ancestor of grab_window\&.
 196 .fi
 197 .if n \{\
 198 .RE
 199 .\}
 200 .sp
 201 .if n \{\
 202 .RS 4
 203 .\}
 204 .nf
 205 The interpretation of the remaining arguments is as for
 206 XIGrabDevice\&. The active grab is terminated automatically when
 207 the logical state of the device has all buttons or keys
 208 released (independent of the logical state of the modifier
 209 keys)\&.
 210 .fi
 211 .if n \{\
 212 .RE
 213 .\}
 214 .sp
 215 .if n \{\
 216 .RS 4
 217 .\}
 218 .nf
 219 If the device is an attached slave device, the device is
 220 automatically detached from the master device when the grab
 221 activates and reattached to the same master device when the
 222 grab deactivates\&. If the master device is removed while the
 223 device is floating as a result of a grab, the device remains
 224 floating once the grab deactivates\&.
 225 .fi
 226 .if n \{\
 227 .RE
 228 .\}
 229 .sp
 230 .if n \{\
 231 .RS 4
 232 .\}
 233 .nf
 234 Note that the logical state of a device (as seen by client
 235 applications) may lag the physical state if device event
 236 processing is frozen\&.
 237 .fi
 238 .if n \{\
 239 .RE
 240 .\}
 241 .sp
 242 .if n \{\
 243 .RS 4
 244 .\}
 245 .nf
 246 This request overrides all previous grabs by the same client on
 247 the same button/modifier or keycode/modifier combinations on the
 248 same window\&. A modifiers of XIAnyModifier is equivalent to
 249 issuing the grab request for all possible modifier combinations
 250 (including the combination of no modifiers)\&. It is not required
 251 that all modifiers specified have currently assigned KeyCodes\&.
 252 A button of XIAnyButton is equivalent to issuing the request
 253 for all possible buttons\&. Otherwise, it is not required that
 254 the specified button currently be assigned to a physical
 255 button\&.
 256 .fi
 257 .if n \{\
 258 .RE
 259 .\}
 260 .sp
 261 .if n \{\
 262 .RS 4
 263 .\}
 264 .nf
 265 If some other client has already issued a XIGrabButton or
 266 XIGrabKeycode with the same button/modifier or keycode/modifier
 267 combination on the same window, a BadAccess error results\&. When
 268 using XIAnyModifier or XIAnyButton , the request fails
 269 completely, and a XIBadAccess error results (no grabs are
 270 established) if there is a conflicting grab for any
 271 combination\&. XIGrabButton and XIGrabKeycode have no effect on an
 272 active grab\&.
 273 .fi
 274 .if n \{\
 275 .RE
 276 .\}
 277 .sp
 278 .if n \{\
 279 .RS 4
 280 .\}
 281 .nf
 282 On success, XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return 0;
 283 If one or more modifier combinations could not be grabbed,
 284 XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return the number of
 285 failed combinations and modifiers_inout contains the failed combinations
 286 and their respective error codes\&.
 287 .fi
 288 .if n \{\
 289 .RE
 290 .\}
 291 .sp
 292 .if n \{\
 293 .RS 4
 294 .\}
 295 .nf
 296 XIGrabButton, XIGrabKeycode and XIGrabTouchBegin can generate BadClass,
 297 BadDevice, BadMatch, BadValue, and BadWindow errors\&.
 298 .fi
 299 .if n \{\
 300 .RE
 301 .\}
 302 .sp
 303 .if n \{\
 304 .RS 4
 305 .\}
 306 .nf
 307 XIUngrabButton, XIUngrabKeycode and XIUngrabTouchBegin release the
 308 passive grab for a button/modifier, keycode/modifier or touch/modifier
 309 combination on the specified window if it was grabbed by this client\&. A
 310 modifier of XIAnyModifier is equivalent to issuing the ungrab request
 311 for all possible modifier combinations, including the
 312 combination of no modifiers\&. A button of XIAnyButton is
 313 equivalent to issuing the request for all possible buttons\&.
 314 XIUngrabButton and XIUngrabKeycode have no effect on an active
 315 grab\&.
 316 .fi
 317 .if n \{\
 318 .RE
 319 .\}
 320 .sp
 321 .if n \{\
 322 .RS 4
 323 .\}
 324 .nf
 325 XIUngrabButton, XIUngrabKeycode and XIUngrabTouchBegin can generate
 326 BadDevice, BadMatch, BadValue and BadWindow errors\&.
 327 .fi
 328 .if n \{\
 329 .RE
 330 .\}
 331 .SH "RETURN VALUE"
 332 .sp
 333 .if n \{\
 334 .RS 4
 335 .\}
 336 .nf
 337 XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return the number of
 338 modifier combination that could not establish a passive grab\&. The
 339 modifiers are returned in modifiers_inout, along with the respective
 340 error for this modifier combination\&. If XIGrabButton, XIGrabKeycode
 341 or XIGrabTouchBegin return zero, passive grabs with all requested
 342 modifier combinations were established successfully\&.
 343 .fi
 344 .if n \{\
 345 .RE
 346 .\}
 347 .SH "DIAGNOSTICS"
 348 .sp
 349 .if n \{\
 350 .RS 4
 351 .\}
 352 .nf
 353 BadDevice
 354        An invalid deviceid was specified\&.
 355 .fi
 356 .if n \{\
 357 .RE
 358 .\}
 359 .sp
 360 .if n \{\
 361 .RS 4
 362 .\}
 363 .nf
 364 BadMatch
 365        This error may occur if XIGrabButton specified a device
 366        that has no buttons, or XIGrabKeycode specified a device
 367        that has no keys, or XIGrabTouchBegin specified a device
 368        that is not touch\-capable\&.
 369 .fi
 370 .if n \{\
 371 .RE
 372 .\}
 373 .sp
 374 .if n \{\
 375 .RS 4
 376 .\}
 377 .nf
 378 BadValue
 379        Some numeric value falls outside the range of values
 380        accepted by the request\&. Unless a specific range is
 381        specified for an argument, the full range defined by the
 382        argument\*(Aqs type is accepted\&. Any argument defined as a
 383        set of alternatives can generate this error\&.
 384 .fi
 385 .if n \{\
 386 .RE
 387 .\}
 388 .sp
 389 .if n \{\
 390 .RS 4
 391 .\}
 392 .nf
 393 BadWindow
 394        A value for a Window argument does not name a defined
 395        Window\&.
 396 .fi
 397 .if n \{\
 398 .RE
 399 .\}
 400 .SH "BUGS"
 401 .sp
 402 .if n \{\
 403 .RS 4
 404 .\}
 405 .nf
 406 The protocol headers for XI 2\&.0 did not provide
 407 XIGrabModeAsync or XIGrabModeSync\&. Use GrabModeSync and
 408 GrabModeAsync instead, respectively\&.
 409 .fi
 410 .if n \{\
 411 .RE
 412 .\}
 413 .SH "SEE ALSO"
 414 .sp
 415 .if n \{\
 416 .RS 4
 417 .\}
 418 .nf
 419 XIAllowEvents(libmansuffix)
 420 .fi
 421 .if n \{\
 422 .RE
 423 .\}