1XIGRABBUTTON(libmansuffix)
2==========================
3
4NAME
5----
6
7   XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode, XIGrabTouchBegin, XIUngrabTouchBegin, XIGrabPinchGestureBegin, XIUngrabPinchGestureBegin, XIGrabSwipeGestureBegin, XIUngrabSwipeGestureBegin - grab/ungrab buttons or keys
8
9SYNOPSIS
10--------
11
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
146DESCRIPTION
147-----------
148
149   XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin,
150   XIGrabSwipeTouchBegin establish a passive grab.
151   The modifier device for a button grab is the paired master device
152   if deviceid specifies a master pointer. Otherwise, the modifier
153   device is the device specified with deviceid. In the future,
154   the device is actively grabbed (as for XIGrabDevice, the
155   last-grab time is set to the time at which the button or keycode
156   was pressed and the XI_ButtonPress or XI_KeyPress event is
157   reported if all of the following conditions are true:
158     * The device is not grabbed, and the specified button or
159       keycode is logically pressed, a touch or a gesture event occurs when the
160       specified modifier keys are logically down on the modifier device
161       and no other buttons or modifier keys are logically down.
162     * Either the grab window is an ancestor of (or is) the focus
163       window, OR the grab window is a descendent of the focus
164       window and contains the device.
165     * A passive grab on the same button/modifier combination does
166       not exist on any ancestor of grab_window.
167
168   The interpretation of the remaining arguments is as for
169   XIGrabDevice. The active grab is terminated automatically when
170   the logical state of the device has all buttons or keys
171   released (independent of the logical state of the modifier
172   keys).
173
174   If the device is an attached slave device, the device is
175   automatically detached from the master device when the grab
176   activates and reattached to the same master device when the
177   grab deactivates. If the master device is removed while the
178   device is floating as a result of a grab, the device remains
179   floating once the grab deactivates.
180
181   Note that the logical state of a device (as seen by client
182   applications) may lag the physical state if device event
183   processing is frozen.
184
185   This request overrides all previous grabs by the same client on
186   the same button/modifier or keycode/modifier combinations on the
187   same window. A modifiers of XIAnyModifier is equivalent to
188   issuing the grab request for all possible modifier combinations
189   (including the combination of no modifiers). It is not required
190   that all modifiers specified have currently assigned KeyCodes.
191   A button of XIAnyButton is equivalent to issuing the request
192   for all possible buttons. Otherwise, it is not required that
193   the specified button currently be assigned to a physical
194   button.
195
196   If some other client has already issued a XIGrabButton or
197   XIGrabKeycode with the same button/modifier or keycode/modifier
198   combination on the same window, a BadAccess error results. When
199   using XIAnyModifier or XIAnyButton , the request fails
200   completely, and a XIBadAccess error results (no grabs are
201   established) if there is a conflicting grab for any
202   combination. XIGrabButton and XIGrabKeycode have no effect on an
203   active grab.
204
205   On success, XIGrabButton, XIGrabKeycode, XIGrabTouchBegin,
206   XIGrabPinchGestureBegin and XIGrabSwipeGestureBegin return 0;
207   If one or more modifier combinations could not be grabbed,
208   XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin
209   and XIGrabSwipeGestureBegin return the number of
210   failed combinations and modifiers_inout contains the failed combinations
211   and their respective error codes.
212
213   XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin
214   and XIGrabSwipeGestureBegin can generate BadClass,
215   BadDevice, BadMatch, BadValue, and BadWindow errors.
216
217   XIUngrabButton, XIUngrabKeycode, XIUngrabTouchBegin, XIUngrabPinchGestureBegin
218   and XIUngrabSwipeGestureBegin release the
219   passive grab for a button/modifier, keycode/modifier or touch/modifier
220   combination on the specified window if it was grabbed by this client. A
221   modifier of XIAnyModifier is equivalent to issuing the ungrab request
222   for all possible modifier combinations, including the
223   combination of no modifiers. A button of XIAnyButton is
224   equivalent to issuing the request for all possible buttons.
225   XIUngrabButton and XIUngrabKeycode have no effect on an active
226   grab.
227
228   XIUngrabButton, XIUngrabKeycode, XIUngrabTouchBegin,
229   XIUngrabPinchGestureBegin and XIUngrabSwipeGestureBegin can generate
230   BadDevice, BadMatch, BadValue and BadWindow errors.
231
232RETURN VALUE
233------------
234   XIGrabButton, XIGrabKeycode, XIGrabTouchBegin and
235   XIGrabPinchGestureBegin and XIGrabSwipeGestureBegin return the number of
236   modifier combination that could not establish a passive grab. The
237   modifiers are returned in modifiers_inout, along with the respective
238   error for this modifier combination. If XIGrabButton, XIGrabKeycode
239   or XIGrabTouchBegin return zero, passive grabs with all requested
240   modifier combinations were established successfully.
241
242DIAGNOSTICS
243-----------
244
245   BadDevice
246          An invalid deviceid was specified.
247
248   BadMatch
249          This error may occur if XIGrabButton specified a device
250          that has no buttons, or XIGrabKeycode specified a device
251          that has no keys,
252          or XIGrabTouchBegin specified a device that is not touch-capable,
253          or XIGrabPinchGestureBegin specified a device that is not gesture-capable,
254          or XIGrabSwipeGestureBegin specified a device that is not gesture-capable.
255
256   BadValue
257          Some numeric value falls outside the range of values
258          accepted by the request. Unless a specific range is
259          specified for an argument, the full range defined by the
260          argument's type is accepted. Any argument defined as a
261          set of alternatives can generate this error.
262
263   BadWindow
264          A value for a Window argument does not name a defined
265          Window.
266
267BUGS
268----
269
270   The protocol headers for XI 2.0 did not provide
271   XIGrabModeAsync or XIGrabModeSync. Use GrabModeSync and
272   GrabModeAsync instead, respectively.
273
274SEE ALSO
275--------
276
277   XIAllowEvents(libmansuffix)
278
279