XIGrabButton.txt revision c27c18e8 
1XIGRABBUTTON(libmansuffix)
2==========================
3
4NAME
5----
6
7   XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode -
8   grab/ungrab buttons or keys
9
10SYNOPSIS
11--------
12
13   #include <X11/extensions/XInput.h>
14
15   int XIGrabButton( Display *display,
16                     int deviceid,
17                     int button,
18                     Window grab_window,
19                     Cursor cursor,
20                     int grab_mode,
21                     int paired_device_mode,
22                     Bool owner_events,
23                     XIEventMask *mask,
24                     int num_modifiers,
25                     XIGrabModifiers *modifiers_inout);
26
27   int XIUngrabButton( Display *display,
28                       int deviceid,
29                       int button,
30                       Window grab_window,
31                       int num_modifiers,
32                       XIGrabModifiers *modifiers);
33
34   int XIGrabKeycode( Display *display,
35                     int deviceid,
36                     int keycode,
37                     Window grab_window,
38                     int grab_mode,
39                     int paired_device_mode,
40                     Bool owner_events,
41                     XIEventMask *mask,
42                     int num_modifiers,
43                     XIGrabModifiers *modifiers_inout);
44   
45   int XIUngrabKeycode( Display *display,
46                       int deviceid,
47                       int keycode,
48                       Window grab_window,
49                       int num_modifiers,
50                       XIGrabModifiers *modifiers);
51
52   display
53          Specifies the connection to the X server.
54
55   device
56          Specifies the device that is to be grabbed or released
57
58   button
59          Specifies the device button that is to be grabbed or
60          released or XIAnyButton.
61
62   keycode
63          Specifies the keycode that is to be grabbed or released
64          or XIAnyKeycode.
65
66   num_modifiers
67          Number of elements in modifiers or modifiers_return
68
69   modifiers
70          Specifies the set of latched and base modifiers or
71          XIAnyModifier to ungrab. The data type is for
72          consistency with the respective grab request and the
73          status code of the XIGrabModifiers struct is ignored.
74
75   modifiers_inout
76          Specifies the set of latched and base modifiers or
77          XIAnyModifier to grab. Returns the modifiers that could
78          not be grabbed and their status code.
79
80   grab_window
81          Specifies the grab window.
82
83   owner_events
84          Specifies a Boolean value that indicates whether the are
85          to be reported as usual or reported with respect to the
86          grab window.
87
88   mask
89          Specifies the event mask.
90
91   grab_mode
92          Specifies further processing of events from this device.
93          You can pass GrabModeSync or GrabModeAsync.
94
95   paired_device_mode
96          Specifies further processing of events from the paired
97          master device. You can pass GrabModeSync or
98          GrabModeAsync. If deviceid specifies a floating slave
99          device, this parameter is ignored.
100
101DESCRIPTION
102-----------
103
104   XIGrabButton and XIGrabKeycode establishes a passive grab. The
105   modifier device for a button grab is the paired master device
106   if deviceid specifies a master pointer. Otherwise, the modifier
107   device is the device specified with deviceid. In the future,
108   the device is actively grabbed (as for XIGrabDevice, the
109   last-grab time is set to the time at which the button or keycode
110   was pressed and the X_XIButtonPress or X_XIKeyPress event is
111   reported if all of the following conditions are true:
112     * The device is not grabbed, and the specified button or
113       keycode is logically pressed when the specified modifier
114       keys are logically down on the modifier device and no other
115       buttons or modifier keys are logically down.
116     * Either the grab window is an ancestor of (or is) the focus
117       window, OR the grab window is a descendent of the focus
118       window and contains the device.
119     * A passive grab on the same button/modifier combination does
120       not exist on any ancestor of grab_window.
121
122   The interpretation of the remaining arguments is as for
123   XIGrabDevice. The active grab is terminated automatically when
124   the logical state of the device has all buttons or keys
125   released (independent of the logical state of the modifier
126   keys).
127
128   If the device is an attached slave device, the device is
129   automatically detached from the master device when the grab
130   activates and reattached to the same master device when the
131   grab deactivates. If the master device is removed while the
132   device is floating as a result of a grab, the device remains
133   floating once the grab deactivates.
134
135   Note that the logical state of a device (as seen by client
136   applications) may lag the physical state if device event
137   processing is frozen.
138
139   This request overrides all previous grabs by the same client on
140   the same button/modifier or keycode/modifier combinations on the
141   same window. A modifiers of XIAnyModifier is equivalent to
142   issuing the grab request for all possible modifier combinations
143   (including the combination of no modifiers). It is not required
144   that all modifiers specified have currently assigned KeyCodes.
145   A button of XIAnyButton is equivalent to issuing the request
146   for all possible buttons. Otherwise, it is not required that
147   the specified button currently be assigned to a physical
148   button.
149
150   If some other client has already issued a XIGrabButton or
151   XIGrabKeycode with the same button/modifier or keycode/modifier
152   combination on the same window, a BadAccess error results. When
153   using XIAnyModifier or XIAnyButton , the request fails
154   completely, and a XIBadAccess error results (no grabs are
155   established) if there is a conflicting grab for any
156   combination. XIGrabButton and XIGrabKeycode have no effect on an
157   active grab.
158
159   XIGrabButton and XIGrabKeycode can generate BadClass, BadDevice,
160   BadMatch, BadValue, and BadWindow errors.
161
162   XIUngrabButton and XIUngrabKeycode releases the passive grab for
163   a button/modifier or keycode/modifier combination on the
164   specified window if it was grabbed by this client. A modifier
165   of XIAnyModifier is equivalent to issuing the ungrab request
166   for all possible modifier combinations, including the
167   combination of no modifiers. A button of XIAnyButton is
168   equivalent to issuing the request for all possible buttons.
169   XIUngrabButton and XIUngrabKeycode have no effect on an active
170   grab.
171
172   XIUngrabButton and XIUngrabKeycode can generate BadDevice,
173   BadMatch, BadValue and BadWindow errors.
174
175DIAGNOSTICS
176-----------
177
178   BadDevice
179          An invalid deviceid was specified.
180
181   BadMatch
182          This error may occur if XIGrabButton specified a device
183          that has no buttons, or XIGrabKeycode specified a device
184          that has no keys.
185
186   BadValue
187          Some numeric value falls outside the range of values
188          accepted by the request. Unless a specific range is
189          specified for an argument, the full range defined by the
190          argument's type is accepted. Any argument defined as a
191          set of alternatives can generate this error.
192
193   BadWindow
194          A value for a Window argument does not name a defined
195          Window.
196
197SEE ALSO
198--------
199
200   XIAllowEvents(libmansuffix)
201
202