diff options
-rw-r--r-- | gdk/gdkdevicemanager.c | 90 |
1 files changed, 58 insertions, 32 deletions
diff --git a/gdk/gdkdevicemanager.c b/gdk/gdkdevicemanager.c index e736f8fa9a..301e790f83 100644 --- a/gdk/gdkdevicemanager.c +++ b/gdk/gdkdevicemanager.c @@ -33,18 +33,37 @@ * In addition to a single pointer and keyboard for user interface input, * GDK contains support for a variety of input devices, including graphics * tablets, touchscreens and multiple pointers/keyboards interacting - * simultaneously with the user interface. Under X, the support for multiple - * input devices is done through the <firstterm>XInput 2</firstterm> extension, - * which also supports additional features such as sub-pixel positioning - * information and additional device-dependent information. + * simultaneously with the user interface. Such input devices often have + * additional features, such as sub-pixel positioning information and + * additional device-dependent information. + * + * In order to query the device hierarchy and be aware of changes in the + * device hierarchy (such as virtual devices being created or removed, or + * physical devices being plugged or unplugged), GDK provides + * #GdkDeviceManager. * * By default, and if the platform supports it, GDK is aware of multiple - * keyboard/pointer pairs and multitouch devices, this behavior can be - * changed by calling gdk_disable_multidevice() before gdk_display_open(), - * although there would rarely be a reason to do that. For a widget or - * window to be dealt as multipointer aware, - * gdk_window_set_support_multidevice() or - * gtk_widget_set_support_multidevice() must have been called on it. + * keyboard/pointer pairs and multitouch devices. This behavior can be + * changed by calling gdk_disable_multidevice() before gdk_display_open(). + * There should rarely be a need to do that though, since GDK defaults + * to a compatibility mode in which it will emit just one enter/leave + * event pair for all devices on a window. To enable per-device + * enter/leave events and other multi-pointer interaction features, + * gdk_window_set_support_multidevice() must be called on + * #GdkWindows (or gtk_widget_set_support_multidevice() on widgets). + * window. See the gdk_window_set_support_multidevice() documentation + * for more information. + * + * On X11, multi-device support is implemented through XInput 2. + * Unless gdk_disable_multidevice() is called, the XInput 2 + * #GdkDeviceManager implementation will be used as the input source. + * Otherwise either the core or XInput 1 implementations will be used. + * + * For simple applications that don't have any special interest in + * input devices, the so-called <firstterm>client pointer</firstterm> + * provides a reasonable approximation to a simple setup with a single + * pointer and keyboard. The device that has been set as the client + * pointer can be accessed via gdk_device_manager_get_client_pointer(). * * Conceptually, in multidevice mode there are 2 device types. Virtual * devices (or master devices) are represented by the pointer cursors @@ -60,28 +79,43 @@ * be controlling each of these virtual devices. Physical devices may also * be "floating", which means they are not attached to any virtual device. * + * <example><title>Master and slave devices</title> + * <screen> + * carlos@sacarino:~$ xinput list + * ⎡ Virtual core pointer id=2 [master pointer (3)] + * ⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)] + * ⎜ ↳ Wacom ISDv4 E6 Pen stylus id=10 [slave pointer (2)] + * ⎜ ↳ Wacom ISDv4 E6 Finger touch id=11 [slave pointer (2)] + * ⎜ ↳ SynPS/2 Synaptics TouchPad id=13 [slave pointer (2)] + * ⎜ ↳ TPPS/2 IBM TrackPoint id=14 [slave pointer (2)] + * ⎜ ↳ Wacom ISDv4 E6 Pen eraser id=16 [slave pointer (2)] + * ⎣ Virtual core keyboard id=3 [master keyboard (2)] + * ↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)] + * ↳ Power Button id=6 [slave keyboard (3)] + * ↳ Video Bus id=7 [slave keyboard (3)] + * ↳ Sleep Button id=8 [slave keyboard (3)] + * ↳ Integrated Camera id=9 [slave keyboard (3)] + * ↳ AT Translated Set 2 keyboard id=12 [slave keyboard (3)] + * ↳ ThinkPad Extra Buttons id=15 [slave keyboard (3)] + * </screen> + * </example> + * * By default, GDK will automatically listen for events coming from all * master devices, setting the #GdkDevice for all events coming from input - * devices, - * <footnote> - * Events containing device information are #GDK_MOTION_NOTIFY, + * devices. Events containing device information are #GDK_MOTION_NOTIFY, * #GDK_BUTTON_PRESS, #GDK_2BUTTON_PRESS, #GDK_3BUTTON_PRESS, * #GDK_BUTTON_RELEASE, #GDK_SCROLL, #GDK_KEY_PRESS, #GDK_KEY_RELEASE, * #GDK_ENTER_NOTIFY, #GDK_LEAVE_NOTIFY, #GDK_FOCUS_CHANGE, * #GDK_PROXIMITY_IN, #GDK_PROXIMITY_OUT, #GDK_DRAG_ENTER, #GDK_DRAG_LEAVE, * #GDK_DRAG_MOTION, #GDK_DRAG_STATUS, #GDK_DROP_START, #GDK_DROP_FINISHED - * and #GDK_GRAB_BROKEN. - * </footnote> - * Although gdk_window_set_support_multidevice() must be called on - * #GdkWindows in order to support additional features of multiple pointer - * interaction, such as multiple per-device enter/leave events, the default - * setting will emit just one enter/leave event pair for all devices on the - * window. See gdk_window_set_support_multidevice() documentation for more - * information. + * and #GDK_GRAB_BROKEN. When dealing with an event on a master device, + * it is possible to get the source (slave) device that the event originated + * from via gdk_event_get_source_device(). * - * In order to listen for events coming from other than a virtual device, - * gdk_window_set_device_events() must be called. Generally, this function - * can be used to modify the event mask for any given device. + * In order to listen for events coming from devices + * other than a virtual device, gdk_window_set_device_events() must be + * called. Generally, this function can be used to modify the event mask + * for any given device. * * Input devices may also provide additional information besides X/Y. * For example, graphics tablets may also provide pressure and X/Y tilt @@ -95,14 +129,6 @@ * Devices may also have associated <firstterm>keys</firstterm> or * macro buttons. Such keys can be globally set to map into normal X * keyboard events. The mapping is set using gdk_device_set_key(). - * - * In order to query the device hierarchy and be aware of changes in the - * device hierarchy (such as virtual devices being created or removed, or - * physical devices being plugged or unplugged), GDK provides - * #GdkDeviceManager. On X11, multidevice support is implemented through - * XInput 2. Unless gdk_disable_multidevice() is called, the XInput 2.x - * #GdkDeviceManager implementation will be used as the input source. Otherwise - * either the core or XInput 1.x implementations will be used. */ static void gdk_device_manager_set_property (GObject *object, |