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