man/XIGrabButton.txt

   1 XIGRABBUTTON(libmansuffix)
   2 ==========================
   3
   4 NAME
   5 ----
   6
   7    XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode -
   8    grab/ungrab buttons or keys
   9
  10 SYNOPSIS
  11 --------
  12
  13    #include <X11/extensions/XInput2.h>
  14
  15    int XIGrabButton( Display *display,
  16                      int deviceid,
  17                      int button,
  18                      Window grab_window,
  19                      Cursor cursor,
  20                      int grab_mode,
  21                      int paired_device_mode,
  22                      Bool owner_events,
  23                      XIEventMask *mask,
  24                      int num_modifiers,
  25                      XIGrabModifiers *modifiers_inout);
  26
  27    int XIUngrabButton( Display *display,
  28                        int deviceid,
  29                        int button,
  30                        Window grab_window,
  31                        int num_modifiers,
  32                        XIGrabModifiers *modifiers);
  33
  34    int XIGrabKeycode( Display *display,
  35                       int deviceid,
  36                       int keycode,
  37                       Window grab_window,
  38                       int grab_mode,
  39                       int paired_device_mode,
  40                       Bool owner_events,
  41                       XIEventMask *mask,
  42                       int num_modifiers,
  43                       XIGrabModifiers *modifiers_inout);
  44
  45    int XIUngrabKeycode( Display *display,
  46                         int deviceid,
  47                         int keycode,
  48                         Window grab_window,
  49                         int num_modifiers,
  50                         XIGrabModifiers *modifiers);
  51
  52    int XIGrabTouchBegin( Display *display,
  53                          int deviceid,
  54                          Window grab_window,
  55                          Bool owner_events,
  56                          XIEventMask *mask,
  57                          int num_modifiers,
  58                          XIGrabModifiers *modifiers_inout);
  59
  60    int XIUngrabTouchBegin( Display *display,
  61                            int deviceid,
  62                            Window grab_window,
  63                            int num_modifiers,
  64                            XIGrabModifiers *modifiers);
  65
  66    display
  67           Specifies the connection to the X server.
  68
  69    device
  70           Specifies the device that is to be grabbed or released
  71
  72    button
  73           Specifies the device button that is to be grabbed or
  74           released or XIAnyButton.
  75
  76    keycode
  77           Specifies the keycode that is to be grabbed or released
  78           or XIAnyKeycode.
  79
  80    num_modifiers
  81           Number of elements in modifiers or modifiers_inout.
  82
  83    modifiers
  84           Specifies the set of latched and base modifiers or
  85           XIAnyModifier to ungrab. The data type is for
  86           consistency with the respective grab request and the
  87           status code of the XIGrabModifiers struct is ignored.
  88
  89    modifiers_inout
  90           Specifies the set of latched and base modifiers or
  91           XIAnyModifier to grab. Returns the modifiers that could
  92           not be grabbed and their error code.
  93
  94    grab_window
  95           Specifies the grab window.
  96
  97    owner_events
  98           Specifies a Boolean value that indicates whether the are
  99           to be reported as usual or reported with respect to the
 100           grab window.
 101
 102    mask
 103           Specifies the event mask.
 104
 105    grab_mode
 106           Specifies further processing of events from this device.
 107           You can pass XIGrabModeSync or XIGrabModeAsync.
 108
 109    paired_device_mode
 110           Specifies further processing of events from the paired
 111           master device. You can pass XIGrabModeSync or
 112           XIGrabModeAsync. If deviceid specifies a floating slave
 113           device, this parameter is ignored.
 114
 115 DESCRIPTION
 116 -----------
 117
 118    XIGrabButton, XIGrabKeycode and XIGrabTouchBegin establish a passive
 119    grab. The modifier device for a button grab is the paired master device
 120    if deviceid specifies a master pointer. Otherwise, the modifier
 121    device is the device specified with deviceid. In the future,
 122    the device is actively grabbed (as for XIGrabDevice, the
 123    last-grab time is set to the time at which the button or keycode
 124    was pressed and the XI_ButtonPress or XI_KeyPress event is
 125    reported if all of the following conditions are true:
 126      * The device is not grabbed, and the specified button or
 127        keycode is logically pressed or a touch event occurs when the
 128        specified modifier keys are logically down on the modifier device
 129        and no other buttons or modifier keys are logically down.
 130      * Either the grab window is an ancestor of (or is) the focus
 131        window, OR the grab window is a descendent of the focus
 132        window and contains the device.
 133      * A passive grab on the same button/modifier combination does
 134        not exist on any ancestor of grab_window.
 135
 136    The interpretation of the remaining arguments is as for
 137    XIGrabDevice. The active grab is terminated automatically when
 138    the logical state of the device has all buttons or keys
 139    released (independent of the logical state of the modifier
 140    keys).
 141
 142    If the device is an attached slave device, the device is
 143    automatically detached from the master device when the grab
 144    activates and reattached to the same master device when the
 145    grab deactivates. If the master device is removed while the
 146    device is floating as a result of a grab, the device remains
 147    floating once the grab deactivates.
 148
 149    Note that the logical state of a device (as seen by client
 150    applications) may lag the physical state if device event
 151    processing is frozen.
 152
 153    This request overrides all previous grabs by the same client on
 154    the same button/modifier or keycode/modifier combinations on the
 155    same window. A modifiers of XIAnyModifier is equivalent to
 156    issuing the grab request for all possible modifier combinations
 157    (including the combination of no modifiers). It is not required
 158    that all modifiers specified have currently assigned KeyCodes.
 159    A button of XIAnyButton is equivalent to issuing the request
 160    for all possible buttons. Otherwise, it is not required that
 161    the specified button currently be assigned to a physical
 162    button.
 163
 164    If some other client has already issued a XIGrabButton or
 165    XIGrabKeycode with the same button/modifier or keycode/modifier
 166    combination on the same window, a BadAccess error results. When
 167    using XIAnyModifier or XIAnyButton , the request fails
 168    completely, and a XIBadAccess error results (no grabs are
 169    established) if there is a conflicting grab for any
 170    combination. XIGrabButton and XIGrabKeycode have no effect on an
 171    active grab.
 172
 173    On success, XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return 0;
 174    If one or more modifier combinations could not be grabbed,
 175    XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return the number of
 176    failed combinations and modifiers_inout contains the failed combinations
 177    and their respective error codes.
 178
 179    XIGrabButton, XIGrabKeycode and XIGrabTouchBegin can generate BadClass,
 180    BadDevice, BadMatch, BadValue, and BadWindow errors.
 181
 182    XIUngrabButton, XIUngrabKeycode and XIUngrabTouchBegin release the
 183    passive grab for a button/modifier, keycode/modifier or touch/modifier
 184    combination on the specified window if it was grabbed by this client. A
 185    modifier of XIAnyModifier is equivalent to issuing the ungrab request
 186    for all possible modifier combinations, including the
 187    combination of no modifiers. A button of XIAnyButton is
 188    equivalent to issuing the request for all possible buttons.
 189    XIUngrabButton and XIUngrabKeycode have no effect on an active
 190    grab.
 191
 192    XIUngrabButton, XIUngrabKeycode and XIUngrabTouchBegin can generate
 193    BadDevice, BadMatch, BadValue and BadWindow errors.
 194
 195 RETURN VALUE
 196 ------------
 197    XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return the number of
 198    modifier combination that could not establish a passive grab. The
 199    modifiers are returned in modifiers_inout, along with the respective
 200    error for this modifier combination. If XIGrabButton, XIGrabKeycode
 201    or XIGrabTouchBegin return zero, passive grabs with all requested
 202    modifier combinations were established successfully.
 203
 204 DIAGNOSTICS
 205 -----------
 206
 207    BadDevice
 208           An invalid deviceid was specified.
 209
 210    BadMatch
 211           This error may occur if XIGrabButton specified a device
 212           that has no buttons, or XIGrabKeycode specified a device
 213           that has no keys, or XIGrabTouchBegin specified a device
 214           that is not touch-capable.
 215
 216    BadValue
 217           Some numeric value falls outside the range of values
 218           accepted by the request. Unless a specific range is
 219           specified for an argument, the full range defined by the
 220           argument's type is accepted. Any argument defined as a
 221           set of alternatives can generate this error.
 222
 223    BadWindow
 224           A value for a Window argument does not name a defined
 225           Window.
 226
 227 BUGS
 228 ----
 229
 230    The protocol headers for XI 2.0 did not provide
 231    XIGrabModeAsync or XIGrabModeSync. Use GrabModeSync and
 232    GrabModeAsync instead, respectively.
 233
 234 SEE ALSO
 235 --------
 236
 237    XIAllowEvents(libmansuffix)
 238