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