ClutterPanAction: Clutter Reference Manual

## ClutterPanAction ClutterPanAction — Action for pan gestures |

## Functions

ClutterAction * | clutter_pan_action_new ()
void | clutter_pan_action_set_pan_axis ()
ClutterPanAxis | clutter_pan_action_get_pan_axis ()
void | clutter_pan_action_set_interpolate ()
gboolean | clutter_pan_action_get_interpolate ()
void | clutter_pan_action_set_deceleration ()
gdouble | clutter_pan_action_get_deceleration ()
void | clutter_pan_action_set_acceleration_factor ()
gdouble | clutter_pan_action_get_acceleration_factor ()
void | clutter_pan_action_get_interpolated_coords ()
gfloat | clutter_pan_action_get_interpolated_delta ()
void | clutter_pan_action_get_motion_coords ()
gfloat | clutter_pan_action_get_motion_delta ()
gfloat | clutter_pan_action_get_constrained_motion_delta ()

## Properties

gdouble | acceleration-factor | Read / Write
gdouble | deceleration | Read / Write
gboolean | interpolate | Read / Write
ClutterPanAxis | pan-axis | Read / Write

## Signals

gboolean | pan | Run Last
void | pan-stopped | Run Last

## Types and Values

struct | ClutterPanAction
struct | ClutterPanActionClass
enum | ClutterPanAxis

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActorMeta
                ╰── ClutterAction
                    ╰── ClutterGestureAction
                        ╰── ClutterPanAction

## Description

ClutterPanAction is a sub-class of ClutterGestureAction that implements the logic for recognizing pan gestures.

The simplest usage of ClutterPanAction consists in adding it to a ClutterActor with a child and setting it as reactive; for instance, the following code:

    1
    2
    clutter_actor_add_action (actor, clutter_pan_action_new ());
    clutter_actor_set_reactive (actor, TRUE);

will automatically result in the actor children to be moved when dragging.

## Functions

### clutter_pan_action_new ()

    ClutterAction *
    clutter_pan_action_new (void);

Creates a new ClutterPanAction instance

#### Returns

the newly created ClutterPanAction

Since: 1.12

### clutter_pan_action_set_pan_axis ()

    void
    clutter_pan_action_set_pan_axis (ClutterPanAction *self,
                                     ClutterPanAxis axis);

Restricts the panning action to a specific axis

#### Parameters

self | a ClutterPanAction |
axis | the axis to constraint the panning to |

Since: 1.12

### clutter_pan_action_get_pan_axis ()

    ClutterPanAxis
    clutter_pan_action_get_pan_axis (ClutterPanAction *self);

Retrieves the axis constraint set by `clutter_pan_action_set_pan_axis()`

#### Parameters

self | a ClutterPanAction |

#### Returns

the axis constraint

Since: 1.12

### clutter_pan_action_set_interpolate ()

    void
    clutter_pan_action_set_interpolate (ClutterPanAction *self,
                                        gboolean should_interpolate);

Sets whether the action should emit interpolated ::pan events after the drag has ended, to emulate the gesture kinetic inertia.

#### Parameters

self | a ClutterPanAction |
should_interpolate | whether to enable interpolated pan events |

Since: 1.12

### clutter_pan_action_get_interpolate ()

    gboolean
    clutter_pan_action_get_interpolate (ClutterPanAction *self);

Checks if the action should emit ::pan events even after releasing the pointer during a panning gesture, to emulate some kind of kinetic inertia.

#### Parameters

self | a ClutterPanAction |

#### Returns

`TRUE` if interpolated events emission is active.

Since: 1.12

### clutter_pan_action_set_deceleration ()

    void
    clutter_pan_action_set_deceleration (ClutterPanAction *self,
                                         gdouble rate);

Sets the deceleration rate of the interpolated ::pan events generated after a pan gesture. This is approximately the value that the momentum at the time of releasing the pointer is divided by every 60th of a second.

#### Parameters

self | A ClutterPanAction |
rate | The deceleration rate |

Since: 1.12

