man/XIGrabEnter.man

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