gdkdevice: Add GdkDeviceTool to identify device tools

GdkDeviceTool is an opaque object 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

@@ -759,6 +759,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

gdk/gdkdevice.c

@@ -2003,3 +2003,101 @@ gdk_device_get_axes (GdkDevice *device)
 
   return device->axis_flags;
 }
+
+G_DEFINE_TYPE (GdkDeviceTool, gdk_device_tool, G_TYPE_OBJECT)
+
+enum {
+  TOOL_PROP_0,
+  TOOL_PROP_SERIAL,
+  N_TOOL_PROPS
+};
+
+GParamSpec *tool_props[N_TOOL_PROPS] = { 0 };
+
+static void
+gdk_device_tool_set_property (GObject      *object,
+                              guint         prop_id,
+                              const GValue *value,
+                              GParamSpec   *pspec)
+{
+  GdkDeviceTool *tool = GDK_DEVICE_TOOL (object);
+
+  switch (prop_id)
+    {
+    case TOOL_PROP_SERIAL:
+      tool->serial = g_value_get_uint64 (value);
+      break;
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
+      break;
+    }
+}
+
+static void
+gdk_device_tool_get_property (GObject    *object,
+                              guint       prop_id,
+                              GValue     *value,
+                              GParamSpec *pspec)
+{
+  GdkDeviceTool *tool = GDK_DEVICE_TOOL (object);
+
+  switch (prop_id)
+    {
+    case TOOL_PROP_SERIAL:
+      g_value_set_uint64 (value, tool->serial);
+      break;
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
+      break;
+    }
+}
+
+static void
+gdk_device_tool_class_init (GdkDeviceToolClass *klass)
+{
+  GObjectClass *object_class = G_OBJECT_CLASS (klass);
+
+  object_class->set_property = gdk_device_tool_set_property;
+  object_class->get_property = gdk_device_tool_get_property;
+
+  tool_props[TOOL_PROP_SERIAL] = g_param_spec_uint64 ("serial",
+                                                      "Serial",
+                                                      "Serial number",
+                                                      0, G_MAXUINT64, 0,
+                                                      G_PARAM_READWRITE |
+                                                      G_PARAM_CONSTRUCT_ONLY);
+
+  g_object_class_install_properties (object_class, N_TOOL_PROPS, tool_props);
+}
+
+static void
+gdk_device_tool_init (GdkDeviceTool *tool)
+{
+}
+
+GdkDeviceTool *
+gdk_device_tool_new (guint64 serial)
+{
+  return g_object_new (GDK_TYPE_DEVICE_TOOL,
+                       "serial", serial,
+                       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.22
+ **/
+guint
+gdk_device_tool_get_serial (GdkDeviceTool *tool)
+{
+  g_return_val_if_fail (tool != NULL, 0);
+
+  return tool->serial;
+}

gdk/gdkdevice.h

@@ -32,7 +32,12 @@ 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 ())
+#define GDK_DEVICE_TOOL(o)      (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_DEVICE_TOOL, GdkDeviceTool))
+#define GDK_IS_DEVICE_TOOL(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_DEVICE_TOOL))
+
 typedef struct _GdkTimeCoord GdkTimeCoord;
+typedef struct _GdkDeviceTool GdkDeviceTool;
 
 /**
  * GdkInputSource:
@@ -320,6 +325,12 @@ GdkSeat     *gdk_device_get_seat            (GdkDevice *device);
 GDK_AVAILABLE_IN_3_22
 GdkAxisFlags gdk_device_get_axes            (GdkDevice *device);
 
+GDK_AVAILABLE_IN_3_22
+GType gdk_device_tool_get_type (void) G_GNUC_CONST;
+
+GDK_AVAILABLE_IN_3_22
+guint gdk_device_tool_get_serial (GdkDeviceTool *tool);
+
 G_END_DECLS
 
 #endif /* __GDK_DEVICE_H__ */

gdk/gdkdeviceprivate.h

@@ -30,8 +30,20 @@ G_BEGIN_DECLS
 #define GDK_DEVICE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GDK_TYPE_DEVICE, GdkDeviceClass))
 
 typedef struct _GdkDeviceClass GdkDeviceClass;
+typedef struct _GdkDeviceToolClass GdkDeviceToolClass;
 typedef struct _GdkDeviceKey GdkDeviceKey;
 
+struct _GdkDeviceTool
+{
+  GObject parent_instance;
+  guint64 serial;
+};
+
+struct _GdkDeviceToolClass
+{
+  GObjectClass parent_class;
+};
+
 struct _GdkDeviceKey
 {
   guint keyval;
@@ -184,6 +196,9 @@ GdkWindow * _gdk_device_window_at_position    (GdkDevice        *device,
 void  gdk_device_set_seat  (GdkDevice *device,
                             GdkSeat   *seat);
 
+/* Device tools */
+GdkDeviceTool *gdk_device_tool_new    (guint64        serial);
+
 G_END_DECLS
 
 #endif /* __GDK_DEVICE_PRIVATE_H__ */