Clutter Reference Manual: ClutterClickAction

## ClutterClickAction ClutterClickAction — Action for clickable actors |

## Functions

ClutterAction * | clutter_click_action_new ()
guint | clutter_click_action_get_button ()
ClutterModifierType | clutter_click_action_get_state ()
void | clutter_click_action_get_coords ()
void | clutter_click_action_release ()

## Properties

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

## Signals

void | clicked | Run Last
gboolean | long-press | Run Last

## Types and Values

struct | ClutterClickAction
struct | ClutterClickActionClass
enum | ClutterLongPressState

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActorMeta
                ╰── ClutterAction
                    ╰── ClutterClickAction

## 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

## Functions

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

action | a ClutterClickAction |

Since 1.4

## Types and Values

### 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

#### Members

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

Since 1.4

### enum ClutterLongPressState

The states for the “long-press” signal.

#### Members

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

## Property Details

### The `“held”` property

      “held”                     gboolean

Whether the clickable actor has the pointer grabbed

Flags: Read

Default value: FALSE

Since 1.4

### The `“long-press-duration”` property

      “long-press-duration”      gint

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.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since 1.8

### The `“long-press-threshold”` property

      “long-press-threshold”     gint

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.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since 1.8

### The `“pressed”` property

      “pressed”                  gboolean

Whether the clickable actor should be in "pressed" state

Flags: Read

Default value: FALSE

Since 1.4

## Signal Details

### The `“clicked”` signal

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

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

#### Parameters

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. |

Flags: Run Last

Since 1.4

### The `“long-press”` signal

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

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()`.

#### Parameters

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

Flags: Run Last

Since 1.8