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