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: >= G_MAXULONG

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: >= G_MAXULONG

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

Generated by GTK-Doc V1.18.1