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

hierarchy this ClutterGesture ancestor_0 ClutterAction ancestor_0--this ancestor_1 ClutterActorMeta ancestor_1--ancestor_0 ancestor_2 GInitiallyUnowned ancestor_2--ancestor_1 ancestor_3 GObject ancestor_3--ancestor_2

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

Clutter.Gesture::cancel

The ::cancel signal is emitted when a continuous gesture got cancelled.

Clutter.Gesture::end

The ::end signal is emitted when a continuous gesture ends.

Clutter.Gesture::may-recognize

The ::may-recognize signal is emitted if the gesture might become active and move to RECOGNIZING. Its purpose is to allow the implementation or a user of a gesture to prohibit the gesture from starting when needed.

Clutter.Gesture::recognize

The ::recognize signal is emitted when the gesture recognizes.

Clutter.Gesture::should-handle-sequence

The ::should-handle-sequence signal is emitted when a sequence gets added to the gesture. Return FALSE to make the gesture ignore the sequence of events.

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.

Virtual methods

Clutter.GestureClass.crossing_event
No description available.

Clutter.GestureClass.may_recognize
No description available.

Clutter.GestureClass.point_began
No description available.

Clutter.GestureClass.point_ended
No description available.

Clutter.GestureClass.point_moved
No description available.

Clutter.GestureClass.sequences_cancelled
No description available.

Clutter.GestureClass.should_influence
No description available.

Clutter.GestureClass.state_changed
No description available.