Class

ClutterGesture

Description [src]

abstract class Clutter.Gesture : Clutter.Action
{
  /* No available fields */
}

A ClutterAction for recognizing gestures

ClutterGesture is a sub-class of ClutterAction and an abstract base class for implementing the logic to recognize various input gestures.

Implementing a ClutterGesture is done by subclassing ClutterGesture, connecting to the should_handle_sequence(), point_began()/moved()/ended() and sequences_cancelled() vfuncs, and then moving the gesture through the ClutterGestureState state machine using clutter_gesture_set_state().

Recognizing new gestures

ClutterGesture uses five separate states to differentiate between the phases of gesture recognition. Those states also define whether to block or allow event delivery:

WAITING: The gesture will be starting out in this state if no points are available. When points are added, the state automatically moves to POSSIBLE before the point_began() vfunc gets called.
POSSIBLE: This is the state the gesture will be in when point_began() gets called the first time. As soon as the implementation is reasonably sure that the sequence of events is the gesture, it should set the state to RECOGNIZING.
RECOGNIZING: A continuous gesture is being recognized. In this state the implementation usually triggers UI changes as feedback to the user.
COMPLETED: The gesture was sucessfully recognized and has been completed. The gesture will automatically move to state WAITING after all the remaining points have ended.
CANCELLED: The gesture was either not started at all because preconditions were not fulfilled or it was cancelled by the implementation. The gesture will automatically move to state WAITING after all the remaining points have ended.

Each ClutterGesture starts out in the WAITING state and automatically moves to POSSIBLE when ClutterGestureClass.should_handle_sequence() returns true for the first event of an event sequence. Events of this sequence must then be handled using the point_began(), point_moved(), point_ended() and sequences_cancelled() vfuncs. From these events, the implementation moves the gesture through the ClutterGestureState state-machine.

Note that point_ended() and sequences_cancelled() both have a default implementation which automatically moves the state of the gesture to CANCELLED.

Note that it’s not guaranteed that clutter_gesture_set_state() will always (and immediately) enter the requested state. To deal with this, never assume the state has changed after calling clutter_gesture_set_state(), and react to state changes by implementing the state_changed() vfunc.

Relationships of gestures

By default, when multiple gestures try to recognize while sharing one or more points, the first gesture to move to RECOGNIZING wins, and implicitly moves all conflicting gestures to state CANCELLED. This behavior can be prohibited by using the clutter_gesture_can_not_cancel() API or by implementing the should_influence() or should_be_influenced_by() vfuncs in your ClutterGesture subclass.

Hierarchy

Ancestors

Instance methods

clutter_gesture_can_not_cancel

In case self and other_gesture are operating on the same points, calling this function will make sure that self does not cancel other_gesture when self moves to state RECOGNIZING.

clutter_gesture_cancel

Cancels the gesture by setting its state to CANCELLED.

clutter_gesture_get_n_points

Retrieves the number of active points the gesture currently has.

clutter_gesture_get_point_begin_coords

Retrieves the begin coordinates of the point with index point_index.

clutter_gesture_get_point_begin_coords_abs

No description available.

clutter_gesture_get_point_coords

Retrieves the latest coordinates of the point with index point_index.

clutter_gesture_get_point_coords_abs

No description available.

clutter_gesture_get_point_event

Retrieves the the latest event of the point with index point_index.

clutter_gesture_get_point_previous_coords

Retrieves the previous coordinates of the point with index point_index.

clutter_gesture_get_point_previous_coords_abs

No description available.

clutter_gesture_get_points

Retrieves an array of the currently active points of the gesture, the array is ordered in the order the points were added in (newest to oldest).

clutter_gesture_get_state

Gets the current state of the gesture.

clutter_gesture_reset_state_machine

No description available.

clutter_gesture_set_state

Sets the state of the gesture. This method is private to gesture implementations.

Methods inherited from ClutterAction (1)

clutter_action_get_phase

No description available.

Methods inherited from ClutterActorMeta (5)

clutter_actor_meta_get_actor

Retrieves a pointer to the ClutterActor that owns meta.

