tap-action: Add TapAction, to handle mouse/touch tapping

TapAction is a GestureAction-subclass that handles clicks and
tap gestures. It is meant to provide a replacement for ClickAction
using GestureAction:

• it handles events trasparently without capturing them, so that it
  can coexists with other GestureActions;

• the ::tap signal is not emitted if the drag threshold is exceeded;

• building upon GestureAction the amount of code is greatly reduced.

TapAction provides:

• tap signal, notifying users when a tap has been performed.

The image-content example program has been updated replacing its
ClickAction usage with TapAction.

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

9 files changed, 273 insertions, 5 deletions

diff --git a/clutter/Makefile.am b/clutter/Makefile.am
index 70a4792c4..b6d092209 100644
--- a/clutter/Makefile.am
+++ b/clutter/Makefile.am
@@ -118,6 +118,7 @@ source_h =					\
 	$(srcdir)/clutter-stage.h 		\
 	$(srcdir)/clutter-stage-manager.h	\
 	$(srcdir)/clutter-table-layout.h	\
+	$(srcdir)/clutter-tap-action.h		\
 	$(srcdir)/clutter-texture.h 		\
 	$(srcdir)/clutter-text.h		\
 	$(srcdir)/clutter-text-buffer.h		\
@@ -201,6 +202,7 @@ source_c = \
 	$(srcdir)/clutter-stage-manager.c	\
 	$(srcdir)/clutter-stage-window.c	\
 	$(srcdir)/clutter-table-layout.c	\
+	$(srcdir)/clutter-tap-action.c		\
 	$(srcdir)/clutter-text.c		\
 	$(srcdir)/clutter-text-buffer.c		\
 	$(srcdir)/clutter-transition-group.c	\
