gdk: Add GdkDevicePad

This is an interface meant to be implemented by the "pad" devices.
This device-specific interface exposes the mapping of all pad features,
it allows retrieving:
- The number of buttons/rings/strips
- The number of groups
- The number of modes a group has
- Whether a given button/ring/strip belongs to a given group

https://bugzilla.gnome.org/show_bug.cgi?id=770026

1 files changed, 150 insertions, 0 deletions

diff --git a/gdk/gdkdevicepad.c b/gdk/gdkdevicepad.c
new file mode 100644
index 0000000000..02282f1068
--- /dev/null
+++ b/gdk/gdkdevicepad.c
@@ -0,0 +1,150 @@
+/* GDK - The GIMP Drawing Kit
+ * Copyright (C) 2016 Red Hat
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Author: Carlos Garnacho <carlosg@gnome.org>
+ */
+
+/**
+ * SECTION:gdkdevicepad
+ * @Short_description: Pad device interface
+ * @Title: GtkDevicePad
+ *
+ * #GdkDevicePad is an interface implemented by devices of type
+ * %GDK_SOURCE_TABLET_PAD, it allows querying the features provided
+ * by the pad device.
+ *
+ * Tablet pads may contain one or more groups, each containing a subset
+ * of the buttons/rings/strips available. gdk_device_pad_get_n_groups()
+ * can be used to obtain the number of groups, gdk_device_pad_get_n_features()
+ * and gdk_device_pad_get_feature_group() can be combined to find out the
+ * number of buttons/rings/strips the device has, and how are they grouped.
+ *
+ * Each of those groups have different modes, which may be used to map
+ * each individual pad feature to multiple actions. Only one mode is
+ * effective (current) for each given group, different groups may have
+ * different current modes. The number of available modes in a group can
+ * be found out through gdk_device_pad_get_group_n_modes(), and the current
+ * mode for a given group will be notified through the #GdkEventPadGroupMode
+ * event.
+ *
+ */
+
+#include "config.h"
+
+#include "gdkdevicepad.h"
+#include "gdkdevicepadprivate.h"
+#include "gdkdeviceprivate.h"
+
+G_DEFINE_INTERFACE (GdkDevicePad, gdk_device_pad, GDK_TYPE_DEVICE)
+
+static void
+gdk_device_pad_default_init (GdkDevicePadInterface *pad)
+{
+}
+
+/**
+ * gdk_device_pad_get_n_groups:
+ * @pad: a #GdkDevicePad
+ *
+ * Returns the number of groups this pad device has. Pads have
+ * at least one group. A pad group is a subcollection of
+ * buttons/strip/rings that is affected collectively by a same
+ * current mode.
+ *
+ * Returns: The number of button/ring/strip groups in the pad.
+ *
+ * Since: 3.22
+ **/
+gint
+gdk_device_pad_get_n_groups (GdkDevicePad *pad)
+{
+  GdkDevicePadInterface *iface = GDK_DEVICE_PAD_GET_IFACE (pad);
+
+  g_return_val_if_fail (GDK_IS_DEVICE_PAD (pad), 0);
+
+  return iface->get_n_groups (pad);
+}
+
+/**
+ * gdk_device_pad_get_group_n_modes:
+ * @pad: a #GdkDevicePad
+ * @group_idx: group to get the number of available modes from
+ *
+ * Returns the number of modes that @group may have.
+ *
+ * Returns: The number of modes available in @group.
+ *
+ * Since: 3.22
+ **/
+gint
+gdk_device_pad_get_group_n_modes (GdkDevicePad *pad,
+                                  gint          group_idx)
+{
+  GdkDevicePadInterface *iface = GDK_DEVICE_PAD_GET_IFACE (pad);
+
+  g_return_val_if_fail (GDK_IS_DEVICE_PAD (pad), 0);
+  g_return_val_if_fail (group_idx >= 0, 0);
+
+  return iface->get_group_n_modes (pad, group_idx);
+}
+
+/**
+ * gdk_device_pad_get_n_features:
+ * @pad: a #GdkDevicePad
+ * @feature: a pad feature
+ *
+ * Returns the number of features a tablet pad has.
+ *
+ * Returns: The amount of elements of type @feature that this pad has.
+ *
+ * Since: 3.22
+ **/
+gint
+gdk_device_pad_get_n_features (GdkDevicePad        *pad,
+                               GdkDevicePadFeature  feature)
+{
+  GdkDevicePadInterface *iface = GDK_DEVICE_PAD_GET_IFACE (pad);
+
+  g_return_val_if_fail (GDK_IS_DEVICE_PAD (pad), 0);
+
+  return iface->get_n_features (pad, feature);
+}
+
+/**
+ * gdk_device_pad_get_feature_group:
+ * @pad: a #GdkDevicePad
+ * @feature: the feature type to get the group from
+ * @feature_idx: the index of the feature to get the group from
+ *
+ * Returns the group the given @feature and @idx belong to,
+ * or -1 if feature/index do not exist in @pad.
+ *
+ * Returns: The group number of the queried pad feature.
+ *
+ * Since: 3.22
+ **/
+gint
+gdk_device_pad_get_feature_group (GdkDevicePad        *pad,
+                                  GdkDevicePadFeature  feature,
+                                  gint                 idx)
+{
+  GdkDevicePadInterface *iface = GDK_DEVICE_PAD_GET_IFACE (pad);
+
+  g_return_val_if_fail (GDK_IS_DEVICE_PAD (pad), -1);
+  g_return_val_if_fail (idx >= 0, -1);
+
+  return iface->get_feature_group (pad, feature, idx);
+}