XGrabDeviceButton.txt revision c27c18e8 
1XGRABDEVICEBUTTON(libmansuffix)
2===============================
3
4NAME
5----
6
7   XGrabDeviceButton, XUngrabDeviceButton - grab/ungrab extension
8   input device buttons
9
10SYNOPSIS
11--------
12
13   #include <X11/extensions/XInput.h>
14
15   int XGrabDeviceButton( Display *display,
16                          XDevice *device,
17                          unsigned int button,
18                          unsigned int modifiers,
19                          XDevice* modifier_device,
20                          Window grab_window,
21                          Bool owner_events,
22                          unsigned int event_count,
23                          XEventClass *event_list,
24                          int this_device_mode,
25                          int other_devices_mode);
26
27   int XUngrabDeviceButton( Display *display,
28                            XDevice *device,
29                            unsigned int button,
30                            unsigned int modifiers,
31                            XDevice* modifier_device,
32                            Window grab_window);
33
34   display
35          Specifies the connection to the X server.
36
37   device
38          Specifies the device that is to be grabbed or released
39
40   button
41          Specifies the device button that is to be grabbed or
42          released or AnyButton.
43
44   modifiers
45          Specifies the set of keymasks or AnyModifier.The mask is
46          the bitwise inclusive OR of the valid keymask bits.
47          Valid bits are: Shiftmask, LockMask, ControlMask,
48          Mod1Mask, Mod2Mask,Mod3Mask, Mod4Mask, Mod5Mask.
49
50   modifier_device
51          specifies the device whose modifiers are to be used. If
52          the modifier_devicespecified is NULL, the X keyboard
53          will be used as the modifier_device.
54
55   grab_window
56          Specifies the grab window.
57
58   owner_events
59          Specifies a Boolean value that indicates whether the
60          deviceevents are to be reported as usual or reported
61          with respect to the grab windowif selected by the event
62          list.
63
64   event_count
65          Specifies the number of event classes in the event list.
66
67   event_list
68          Specifies which events are reported to the client.
69
70   this_device_mode
71          Specifies further processing of events from this
72          device.You can pass GrabModeSync or GrabModeAsync.
73
74   other_devices_mode
75          Specifies further processing of events from all other
76          devices.You can pass GrabModeSync or GrabModeAsync.
77
78DESCRIPTION
79-----------
80
81   The XGrabDeviceButton request establishes a passive grab. In
82   the future, the device is actively grabbed (as for XGrabDevice,
83   the last-grab time is set to the time at which the button was
84   pressed (as transmitted in the DeviceButtonPress event), and
85   the DeviceButtonPress event is reported if all of the following
86   conditions are true:
87     * The device is not grabbed, and the specified button is
88       logically pressed when the specified modifier keys are
89       logically down on the specified modifier device and no
90       other buttons or modifier keys are logically down.
91     * Either the grab window is an ancestor of (or is) the focus
92       window, OR the grab window is a descendent of the focus
93       window and contains the device.
94     * A passive grab on the same button/modifier combination does
95       not exist on any ancestor of grab_window.
96
97   The interpretation of the remaining arguments is as for
98   XGrabDevice. The active grab is terminated automatically when
99   the logical state of the device has all buttons released
100   (independent of the logical state of the modifier keys).
101
102   Note that the logical state of a device (as seen by client
103   applications) may lag the physical state if device event
104   processing is frozen.
105
106   This request overrides all previous grabs by the same client on
107   the same button/modifier combinations on the same window. A
108   modifiers of AnyModifier is equivalent to issuing the grab
109   request for all possible modifier combinations (including the
110   combination of no modifiers). It is not required that all
111   modifiers specified have currently assigned KeyCodes. A button
112   of AnyButton is equivalent to issuing the request for all
113   possible buttons. Otherwise, it is not required that the
114   specified button currently be assigned to a physical button.
115
116   A modifier_device of NULL indicates that the X keyboard is to
117   be used as the modifier_device.
118
119   If some other client has already issued a XGrabDeviceButton
120   with the same button/modifier combination on the same window, a
121   BadAccess error results. When using AnyModifier or AnyButton ,
122   the request fails completely, and a BadAccess error results (no
123   grabs are established) if there is a conflicting grab for any
124   combination. XGrabDeviceButton has no effect on an active grab.
125
126   XGrabDeviceButton can generate BadClass, BadDevice, BadMatch,
127   BadValue, and BadWindow errors..P The XUngrabDeviceButton
128   request releases the passive grab for a button/modifier
129   combination on the specified window if it was grabbed by this
130   client. A modifier of AnyModifier is equivalent to issuing the
131   ungrab request for all possible modifier combinations,
132   including the combination of no modifiers. A button of
133   AnyButton is equivalent to issuing the request for all possible
134   buttons. XUngrabDeviceButton has no effect on an active grab.
135
136   A modifier_device of NULL indicates that the X keyboard should
137   be used as the modifier_device.
138
139   XUngrabDeviceButton can generate BadDevice, BadMatch, BadValue
140   and BadWindow errors.
141
142DIAGNOSTICS
143-----------
144
145   BadDevice
146          An invalid device was specified. The specified device
147          does not exist or has not been opened by this client via
148          XOpenInputDevice. This error may also occur if the
149          specified device is the X keyboard or X pointer device.
150
151   BadMatch
152          This error may occur if an XGrabDeviceButton request was
153          made specifying a device that has no buttons, or
154          specifying a modifier device that has no keys.
155
156   BadValue
157          Some numeric value falls outside the range of values
158          accepted by the request. Unless a specific range is
159          specified for an argument, the full range defined by the
160          argument's type is accepted. Any argument defined as a
161          set of alternatives can generate this error.
162
163   BadWindow
164          A value for a Window argument does not name a defined
165          Window.
166
167SEE ALSO
168--------
169
170   XAllowDeviceEvents(libmansuffix), XGrabDevice(libmansuffix), XGrabDeviceKey(libmansuffix)
171