1/* GDK - The GIMP Drawing Kit
2 * Copyright (C) 2015 Red Hat
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 * Author: Carlos Garnacho <carlosg@gnome.org>
18 */
19
20#include "config.h"
21
22#include <glib-object.h>
23#include "gdkdisplay.h"
24#include "gdkdevice.h"
25#include "gdkseatprivate.h"
26#include "gdkdeviceprivate.h"
27#include "gdkintl.h"
28
29/**
30 * SECTION:gdkseat
31 * @Short_description: Object representing an user seat
32 * @Title: GdkSeat
33 * @See_also: #GdkDisplay, #GdkDevice
34 *
35 * The #GdkSeat object represents a collection of input devices
36 * that belong to a user.
37 */
38
39typedef struct _GdkSeatPrivate GdkSeatPrivate;
40
41struct _GdkSeatPrivate
42{
43 GdkDisplay *display;
44};
45
46enum {
47 DEVICE_ADDED,
48 DEVICE_REMOVED,
49 TOOL_ADDED,
50 TOOL_REMOVED,
51 N_SIGNALS
52};
53
54enum {
55 PROP_0,
56 PROP_DISPLAY,
57 N_PROPS
58};
59
60static guint signals[N_SIGNALS] = { 0 };
61static GParamSpec *props[N_PROPS] = { NULL };
62
63G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkSeat, gdk_seat, G_TYPE_OBJECT)
64
65static void
66gdk_seat_set_property (GObject *object,
67 guint prop_id,
68 const GValue *value,
69 GParamSpec *pspec)
70{
71 GdkSeatPrivate *priv = gdk_seat_get_instance_private (GDK_SEAT (object));
72
73 switch (prop_id)
74 {
75 case PROP_DISPLAY:
76 priv->display = g_value_get_object (value);
77 break;
78 default:
79 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
80 break;
81 }
82}
83
84static void
85gdk_seat_get_property (GObject *object,
86 guint prop_id,
87 GValue *value,
88 GParamSpec *pspec)
89{
90 GdkSeatPrivate *priv = gdk_seat_get_instance_private (GDK_SEAT (object));
91
92 switch (prop_id)
93 {
94 case PROP_DISPLAY:
95 g_value_set_object (value, priv->display);
96 break;
97 default:
98 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
99 break;
100 }
101}
102
103static void
104gdk_seat_class_init (GdkSeatClass *klass)
105{
106 GObjectClass *object_class = G_OBJECT_CLASS (klass);
107
108 object_class->set_property = gdk_seat_set_property;
109 object_class->get_property = gdk_seat_get_property;
110
111 /**
112 * GdkSeat::device-added:
113 * @seat: the object on which the signal is emitted
114 * @device: the newly added #GdkDevice.
115 *
116 * The ::device-added signal is emitted when a new input
117 * device is related to this seat.
118 *
119 * Since: 3.20
120 */
121 signals [DEVICE_ADDED] =
122 g_signal_new (g_intern_static_string ("device-added"),
123 G_TYPE_FROM_CLASS (klass),
124 G_SIGNAL_RUN_LAST,
125 G_STRUCT_OFFSET (GdkSeatClass, device_added),
126 NULL, NULL,
127 g_cclosure_marshal_VOID__OBJECT,
128 G_TYPE_NONE, 1,
129 GDK_TYPE_DEVICE);
130
131 /**
132 * GdkSeat::device-removed:
133 * @seat: the object on which the signal is emitted
134 * @device: the just removed #GdkDevice.
135 *
136 * The ::device-removed signal is emitted when an
137 * input device is removed (e.g. unplugged).
138 *
139 * Since: 3.20
140 */
141 signals [DEVICE_REMOVED] =
142 g_signal_new (g_intern_static_string ("device-removed"),
143 G_TYPE_FROM_CLASS (klass),
144 G_SIGNAL_RUN_LAST,
145 G_STRUCT_OFFSET (GdkSeatClass, device_removed),
146 NULL, NULL,
147 g_cclosure_marshal_VOID__OBJECT,
148 G_TYPE_NONE, 1,
149 GDK_TYPE_DEVICE);
150
151 /**
152 * GdkSeat::tool-added:
153 * @seat: the object on which the signal is emitted
154 * @tool: the new #GdkDeviceTool known to the seat
155 *
156 * The ::tool-added signal is emitted whenever a new tool
157 * is made known to the seat. The tool may later be assigned
158 * to a device (i.e. on proximity with a tablet). The device
159 * will emit the #GdkDevice::tool-changed signal accordingly.
160 *
161 * A same tool may be used by several devices.
162 *
163 * Since: 3.22
164 */
165 signals [TOOL_ADDED] =
166 g_signal_new (g_intern_static_string ("tool-added"),
167 G_TYPE_FROM_CLASS (klass),
168 G_SIGNAL_RUN_LAST,
169 0, NULL, NULL,
170 g_cclosure_marshal_VOID__BOXED,
171 G_TYPE_NONE, 1,
172 GDK_TYPE_DEVICE_TOOL);
173
174 /**
175 * GdkSeat::tool-removed:
176 * @seat: the object on which the signal is emitted
177 * @tool: the just removed #GdkDeviceTool
178 *
179 * This signal is emitted whenever a tool is no longer known
180 * to this @seat.
181 *
182 * Since: 3.22
183 */
184 signals [TOOL_REMOVED] =
185 g_signal_new (g_intern_static_string ("tool-removed"),
186 G_TYPE_FROM_CLASS (klass),
187 G_SIGNAL_RUN_LAST,
188 0, NULL, NULL,
189 g_cclosure_marshal_VOID__BOXED,
190 G_TYPE_NONE, 1,
191 GDK_TYPE_DEVICE_TOOL);
192
193 /**
194 * GdkSeat:display:
195 *
196 * #GdkDisplay of this seat.
197 *
198 * Since: 3.20
199 */
200 props[PROP_DISPLAY] =
201 g_param_spec_object ("display",
202 P_("Display"),
203 P_("Display"),
204 GDK_TYPE_DISPLAY,
205 G_PARAM_READWRITE |
206 G_PARAM_CONSTRUCT_ONLY |
207 G_PARAM_STATIC_STRINGS);
208
209 g_object_class_install_properties (object_class, N_PROPS, props);
210}
211
212static void
213gdk_seat_init (GdkSeat *seat)
214{
215}
216
217/**
218 * gdk_seat_get_capabilities:
219 * @seat: a #GdkSeat
220 *
221 * Returns the capabilities this #GdkSeat currently has.
222 *
223 * Returns: the seat capabilities
224 *
225 * Since: 3.20
226 **/
227GdkSeatCapabilities
228gdk_seat_get_capabilities (GdkSeat *seat)
229{
230 GdkSeatClass *seat_class;
231
232 g_return_val_if_fail (GDK_IS_SEAT (seat), GDK_SEAT_CAPABILITY_NONE);
233
234 seat_class = GDK_SEAT_GET_CLASS (seat);
235 return seat_class->get_capabilities (seat);
236}
237
238/**
239 * gdk_seat_grab:
240 * @seat: a #GdkSeat
241 * @window: the #GdkWindow which will own the grab
242 * @capabilities: capabilities that will be grabbed
243 * @owner_events: if %FALSE then all device events are reported with respect to
244 * @window and are only reported if selected by @event_mask. If
245 * %TRUE then pointer events for this application are reported
246 * as normal, but pointer events outside this application are
247 * reported with respect to @window and only if selected by
248 * @event_mask. In either mode, unreported events are discarded.
249 * @cursor: (nullable): the cursor to display while the grab is active. If
250 * this is %NULL then the normal cursors are used for
251 * @window and its descendants, and the cursor for @window is used
252 * elsewhere.
253 * @event: (nullable): the event that is triggering the grab, or %NULL if none
254 * is available.
255 * @prepare_func: (nullable) (scope call) (closure prepare_func_data): function to
256 * prepare the window to be grabbed, it can be %NULL if @window is
257 * visible before this call.
258 * @prepare_func_data: user data to pass to @prepare_func
259 *
260 * Grabs the seat so that all events corresponding to the given @capabilities
261 * are passed to this application until the seat is ungrabbed with gdk_seat_ungrab(),
262 * or the window becomes hidden. This overrides any previous grab on the
263 * seat by this client.
264 *
265 * As a rule of thumb, if a grab is desired over %GDK_SEAT_CAPABILITY_POINTER,
266 * all other "pointing" capabilities (eg. %GDK_SEAT_CAPABILITY_TOUCH) should
267 * be grabbed too, so the user is able to interact with all of those while
268 * the grab holds, you should thus use %GDK_SEAT_CAPABILITY_ALL_POINTING most
269 * commonly.
270 *
271 * Grabs are used for operations which need complete control over the
272 * events corresponding to the given capabilities. For example in GTK+ this
273 * is used for Drag and Drop operations, popup menus and such.
274 *
275 * Note that if the event mask of a #GdkWindow has selected both button press
276 * and button release events, or touch begin and touch end, then a press event
277 * will cause an automatic grab until the button is released, equivalent to a
278 * grab on the window with @owner_events set to %TRUE. This is done because most
279 * applications expect to receive paired press and release events.
280 *
281 * If you set up anything at the time you take the grab that needs to be
282 * cleaned up when the grab ends, you should handle the #GdkEventGrabBroken
283 * events that are emitted when the grab ends unvoluntarily.
284 *
285 * Returns: %GDK_GRAB_SUCCESS if the grab was successful.
286 *
287 * Since: 3.20
288 **/
289GdkGrabStatus
290gdk_seat_grab (GdkSeat *seat,
291 GdkWindow *window,
292 GdkSeatCapabilities capabilities,
293 gboolean owner_events,
294 GdkCursor *cursor,
295 const GdkEvent *event,
296 GdkSeatGrabPrepareFunc prepare_func,
297 gpointer prepare_func_data)
298{
299 GdkSeatClass *seat_class;
300
301 g_return_val_if_fail (GDK_IS_SEAT (seat), GDK_GRAB_FAILED);
302 g_return_val_if_fail (GDK_IS_WINDOW (window), GDK_GRAB_FAILED);
303
304 capabilities &= GDK_SEAT_CAPABILITY_ALL;
305 g_return_val_if_fail (capabilities != GDK_SEAT_CAPABILITY_NONE, GDK_GRAB_FAILED);
306
307 seat_class = GDK_SEAT_GET_CLASS (seat);
308
309 return seat_class->grab (seat, window, capabilities, owner_events, cursor,
310 event, prepare_func, prepare_func_data);
311}
312
313/**
314 * gdk_seat_ungrab:
315 * @seat: a #GdkSeat
316 *
317 * Releases a grab added through gdk_seat_grab().
318 *
319 * Since: 3.20
320 **/
321void
322gdk_seat_ungrab (GdkSeat *seat)
323{
324 GdkSeatClass *seat_class;
325
326 g_return_if_fail (GDK_IS_SEAT (seat));
327
328 seat_class = GDK_SEAT_GET_CLASS (seat);
329 seat_class->ungrab (seat);
330}
331
332/**
333 * gdk_seat_get_slaves:
334 * @seat: a #GdkSeat
335 * @capabilities: capabilities to get devices for
336 *
337 * Returns the slave devices that match the given capabilities.
338 *
339 * Returns: (transfer container) (element-type GdkDevice): A list of #GdkDevices.
340 * The list must be freed with g_list_free(), the elements are owned
341 * by GDK and must not be freed.
342 *
343 * Since: 3.20
344 **/
345GList *
346gdk_seat_get_slaves (GdkSeat *seat,
347 GdkSeatCapabilities capabilities)
348{
349 GdkSeatClass *seat_class;
350
351 g_return_val_if_fail (GDK_IS_SEAT (seat), NULL);
352
353 seat_class = GDK_SEAT_GET_CLASS (seat);
354 return seat_class->get_slaves (seat, capabilities);
355}
356
357/**
358 * gdk_seat_get_pointer:
359 * @seat: a #GdkSeat
360 *
361 * Returns the master device that routes pointer events.
362 *
363 * Returns: (transfer none) (nullable): a master #GdkDevice with pointer
364 * capabilities. This object is owned by GTK+ and must not be freed.
365 *
366 * Since: 3.20
367 **/
368GdkDevice *
369gdk_seat_get_pointer (GdkSeat *seat)
370{
371 GdkSeatClass *seat_class;
372
373 g_return_val_if_fail (GDK_IS_SEAT (seat), NULL);
374
375 seat_class = GDK_SEAT_GET_CLASS (seat);
376 return seat_class->get_master (seat, GDK_SEAT_CAPABILITY_POINTER);
377}
378
379/**
380 * gdk_seat_get_keyboard:
381 * @seat: a #GdkSeat
382 *
383 * Returns the master device that routes keyboard events.
384 *
385 * Returns: (transfer none) (nullable): a master #GdkDevice with keyboard
386 * capabilities. This object is owned by GTK+ and must not be freed.
387 *
388 * Since: 3.20
389 **/
390GdkDevice *
391gdk_seat_get_keyboard (GdkSeat *seat)
392{
393 GdkSeatClass *seat_class;
394
395 g_return_val_if_fail (GDK_IS_SEAT (seat), NULL);
396
397 seat_class = GDK_SEAT_GET_CLASS (seat);
398 return seat_class->get_master (seat, GDK_SEAT_CAPABILITY_KEYBOARD);
399}
400
401void
402gdk_seat_device_added (GdkSeat *seat,
403 GdkDevice *device)
404{
405 gdk_device_set_seat (device, seat);
406 g_signal_emit (seat, signals[DEVICE_ADDED], 0, device);
407}
408
409void
410gdk_seat_device_removed (GdkSeat *seat,
411 GdkDevice *device)
412{
413 gdk_device_set_seat (device, NULL);
414 g_signal_emit (seat, signals[DEVICE_REMOVED], 0, device);
415}
416
417/**
418 * gdk_seat_get_display:
419 * @seat: a #GdkSeat
420 *
421 * Returns the #GdkDisplay this seat belongs to.
422 *
423 * Returns: (transfer none): a #GdkDisplay. This object is owned by GTK+
424 * and must not be freed.
425 **/
426GdkDisplay *
427gdk_seat_get_display (GdkSeat *seat)
428{
429 GdkSeatPrivate *priv = gdk_seat_get_instance_private (seat);
430
431 g_return_val_if_fail (GDK_IS_SEAT (seat), NULL);
432
433 return priv->display;
434}
435
436void
437gdk_seat_tool_added (GdkSeat *seat,
438 GdkDeviceTool *tool)
439{
440 g_signal_emit (seat, signals[TOOL_ADDED], 0, tool);
441}
442
443void
444gdk_seat_tool_removed (GdkSeat *seat,
445 GdkDeviceTool *tool)
446{
447 g_signal_emit (seat, signals[TOOL_REMOVED], 0, tool);
448}
449
450GdkDeviceTool *
451gdk_seat_get_tool (GdkSeat *seat,
452 guint64 serial)
453{
454 GdkSeatClass *seat_class;
455
456 g_return_val_if_fail (GDK_IS_SEAT (seat), NULL);
457
458 seat_class = GDK_SEAT_GET_CLASS (seat);
459 return seat_class->get_tool (seat, serial);
460}
461