ClutterClickAction

ClutterClickAction — Action for clickable actors

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

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