Clutter.Gesture
Description: Reference for Clutter.Gesture

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

#### Ancestors

- ClutterAction
- ClutterActorMeta
- GInitiallyUnowned
- GObject

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

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

No description available.

###### Clutter.GestureClass.should_handle_sequence

No description available.

###### Clutter.GestureClass.should_influence

No description available.

###### Clutter.GestureClass.state_changed

No description available.