### clutter_pan_action_get_deceleration ()

    gdouble
    clutter_pan_action_get_deceleration (ClutterPanAction *self);

Retrieves the deceleration rate of interpolated ::pan events.

#### Parameters

self | A ClutterPanAction |

#### Returns

The deceleration rate of the interpolated events.

Since: 1.12

### clutter_pan_action_set_acceleration_factor ()

    void
    clutter_pan_action_set_acceleration_factor
                                   (ClutterPanAction *self,
                                    gdouble factor);

Factor applied to the momentum velocity at the time of releasing the pointer when generating interpolated ::pan events.

#### Parameters

self | A ClutterPanAction |
factor | The acceleration factor |

Since: 1.12

### clutter_pan_action_get_acceleration_factor ()

    gdouble
    clutter_pan_action_get_acceleration_factor
                                   (ClutterPanAction *self);

Retrieves the initial acceleration factor for interpolated ::pan events.

#### Parameters

self | A ClutterPanAction |

#### Returns

The initial acceleration factor for interpolated events.

Since: 1.12

### clutter_pan_action_get_interpolated_coords ()

    void
    clutter_pan_action_get_interpolated_coords
                                   (ClutterPanAction *self,
                                    gfloat *interpolated_x,
                                    gfloat *interpolated_y);

Retrieves the coordinates, in stage space, of the latest interpolated event, analogous to `clutter_gesture_action_get_motion_coords()`.

#### Parameters

self | A ClutterPanAction |
interpolated_x | return location for the latest interpolated event's X coordinate. | [out][allow-none]
interpolated_y | return location for the latest interpolated event's Y coordinate. | [out][allow-none]

Since: 1.12

### clutter_pan_action_get_interpolated_delta ()

    gfloat
    clutter_pan_action_get_interpolated_delta
                                   (ClutterPanAction *self,
                                    gfloat *delta_x,
                                    gfloat *delta_y);

Retrieves the delta, in stage space, since the latest interpolated event, analogous to `clutter_gesture_action_get_motion_delta()`.

#### Parameters

self | A ClutterPanAction |
delta_x | return location for the X delta since the latest interpolated event. | [out][allow-none]
delta_y | return location for the Y delta since the latest interpolated event. | [out][allow-none]

#### Returns

the distance since the latest interpolated event

Since: 1.12

### clutter_pan_action_get_motion_coords ()

    void
    clutter_pan_action_get_motion_coords (ClutterPanAction *self,
                                          guint point,
                                          gfloat *motion_x,
                                          gfloat *motion_y);

Retrieves the coordinates, in stage space, dependent on the current state of the ClutterPanAction. If it is inactive, both fields will be set to 0. If it is panning by user action, the values will be equivalent to those returned by `clutter_gesture_action_get_motion_coords()`. If it is interpolating with some form of kinetic scrolling, the values will be equivalent to those returned by `clutter_pan_action_get_interpolated_coords()`. This is a convenience method designed to be used in replacement "pan" signal handlers.

#### Parameters

self | A ClutterPanAction |
point | the touch point index, with 0 being the first touch point received by the action |
motion_x | return location for the X coordinate. | [out][allow-none]
motion_y | return location for the Y coordinate. | [out][allow-none]

Since: 1.14

### clutter_pan_action_get_motion_delta ()

    gfloat
    clutter_pan_action_get_motion_delta (ClutterPanAction *self,
                                         guint point,
                                         gfloat *delta_x,
                                         gfloat *delta_y);

Retrieves the delta, in stage space, dependent on the current state of the ClutterPanAction. If it is inactive, both fields will be set to 0. If it is panning by user action, the values will be equivalent to those returned by `clutter_gesture_action_get_motion_delta()`. If it is interpolating with some form of kinetic scrolling, the values will be equivalent to those returned by `clutter_pan_action_get_interpolated_delta()`. This is a convenience method designed to be used in replacement "pan" signal handlers.

#### Parameters

self | A ClutterPanAction |
point | the touch point index, with 0 being the first touch point received by the action |
delta_x | return location for the X delta. | [out][allow-none]
delta_y | return location for the Y delta. | [out][allow-none]

