[gtk+/wip/tablet-tools: 1/5] gdkdevice: Add GdkDeviceTool to identify device tools

[Carlos Garnacho <carlosg src gnome org>]

commit 78e902aa9fd2003fc4226e72e78e2fac60952749
Author: Carlos Garnacho <carlosg gnome org>
Date:   Tue Jan 6 14:38:14 2015 +0100

    gdkdevice: Add GdkDeviceTool to identify device tools
    
    GdkDeviceTool is an opaque typedef that can be used to identify a given
    tool (eg. pens on tablets) during the app/device lifetime. Tools are only
    set on non-master devices, and are owned by these.
    
    The accounting functions are made private, the only public call on
    GdkDeviceTool so far is gdk_device_tool_get_serial(), useful to identify
    the tool across runs.

 docs/reference/gdk/gdk3-sections.txt |    3 +
 gdk/gdkdevice.c                      |   94 ++++++++++++++++++++++++++++++++++
 gdk/gdkdevice.h                      |    9 +++
 gdk/gdkdeviceprivate.h               |    9 +++
 4 files changed, 115 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt
index b40b04b..d8a6593 100644
--- a/docs/reference/gdk/gdk3-sections.txt
+++ b/docs/reference/gdk/gdk3-sections.txt
@@ -747,6 +747,9 @@ gdk_device_list_axes
 gdk_device_get_axis_value
 gdk_device_get_last_event_window
 
+<SUBSECTION>
+gdk_device_tool_get_serial
+
 <SUBSECTION Standard>
 GDK_TYPE_AXIS_USE
 GDK_TYPE_EXTENSION_MODE
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index ebef53b..0e6ab40 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -43,6 +43,11 @@
 
 typedef struct _GdkAxisInfo GdkAxisInfo;
 
+struct _GdkDeviceTool
+{
+  guint serial;
+};
+
 struct _GdkAxisInfo
 {
   GdkAtom label;
@@ -287,6 +292,12 @@ gdk_device_dispose (GObject *object)
       device->axes = NULL;
     }
 
+  if (device->tools)
+    {
+      g_ptr_array_free (device->tools, TRUE);
+      device->tools = NULL;
+    }
+
   g_free (device->name);
   g_free (device->keys);
 
@@ -1757,3 +1768,86 @@ gdk_device_get_last_event_window (GdkDevice *device)
 
   return info->window_under_pointer;
 }
+
+static GdkDeviceTool *
+gdk_device_tool_copy (GdkDeviceTool *tool)
+{
+  return tool;
+}
+
+static void
+gdk_device_tool_free (GdkDeviceTool *tool)
+{
+  /* Nothing to free here, memory is owned by GdkDevice */
+}
+
+G_DEFINE_BOXED_TYPE (GdkDeviceTool, gdk_device_tool,
+                     gdk_device_tool_copy, gdk_device_tool_free);
+
+GdkDeviceTool *
+gdk_device_tool_new (guint serial)
+{
+  GdkDeviceTool *tool;
+
+  tool = g_new0 (GdkDeviceTool, 1);
+  tool->serial = serial;
+
+  return tool;
+}
+
+void
+gdk_device_add_tool (GdkDevice     *device,
+                     GdkDeviceTool *tool)
+{
+  g_return_if_fail (GDK_IS_DEVICE (device));
+  g_return_if_fail (gdk_device_get_device_type (device) == GDK_DEVICE_TYPE_MASTER);
+  g_return_if_fail (tool != NULL);
+
+  if (!device->tools)
+    device->tools = g_ptr_array_new_with_free_func ((GDestroyNotify) g_free);
+
+  g_ptr_array_add (device->tools, tool);
+}
+
+GdkDeviceTool *
+gdk_device_lookup_tool (GdkDevice *device,
+                        guint      serial)
+{
+  GdkDeviceTool *tool;
+  guint i;
+
+  g_return_val_if_fail (GDK_IS_DEVICE (device), NULL);
+  g_return_val_if_fail (gdk_device_get_device_type (device) == GDK_DEVICE_TYPE_MASTER, NULL);
+
+  if (!device->tools)
+    return NULL;
+
+  for (i = 0; i < device->tools->len; i++)
+    {
+      tool = g_ptr_array_index (device->tools, i);
+
+      if (tool->serial == serial)
+        return tool;
+    }
+
+  return NULL;
+}
+
+/**
+ * gdk_device_tool_get_serial:
+ * @tool: a #GdkDeviceTool
+ *
+ * Gets the serial of this tool, this value can be used to identify a
+ * physical tool (eg. a tablet pen) across program executions.
+ *
+ * Returns: The serial ID for this tool
+ *
+ * Since: 3.16
+ **/
+guint
+gdk_device_tool_get_serial (GdkDeviceTool *tool)
+{
+  g_return_val_if_fail (tool != NULL, 0);
+
+  return tool->serial;
+}
diff --git a/gdk/gdkdevice.h b/gdk/gdkdevice.h
index 7e1094e..8467b14 100644
--- a/gdk/gdkdevice.h
+++ b/gdk/gdkdevice.h
@@ -32,7 +32,10 @@ G_BEGIN_DECLS
 #define GDK_DEVICE(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_DEVICE, GdkDevice))
 #define GDK_IS_DEVICE(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_DEVICE))
 
+#define GDK_TYPE_DEVICE_TOOL    (gdk_device_tool_get_type ())
+
 typedef struct _GdkTimeCoord GdkTimeCoord;
+typedef struct _GdkDeviceTool GdkDeviceTool;
 
 /**
  * GdkInputSource:
@@ -274,6 +277,12 @@ gboolean gdk_device_grab_info_libgtk_only (GdkDisplay  *display,
 GDK_AVAILABLE_IN_3_12
 GdkWindow *gdk_device_get_last_event_window (GdkDevice *device);
 
+GDK_AVAILABLE_IN_3_16
+GType gdk_device_tool_get_type (void) G_GNUC_CONST;
+
+GDK_AVAILABLE_IN_3_16
+guint gdk_device_tool_get_serial (GdkDeviceTool *tool);
+
 G_END_DECLS
 
 #endif /* __GDK_DEVICE_H__ */
diff --git a/gdk/gdkdeviceprivate.h b/gdk/gdkdeviceprivate.h
index a8526b5..902fe4f 100644
--- a/gdk/gdkdeviceprivate.h
+++ b/gdk/gdkdeviceprivate.h
@@ -56,6 +56,8 @@ struct _GdkDevice
   GList *slaves;
   GdkDeviceType type;
   GArray *axes;
+
+  GPtrArray *tools;
 };
 
 struct _GdkDeviceClass
@@ -173,6 +175,13 @@ GdkWindow * _gdk_device_window_at_position    (GdkDevice        *device,
                                                GdkModifierType  *mask,
                                                gboolean          get_toplevel);
 
+/* Device tools */
+GdkDeviceTool *gdk_device_tool_new    (guint          serial);
+GdkDeviceTool *gdk_device_lookup_tool (GdkDevice     *device,
+                                       guint          serial);
+void           gdk_device_add_tool    (GdkDevice     *device,
+                                       GdkDeviceTool *tool);
+
 G_END_DECLS
 
 #endif /* __GDK_DEVICE_PRIVATE_H__ */