man/XIGrabEnter.txt

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