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

NAME

6       XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode,
7       XIGrabTouchBegin, XIUngrabTouchBegin - grab/ungrab buttons or keys
8

SYNOPSIS

10       #include <X11/extensions/XInput2.h>
11
12       int XIGrabButton( Display *display,
13                         int deviceid,
14                         int button,
15                         Window grab_window,
16                         Cursor cursor,
17                         int grab_mode,
18                         int paired_device_mode,
19                         Bool owner_events,
20                         XIEventMask *mask,
21                         int num_modifiers,
22                         XIGrabModifiers *modifiers_inout);
23
24       int XIUngrabButton( Display *display,
25                           int deviceid,
26                           int button,
27                           Window grab_window,
28                           int num_modifiers,
29                           XIGrabModifiers *modifiers);
30
31       int XIGrabKeycode( Display *display,
32                          int deviceid,
33                          int keycode,
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 XIUngrabKeycode( Display *display,
43                            int deviceid,
44                            int keycode,
45                            Window grab_window,
46                            int num_modifiers,
47                            XIGrabModifiers *modifiers);
48
49       int XIGrabTouchBegin( Display *display,
50                             int deviceid,
51                             Window grab_window,
52                             Bool owner_events,
53                             XIEventMask *mask,
54                             int num_modifiers,
55                             XIGrabModifiers *modifiers_inout);
56
57       int XIUngrabTouchBegin( Display *display,
58                               int deviceid,
59                               Window grab_window,
60                               int num_modifiers,
61                               XIGrabModifiers *modifiers);
62
63       display
64              Specifies the connection to the X server.
65
66       device
67              Specifies the device that is to be grabbed or released
68
69       button
70              Specifies the device button that is to be grabbed or
71              released or XIAnyButton.
72
73       keycode
74              Specifies the keycode that is to be grabbed or released
75              or XIAnyKeycode.
76
77       num_modifiers
78              Number of elements in modifiers or modifiers_inout.
79
80       modifiers
81              Specifies the set of latched and base modifiers or
82              XIAnyModifier to ungrab. The data type is for
83              consistency with the respective grab request and the
84              status code of the XIGrabModifiers struct is ignored.
85
86       modifiers_inout
87              Specifies the set of latched and base modifiers or
88              XIAnyModifier to grab. Returns the modifiers that could
89              not be grabbed and their error code.
90
91       grab_window
92              Specifies the grab window.
93
94       owner_events
95              Specifies a Boolean value that indicates whether the are
96              to be reported as usual or reported with respect to the
97              grab window.
98
99       mask
100              Specifies the event mask.
101
102       grab_mode
103              Specifies further processing of events from this device.
104              You can pass XIGrabModeSync or XIGrabModeAsync.
105
106       paired_device_mode
107              Specifies further processing of events from the paired
108              master device. You can pass XIGrabModeSync or
109              XIGrabModeAsync. If deviceid specifies a floating slave
110              device, this parameter is ignored.
111

DESCRIPTION

113           XIGrabButton, XIGrabKeycode and XIGrabTouchBegin establish a passive
114           grab. The modifier device for a button grab is the paired master device
115           if deviceid specifies a master pointer. Otherwise, the modifier
116           device is the device specified with deviceid. In the future,
117           the device is actively grabbed (as for XIGrabDevice, the
118           last-grab time is set to the time at which the button or keycode
119           was pressed and the XI_ButtonPress or XI_KeyPress event is
120           reported if all of the following conditions are true:
121             * The device is not grabbed, and the specified button or
122               keycode is logically pressed or a touch event occurs when the
123               specified modifier keys are logically down on the modifier device
124               and no other buttons or modifier keys are logically down.
125             * Either the grab window is an ancestor of (or is) the focus
126               window, OR the grab window is a descendent of the focus
127               window and contains the device.
128             * A passive grab on the same button/modifier combination does
129               not exist on any ancestor of grab_window.
130
131           The interpretation of the remaining arguments is as for
132           XIGrabDevice. The active grab is terminated automatically when
133           the logical state of the device has all buttons or keys
134           released (independent of the logical state of the modifier
135           keys).
136
137           If the device is an attached slave device, the device is
138           automatically detached from the master device when the grab
139           activates and reattached to the same master device when the
140           grab deactivates. If the master device is removed while the
141           device is floating as a result of a grab, the device remains
142           floating once the grab deactivates.
143
144           Note that the logical state of a device (as seen by client
145           applications) may lag the physical state if device event
146           processing is frozen.
147
148           This request overrides all previous grabs by the same client on
149           the same button/modifier or keycode/modifier combinations on the
150           same window. A modifiers of XIAnyModifier is equivalent to
151           issuing the grab request for all possible modifier combinations
152           (including the combination of no modifiers). It is not required
153           that all modifiers specified have currently assigned KeyCodes.
154           A button of XIAnyButton is equivalent to issuing the request
155           for all possible buttons. Otherwise, it is not required that
156           the specified button currently be assigned to a physical
157           button.
158
159           If some other client has already issued a XIGrabButton or
160           XIGrabKeycode with the same button/modifier or keycode/modifier
161           combination on the same window, a BadAccess error results. When
162           using XIAnyModifier or XIAnyButton , the request fails
163           completely, and a XIBadAccess error results (no grabs are
164           established) if there is a conflicting grab for any
165           combination. XIGrabButton and XIGrabKeycode have no effect on an
166           active grab.
167
168           On success, XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return 0;
169           If one or more modifier combinations could not be grabbed,
170           XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return the number of
171           failed combinations and modifiers_inout contains the failed combinations
172           and their respective error codes.
173
174           XIGrabButton, XIGrabKeycode and XIGrabTouchBegin can generate BadClass,
175           BadDevice, BadMatch, BadValue, and BadWindow errors.
176
177           XIUngrabButton, XIUngrabKeycode and XIUngrabTouchBegin release the
178           passive grab for a button/modifier, keycode/modifier or touch/modifier
179           combination on the specified window if it was grabbed by this client. A
180           modifier of XIAnyModifier is equivalent to issuing the ungrab request
181           for all possible modifier combinations, including the
182           combination of no modifiers. A button of XIAnyButton is
183           equivalent to issuing the request for all possible buttons.
184           XIUngrabButton and XIUngrabKeycode have no effect on an active
185           grab.
186
187           XIUngrabButton, XIUngrabKeycode and XIUngrabTouchBegin can generate
188           BadDevice, BadMatch, BadValue and BadWindow errors.
189

RETURN VALUE

191           XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return the number of
192           modifier combination that could not establish a passive grab. The
193           modifiers are returned in modifiers_inout, along with the respective
194           error for this modifier combination. If XIGrabButton, XIGrabKeycode
195           or XIGrabTouchBegin return zero, passive grabs with all requested
196           modifier combinations were established successfully.
197

DIAGNOSTICS

199           BadDevice
200                  An invalid deviceid was specified.
201
202           BadMatch
203                  This error may occur if XIGrabButton specified a device
204                  that has no buttons, or XIGrabKeycode specified a device
205                  that has no keys, or XIGrabTouchBegin specified a device
206                  that is not touch-capable.
207
208           BadValue
209                  Some numeric value falls outside the range of values
210                  accepted by the request. Unless a specific range is
211                  specified for an argument, the full range defined by the
212                  argument's type is accepted. Any argument defined as a
213                  set of alternatives can generate this error.
214
215           BadWindow
216                  A value for a Window argument does not name a defined
217                  Window.
218

BUGS

220           The protocol headers for XI 2.0 did not provide
221           XIGrabModeAsync or XIGrabModeSync. Use GrabModeSync and
222           GrabModeAsync instead, respectively.
223

SEE ALSO

225           XIAllowEvents(3)
226
227
228
229                                  03/09/2013                   XIGRABBUTTON(3)
Impressum