Pileus Git - ~andy/gtk/blob - gdk/gdkdevicemanager.c

   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, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include "config.h"
  21
  22 #include "gdkdevicemanager.h"
  23
  24 #include "gdkintl.h"
  25 #include "gdkinternals.h"
  26
  27
  28 /**
  29  * SECTION:gdkdevicemanager
  30  * @Short_description: Functions for handling input devices
  31  * @Long_description: In addition to a single pointer and keyboard for user interface input, GDK
  32  *                    contains support for a variety of input devices, including graphics tablets,
  33  *                    touchscreens and multiple pointers/keyboards interacting simultaneously with
  34  *                    the user interface. Under X, the support for multiple input devices is done
  35  *                    through the <firstterm>XInput 2</firstterm> extension, which also supports
  36  *                    additional features such as sub-pixel positioning information and additional
  37  *                    device-dependent information.
  38  * @Title: GdkDeviceManager
  39  * @See_also: #GdkDevice, #GdkEvent, gdk_disable_multidevice()
  40  *
  41  * By default, and if the platform supports it, GDK is aware of multiple keyboard/pointer pairs
  42  * and multitouch devices, this behavior can be changed by calling gdk_disable_multidevice()
  43  * before gdk_display_open(), although there would be rarely a reason to do that. For a widget
  44  * or window to be dealt as multipointer aware, gdk_window_set_support_multidevice() or
  45  * gtk_widget_set_support_multidevice() must have been called on it.
  46  *
  47  * Conceptually, in multidevice mode there are 2 device types, virtual devices (or master devices)
  48  * are represented by the pointer cursors and keyboard foci that are seen on the screen. physical
  49  * devices (or slave devices) represent the hardware that is controlling the virtual devices, and
  50  * thus has no visible cursor on the screen.
  51  *
  52  * Virtual devices are always paired, there is a keyboard device for every pointer device,
  53  * associations between devices may be inspected through gdk_device_get_associated_device().
  54  *
  55  * There may be several virtual devices, and several physical devices could be controlling each of
  56  * these virtual devices. Physical devices may also be "floating", which means they are not attached
  57  * to any virtual device.
  58  *
  59  * By default, GDK will automatically listen for events coming from all master devices, setting the
  60  * #GdkDevice for all events coming from input devices
  61  * <footnote>
  62  *   Events containing device information are #GDK_MOTION_NOTIFY, #GDK_BUTTON_PRESS, #GDK_2BUTTON_PRESS,
  63  *   #GDK_3BUTTON_PRESS, #GDK_BUTTON_RELEASE, #GDK_SCROLL, #GDK_KEY_PRESS, #GDK_KEY_RELEASE,
  64  *   #GDK_ENTER_NOTIFY, #GDK_LEAVE_NOTIFY, #GDK_FOCUS_CHANGE, #GDK_PROXIMITY_IN, #GDK_PROXIMITY_OUT,
  65  *   #GDK_DRAG_ENTER, #GDK_DRAG_LEAVE, #GDK_DRAG_MOTION, #GDK_DRAG_STATUS, #GDK_DROP_START,
  66  *   #GDK_DROP_FINISHED and #GDK_GRAB_BROKEN.
  67  * </footnote>
  68  * , although gdk_window_set_support_multidevice() has to be called on #GdkWindow<!-- --> in order to
  69  * support additional features of multiple pointer interaction, such as multiple, per-device enter/leave
  70  * events. The default setting will emit just one enter/leave event pair for all devices on the window.
  71  * See gdk_window_set_support_multidevice() documentation for more information.
  72  *
  73  * In order to listen for events coming from other than a virtual device, gdk_window_set_device_events()
  74  * must be called. Generally, this function can be used to modify the event mask for any given device.
  75  *
  76  * Input devices may also provide additional information besides X/Y. For example, graphics tablets may
  77  * also provide pressure and X/Y tilt information. This information is device-dependent, and may be
  78  * queried through gdk_device_get_axis(). In multidevice mode, virtual devices will change axes in order
  79  * to always represent the physical device that is routing events through it. Whenever the physical device
  80  * changes, the #GdkDevice:n-axes property will be notified, and gdk_device_list_axes() will return the
  81  * new device axes.
  82  *
  83  * Devices may also have associated <firstterm>keys</firstterm> or macro buttons. Such keys can be
  84  * globally set to map into normal X keyboard events. The mapping is set using gdk_device_set_key().
  85  *
  86  * In order to query the device hierarchy and be aware of changes in the device hierarchy (such as
  87  * virtual devices being created or removed, or physical devices being plugged or unplugged), GDK
  88  * provides #GdkDeviceManager. On X11, multidevice support is implemented through XInput 2. If
  89  * gdk_enable_multidevice() is called, the XInput 2.x #GdkDeviceManager implementation will be used
  90  * as input source, else either the core or XInput 1.x implementations will be used.
  91  */
  92
  93 static void gdk_device_manager_set_property (GObject      *object,
  94                                              guint         prop_id,
  95                                              const GValue *value,
  96                                              GParamSpec   *pspec);
  97 static void gdk_device_manager_get_property (GObject      *object,
  98                                              guint         prop_id,
  99                                              GValue       *value,
 100                                              GParamSpec   *pspec);
 101
 102
 103 G_DEFINE_ABSTRACT_TYPE (GdkDeviceManager, gdk_device_manager, G_TYPE_OBJECT)
 104
 105 enum {
 106   PROP_0,
 107   PROP_DISPLAY
 108 };
 109
 110 enum {
 111   DEVICE_ADDED,
 112   DEVICE_REMOVED,
 113   DEVICE_CHANGED,
 114   LAST_SIGNAL
 115 };
 116
 117 static guint signals [LAST_SIGNAL] = { 0 };
 118
 119
 120 struct _GdkDeviceManagerPrivate
 121 {
 122   GdkDisplay *display;
 123 };
 124
 125
 126 static void
 127 gdk_device_manager_class_init (GdkDeviceManagerClass *klass)
 128 {
 129   GObjectClass *object_class = G_OBJECT_CLASS (klass);
 130
 131   object_class->set_property = gdk_device_manager_set_property;
 132   object_class->get_property = gdk_device_manager_get_property;
 133
 134   g_object_class_install_property (object_class,
 135                                    PROP_DISPLAY,
 136                                    g_param_spec_object ("display",
 137                                                         P_("Display"),
 138                                                         P_("Display for the device manager"),
 139                                                         GDK_TYPE_DISPLAY,
 140                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
 141                                                         G_PARAM_STATIC_STRINGS));
 142
 143   /**
 144    * GdkDeviceManager::device-added:
 145    * @device_manager: the object on which the signal is emitted
 146    * @device: the newly added #GdkDevice.
 147    *
 148    * The ::device-added signal is emitted either when a new master
 149    * pointer is created, or when a slave (Hardware) input device
 150    * is plugged in.
 151    */
 152   signals [DEVICE_ADDED] =
 153     g_signal_new (g_intern_static_string ("device-added"),
 154                   G_TYPE_FROM_CLASS (klass),
 155                   G_SIGNAL_RUN_LAST,
 156                   G_STRUCT_OFFSET (GdkDeviceManagerClass, device_added),
 157                   NULL, NULL,
 158                   g_cclosure_marshal_VOID__OBJECT,
 159                   G_TYPE_NONE, 1,
 160                   GDK_TYPE_DEVICE);
 161
 162   /**
 163    * GdkDeviceManager::device-removed:
 164    * @device_manager: the object on which the signal is emitted
 165    * @device: the just removed #GdkDevice.
 166    *
 167    * The ::device-removed signal is emitted either when a master
 168    * pointer is removed, or when a slave (Hardware) input device
 169    * is unplugged.
 170    */
 171   signals [DEVICE_REMOVED] =
 172     g_signal_new (g_intern_static_string ("device-removed"),
 173                   G_TYPE_FROM_CLASS (klass),
 174                   G_SIGNAL_RUN_LAST,
 175                   G_STRUCT_OFFSET (GdkDeviceManagerClass, device_removed),
 176                   NULL, NULL,
 177                   g_cclosure_marshal_VOID__OBJECT,
 178                   G_TYPE_NONE, 1,
 179                   GDK_TYPE_DEVICE);
 180
 181   /**
 182    * GdkDeviceManager::device-changed:
 183    * @device_manager: the object on which the signal is emitted
 184    * @device: the #GdkDevice that changed.
 185    *
 186    * The ::device-changed signal is emitted whenever a device
 187    * has changed in the hierarchy, either slave devices being
 188    * disconnected from their master device or connected to
 189    * another one, or master devices being added or removed
 190    * a slave device.
 191    *
 192    * If a slave device is detached from all master devices
 193    * (gdk_device_get_associated_device() returns %NULL), its
 194    * #GdkDeviceType will change to %GDK_DEVICE_TYPE_FLOATING,
 195    * if it's attached, it will change to %GDK_DEVICE_TYPE_SLAVE.
 196    */
 197   signals [DEVICE_CHANGED] =
 198     g_signal_new (g_intern_static_string ("device-changed"),
 199                   G_TYPE_FROM_CLASS (klass),
 200                   G_SIGNAL_RUN_LAST,
 201                   G_STRUCT_OFFSET (GdkDeviceManagerClass, device_changed),
 202                   NULL, NULL,
 203                   g_cclosure_marshal_VOID__OBJECT,
 204                   G_TYPE_NONE, 1,
 205                   GDK_TYPE_DEVICE);
 206
 207   g_type_class_add_private (object_class, sizeof (GdkDeviceManagerPrivate));
 208 }
 209
 210 static void
 211 gdk_device_manager_init (GdkDeviceManager *device_manager)
 212 {
 213   GdkDeviceManagerPrivate *priv;
 214
 215   device_manager->priv = priv = G_TYPE_INSTANCE_GET_PRIVATE (device_manager,
 216                                                              GDK_TYPE_DEVICE_MANAGER,
 217                                                              GdkDeviceManagerPrivate);
 218 }
 219
 220 static void
 221 gdk_device_manager_set_property (GObject      *object,
 222                                  guint         prop_id,
 223                                  const GValue *value,
 224                                  GParamSpec   *pspec)
 225 {
 226   GdkDeviceManagerPrivate *priv;
 227
 228   priv = GDK_DEVICE_MANAGER (object)->priv;
 229
 230   switch (prop_id)
 231     {
 232     case PROP_DISPLAY:
 233       priv->display = g_value_get_object (value);
 234       break;
 235     default:
 236       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 237       break;
 238     }
 239 }
 240
 241 static void
 242 gdk_device_manager_get_property (GObject      *object,
 243                                  guint         prop_id,
 244                                  GValue       *value,
 245                                  GParamSpec   *pspec)
 246 {
 247   GdkDeviceManagerPrivate *priv;
 248
 249   priv = GDK_DEVICE_MANAGER (object)->priv;
 250
 251   switch (prop_id)
 252     {
 253     case PROP_DISPLAY:
 254       g_value_set_object (value, priv->display);
 255       break;
 256     default:
 257       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 258       break;
 259     }
 260 }
 261
 262 /**
 263  * gdk_device_manager_get_display:
 264  * @device_manager: a #GdkDeviceManager
 265  *
 266  * Gets the #GdkDisplay associated to @device_manager.
 267  *
 268  * Returns: (transfer none): the #GdkDisplay to which @device_manager is
 269  *          associated to, or #NULL. This memory is owned by GDK and
 270  *          must not be freed or unreferenced.
 271  *
 272  * Since: 3.0
 273  **/
 274 GdkDisplay *
 275 gdk_device_manager_get_display (GdkDeviceManager *device_manager)
 276 {
 277   GdkDeviceManagerPrivate *priv;
 278
 279   g_return_val_if_fail (GDK_IS_DEVICE_MANAGER (device_manager), NULL);
 280
 281   priv = device_manager->priv;
 282
 283   return priv->display;
 284 }
 285
 286 /**
 287  * gdk_device_manager_list_devices:
 288  * @device_manager: a #GdkDeviceManager
 289  * @type: device type to get.
 290  *
 291  * Returns the list of devices of type @type currently attached to
 292  * @device_manager.
 293  *
 294  * Returns: (transfer container) (element-type Gdk.Device): a list of
 295  *          #GdkDevice<!-- -->s. The returned list must be
 296  *          freed with g_list_free (). The list elements are owned by
 297  *          GTK+ and must not be freed or unreffed.
 298  *
 299  * Since: 3.0
 300  **/
 301 GList *
 302 gdk_device_manager_list_devices (GdkDeviceManager *device_manager,
 303                                  GdkDeviceType     type)
 304 {
 305   g_return_val_if_fail (GDK_IS_DEVICE_MANAGER (device_manager), NULL);
 306
 307   return GDK_DEVICE_MANAGER_GET_CLASS (device_manager)->list_devices (device_manager, type);
 308 }
 309
 310 /**
 311  * gdk_device_manager_get_client_pointer:
 312  * @device_manager: a #GdkDeviceManager
 313  *
 314  * Returns the client pointer, that is, the master pointer that acts as the core pointer
 315  * for this application. In X11, window managers may change this depending on the interaction
 316  * pattern under the presence of several pointers.
 317  *
 318  * You should use this function sheldomly, only in code that isn't triggered by a #GdkEvent
 319  * and there aren't other means to get a meaningful #GdkDevice to operate on.
 320  *
 321  * Returns: (transfer none): The client pointer. This memory is
 322  *          owned by GDK and must not be freed or unreferenced.
 323  *
 324  * Since: 3.0
 325  **/
 326 GdkDevice *
 327 gdk_device_manager_get_client_pointer (GdkDeviceManager *device_manager)
 328 {
 329   g_return_val_if_fail (GDK_IS_DEVICE_MANAGER (device_manager), NULL);
 330
 331   return GDK_DEVICE_MANAGER_GET_CLASS (device_manager)->get_client_pointer (device_manager);
 332 }