clutter_actor_meta_get_enabled

Retrieves whether meta is enabled.

clutter_actor_meta_get_name

Retrieves the name set using clutter_actor_meta_set_name().

clutter_actor_meta_set_enabled

Sets whether meta should be enabled or not.

clutter_actor_meta_set_name

Sets the name of meta.

Methods inherited from GObject (43)

Please see GObject for a full list of methods.

Properties

Clutter.Gesture:state

The current state of the gesture.

Properties inherited from ClutterActorMeta (3)

Clutter.ActorMeta:actor

The ClutterActor attached to the ClutterActorMeta instance.

Clutter.ActorMeta:enabled

Whether or not the ClutterActorMeta is enabled.

Clutter.ActorMeta:name

The unique name to access the ClutterActorMeta.

Signals inherited from GObject (1)

GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Class structure

struct ClutterGestureClass {
  ClutterActionClass parent_class;
  gboolean (* should_handle_sequence) (
    ClutterGesture* self,
    const ClutterEvent* sequence_begin_event
  );
  void (* point_began) (
    ClutterGesture* self,
    unsigned int sequence_index
  );
  void (* point_moved) (
    ClutterGesture* self,
    unsigned int sequence_index
  );
  void (* point_ended) (
    ClutterGesture* self,
    unsigned int sequence_index
  );
  void (* sequences_cancelled) (
    ClutterGesture* self,
    unsigned int* sequences,
    unsigned int n_sequences
  );
  void (* state_changed) (
    ClutterGesture* self,
    ClutterGestureState old_state,
    ClutterGestureState new_state
  );
  void (* crossing_event) (
    ClutterGesture* self,
    unsigned int sequence_index,
    ClutterEventType type,
    uint32_t time,
    ClutterEventFlags flags,
    ClutterActor* source_actor,
    ClutterActor* related_actor
  );
  gboolean (* may_recognize) (
    ClutterGesture* self
  );
  void (* should_influence) (
    ClutterGesture* self,
    ClutterGesture* other_gesture,
    gboolean* cancel_on_recognizing
  );
  void (* should_be_influenced_by) (
    ClutterGesture* self,
    ClutterGesture* other_gesture,
    gboolean* cancelled_on_recognizing
  );
  
}

No description available.

Class members

parent_class: ClutterActionClass: No description available.
should_handle_sequence: gboolean (* should_handle_sequence) ( ClutterGesture* self, const ClutterEvent* sequence_begin_event ): No description available.
point_began: void (* point_began) ( ClutterGesture* self, unsigned int sequence_index ): No description available.
point_moved: void (* point_moved) ( ClutterGesture* self, unsigned int sequence_index ): No description available.
point_ended: void (* point_ended) ( ClutterGesture* self, unsigned int sequence_index ): No description available.
sequences_cancelled: void (* sequences_cancelled) ( ClutterGesture* self, unsigned int* sequences, unsigned int n_sequences ): No description available.
state_changed: void (* state_changed) ( ClutterGesture* self, ClutterGestureState old_state, ClutterGestureState new_state ): No description available.
crossing_event: void (* crossing_event) ( ClutterGesture* self, unsigned int sequence_index, ClutterEventType type, uint32_t time, ClutterEventFlags flags, ClutterActor* source_actor, ClutterActor* related_actor ): No description available.
may_recognize: gboolean (* may_recognize) ( ClutterGesture* self ): No description available.
should_influence: void (* should_influence) ( ClutterGesture* self, ClutterGesture* other_gesture, gboolean* cancel_on_recognizing ): No description available.
should_be_influenced_by: void (* should_be_influenced_by) ( ClutterGesture* self, ClutterGesture* other_gesture, gboolean* cancelled_on_recognizing ): No description available.

Description [src]

Recognizing new gestures

Relationships of gestures

Hierarchy

Ancestors

Instance methods

Methods inherited from ClutterAction (1)

Methods inherited from ClutterActorMeta (5)

Methods inherited from GObject (43)

Properties

Properties inherited from ClutterActorMeta (3)

Signals

Signals inherited from GObject (1)

Class structure

Class members

Virtual methods