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_device specified 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          device events are to be reported as usual or reported
61          with respect to the grab window if 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.
128
129   The XUngrabDeviceButton request releases the passive grab for a
130   button/modifier combination on the specified window if it was
131   grabbed by this client. A modifier of AnyModifier is equivalent to
132   issuing the ungrab request for all possible modifier combinations,
133   including the combination of no modifiers. A button of AnyButton is
134   equivalent to issuing the request for all possible buttons.
135   XUngrabDeviceButton has no effect on an active grab.
136
137   A modifier_device of NULL indicates that the X keyboard should
138   be used as the modifier_device.
139
140   XUngrabDeviceButton can generate BadDevice, BadMatch, BadValue
141   and BadWindow errors.
142
143DIAGNOSTICS
144-----------
145
146   BadDevice
147          An invalid device was specified. The specified device
148          does not exist or has not been opened by this client via
149          XOpenInputDevice. This error may also occur if the
150          specified device is the X keyboard or X pointer device.
151
152   BadMatch
153          This error may occur if an XGrabDeviceButton request was
154          made specifying a device that has no buttons, or
155          specifying a modifier device that has no keys.
156
157   BadValue
158          Some numeric value falls outside the range of values
159          accepted by the request. Unless a specific range is
160          specified for an argument, the full range defined by the
161          argument's type is accepted. Any argument defined as a
162          set of alternatives can generate this error.
163
164   BadWindow
165          A value for a Window argument does not name a defined
166          Window.
167
168SEE ALSO
169--------
170
171   XAllowDeviceEvents(libmansuffix), XGrabDevice(libmansuffix), XGrabDeviceKey(libmansuffix)
172