diff --git a/clutter/clutter-tap-action.c b/clutter/clutter-tap-action.c
new file mode 100644
index 000000000..3424455d4
--- /dev/null
+++ b/clutter/clutter-tap-action.c
@@ -0,0 +1,142 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2010  Intel Corporation.
+ * Copyright (C) 2011  Robert Bosch Car Multimedia GmbH.
+ * Copyright (C) 2012  Collabora Ltd.
+ *
+ * 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:
+ *   Emanuele Aina <emanuele.aina@collabora.com>
+ *
+ * Based on ClutterPanAction
+ * Based on ClutterDragAction, ClutterSwipeAction, and MxKineticScrollView,
+ * written by:
+ *   Emmanuele Bassi <ebassi@linux.intel.com>
+ *   Tomeu Vizoso <tomeu.vizoso@collabora.co.uk>
+ *   Chris Lord <chris@linux.intel.com>
+ */
+
+/**
+ * SECTION:clutter-tap-action
+ * @Title: ClutterTapAction
+ * @Short_Description: Action for tap gestures
+ *
+ * #ClutterTapAction is a sub-class of #ClutterGestureAction that implements
+ * the logic for recognizing mouse clicks and touch tap gestures.
+ *
+ * The simplest usage of #ClutterTapAction consists in adding it to
+ * a #ClutterActor with a child, setting it as reactive and connecting a
+ * callback for the #ClutterTapAction::tap signal, along the lines of the
+ * following code:
+ *
+ * |[
+ *   clutter_actor_add_action (actor, clutter_tap_action_new ());
+ *   clutter_actor_set_reactive (actor, TRUE);
+ *   g_signal_connect (action, "tap", G_CALLBACK (on_tap_callback), NULL);
+ * ]|
+ *
+ * Since: 1.14
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include "clutter-tap-action.h"
+
+#include "clutter-debug.h"
+#include "clutter-enum-types.h"
+#include "clutter-gesture-action-private.h"
+#include "clutter-marshal.h"
+#include "clutter-private.h"
+
+enum
+{
+  TAP,
+
+  LAST_SIGNAL
+};
+
+static guint tap_signals[LAST_SIGNAL] = { 0, };
+
+G_DEFINE_TYPE (ClutterTapAction, clutter_tap_action,
+               CLUTTER_TYPE_GESTURE_ACTION);
+
+static void
+emit_tap (ClutterTapAction *self,
+          ClutterActor     *actor)
+{
+  g_signal_emit (self, tap_signals[TAP], 0, actor);
+}
+
+static void
+gesture_end (ClutterGestureAction *gesture,
+             ClutterActor         *actor)
+{
+  emit_tap (CLUTTER_TAP_ACTION (gesture), actor);
+}
+
+static void
+clutter_tap_action_class_init (ClutterTapActionClass *klass)
+{
+  ClutterGestureActionClass *gesture_class =
+      CLUTTER_GESTURE_ACTION_CLASS (klass);
+
+  gesture_class->gesture_end = gesture_end;
+
+  /**
+   * ClutterTapAction::tap:
+   * @action: the #ClutterTapAction that emitted the signal
+   * @actor: the #ClutterActor attached to the @action
+   *
+   * The ::tap signal is emitted when the tap gesture is complete.
+   *
+   * Since: 1.14
+   */
+  tap_signals[TAP] =
+    g_signal_new (I_("tap"),
+                  G_TYPE_FROM_CLASS (klass),
+                  G_SIGNAL_RUN_LAST,
+                  G_STRUCT_OFFSET (ClutterTapActionClass, tap),
+                  NULL, NULL,
+                  _clutter_marshal_VOID__OBJECT,
+                  G_TYPE_NONE, 1,
+                  CLUTTER_TYPE_ACTOR);
+}
+
+static void
+clutter_tap_action_init (ClutterTapAction *self)
+{
+  _clutter_gesture_action_set_threshold_trigger_edge (CLUTTER_GESTURE_ACTION (self),
+                                                      CLUTTER_GESTURE_TRIGGER_EDGE_BEFORE);
+}
+
+/**
+ * clutter_tap_action_new:
+ *
+ * Creates a new #ClutterTapAction instance
+ *
+ * Return value: the newly created #ClutterTapAction
+ *
+ * Since: 1.14
+ */
+ClutterAction *
+clutter_tap_action_new (void)
+{
+  return g_object_new (CLUTTER_TYPE_TAP_ACTION, NULL);
+}
diff --git a/clutter/clutter-tap-action.h b/clutter/clutter-tap-action.h
new file mode 100644
index 000000000..12f54173c
--- /dev/null
+++ b/clutter/clutter-tap-action.h
@@ -0,0 +1,102 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2010  Intel Corporation.
+ * Copyright (C) 2011  Robert Bosch Car Multimedia GmbH.
+ * Copyright (C) 2012  Collabora Ltd.
+ *
+ * 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:
+ *   Emanuele Aina <emanuele.aina@collabora.com>
+ *
+ * Based on ClutterPanAction
+ * Based on ClutterDragAction, ClutterSwipeAction, and MxKineticScrollView,
+ * written by:
+ *   Emmanuele Bassi <ebassi@linux.intel.com>
+ *   Tomeu Vizoso <tomeu.vizoso@collabora.co.uk>
+ *   Chris Lord <chris@linux.intel.com>
+ */
+
+#if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
+#error "Only <clutter/clutter.h> can be included directly."
+#endif
+
+#ifndef __CLUTTER_TAP_ACTION_H__
+#define __CLUTTER_TAP_ACTION_H__
+
+#include <clutter/clutter-gesture-action.h>
+
+G_BEGIN_DECLS
+
+#define CLUTTER_TYPE_TAP_ACTION               (clutter_tap_action_get_type ())
+#define CLUTTER_TAP_ACTION(obj)               (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_TAP_ACTION, ClutterTapAction))
+#define CLUTTER_IS_TAP_ACTION(obj)            (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_TAP_ACTION))
+#define CLUTTER_TAP_ACTION_CLASS(klass)       (G_TYPE_CHECK_CLASS_CAST ((klass), CLUTTER_TYPE_TAP_ACTION, ClutterTapActionClass))
+#define CLUTTER_IS_TAP_ACTION_CLASS(klass)    (G_TYPE_CHECK_CLASS_TYPE ((klass), CLUTTER_TYPE_TAP_ACTION))
+#define CLUTTER_TAP_ACTION_GET_CLASS(obj)     (G_TYPE_INSTANCE_GET_CLASS ((obj), CLUTTER_TYPE_TAP_ACTION, ClutterTapActionClass))
+
+typedef struct _ClutterTapAction              ClutterTapAction;
+typedef struct _ClutterTapActionPrivate       ClutterTapActionPrivate;
+typedef struct _ClutterTapActionClass         ClutterTapActionClass;
+
+/**
+ * ClutterTapAction:
+ *
+ * The <structname>ClutterTapAction</structname> structure contains
+ * only private data and should be accessed using the provided API
+ *
+ * Since: 1.14
+ */
+struct _ClutterTapAction
+{
+  /*< private >*/
+  ClutterGestureAction parent_instance;
+};
+
+/**
+ * ClutterTapActionClass:
+ * @tap: class handler for the #ClutterTapAction::tap signal
+ *
+ * The <structname>ClutterTapActionClass</structname> structure contains
+ * only private data.
+ */
+struct _ClutterTapActionClass
+{
+  /*< private >*/
+  ClutterGestureActionClass parent_class;
+
+  /*< public >*/
+  gboolean (* tap)               (ClutterTapAction    *action,
+                                  ClutterActor        *actor);
+
+  /*< private >*/
+  void (* _clutter_tap_action1) (void);
+  void (* _clutter_tap_action2) (void);
+  void (* _clutter_tap_action3) (void);
+  void (* _clutter_tap_action4) (void);
+  void (* _clutter_tap_action5) (void);
+  void (* _clutter_tap_action6) (void);
+};
+
+CLUTTER_AVAILABLE_IN_1_14
+GType clutter_tap_action_get_type (void) G_GNUC_CONST;
+
+CLUTTER_AVAILABLE_IN_1_14
+ClutterAction * clutter_tap_action_new   (void);
+G_END_DECLS
+
+#endif /* __CLUTTER_TAP_ACTION_H__ */
diff --git a/clutter/clutter.h b/clutter/clutter.h
index 76a94bc7a..5bdd6bcf5 100644
--- a/clutter/clutter.h
+++ b/clutter/clutter.h
@@ -99,6 +99,7 @@
 #include "clutter-stage.h"
 #include "clutter-stage-manager.h"
 #include "clutter-table-layout.h"
