
@c %start of fragment

@node ClutterClickAction
@chapter ClutterClickAction
Action for clickable actors

@section Overview
@code{<clutter-click-action>} is a sub-class of @code{<clutter-action>}
that implements the logic for clickable actors, by using the low level
events of @code{<clutter-actor>}, such as
@code{<“button-press-event”>} and
@code{<“button-release-event”>}, to synthesize the high level
@code{<“clicked”>} signal.

To use @code{<clutter-click-action>} you just need to apply it to a
@code{<clutter-actor>} using @code{clutter-actor-add-action} and connect
to the @code{<“clicked”>} signal:

@example 

  ClutterAction *action = clutter_click_action_new ();

  clutter_actor_add_action (actor, action);

  g_signal_connect (action, "clicked", G_CALLBACK (on_clicked), NULL);
@end example

@code{<clutter-click-action>} also supports long press gestures: a long
press is activated if the pointer remains pressed within a certain
threshold (as defined by the @code{<“long-press-threshold”>}
property) for a minimum amount of time (as the defined by the
@code{<“long-press-duration”>} property).  The
@code{<“long-press”>} signal is emitted multiple times, using
different @code{<clutter-long-press-state>} values; to handle long
presses you should connect to the @code{<“long-press”>} signal and
handle the different states:

@example 

  static gboolean
  on_long_press (ClutterClickAction    *action,
                 ClutterActor          *actor,
                 ClutterLongPressState  state)
  @{
    switch (state)
      @{
      case CLUTTER_LONG_PRESS_QUERY:
        /* return TRUE if the actor should support long press
         * gestures, and FALSE otherwise; this state will be
         * emitted on button presses
         */
        return TRUE;

      case CLUTTER_LONG_PRESS_ACTIVATE:
        /* this state is emitted if the minimum duration has
         * been reached without the gesture being cancelled.
         * the return value is not used
         */
        return TRUE;

      case CLUTTER_LONG_PRESS_CANCEL:
        /* this state is emitted if the long press was cancelled;
         * for instance, the pointer went outside the actor or the
         * allowed threshold, or the button was released before
         * the minimum duration was reached. the return value is
         * not used
         */
        return FALSE;
      @}
  @}
@end example

@code{<clutter-click-action>} is available since Clutter 1.4

@section Usage
@include defuns-clutter-click-action.xml.texi

@c %end of fragment