Since: 1.14

### clutter_pan_action_get_constrained_motion_delta ()

    gfloat
    clutter_pan_action_get_constrained_motion_delta
                                   (ClutterPanAction *self,
                                    guint point,
                                    gfloat *delta_x,
                                    gfloat *delta_y);

Retrieves the delta, in stage space, dependent on the current state of the ClutterPanAction, and respecting the constraint specified by the “pan-axis” property.

#### Parameters

self | A ClutterPanAction |
point | the touch point index, with 0 being the first touch point received by the action |
delta_x | return location for the X delta. | [out][optional]
delta_y | return location for the Y delta. | [out][optional]

#### Returns

the distance since last motion event

Since: 1.24

## Types and Values

### struct ClutterPanAction

    struct ClutterPanAction;

The ClutterPanAction structure contains only private data and should be accessed using the provided API

Since: 1.12

### struct ClutterPanActionClass

    struct ClutterPanActionClass {
      gboolean (* pan)               (ClutterPanAction    *action,
                                      ClutterActor        *actor,
                                      gboolean             is_interpolated);
      void     (* pan_stopped)       (ClutterPanAction    *action,
                                      ClutterActor        *actor);
    };

The ClutterPanActionClass structure contains only private data.

#### Members

`pan` () | class handler for the “pan” signal |
`pan_stopped` () | class handler for the “pan-stopped” signal |

Since: 1.12

### enum ClutterPanAxis

The axis of the constraint that should be applied on the panning action

#### Members

CLUTTER_PAN_AXIS_NONE | No constraint |
CLUTTER_PAN_X_AXIS | Set a constraint on the X axis |
CLUTTER_PAN_Y_AXIS | Set a constraint on the Y axis |
CLUTTER_PAN_AXIS_AUTO | Constrain panning automatically based on initial movement (available since 1.24) |

Since: 1.12

## Property Details

### The `“acceleration-factor”` property

      “acceleration-factor”      gdouble

The initial acceleration factor

The kinetic momentum measured at the time of releasing the pointer will be multiplied by the factor specified by this property before being used to generate interpolated ::pan events.

Flags: Read / Write

Allowed values: >= 1

Default value: 1

Since: 1.12

### The `“deceleration”` property

      “deceleration”             gdouble

The rate at which the interpolated panning will decelerate in

ClutterPanAction will emit interpolated ::pan events with decreasing scroll deltas, using the rate specified by this property.

Flags: Read / Write

Allowed values: [1e-15,1]

Default value: 0.95

Since: 1.12

### The `“interpolate”` property

      “interpolate”              gboolean

Whether interpolated events emission is enabled.

Flags: Read / Write

Default value: FALSE

Since: 1.12

### The `“pan-axis”` property

      “pan-axis”                 ClutterPanAxis

Constraints the panning action to the specified axis

Flags: Read / Write

Default value: CLUTTER_PAN_AXIS_NONE

Since: 1.12

## Signal Details

### The `“pan”` signal

    gboolean
    user_function (ClutterPanAction *action,
                   ClutterActor     *actor,
                   gboolean          is_interpolated,
                   gpointer          user_data)

The ::pan signal is emitted to keep track of the motion during a pan gesture. `is_interpolated` is set to `TRUE` during the interpolation phase of the pan, after the drag has ended and the :interpolate property was set to `TRUE`.

#### Parameters

action | the ClutterPanAction that emitted the signal |
actor | the ClutterActor attached to the `action` |
is_interpolated | if the event is the result of interpolating the motion velocity at the end of the drag |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the pan should continue, and `FALSE` if the pan should be cancelled.

Flags: Run Last

Since: 1.12

### The `“pan-stopped”` signal

    void
    user_function (ClutterPanAction *action,
                   ClutterActor     *actor,
                   gpointer          user_data)

The ::pan-stopped signal is emitted at the end of the interpolation phase of the pan action, only when :interpolate is set to `TRUE`.

#### Parameters

action | the ClutterPanAction 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.12