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