1XIGRABBUTTON(3)                                                XIGRABBUTTON(3)
2
3
4

NAME

6       XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode,
7       XIGrabTouchBegin, XIUngrabTouchBegin, XIGrabPinchGestureBegin,
8       XIUngrabPinchGestureBegin, XIGrabSwipeGestureBegin - grab/ungrab
9       buttons or keys
10

SYNOPSIS

12       #include <X11/extensions/XInput2.h>
13
14       int XIGrabButton( Display *display,
15                         int deviceid,
16                         int button,
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 XIUngrabButton( Display *display,
27                           int deviceid,
28                           int button,
29                           Window grab_window,
30                           int num_modifiers,
31                           XIGrabModifiers *modifiers);
32
33       int XIGrabKeycode( Display *display,
34                          int deviceid,
35                          int keycode,
36                          Window grab_window,
37                          int grab_mode,
38                          int paired_device_mode,
39                          Bool owner_events,
40                          XIEventMask *mask,
41                          int num_modifiers,
42                          XIGrabModifiers *modifiers_inout);
43
44       int XIUngrabKeycode( Display *display,
45                            int deviceid,
46                            int keycode,
47                            Window grab_window,
48                            int num_modifiers,
49                            XIGrabModifiers *modifiers);
50
51       int XIGrabTouchBegin( Display *display,
52                             int deviceid,
53                             Window grab_window,
54                             Bool owner_events,
55                             XIEventMask *mask,
56                             int num_modifiers,
57                             XIGrabModifiers *modifiers_inout);
58
59       int XIUngrabTouchBegin( Display *display,
60                               int deviceid,
61                               Window grab_window,
62                               int num_modifiers,
63                               XIGrabModifiers *modifiers);
64
65       int XIGrabPinchGestureBegin( Display* display,
66                                    int deviceid,
67                                    Window grab_window,
68                                    int grab_mode,
69                                    int paired_device_mode,
70                                    int owner_events,
71                                    XIEventMask *mask,
72                                    int num_modifiers,
73                                    XIGrabModifiers *modifiers_inout);
74
75       int XIUngrabPinchGestureBegin( Display* display,
76                                      int deviceid,
77                                      Window grab_window,
78                                      int num_modifiers,
79                                      XIGrabModifiers *modifiers);
80
81       int XIGrabSwipeGestureBegin( Display* display,
82                                    int deviceid,
83                                    Window grab_window,
84                                    int grab_mode,
85                                    int paired_device_mode,
86                                    int owner_events,
87                                    XIEventMask *mask,
88                                    int num_modifiers,
89                                    XIGrabModifiers *modifiers_inout);
90
91       int XIUngrabSwipeGestureBegin( Display* display,
92                                      int deviceid,
93                                      Window grab_window,
94                                      int num_modifiers,
95                                      XIGrabModifiers *modifiers);
96
97       display
98              Specifies the connection to the X server.
99
100       device
101              Specifies the device that is to be grabbed or released
102
103       button
104              Specifies the device button that is to be grabbed or
105              released or XIAnyButton.
106
107       keycode
108              Specifies the keycode that is to be grabbed or released
109              or XIAnyKeycode.
110
111       num_modifiers
112              Number of elements in modifiers or modifiers_inout.
113
114       modifiers
115              Specifies the set of latched and base modifiers or
116              XIAnyModifier to ungrab. The data type is for
117              consistency with the respective grab request and the
118              status code of the XIGrabModifiers struct is ignored.
119
120       modifiers_inout
121              Specifies the set of latched and base modifiers or
122              XIAnyModifier to grab. Returns the modifiers that could
123              not be grabbed and their error code.
124
125       grab_window
126              Specifies the grab window.
127
128       owner_events
129              Specifies a Boolean value that indicates whether the are
130              to be reported as usual or reported with respect to the
131              grab window.
132
133       mask
134              Specifies the event mask.
135
136       grab_mode
137              Specifies further processing of events from this device.
138              You can pass XIGrabModeSync or XIGrabModeAsync.
139
140       paired_device_mode
141              Specifies further processing of events from the paired
142              master device. You can pass XIGrabModeSync or
143              XIGrabModeAsync. If deviceid specifies a floating slave
144              device, this parameter is ignored.
145

DESCRIPTION

147           XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin,
148           XIGrabSwipeTouchBegin establish a passive grab.
149           The modifier device for a button grab is the paired master device
150           if deviceid specifies a master pointer. Otherwise, the modifier
151           device is the device specified with deviceid. In the future,
152           the device is actively grabbed (as for XIGrabDevice, the
153           last-grab time is set to the time at which the button or keycode
154           was pressed and the XI_ButtonPress or XI_KeyPress event is
155           reported if all of the following conditions are true:
156             * The device is not grabbed, and the specified button or
157               keycode is logically pressed, a touch or a gesture event occurs when the
158               specified modifier keys are logically down on the modifier device
159               and no other buttons or modifier keys are logically down.
160             * Either the grab window is an ancestor of (or is) the focus
161               window, OR the grab window is a descendent of the focus
162               window and contains the device.
163             * A passive grab on the same button/modifier combination does
164               not exist on any ancestor of grab_window.
165
166           The interpretation of the remaining arguments is as for
167           XIGrabDevice. The active grab is terminated automatically when
168           the logical state of the device has all buttons or keys
169           released (independent of the logical state of the modifier
170           keys).
171
172           If the device is an attached slave device, the device is
173           automatically detached from the master device when the grab
174           activates and reattached to the same master device when the
175           grab deactivates. If the master device is removed while the
176           device is floating as a result of a grab, the device remains
177           floating once the grab deactivates.
178
179           Note that the logical state of a device (as seen by client
180           applications) may lag the physical state if device event
181           processing is frozen.
182
183           This request overrides all previous grabs by the same client on
184           the same button/modifier or keycode/modifier combinations on the
185           same window. A modifiers of XIAnyModifier is equivalent to
186           issuing the grab request for all possible modifier combinations
187           (including the combination of no modifiers). It is not required
188           that all modifiers specified have currently assigned KeyCodes.
189           A button of XIAnyButton is equivalent to issuing the request
190           for all possible buttons. Otherwise, it is not required that
191           the specified button currently be assigned to a physical
192           button.
193
194           If some other client has already issued a XIGrabButton or
195           XIGrabKeycode with the same button/modifier or keycode/modifier
196           combination on the same window, a BadAccess error results. When
197           using XIAnyModifier or XIAnyButton , the request fails
198           completely, and a XIBadAccess error results (no grabs are
199           established) if there is a conflicting grab for any
200           combination. XIGrabButton and XIGrabKeycode have no effect on an
201           active grab.
202
203           On success, XIGrabButton, XIGrabKeycode, XIGrabTouchBegin,
204           XIGrabPinchGestureBegin and XIGrabSwipeGestureBegin return 0;
205           If one or more modifier combinations could not be grabbed,
206           XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin
207           and XIGrabSwipeGestureBegin return the number of
208           failed combinations and modifiers_inout contains the failed combinations
209           and their respective error codes.
210
211           XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin
212           and XIGrabSwipeGestureBegin can generate BadClass,
213           BadDevice, BadMatch, BadValue, and BadWindow errors.
214
215           XIUngrabButton, XIUngrabKeycode, XIUngrabTouchBegin, XIUngrabPinchGestureBegin
216           and XIUngrabSwipeGestureBegin release the
217           passive grab for a button/modifier, keycode/modifier or touch/modifier
218           combination on the specified window if it was grabbed by this client. A
219           modifier of XIAnyModifier is equivalent to issuing the ungrab request
220           for all possible modifier combinations, including the
221           combination of no modifiers. A button of XIAnyButton is
222           equivalent to issuing the request for all possible buttons.
223           XIUngrabButton and XIUngrabKeycode have no effect on an active
224           grab.
225
226           XIUngrabButton, XIUngrabKeycode, XIUngrabTouchBegin,
227           XIUngrabPinchGestureBegin and XIUngrabSwipeGestureBegin can generate
228           BadDevice, BadMatch, BadValue and BadWindow errors.
229

RETURN VALUE

231           XIGrabButton, XIGrabKeycode, XIGrabTouchBegin and
232           XIGrabPinchGestureBegin and XIGrabSwipeGestureBegin return the number of
233           modifier combination that could not establish a passive grab. The
234           modifiers are returned in modifiers_inout, along with the respective
235           error for this modifier combination. If XIGrabButton, XIGrabKeycode
236           or XIGrabTouchBegin return zero, passive grabs with all requested
237           modifier combinations were established successfully.
238

DIAGNOSTICS

240           BadDevice
241                  An invalid deviceid was specified.
242
243           BadMatch
244                  This error may occur if XIGrabButton specified a device
245                  that has no buttons, or XIGrabKeycode specified a device
246                  that has no keys,
247                  or XIGrabTouchBegin specified a device that is not touch-capable,
248                  or XIGrabPinchGestureBegin specified a device that is not gesture-capable,
249                  or XIGrabSwipeGestureBegin specified a device that is not gesture-capable.
250
251           BadValue
252                  Some numeric value falls outside the range of values
253                  accepted by the request. Unless a specific range is
254                  specified for an argument, the full range defined by the
255                  argument's type is accepted. Any argument defined as a
256                  set of alternatives can generate this error.
257
258           BadWindow
259                  A value for a Window argument does not name a defined
260                  Window.
261

BUGS

263           The protocol headers for XI 2.0 did not provide
264           XIGrabModeAsync or XIGrabModeSync. Use GrabModeSync and
265           GrabModeAsync instead, respectively.
266

SEE ALSO

268           XIAllowEvents(3)
269
270
271
272                                  09/15/2021                   XIGRABBUTTON(3)
Impressum