1 /* GDK - The GIMP Drawing Kit
2 * Copyright (C) 2009 Carlos Garnacho <carlosg@gnome.org>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 */
17
18 #include "config.h"
19
20 #include "gdkdevicemanagerprivate.h"
21 #include "gdkdisplay.h"
22 #include "gdkintl.h"
23
24
25 /**
26 * SECTION:gdkdevicemanager
27 * @Short_description: Functions for handling input devices
28 * @Title: GdkDeviceManager
29 * @See_also: #GdkDevice, #GdkEvent
30 *
31 * In addition to a single pointer and keyboard for user interface input,
32 * GDK contains support for a variety of input devices, including graphics
33 * tablets, touchscreens and multiple pointers/keyboards interacting
34 * simultaneously with the user interface. Such input devices often have
35 * additional features, such as sub-pixel positioning information and
36 * additional device-dependent information.
37 *
38 * In order to query the device hierarchy and be aware of changes in the
39 * device hierarchy (such as virtual devices being created or removed, or
40 * physical devices being plugged or unplugged), GDK provides
41 * #GdkDeviceManager.
42 *
43 * By default, and if the platform supports it, GDK is aware of multiple
44 * keyboard/pointer pairs and multitouch devices. This behavior can be
45 * changed by calling gdk_disable_multidevice() before gdk_display_open().
46 * There should rarely be a need to do that though, since GDK defaults
47 * to a compatibility mode in which it will emit just one enter/leave
48 * event pair for all devices on a window. To enable per-device
49 * enter/leave events and other multi-pointer interaction features,
50 * gdk_window_set_support_multidevice() must be called on
51 * #GdkWindows (or gtk_widget_set_support_multidevice() on widgets).
52 * window. See the gdk_window_set_support_multidevice() documentation
53 * for more information.
54 *
55 * On X11, multi-device support is implemented through XInput 2.
56 * Unless gdk_disable_multidevice() is called, the XInput 2
57 * #GdkDeviceManager implementation will be used as the input source.
58 * Otherwise either the core or XInput 1 implementations will be used.
59 *
60 * For simple applications that don’t have any special interest in
61 * input devices, the so-called “client pointer”
62 * provides a reasonable approximation to a simple setup with a single
63 * pointer and keyboard. The device that has been set as the client
64 * pointer can be accessed via gdk_device_manager_get_client_pointer().
65 *
66 * Conceptually, in multidevice mode there are 2 device types. Virtual
67 * devices (or master devices) are represented by the pointer cursors
68 * and keyboard foci that are seen on the screen. Physical devices (or
69 * slave devices) represent the hardware that is controlling the virtual
70 * devices, and thus have no visible cursor on the screen.
71 *
72 * Virtual devices are always paired, so there is a keyboard device for every
73 * pointer device. Associations between devices may be inspected through
74 * gdk_device_get_associated_device().
75 *
76 * There may be several virtual devices, and several physical devices could
77 * be controlling each of these virtual devices. Physical devices may also
78 * be “floating”, which means they are not attached to any virtual device.
79 *
80 * # Master and slave devices
81 *
82 * |[
83 * carlos@sacarino:~$ xinput list
84 * ⎡ Virtual core pointer id=2 [master pointer (3)]
85 * ⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)]
86 * ⎜ ↳ Wacom ISDv4 E6 Pen stylus id=10 [slave pointer (2)]
87 * ⎜ ↳ Wacom ISDv4 E6 Finger touch id=11 [slave pointer (2)]
88 * ⎜ ↳ SynPS/2 Synaptics TouchPad id=13 [slave pointer (2)]
89 * ⎜ ↳ TPPS/2 IBM TrackPoint id=14 [slave pointer (2)]
90 * ⎜ ↳ Wacom ISDv4 E6 Pen eraser id=16 [slave pointer (2)]
91 * ⎣ Virtual core keyboard id=3 [master keyboard (2)]
92 * ↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)]
93 * ↳ Power Button id=6 [slave keyboard (3)]
94 * ↳ Video Bus id=7 [slave keyboard (3)]
95 * ↳ Sleep Button id=8 [slave keyboard (3)]
96 * ↳ Integrated Camera id=9 [slave keyboard (3)]
97 * ↳ AT Translated Set 2 keyboard id=12 [slave keyboard (3)]
98 * ↳ ThinkPad Extra Buttons id=15 [slave keyboard (3)]
99 * ]|
100 *
101 * By default, GDK will automatically listen for events coming from all
102 * master devices, setting the #GdkDevice for all events coming from input
103 * devices. Events containing device information are #GDK_MOTION_NOTIFY,
104 * #GDK_BUTTON_PRESS, #GDK_2BUTTON_PRESS, #GDK_3BUTTON_PRESS,
105 * #GDK_BUTTON_RELEASE, #GDK_SCROLL, #GDK_KEY_PRESS, #GDK_KEY_RELEASE,
106 * #GDK_ENTER_NOTIFY, #GDK_LEAVE_NOTIFY, #GDK_FOCUS_CHANGE,
107 * #GDK_PROXIMITY_IN, #GDK_PROXIMITY_OUT, #GDK_DRAG_ENTER, #GDK_DRAG_LEAVE,
108 * #GDK_DRAG_MOTION, #GDK_DRAG_STATUS, #GDK_DROP_START, #GDK_DROP_FINISHED
109 * and #GDK_GRAB_BROKEN. When dealing with an event on a master device,
110 * it is possible to get the source (slave) device that the event originated
111 * from via gdk_event_get_source_device().
112 *
113 * On a standard session, all physical devices are connected by default to
114 * the "Virtual Core Pointer/Keyboard" master devices, hence routing all events
115 * through these. This behavior is only modified by device grabs, where the
116 * slave device is temporarily detached for as long as the grab is held, and
117 * more permanently by user modifications to the device hierarchy.
118 *
119 * On certain application specific setups, it may make sense
120 * to detach a physical device from its master pointer, and mapping it to
121 * an specific window. This can be achieved by the combination of
122 * gdk_device_grab() and gdk_device_set_mode().
123 *
124 * In order to listen for events coming from devices
125 * other than a virtual device, gdk_window_set_device_events() must be
126 * called. Generally, this function can be used to modify the event mask
127 * for any given device.
128 *
129 * Input devices may also provide additional information besides X/Y.
130 * For example, graphics tablets may also provide pressure and X/Y tilt
131 * information. This information is device-dependent, and may be
132 * queried through gdk_device_get_axis(). In multidevice mode, virtual
133 * devices will change axes in order to always represent the physical
134 * device that is routing events through it. Whenever the physical device
135 * changes, the #GdkDevice:n-axes property will be notified, and
136 * gdk_device_list_axes() will return the new device axes.
137 *
138 * Devices may also have associated “keys” or
139 * macro buttons. Such keys can be globally set to map into normal X
140 * keyboard events. The mapping is set using gdk_device_set_key().
141 *
142 * In GTK+ 3.20, a new #GdkSeat object has been introduced that
143 * supersedes #GdkDeviceManager and should be preferred in newly
144 * written code.
145 */
146
147 static void gdk_device_manager_set_property (GObject *object,
148 guint prop_id,
149 const GValue *value,
150 GParamSpec *pspec);
151 static void gdk_device_manager_get_property (GObject *object,
152 guint prop_id,
153 GValue *value,
154 GParamSpec *pspec);
155
156
157 G_DEFINE_ABSTRACT_TYPE (GdkDeviceManager, gdk_device_manager, G_TYPE_OBJECT)
158
159 enum {
160 PROP_0,
161 PROP_DISPLAY
162 };
163
164 enum {
165 DEVICE_ADDED,
166 DEVICE_REMOVED,
167 DEVICE_CHANGED,
168 LAST_SIGNAL
169 };
170
171 static guint signals [LAST_SIGNAL] = { 0 };
172
173
174 static void
gdk_device_manager_class_init(GdkDeviceManagerClass * klass)175 gdk_device_manager_class_init (GdkDeviceManagerClass *klass)
176 {
177 GObjectClass *object_class = G_OBJECT_CLASS (klass);
178
179 object_class->set_property = gdk_device_manager_set_property;
180 object_class->get_property = gdk_device_manager_get_property;
181
182 g_object_class_install_property (object_class,
183 PROP_DISPLAY,
184 g_param_spec_object ("display",
185 P_("Display"),
186 P_("Display for the device manager"),
187 GDK_TYPE_DISPLAY,
188 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
189 G_PARAM_STATIC_STRINGS));
190
191 /**
192 * GdkDeviceManager::device-added:
193 * @device_manager: the object on which the signal is emitted
194 * @device: the newly added #GdkDevice.
195 *
196 * The ::device-added signal is emitted either when a new master
197 * pointer is created, or when a slave (Hardware) input device
198 * is plugged in.
199 */
200 signals [DEVICE_ADDED] =
201 g_signal_new (g_intern_static_string ("device-added"),
202 G_TYPE_FROM_CLASS (klass),
203 G_SIGNAL_RUN_LAST,
204 G_STRUCT_OFFSET (GdkDeviceManagerClass, device_added),
205 NULL, NULL,
206 NULL,
207 G_TYPE_NONE, 1,
208 GDK_TYPE_DEVICE);
209
210 /**
211 * GdkDeviceManager::device-removed:
212 * @device_manager: the object on which the signal is emitted
213 * @device: the just removed #GdkDevice.
214 *
215 * The ::device-removed signal is emitted either when a master
216 * pointer is removed, or when a slave (Hardware) input device
217 * is unplugged.
218 */
219 signals [DEVICE_REMOVED] =
220 g_signal_new (g_intern_static_string ("device-removed"),
221 G_TYPE_FROM_CLASS (klass),
222 G_SIGNAL_RUN_LAST,
223 G_STRUCT_OFFSET (GdkDeviceManagerClass, device_removed),
224 NULL, NULL,
225 NULL,
226 G_TYPE_NONE, 1,
227 GDK_TYPE_DEVICE);
228
229 /**
230 * GdkDeviceManager::device-changed:
231 * @device_manager: the object on which the signal is emitted
232 * @device: the #GdkDevice that changed.
233 *
234 * The ::device-changed signal is emitted whenever a device
235 * has changed in the hierarchy, either slave devices being
236 * disconnected from their master device or connected to
237 * another one, or master devices being added or removed
238 * a slave device.
239 *
240 * If a slave device is detached from all master devices
241 * (gdk_device_get_associated_device() returns %NULL), its
242 * #GdkDeviceType will change to %GDK_DEVICE_TYPE_FLOATING,
243 * if it's attached, it will change to %GDK_DEVICE_TYPE_SLAVE.
244 */
245 signals [DEVICE_CHANGED] =
246 g_signal_new (g_intern_static_string ("device-changed"),
247 G_TYPE_FROM_CLASS (klass),
248 G_SIGNAL_RUN_LAST,
249 G_STRUCT_OFFSET (GdkDeviceManagerClass, device_changed),
250 NULL, NULL,
251 NULL,
252 G_TYPE_NONE, 1,
253 GDK_TYPE_DEVICE);
254 }
255
256 static void
gdk_device_manager_init(GdkDeviceManager * device_manager)257 gdk_device_manager_init (GdkDeviceManager *device_manager)
258 {
259 }
260
261 static void
gdk_device_manager_set_property(GObject * object,guint prop_id,const GValue * value,GParamSpec * pspec)262 gdk_device_manager_set_property (GObject *object,
263 guint prop_id,
264 const GValue *value,
265 GParamSpec *pspec)
266 {
267 switch (prop_id)
268 {
269 case PROP_DISPLAY:
270 GDK_DEVICE_MANAGER (object)->display = g_value_get_object (value);
271 break;
272 default:
273 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
274 break;
275 }
276 }
277
278 static void
gdk_device_manager_get_property(GObject * object,guint prop_id,GValue * value,GParamSpec * pspec)279 gdk_device_manager_get_property (GObject *object,
280 guint prop_id,
281 GValue *value,
282 GParamSpec *pspec)
283 {
284
285 switch (prop_id)
286 {
287 case PROP_DISPLAY:
288 g_value_set_object (value, GDK_DEVICE_MANAGER (object)->display);
289 break;
290 default:
291 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
292 break;
293 }
294 }
295
296 /**
297 * gdk_device_manager_get_display:
298 * @device_manager: a #GdkDeviceManager
299 *
300 * Gets the #GdkDisplay associated to @device_manager.
301 *
302 * Returns: (nullable) (transfer none): the #GdkDisplay to which
303 * @device_manager is associated to, or %NULL. This memory is
304 * owned by GDK and must not be freed or unreferenced.
305 *
306 * Since: 3.0
307 **/
308 GdkDisplay *
gdk_device_manager_get_display(GdkDeviceManager * device_manager)309 gdk_device_manager_get_display (GdkDeviceManager *device_manager)
310 {
311 g_return_val_if_fail (GDK_IS_DEVICE_MANAGER (device_manager), NULL);
312
313 return device_manager->display;
314 }
315
316 /**
317 * gdk_device_manager_list_devices:
318 * @device_manager: a #GdkDeviceManager
319 * @type: device type to get.
320 *
321 * Returns the list of devices of type @type currently attached to
322 * @device_manager.
323 *
324 * Returns: (transfer container) (element-type Gdk.Device): a list of
325 * #GdkDevices. The returned list must be
326 * freed with g_list_free (). The list elements are owned by
327 * GTK+ and must not be freed or unreffed.
328 *
329 * Since: 3.0
330 *
331 * Deprecated: 3.20, use gdk_seat_get_pointer(), gdk_seat_get_keyboard()
332 * and gdk_seat_get_slaves() instead.
333 **/
334 GList *
gdk_device_manager_list_devices(GdkDeviceManager * device_manager,GdkDeviceType type)335 gdk_device_manager_list_devices (GdkDeviceManager *device_manager,
336 GdkDeviceType type)
337 {
338 g_return_val_if_fail (GDK_IS_DEVICE_MANAGER (device_manager), NULL);
339
340 return GDK_DEVICE_MANAGER_GET_CLASS (device_manager)->list_devices (device_manager, type);
341 }
342
343 /**
344 * gdk_device_manager_get_client_pointer:
345 * @device_manager: a #GdkDeviceManager
346 *
347 * Returns the client pointer, that is, the master pointer that acts as the core pointer
348 * for this application. In X11, window managers may change this depending on the interaction
349 * pattern under the presence of several pointers.
350 *
351 * You should use this function seldomly, only in code that isn’t triggered by a #GdkEvent
352 * and there aren’t other means to get a meaningful #GdkDevice to operate on.
353 *
354 * Returns: (transfer none): The client pointer. This memory is
355 * owned by GDK and must not be freed or unreferenced.
356 *
357 * Since: 3.0
358 *
359 * Deprecated: 3.20: Use gdk_seat_get_pointer() instead.
360 **/
361 GdkDevice *
gdk_device_manager_get_client_pointer(GdkDeviceManager * device_manager)362 gdk_device_manager_get_client_pointer (GdkDeviceManager *device_manager)
363 {
364 g_return_val_if_fail (GDK_IS_DEVICE_MANAGER (device_manager), NULL);
365
366 return GDK_DEVICE_MANAGER_GET_CLASS (device_manager)->get_client_pointer (device_manager);
367 }
368