summaryrefslogtreecommitdiff
path: root/man/XIGrabButton.txt
blob: 09b625410add98956f898742ff23d708c9e3409d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
XIGRABBUTTON(libmansuffix)
==========================

NAME
----

   XIGrabButton, XIUngrabButton, XIGrabKeysym, XIUngrabKeysym -
   grab/ungrab buttons or keys

SYNOPSIS
--------

   #include <X11/extensions/XInput.h>

   int XIGrabButton( Display *display,
                     int deviceid,
                     int button,
                     Window grab_window,
                     Cursor cursor,
                     int grab_mode,
                     int paired_device_mode,
                     Bool owner_events,
                     XIEventMask *mask,
                     int num_modifiers,
                     XIGrabModifiers *modifiers_inout);

   int XIUngrabButton( Display *display,
                       int deviceid,
                       int button,
                       Window grab_window,
                       int num_modifiers,
                       XIGrabModifiers *modifiers);

   int XIGrabKeysym( Display *display,
                     int deviceid,
                     int keysym,
                     Window grab_window,
                     Cursor cursor,
                     int grab_mode,
                     int paired_device_mode,
                     Bool owner_events,
                     XIEventMask *mask,
                     int num_modifiers,
                     XIGrabModifiers *modifiers_inout);
   
   int XIUngrabKeysym( Display *display,
                       int deviceid,
                       int keysym,
                       Window grab_window,
                       int num_modifiers,
                       XIGrabModifiers *modifiers);

   display
          Specifies the connection to the X server.

   device
          Specifies the device that is to be grabbed or released

   button
          Specifies the device button that is to be grabbed or
          released or XIAnyButton.

   keysym
          Specifies the keysym that is to be grabbed or released
          or XIAnyKeysym.

   num_modifiers
          Number of elements in modifiers or modifiers_return

   modifiers
          Specifies the set of latched and base modifiers or
          XIAnyModifier to ungrab. The data type is for
          consistency with the respective grab request and the
          status code of the XIGrabModifiers struct is ignored.

   modifiers_inout
          Specifies the set of latched and base modifiers or
          XIAnyModifier to grab. Returns the modifiers that could
          not be grabbed and their status code.

   grab_window
          Specifies the grab window.

   owner_events
          Specifies a Boolean value that indicates whether the are
          to be reported as usual or reported with respect to the
          grab window.

   mask
          Specifies the event mask.

   grab_mode
          Specifies further processing of events from this device.
          You can pass GrabModeSync or GrabModeAsync.

   paired_device_mode
          Specifies further processing of events from the paired
          master device. You can pass GrabModeSync or
          GrabModeAsync. If deviceid specifies a floating slave
          device, this parameter is ignored.

DESCRIPTION
-----------

   XIGrabButton and XIGrabKeysym establishes a passive grab. The
   modifier device for a button grab is the paired master device
   if deviceid specifies a master pointer. Otherwise, the modifier
   device is the device specified with deviceid. In the future,
   the device is actively grabbed (as for XIGrabDevice, the
   last-grab time is set to the time at which the button or keysym
   was pressed and the X_XIButtonPress or X_XIKeyPress event is
   reported if all of the following conditions are true:
     * The device is not grabbed, and the specified button or
       keysym is logically pressed when the specified modifier
       keys are logically down on the modifier device and no other
       buttons or modifier keys are logically down.
     * Either the grab window is an ancestor of (or is) the focus
       window, OR the grab window is a descendent of the focus
       window and contains the device.
     * A passive grab on the same button/modifier combination does
       not exist on any ancestor of grab_window.

   The interpretation of the remaining arguments is as for
   XIGrabDevice. The active grab is terminated automatically when
   the logical state of the device has all buttons or keys
   released (independent of the logical state of the modifier
   keys).

   Note that the logical state of a device (as seen by client
   applications) may lag the physical state if device event
   processing is frozen.

   This request overrides all previous grabs by the same client on
   the same button/modifier or keysym/modifier combinations on the
   same window. A modifiers of XIAnyModifier is equivalent to
   issuing the grab request for all possible modifier combinations
   (including the combination of no modifiers). It is not required
   that all modifiers specified have currently assigned KeyCodes.
   A button of XIAnyButton is equivalent to issuing the request
   for all possible buttons. Otherwise, it is not required that
   the specified button currently be assigned to a physical
   button.

   If some other client has already issued a XIGrabButton or
   XIGrabKeysym with the same button/modifier or keysym/modifier
   combination on the same window, a BadAccess error results. When
   using XIAnyModifier or XIAnyButton , the request fails
   completely, and a XIBadAccess error results (no grabs are
   established) if there is a conflicting grab for any
   combination. XIGrabButton and XIGrabKeysym have no effect on an
   active grab.

   XIGrabButton and XIGrabKeysym can generate BadClass, BadDevice,
   BadMatch, BadValue, and BadWindow errors.

   XIUngrabButton and XIUngrabKeysym releases the passive grab for
   a button/modifier or keysym/modifier combination on the
   specified window if it was grabbed by this client. A modifier
   of XIAnyModifier is equivalent to issuing the ungrab request
   for all possible modifier combinations, including the
   combination of no modifiers. A button of XIAnyButton is
   equivalent to issuing the request for all possible buttons.
   XIUngrabButton and XIUngrabKeysym have no effect on an active
   grab.

   XIUngrabButton and XIUngrabKeysym can generate BadDevice,
   BadMatch, BadValue and BadWindow errors.

DIAGNOSTICS
-----------

   BadDevice
          An invalid deviceid was specified.

   BadMatch
          This error may occur if XIGrabButton specified a device
          that has no buttons, or XIGrabKeysym specified a device
          that has no keys.

   BadValue
          Some numeric value falls outside the range of values
          accepted by the request. Unless a specific range is
          specified for an argument, the full range defined by the
          argument's type is accepted. Any argument defined as a
          set of alternatives can generate this error.

   BadWindow
          A value for a Window argument does not name a defined
          Window.

SEE ALSO
--------

   XIAllowEvents(libmansuffix)