Merge branch 'master' of ssh://tz.otcshare.org/profile/base/libXi
[platform/upstream/libXi.git] / man / XIGrabEnter.man
1 '\" t
2 .\"     Title: xigrabenter
3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\"      Date: 12/21/2011
6 .\"    Manual: [FIXME: manual]
7 .\"    Source: [FIXME: source]
8 .\"  Language: English
9 .\"
10 .TH "XIGRABENTER" "libmansuffix" "12/21/2011" "[FIXME: source]" "[FIXME: manual]"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el       .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 XIGrabEnter, XIUngrabEnter, XIGrabFocusIn, XIUngrabFocusIn \- grab/ungrab enter or focus in events\&.
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 #include <X11/extensions/XInput\&.h>
36 .fi
37 .sp
38 .nf
39 int XIGrabEnter( Display *display,
40                  int deviceid,
41                  Window grab_window,
42                  Cursor cursor,
43                  int grab_mode,
44                  int paired_device_mode,
45                  Bool owner_events,
46                  XIEventMask *mask,
47                  int num_modifiers,
48                  XIGrabModifiers *modifiers_inout);
49 .fi
50 .sp
51 .nf
52 int XIUngrabEnter( Display *display,
53                    int deviceid,
54                    Window grab_window
55                    int num_modifiers,
56                    XIGrabModifiers *modifiers);
57 .fi
58 .sp
59 .nf
60 int XIGrabFocusIn ( Display *display,
61                     int deviceid,
62                     Window grab_window
63                     int grab_mode,
64                     int paired_device_mode,
65                     Bool owner_events,
66                     XIEventMask *mask,
67                     int num_modifiers,
68                     XIGrabModifiers *modifiers_inout);
69 .fi
70 .sp
71 .nf
72 int XIUngrabFocusIn( Display *display,
73                      int deviceid,
74                      Window grab_window
75                      int num_modifiers,
76                      XIGrabModifiers *modifiers);
77 display
78        Specifies the connection to the X server\&.
79 .fi
80 .sp
81 .nf
82 device
83        Specifies the device that is to be grabbed or released
84 .fi
85 .sp
86 .nf
87 num_modifiers
88        Number of elements in modifiers or modifiers_inout\&.
89 .fi
90 .sp
91 .nf
92 modifiers
93        Specifies the set of latched and base modifiers or
94        XIAnyModifier to ungrab\&. The data type is for
95        consistency with the respective grab request and the
96        status code of the XIGrabModifiers struct is ignored\&.
97 .fi
98 .sp
99 .nf
100 modifiers_inout
101        Specifies the set of latched and base modifiers or
102        XIAnyModifier to grab\&. Returns the modifiers that could
103        not be grabbed and their status code\&.
104 .fi
105 .sp
106 .nf
107 grab_window
108        Specifies the grab window\&.
109 .fi
110 .sp
111 .nf
112 owner_events
113        Specifies a Boolean value that indicates whether the are
114        to be reported as usual or reported with respect to the
115        grab window\&.
116 .fi
117 .sp
118 .nf
119 mask
120        Specifies the event mask\&.
121 .fi
122 .sp
123 .nf
124 grab_mode
125        Specifies further processing of events from this device\&.
126        You can pass XIGrabModeSync or XIGrabModeAsync\&.
127 .fi
128 .sp
129 .nf
130 paired_device_mode
131        Specifies further processing of events from the paired
132        master device\&. You can pass XIGrabModeSync or
133        XIGrabModeAsync\&. If deviceid specifies a floating slave
134        device, this parameter is ignored\&.
135 .fi
136 .SH "DESCRIPTION"
137 .sp
138 .if n \{\
139 .RS 4
140 .\}
141 .nf
142 XIGrabEnter and XIGrabFocusIn establish a passive grab\&. The
143 modifier device for a enter grab is the paired master device if
144 deviceid specifies a master pointer\&. Otherwise, the modifier
145 device is the device specified with deviceid\&.
146 .fi
147 .if n \{\
148 .RE
149 .\}
150 .sp
151 .if n \{\
152 .RS 4
153 .\}
154 .nf
155 For XIGrabEnter and XIGrabFocusIn, in the future, the device is
156 actively grabbed (as for XIGrabDevice, the last\-grab time is
157 set to the time at which the pointer/focus entered window) if
158 the device is not grabbed and the pointer has entered the
159 grab_window or the focus has been set to the grab_window when
160 the specified modifier keys are logically down on the modifier
161 device and no other buttons or modifier keys are logically
162 down\&.
163 .fi
164 .if n \{\
165 .RE
166 .\}
167 .sp
168 .if n \{\
169 .RS 4
170 .\}
171 .nf
172 The interpretation of the remaining arguments is as for
173 XIGrabDevice\&. The active grab is terminated automatically when
174 the pointer leaves the window or the focus is set to a
175 different window (independent of the logical state of the
176 modifier keys)\&.
177 .fi
178 .if n \{\
179 .RE
180 .\}
181 .sp
182 .if n \{\
183 .RS 4
184 .\}
185 .nf
186 If the device is an attached slave device, the device is
187 automatically detached from the master device when the grab
188 activates and reattached to the same master device when the
189 grab deactivates\&. If the master device is removed while the
190 device is floating as a result of a grab, the device remains
191 floating once the grab deactivates\&.
192 .fi
193 .if n \{\
194 .RE
195 .\}
196 .sp
197 .if n \{\
198 .RS 4
199 .\}
200 .nf
201 Note that the logical state of a device (as seen by client
202 applications) may lag the physical state if device event
203 processing is frozen\&.
204 .fi
205 .if n \{\
206 .RE
207 .\}
208 .sp
209 .if n \{\
210 .RS 4
211 .\}
212 .nf
213 This request overrides all previous grabs by the same client of
214 the same type and modifier combinations on the same window\&. A
215 modifiers of XIAnyModifier is equivalent to issuing the grab
216 request for all possible modifier combinations (including the
217 combination of no modifiers)\&. It is not required that all
218 modifiers specified have currently assigned KeyCodes\&.
219 .fi
220 .if n \{\
221 .RE
222 .\}
223 .sp
224 .if n \{\
225 .RS 4
226 .\}
227 .nf
228 If some other client has already issued a XIGrabEnter or
229 XIGrabFocusIn  on the same window, a BadAccess error results\&.
230 When using XIAnyModifier, the request fails completely, and a
231 XIBadAccess error results (no grabs are established) if there
232 is a conflicting grab for any combination\&. XIGrabEnter and
233 XIGrabFocusin have no effect on an active grab\&.
234 .fi
235 .if n \{\
236 .RE
237 .\}
238 .sp
239 .if n \{\
240 .RS 4
241 .\}
242 .nf
243 On success, XIGrabEnter and XIGrabFocusIn return 0;
244 If one or more modifier combinations could not be grabbed,
245 XIGrabEnter and XIGrabFocusIn return the number of failed
246 combinations and modifiers_inout contains the failed combinations
247 and their respective status codes\&.
248 .fi
249 .if n \{\
250 .RE
251 .\}
252 .sp
253 .if n \{\
254 .RS 4
255 .\}
256 .nf
257 XIGrabEnter and XIGrabFocusIn can generate BadDevice,
258 BadMatch, BadValue, and BadWindow errors\&.
259 .fi
260 .if n \{\
261 .RE
262 .\}
263 .sp
264 .if n \{\
265 .RS 4
266 .\}
267 .nf
268 XIUngrabEnter and XIUngrabFocusIn releases the passive grab on
269 the specified window if it was grabbed by this client\&. A
270 modifier of XIAnyModifier is equivalent to issuing the ungrab
271 request for all possible modifier combinations, including the
272 combination of no modifiers\&. XIUngrabEnter and XIUngrabFocusIn
273 have no effect on an active grab\&.
274 .fi
275 .if n \{\
276 .RE
277 .\}
278 .sp
279 .if n \{\
280 .RS 4
281 .\}
282 .nf
283 XIUngrabEnter and XIUngrabFocusIn can generate BadDevice,
284 BadMatch, BadValue and BadWindow errors\&.
285 .fi
286 .if n \{\
287 .RE
288 .\}
289 .SH "RETURN VALUE"
290 .sp
291 .if n \{\
292 .RS 4
293 .\}
294 .nf
295 XIGrabEnter and XIGrabFocusIn return the number of modifier combination
296 that could not establish a passive grab\&. The modifiers are returned in
297 modifiers_inout, along with the respective error for this modifier
298 combination\&. If XIGrabEnter or XIGrabFocusIn return zero, passive grabs
299 with all requested modifier combinations were established successfully\&.
300 .fi
301 .if n \{\
302 .RE
303 .\}
304 .SH "DIAGNOSTICS"
305 .sp
306 .if n \{\
307 .RS 4
308 .\}
309 .nf
310 BadDevice
311        An invalid deviceid was specified\&.
312 .fi
313 .if n \{\
314 .RE
315 .\}
316 .sp
317 .if n \{\
318 .RS 4
319 .\}
320 .nf
321 BadMatch
322        This error may occur if XIGrabEnter specified a device
323        that has no valuators, or XIGrabFocusIn specified a device
324        that has no keys\&.
325 .fi
326 .if n \{\
327 .RE
328 .\}
329 .sp
330 .if n \{\
331 .RS 4
332 .\}
333 .nf
334 BadValue
335        Some numeric value falls outside the range of values
336        accepted by the request\&. Unless a specific range is
337        specified for an argument, the full range defined by the
338        argument\*(Aqs type is accepted\&. Any argument defined as a
339        set of alternatives can generate this error\&.
340 .fi
341 .if n \{\
342 .RE
343 .\}
344 .sp
345 .if n \{\
346 .RS 4
347 .\}
348 .nf
349 BadWindow
350        A value for a Window argument does not name a defined
351        Window\&.
352 .fi
353 .if n \{\
354 .RE
355 .\}
356 .SH "BUGS"
357 .sp
358 .if n \{\
359 .RS 4
360 .\}
361 .nf
362 The protocol headers for XI 2\&.0 did not provide
363 XIGrabModeAsync or XIGrabModeSync\&. Use GrabModeSync and
364 GrabModeAsync instead, respectively\&.
365 .fi
366 .if n \{\
367 .RE
368 .\}
369 .SH "SEE ALSO"
370 .sp
371 .if n \{\
372 .RS 4
373 .\}
374 .nf
375 XIAllowEvents(libmansuffix)
376 .fi
377 .if n \{\
378 .RE
379 .\}