Pileus Git - ~andy/gtk/blob - gdk/gdkdevice.h

   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 #if !defined (__GDK_H_INSIDE__) && !defined (GDK_COMPILATION)
  21 #error "Only <gdk/gdk.h> can be included directly."
  22 #endif
  23
  24 #ifndef __GDK_DEVICE_H__
  25 #define __GDK_DEVICE_H__
  26
  27 #include <gdk/gdktypes.h>
  28
  29
  30 G_BEGIN_DECLS
  31
  32 #define GDK_TYPE_DEVICE         (gdk_device_get_type ())
  33 #define GDK_DEVICE(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_DEVICE, GdkDevice))
  34 #define GDK_IS_DEVICE(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_DEVICE))
  35
  36 typedef struct _GdkDevice GdkDevice;
  37 typedef struct _GdkDevicePrivate GdkDevicePrivate;
  38
  39 typedef struct _GdkDeviceKey GdkDeviceKey;
  40 typedef struct _GdkDeviceAxis GdkDeviceAxis;
  41 typedef struct _GdkTimeCoord GdkTimeCoord;
  42
  43 /**
  44  * GdkExtensionMode:
  45  * @GDK_EXTENSION_EVENTS_NONE: no extension events are desired.
  46  * @GDK_EXTENSION_EVENTS_ALL: all extension events are desired.
  47  * @GDK_EXTENSION_EVENTS_CURSOR: extension events are desired only if a cursor
  48  *                               will be displayed for the device.
  49  *
  50  * An enumeration used to specify which extension events
  51  * are desired for a particular widget.
  52  */
  53 typedef enum
  54 {
  55   GDK_EXTENSION_EVENTS_NONE,
  56   GDK_EXTENSION_EVENTS_ALL,
  57   GDK_EXTENSION_EVENTS_CURSOR
  58 } GdkExtensionMode;
  59
  60 /**
  61  * GdkInputSource:
  62  * @GDK_SOURCE_MOUSE: the device is a mouse. (This will be reported for the core
  63  *                    pointer, even if it is something else, such as a trackball.)
  64  * @GDK_SOURCE_PEN: the device is a stylus of a graphics tablet or similar device.
  65  * @GDK_SOURCE_ERASER: the device is an eraser. Typically, this would be the other end
  66  *                     of a stylus on a graphics tablet.
  67  * @GDK_SOURCE_CURSOR: the device is a graphics tablet "puck" or similar device.
  68  * @GDK_SOURCE_KEYBOARD: the device is a keyboard.
  69  *
  70  * An enumeration describing the type of an input device in general terms.
  71  */
  72 typedef enum
  73 {
  74   GDK_SOURCE_MOUSE,
  75   GDK_SOURCE_PEN,
  76   GDK_SOURCE_ERASER,
  77   GDK_SOURCE_CURSOR,
  78   GDK_SOURCE_KEYBOARD
  79 } GdkInputSource;
  80
  81 /**
  82  * GdkInputMode:
  83  * @GDK_MODE_DISABLED: the device is disabled and will not report any events.
  84  * @GDK_MODE_SCREEN: the device is enabled. The device's coordinate space
  85  *                   maps to the entire screen.
  86  * @GDK_MODE_WINDOW: the device is enabled. The device's coordinate space
  87  *                   is mapped to a single window. The manner in which this window
  88  *                   is chosen is undefined, but it will typically be the same
  89  *                   way in which the focus window for key events is determined.
  90  *
  91  * An enumeration that describes the mode of an input device.
  92  */
  93 typedef enum
  94 {
  95   GDK_MODE_DISABLED,
  96   GDK_MODE_SCREEN,
  97   GDK_MODE_WINDOW
  98 } GdkInputMode;
  99
 100 /**
 101  * GdkAxisUse:
 102  * @GDK_AXIS_IGNORE: the axis is ignored.
 103  * @GDK_AXIS_X: the axis is used as the x axis.
 104  * @GDK_AXIS_Y: the axis is used as the y axis.
 105  * @GDK_AXIS_PRESSURE: the axis is used for pressure information.
 106  * @GDK_AXIS_XTILT: the axis is used for x tilt information.
 107  * @GDK_AXIS_YTILT: the axis is used for x tilt information.
 108  * @GDK_AXIS_WHEEL: the axis is used for wheel information.
 109  * @GDK_AXIS_LAST: a constant equal to the numerically highest axis value.
 110  *
 111  * An enumeration describing the way in which a device
 112  * axis (valuator) maps onto the predefined valuator
 113  * types that GTK+ understands.
 114  */
 115 typedef enum
 116 {
 117   GDK_AXIS_IGNORE,
 118   GDK_AXIS_X,
 119   GDK_AXIS_Y,
 120   GDK_AXIS_PRESSURE,
 121   GDK_AXIS_XTILT,
 122   GDK_AXIS_YTILT,
 123   GDK_AXIS_WHEEL,
 124   GDK_AXIS_LAST
 125 } GdkAxisUse;
 126
 127 /**
 128  * GdkDeviceType:
 129  * @GDK_DEVICE_TYPE_MASTER: Device is a master (or virtual) device. There will
 130  *                          be an associated focus indicator on the screen.
 131  * @GDK_DEVICE_TYPE_SLAVE: Device is a slave (or physical) device.
 132  * @GDK_DEVICE_TYPE_FLOATING: Device is a physical device, currently not attached to
 133  *                            any virtual device.
 134  *
 135  * Indicates the device type. See <link linkend="GdkDeviceManager.description">above</link>
 136  * for more information about the meaning of these device types.
 137  */
 138 typedef enum {
 139   GDK_DEVICE_TYPE_MASTER,
 140   GDK_DEVICE_TYPE_SLAVE,
 141   GDK_DEVICE_TYPE_FLOATING
 142 } GdkDeviceType;
 143
 144 /**
 145  * GdkDeviceKey:
 146  * @keyval: the keyval to generate when the macro button is pressed.
 147  *          If this is 0, no keypress will be generated.
 148  * @modifiers: the modifiers set for the generated key event.
 149  *
 150  * The <structname>GdkDeviceKey</structname> structure contains information
 151  * about the mapping of one device macro button onto a normal X key event.
 152  */
 153 struct _GdkDeviceKey
 154 {
 155   guint keyval;
 156   GdkModifierType modifiers;
 157 };
 158
 159 /**
 160  * GdkDeviceAxis:
 161  * @use: specifies how the axis is used.
 162  * @min: the minimal value that will be reported by this axis.
 163  * @max: the maximal value that will be reported by this axis.
 164  *
 165  * The <structname>GdkDeviceAxis</structname> structure contains information
 166  * about the range and mapping of a device axis.
 167  */
 168 struct _GdkDeviceAxis
 169 {
 170   GdkAxisUse use;
 171   gdouble    min;
 172   gdouble    max;
 173 };
 174
 175 /* We don't allocate each coordinate this big, but we use it to
 176  * be ANSI compliant and avoid accessing past the defined limits.
 177  */
 178 #define GDK_MAX_TIMECOORD_AXES 128
 179
 180 /**
 181  * GdkTimeCoord:
 182  * @time: The timestamp for this event.
 183  * @axes: the values of the device's axes.
 184  *
 185  * The #GdkTimeCoord structure stores a single event in a motion history.
 186  */
 187 struct _GdkTimeCoord
 188 {
 189   guint32 time;
 190   gdouble axes[GDK_MAX_TIMECOORD_AXES];
 191 };
 192
 193 struct _GdkDevice
 194 {
 195   GObject parent_instance;
 196
 197   /* All fields are read-only */
 198   gchar *GSEAL (name);
 199   GdkInputSource GSEAL (source);
 200   GdkInputMode GSEAL (mode);
 201   gboolean GSEAL (has_cursor);       /* TRUE if a X pointer follows device motion */
 202
 203   gint GSEAL (num_axes);
 204   GdkDeviceAxis *GSEAL (axes);
 205
 206   gint GSEAL (num_keys);
 207   GdkDeviceKey *GSEAL (keys);
 208
 209   /*< private >*/
 210   GdkDevicePrivate *priv;
 211 };
 212
 213 GType gdk_device_get_type (void) G_GNUC_CONST;
 214
 215 G_CONST_RETURN gchar *gdk_device_get_name       (GdkDevice *device);
 216 gboolean              gdk_device_get_has_cursor (GdkDevice *device);
 217
 218 /* Functions to configure a device */
 219 GdkInputSource gdk_device_get_source    (GdkDevice      *device);
 220 void           gdk_device_set_source    (GdkDevice      *device,
 221                                          GdkInputSource  source);
 222
 223 GdkInputMode   gdk_device_get_mode      (GdkDevice      *device);
 224 gboolean       gdk_device_set_mode      (GdkDevice      *device,
 225                                          GdkInputMode    mode);
 226
 227 gboolean       gdk_device_get_key       (GdkDevice       *device,
 228                                          guint            index_,
 229                                          guint           *keyval,
 230                                          GdkModifierType *modifiers);
 231 void           gdk_device_set_key       (GdkDevice      *device,
 232                                          guint           index_,
 233                                          guint           keyval,
 234                                          GdkModifierType modifiers);
 235
 236 GdkAxisUse     gdk_device_get_axis_use  (GdkDevice         *device,
 237                                          guint              index_);
 238 void           gdk_device_set_axis_use  (GdkDevice         *device,
 239                                          guint              index_,
 240                                          GdkAxisUse         use);
 241
 242
 243 void     gdk_device_get_state    (GdkDevice         *device,
 244                                   GdkWindow         *window,
 245                                   gdouble           *axes,
 246                                   GdkModifierType   *mask);
 247 gboolean gdk_device_get_history  (GdkDevice         *device,
 248                                   GdkWindow         *window,
 249                                   guint32            start,
 250                                   guint32            stop,
 251                                   GdkTimeCoord    ***events,
 252                                   gint              *n_events);
 253 void     gdk_device_free_history (GdkTimeCoord     **events,
 254                                   gint               n_events);
 255
 256 guint    gdk_device_get_n_axes     (GdkDevice       *device);
 257 GList *  gdk_device_list_axes      (GdkDevice       *device);
 258 gboolean gdk_device_get_axis_value (GdkDevice       *device,
 259                                     gdouble         *axes,
 260                                     GdkAtom          axis_label,
 261                                     gdouble         *value);
 262
 263 gboolean gdk_device_get_axis     (GdkDevice         *device,
 264                                   gdouble           *axes,
 265                                   GdkAxisUse         use,
 266                                   gdouble           *value);
 267 GdkDisplay * gdk_device_get_display (GdkDevice      *device);
 268
 269 GdkDevice  * gdk_device_get_associated_device (GdkDevice     *device);
 270
 271 GdkDeviceType gdk_device_get_device_type (GdkDevice *device);
 272
 273 GdkGrabStatus gdk_device_grab        (GdkDevice        *device,
 274                                       GdkWindow        *window,
 275                                       GdkGrabOwnership  grab_ownership,
 276                                       gboolean          owner_events,
 277                                       GdkEventMask      event_mask,
 278                                       GdkCursor        *cursor,
 279                                       guint32           time_);
 280
 281 void          gdk_device_ungrab      (GdkDevice        *device,
 282                                       guint32           time_);
 283
 284 gboolean gdk_device_grab_info_libgtk_only (GdkDisplay  *display,
 285                                            GdkDevice   *device,
 286                                            GdkWindow  **grab_window,
 287                                            gboolean    *owner_events);
 288
 289
 290 G_END_DECLS
 291
 292 #endif /* __GDK_DEVICE_H__ */