+#include "clutter-tap-action.h"
 #include "clutter-texture.h"
 #include "clutter-text.h"
 #include "clutter-timeline.h"
diff --git a/clutter/clutter.symbols b/clutter/clutter.symbols
index b8e2a527e..1378745fc 100644
--- a/clutter/clutter.symbols
+++ b/clutter/clutter.symbols
@@ -1343,6 +1343,8 @@ clutter_table_layout_set_fill
 clutter_table_layout_set_row_spacing
 clutter_table_layout_set_span
 clutter_table_layout_set_use_animations
+clutter_tap_action_get_type
+clutter_tap_action_new
 clutter_texture_get_base_size
 clutter_texture_get_cogl_texture
 clutter_texture_get_cogl_material
diff --git a/doc/reference/clutter/clutter-docs.xml.in b/doc/reference/clutter/clutter-docs.xml.in
index 08aa2494c..10ea5872b 100644
--- a/doc/reference/clutter/clutter-docs.xml.in
+++ b/doc/reference/clutter/clutter-docs.xml.in
@@ -100,6 +100,7 @@
       <xi:include href="xml/clutter-swipe-action.xml"/>
       <xi:include href="xml/clutter-rotate-action.xml"/>
       <xi:include href="xml/clutter-zoom-action.xml"/>
+      <xi:include href="xml/clutter-tap-action.xml"/>
     </chapter>
 
     <chapter>
diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt
index 287644395..c3c701c0e 100644
--- a/doc/reference/clutter/clutter-sections.txt
+++ b/doc/reference/clutter/clutter-sections.txt
@@ -3483,3 +3483,20 @@ CLUTTER_PAN_ACTION_GET_CLASS
 ClutterPanActionPrivate
 clutter_pan_action_get_type
 </SECTION>
+
+<SECTION>
+<FILE>clutter-tap-action</FILE>
+ClutterTapAction
+ClutterTapActionClass
+clutter_tap_action_new
+<SUBSECTION Standard>
+CLUTTER_IS_TAP_ACTION
+CLUTTER_IS_TAP_ACTION_CLASS
+CLUTTER_TYPE_TAP_ACTION
+CLUTTER_TAP_ACTION
+CLUTTER_TAP_ACTION_CLASS
+CLUTTER_TAP_ACTION_GET_CLASS
+<SUBSECTION Private>
+ClutterTapActionPrivate
+clutter_tap_action_get_type
+</SECTION>
diff --git a/doc/reference/clutter/clutter.types b/doc/reference/clutter/clutter.types
index cc6d8b2c9..1fd1996de 100644
--- a/doc/reference/clutter/clutter.types
+++ b/doc/reference/clutter/clutter.types
@@ -74,6 +74,7 @@ clutter_stage_manager_get_type
 clutter_state_get_type
 clutter_swipe_action_get_type
 clutter_table_layout_get_type
+clutter_tap_action_get_type
 clutter_text_buffer_get_type
 clutter_text_get_type
 clutter_texture_get_type
diff --git a/examples/image-content.c b/examples/image-content.c
index 2c7ad6d71..a661d2caa 100644
--- a/examples/image-content.c
+++ b/examples/image-content.c
@@ -26,9 +26,9 @@ static int n_gravities = G_N_ELEMENTS (gravities);
 static int cur_gravity = 0;
 
 static void
-on_clicked (ClutterClickAction *action,
-            ClutterActor       *actor,
-            ClutterText        *label)
+on_tap (ClutterTapAction *action,
+        ClutterActor       *actor,
+        ClutterText        *label)
 {
   gchar *str;
 
@@ -105,8 +105,8 @@ main (int argc, char *argv[])
 
   g_free (str);
 
-  action = clutter_click_action_new ();
-  g_signal_connect (action, "clicked", G_CALLBACK (on_clicked), text);
+  action = clutter_tap_action_new ();
+  g_signal_connect (action, "tap", G_CALLBACK (on_tap), text);
   clutter_actor_set_reactive (box, TRUE);
   clutter_actor_add_action (box, action);