1XIGRABBUTTON(3) XIGRABBUTTON(3)
2
6 XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode,
7 XIGrabTouchBegin, XIUngrabTouchBegin, XIGrabPinchGestureBegin,
8 XIUngrabPinchGestureBegin, XIGrabSwipeGestureBegin - grab/ungrab
9 buttons or keys
10
12 #include <X11/extensions/XInput2.h>
13 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 int XIUngrabButton( Display *display,
27 int deviceid,
28 int button,
29 Window grab_window,
30 int num_modifiers,
31 XIGrabModifiers *modifiers);
32 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 int XIUngrabKeycode( Display *display,
45 int deviceid,
46 int keycode,
47 Window grab_window,
48 int num_modifiers,
49 XIGrabModifiers *modifiers);
50 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 int XIUngrabTouchBegin( Display *display,
60 int deviceid,
61 Window grab_window,
62 int num_modifiers,
63 XIGrabModifiers *modifiers);
64 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 int XIUngrabPinchGestureBegin( Display* display,
76 int deviceid,
77 Window grab_window,
78 int num_modifiers,
79 XIGrabModifiers *modifiers);
80 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 int XIUngrabSwipeGestureBegin( Display* display,
92 int deviceid,
93 Window grab_window,
94 int num_modifiers,
95 XIGrabModifiers *modifiers);
96 display
98 Specifies the connection to the X server.
99 device
101 Specifies the device that is to be grabbed or released
102 button
104 Specifies the device button that is to be grabbed or
105 released or XIAnyButton.
106 keycode
108 Specifies the keycode that is to be grabbed or released
109 or XIAnyKeycode.
110 num_modifiers
112 Number of elements in modifiers or modifiers_inout.
113 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 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 grab_window
126 Specifies the grab window.
127 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 mask
134 Specifies the event mask.
135 grab_mode
137 Specifies further processing of events from this device.
138 You can pass XIGrabModeSync or XIGrabModeAsync.
139 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
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 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 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 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 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 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 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 XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin
212 and XIGrabSwipeGestureBegin can generate BadClass,
213 BadDevice, BadMatch, BadValue, and BadWindow errors.
214 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 XIUngrabButton, XIUngrabKeycode, XIUngrabTouchBegin,
227 XIUngrabPinchGestureBegin and XIUngrabSwipeGestureBegin can generate
228 BadDevice, BadMatch, BadValue and BadWindow errors.
229
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
240 BadDevice
241 An invalid deviceid was specified.
242 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 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 BadWindow
259 A value for a Window argument does not name a defined
260 Window.
261
263 The protocol headers for XI 2.0 did not provide
264 XIGrabModeAsync or XIGrabModeSync. Use GrabModeSync and
265 GrabModeAsync instead, respectively.
266
268 XIAllowEvents(3)
269 05/04/2023 XIGRABBUTTON(3)