Clutter Reference Manual: ClutterClickAction

## ClutterClickAction ClutterClickAction — Action for clickable actors |

## Synopsis

    struct              ClutterClickAction;
    struct              ClutterClickActionClass;
    enum                ClutterLongPressState;
    ClutterAction *     clutter_click_action_new            (void);

    guint               clutter_click_action_get_button     (ClutterClickAction *action);
    ClutterModifierType clutter_click_action_get_state      (ClutterClickAction *action);
    void                clutter_click_action_get_coords     (ClutterClickAction *action,
                                                             gfloat *press_x,
                                                             gfloat *press_y);

    void                clutter_click_action_release        (ClutterClickAction *action);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActorMeta
                   +----ClutterAction
                         +----ClutterClickAction

## Properties

      "held"                     gboolean              : Read
      "long-press-duration"      gint                  : Read / Write
      "long-press-threshold"     gint                  : Read / Write
      "pressed"                  gboolean              : Read

## Signals

      "clicked"                                        : Run Last
      "long-press"                                     : Run Last

## Description

ClutterClickAction is a sub-class of ClutterAction that implements the logic for clickable actors, by using the low level events of ClutterActor, such as "button-press-event" and "button-release-event", to synthesize the high level "clicked" signal.

To use ClutterClickAction you just need to apply it to a ClutterActor using `clutter_actor_add_action()` and connect to the "clicked" signal:

    1
    2
    3
    4
    5
    ClutterAction *action = clutter_click_action_new ();

    clutter_actor_add_action (actor, action);

    g_signal_connect (action, "clicked", G_CALLBACK (on_clicked), NULL);

ClutterClickAction also supports long press gestures: a long press is activated if the pointer remains pressed within a certain threshold (as defined by the "long-press-threshold" property) for a minimum amount of time (as the defined by the "long-press-duration" property). The "long-press" signal is emitted multiple times, using different ClutterLongPressState values; to handle long presses you should connect to the "long-press" signal and handle the different states:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    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;
        }
    }

ClutterClickAction is available since Clutter 1.4

## Details

### struct ClutterClickAction

    struct ClutterClickAction;

The ClutterClickAction structure contains only private data and should be accessed using the provided API

Since 1.4

### struct ClutterClickActionClass

    struct ClutterClickActionClass {
      void     (* clicked)    (ClutterClickAction    *action,
                               ClutterActor          *actor);

      gboolean (* long_press) (ClutterClickAction    *action,
                               ClutterActor          *actor,
                               ClutterLongPressState  state);
    };

The ClutterClickActionClass structure contains only private data

`clicked` () | class handler for the "clicked" signal
`long_press` () | class handler for the "long-press" signal

Since 1.4

### enum ClutterLongPressState

    typedef enum {
     /*< prefix=CLUTTER_LONG_PRESS >*/
      CLUTTER_LONG_PRESS_QUERY,
      CLUTTER_LONG_PRESS_ACTIVATE,
      CLUTTER_LONG_PRESS_CANCEL
    } ClutterLongPressState;

The states for the "long-press" signal.

`CLUTTER_LONG_PRESS_QUERY` | Queries the action whether it supports long presses
`CLUTTER_LONG_PRESS_ACTIVATE` | Activates the action on a long press
`CLUTTER_LONG_PRESS_CANCEL` | The long press was cancelled

Since 1.8

### clutter_click_action_new ()

    ClutterAction *     clutter_click_action_new            (void);

Creates a new ClutterClickAction instance

Returns : | the newly created ClutterClickAction

Since 1.4

### clutter_click_action_get_button ()

    guint               clutter_click_action_get_button     (ClutterClickAction *action);

Retrieves the button that was pressed.

`action` : | a ClutterClickAction
Returns : | the button value

Since 1.4

### clutter_click_action_get_state ()

    ClutterModifierType clutter_click_action_get_state      (ClutterClickAction *action);

Retrieves the modifier state of the click action.

`action` : | a ClutterClickAction
Returns : | the modifier state parameter, or 0

Since 1.6

### clutter_click_action_get_coords ()

    void                clutter_click_action_get_coords     (ClutterClickAction *action,
                                                             gfloat *press_x,
                                                             gfloat *press_y);

Retrieves the screen coordinates of the button press.

`action` : | a ClutterClickAction
`press_x` : | return location for the X coordinate, or `NULL`. [out]
`press_y` : | return location for the Y coordinate, or `NULL`. [out]

Since 1.8

### clutter_click_action_release ()

    void                clutter_click_action_release        (ClutterClickAction *action);

Emulates a release of the pointer button, which ungrabs the pointer and unsets the "pressed" state.

This function will also cancel the long press gesture if one was initiated.

This function is useful to break a grab, for instance after a certain amount of time has passed.

`action` : | a ClutterClickAction

Since 1.4

## Property Details

### The `"held"` property

      "held"                     gboolean              : Read

Whether the clickable actor has the pointer grabbed

Default value: FALSE

Since 1.4

### The `"long-press-duration"` property

      "long-press-duration"      gint                  : Read / Write

The minimum duration of a press for it to be recognized as a long press gesture, in milliseconds.

A value of -1 will make the ClutterClickAction use the value of the "long-press-duration" property.

Allowed values: >= -1

Default value: -1

Since 1.8

### The `"long-press-threshold"` property

      "long-press-threshold"     gint                  : Read / Write

The maximum allowed distance that can be covered (on both axes) before a long press gesture is cancelled, in pixels.

A value of -1 will make the ClutterClickAction use the value of the "dnd-drag-threshold" property.

Allowed values: >= -1

Default value: -1

Since 1.8

### The `"pressed"` property

      "pressed"                  gboolean              : Read

Whether the clickable actor should be in "pressed" state

Default value: FALSE

Since 1.4

## Signal Details

### The `"clicked"` signal

    void                user_function                      (ClutterClickAction *action,
                                                            ClutterActor       *actor,
                                                            gpointer            user_data)      : Run Last

The ::clicked signal is emitted when the ClutterActor to which a ClutterClickAction has been applied should respond to a pointer button press and release events

`action` : | the ClutterClickAction that emitted the signal
`actor` : | the ClutterActor attached to the `action`
`user_data` : | user data set when the signal handler was connected.

Since 1.4

### The `"long-press"` signal

    gboolean            user_function                      (ClutterClickAction   *action,
                                                            ClutterActor         *actor,
                                                            ClutterLongPressState state,
                                                            gpointer              user_data)      : Run Last

The ::long-press signal is emitted during the long press gesture handling.

This signal can be emitted multiple times with different states.

The `CLUTTER_LONG_PRESS_QUERY` state will be emitted on button presses, and its return value will determine whether the long press handling should be initiated. If the signal handlers will return `TRUE`, the `CLUTTER_LONG_PRESS_QUERY` state will be followed either by a signal emission with the `CLUTTER_LONG_PRESS_ACTIVATE` state if the long press constraints were respected, or by a signal emission with the `CLUTTER_LONG_PRESS_CANCEL` state if the long press was cancelled.

It is possible to forcibly cancel a long press detection using `clutter_click_action_release()`.

`action` : | the ClutterClickAction that emitted the signal
`actor` : | the ClutterActor attached to the `action`
`state` : | the long press state
`user_data` : | user data set when the signal handler was connected.
Returns : | Only the `CLUTTER_LONG_PRESS_QUERY` state uses the returned value of the handler; other states will ignore it

Since 1.8