XIGrabButton.txt revision f1ee322d 
1XIGRABBUTTON(libmansuffix)
2==========================
3
4NAME
5----
6
7   XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode, XIGrabTouchBegin, XIUngrabTouchBegin - 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   display
66          Specifies the connection to the X server.
67
68   device
69          Specifies the device that is to be grabbed or released
70
71   button
72          Specifies the device button that is to be grabbed or
73          released or XIAnyButton.
74
75   keycode
76          Specifies the keycode that is to be grabbed or released
77          or XIAnyKeycode.
78
79   num_modifiers
80          Number of elements in modifiers or modifiers_inout.
81
82   modifiers
83          Specifies the set of latched and base modifiers or
84          XIAnyModifier to ungrab. The data type is for
85          consistency with the respective grab request and the
86          status code of the XIGrabModifiers struct is ignored.
87
88   modifiers_inout
89          Specifies the set of latched and base modifiers or
90          XIAnyModifier to grab. Returns the modifiers that could
91          not be grabbed and their error code.
92
93   grab_window
94          Specifies the grab window.
95
96   owner_events
97          Specifies a Boolean value that indicates whether the are
98          to be reported as usual or reported with respect to the
99          grab window.
100
101   mask
102          Specifies the event mask.
103
104   grab_mode
105          Specifies further processing of events from this device.
106          You can pass XIGrabModeSync or XIGrabModeAsync.
107
108   paired_device_mode
109          Specifies further processing of events from the paired
110          master device. You can pass XIGrabModeSync or
111          XIGrabModeAsync. If deviceid specifies a floating slave
112          device, this parameter is ignored.
113
114DESCRIPTION
115-----------
116
117   XIGrabButton, XIGrabKeycode and XIGrabTouchBegin establish a passive
118   grab. The modifier device for a button grab is the paired master device
119   if deviceid specifies a master pointer. Otherwise, the modifier
120   device is the device specified with deviceid. In the future,
121   the device is actively grabbed (as for XIGrabDevice, the
122   last-grab time is set to the time at which the button or keycode
123   was pressed and the XI_ButtonPress or XI_KeyPress event is
124   reported if all of the following conditions are true:
125     * The device is not grabbed, and the specified button or
126       keycode is logically pressed or a touch event occurs when the
127       specified modifier keys are logically down on the modifier device
128       and no other buttons or modifier keys are logically down.
129     * Either the grab window is an ancestor of (or is) the focus
130       window, OR the grab window is a descendent of the focus
131       window and contains the device.
132     * A passive grab on the same button/modifier combination does
133       not exist on any ancestor of grab_window.
134
135   The interpretation of the remaining arguments is as for
136   XIGrabDevice. The active grab is terminated automatically when
137   the logical state of the device has all buttons or keys
138   released (independent of the logical state of the modifier
139   keys).
140
141   If the device is an attached slave device, the device is
142   automatically detached from the master device when the grab
143   activates and reattached to the same master device when the
144   grab deactivates. If the master device is removed while the
145   device is floating as a result of a grab, the device remains
146   floating once the grab deactivates.
147
148   Note that the logical state of a device (as seen by client
149   applications) may lag the physical state if device event
150   processing is frozen.
151
152   This request overrides all previous grabs by the same client on
153   the same button/modifier or keycode/modifier combinations on the
154   same window. A modifiers of XIAnyModifier is equivalent to
155   issuing the grab request for all possible modifier combinations
156   (including the combination of no modifiers). It is not required
157   that all modifiers specified have currently assigned KeyCodes.
158   A button of XIAnyButton is equivalent to issuing the request
159   for all possible buttons. Otherwise, it is not required that
160   the specified button currently be assigned to a physical
161   button.
162
163   If some other client has already issued a XIGrabButton or
164   XIGrabKeycode with the same button/modifier or keycode/modifier
165   combination on the same window, a BadAccess error results. When
166   using XIAnyModifier or XIAnyButton , the request fails
167   completely, and a XIBadAccess error results (no grabs are
168   established) if there is a conflicting grab for any
169   combination. XIGrabButton and XIGrabKeycode have no effect on an
170   active grab.
171
172   On success, XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return 0;
173   If one or more modifier combinations could not be grabbed,
174   XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return the number of
175   failed combinations and modifiers_inout contains the failed combinations
176   and their respective error codes.
177
178   XIGrabButton, XIGrabKeycode and XIGrabTouchBegin can generate BadClass,
179   BadDevice, BadMatch, BadValue, and BadWindow errors.
180
181   XIUngrabButton, XIUngrabKeycode and XIUngrabTouchBegin release the
182   passive grab for a button/modifier, keycode/modifier or touch/modifier
183   combination on the specified window if it was grabbed by this client. A
184   modifier of XIAnyModifier is equivalent to issuing the ungrab request
185   for all possible modifier combinations, including the
186   combination of no modifiers. A button of XIAnyButton is
187   equivalent to issuing the request for all possible buttons.
188   XIUngrabButton and XIUngrabKeycode have no effect on an active
189   grab.
190
191   XIUngrabButton, XIUngrabKeycode and XIUngrabTouchBegin can generate
192   BadDevice, BadMatch, BadValue and BadWindow errors.
193
194RETURN VALUE
195------------
196   XIGrabButton, XIGrabKeycode and XIGrabTouchBegin return the number of
197   modifier combination that could not establish a passive grab. The
198   modifiers are returned in modifiers_inout, along with the respective
199   error for this modifier combination. If XIGrabButton, XIGrabKeycode
200   or XIGrabTouchBegin return zero, passive grabs with all requested
201   modifier combinations were established successfully.
202
203DIAGNOSTICS
204-----------
205
206   BadDevice
207          An invalid deviceid was specified.
208
209   BadMatch
210          This error may occur if XIGrabButton specified a device
211          that has no buttons, or XIGrabKeycode specified a device
212          that has no keys, or XIGrabTouchBegin specified a device
213          that is not touch-capable.
214
215   BadValue
216          Some numeric value falls outside the range of values
217          accepted by the request. Unless a specific range is
218          specified for an argument, the full range defined by the
219          argument's type is accepted. Any argument defined as a
220          set of alternatives can generate this error.
221
222   BadWindow
223          A value for a Window argument does not name a defined
224          Window.
225
226BUGS
227----
228
229   The protocol headers for XI 2.0 did not provide
230   XIGrabModeAsync or XIGrabModeSync. Use GrabModeSync and
231   GrabModeAsync instead, respectively.
232
233SEE ALSO
234--------
235
236   XIAllowEvents(libmansuffix)
237
238