Defining Timelines in ClutterScript

A ClutterTimeline can be described in ClutterScript like any other object. Additionally, it is possible to define markers directly inside the JSON definition by using the markers JSON object member, such as:

1
2
3
4
5
6
7
8
9

{
  "type" : "ClutterTimeline",
  "duration" : 1000,
  "markers" : [
    { "name" : "quarter", "time" : 250 },
    { "name" : "half-time", "time" : 500 },
    { "name" : "three-quarters", "time" : 750 }
  ]
}

ClutterTimeline

typedef struct _ClutterTimeline ClutterTimeline;

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

Since 0.2

struct ClutterTimelineClass

struct ClutterTimelineClass {
  void (*started)        (ClutterTimeline *timeline);
  void (*completed)      (ClutterTimeline *timeline);
  void (*paused)         (ClutterTimeline *timeline);
  
  void (*new_frame)      (ClutterTimeline *timeline,
		          gint             msecs);

  void (*marker_reached) (ClutterTimeline *timeline,
                          const gchar     *marker_name,
                          gint             msecs);
  void (*stopped)        (ClutterTimeline *timeline,
                          gboolean         is_finished);
};

The ClutterTimelineClass structure contains only private data

Since 0.2

clutter_timeline_new ()

ClutterTimeline *   clutter_timeline_new                (guint msecs);

Creates a new ClutterTimeline with a duration of msecs.

Since 0.6

clutter_timeline_clone ()

ClutterTimeline *   clutter_timeline_clone              (ClutterTimeline *timeline);

Create a new ClutterTimeline instance which has property values matching that of supplied timeline. The cloned timeline will not be started and will not be positioned to the current position of the original timeline: you will have to start it with clutter_timeline_start().

Since 0.4

clutter_timeline_set_duration ()

void                clutter_timeline_set_duration       (ClutterTimeline *timeline,
                                                         guint msecs);

Sets the duration of the timeline, in milliseconds. The speed of the timeline depends on the ClutterTimeline:fps setting.

Since 0.6

clutter_timeline_get_duration ()

guint               clutter_timeline_get_duration       (ClutterTimeline *timeline);

Retrieves the duration of a ClutterTimeline in milliseconds. See clutter_timeline_set_duration().

Since 0.6

clutter_timeline_set_repeat_count ()

void                clutter_timeline_set_repeat_count   (ClutterTimeline *timeline,
                                                         gint count);

Sets the number of times the timeline should repeat.

If count is 0, the timeline never repeats.

If count is -1, the timeline will always repeat until it's stopped.

Since 1.10

clutter_timeline_get_repeat_count ()

gint                clutter_timeline_get_repeat_count   (ClutterTimeline *timeline);

Retrieves the number set using clutter_timeline_set_repeat_count().

Since 1.10

clutter_timeline_set_delay ()

void                clutter_timeline_set_delay          (ClutterTimeline *timeline,
                                                         guint msecs);

Sets the delay, in milliseconds, before timeline should start.

Since 0.4

clutter_timeline_get_delay ()

guint               clutter_timeline_get_delay          (ClutterTimeline *timeline);

Retrieves the delay set using clutter_timeline_set_delay().

Since 0.4

enum ClutterTimelineDirection

typedef enum {
  CLUTTER_TIMELINE_FORWARD,
  CLUTTER_TIMELINE_BACKWARD
} ClutterTimelineDirection;

The direction of a ClutterTimeline

Since 0.6

clutter_timeline_set_direction ()

void                clutter_timeline_set_direction      (ClutterTimeline *timeline,
                                                         ClutterTimelineDirection direction);

Sets the direction of timeline, either CLUTTER_TIMELINE_FORWARD or CLUTTER_TIMELINE_BACKWARD.

Since 0.6

clutter_timeline_get_direction ()

ClutterTimelineDirection clutter_timeline_get_direction (ClutterTimeline *timeline);

Retrieves the direction of the timeline set with clutter_timeline_set_direction().

Since 0.6

clutter_timeline_set_auto_reverse ()

void                clutter_timeline_set_auto_reverse   (ClutterTimeline *timeline,
                                                         gboolean reverse);

Sets whether timeline should reverse the direction after the emission of the "completed" signal.

Setting the "auto-reverse" property to TRUE is the equivalent of connecting a callback to the "completed" signal and changing the direction of the timeline from that callback; for instance, this code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

static void
reverse_timeline (ClutterTimeline *timeline)
{
  ClutterTimelineDirection dir = clutter_timeline_get_direction (timeline);

  if (dir == CLUTTER_TIMELINE_FORWARD)
    dir = CLUTTER_TIMELINE_BACKWARD;
  else
    dir = CLUTTER_TIMELINE_FORWARD;

  clutter_timeline_set_direction (timeline, dir);
}
...
  timeline = clutter_timeline_new (1000);
  clutter_timeline_set_repeat_count (timeline, -1);
  g_signal_connect (timeline, "completed",
                    G_CALLBACK (reverse_timeline),
                    NULL);

can be effectively replaced by:

1
2
3

timeline = clutter_timeline_new (1000);
clutter_timeline_set_repeat_count (timeline, -1);
clutter_timeline_set_auto_reverse (timeline);

Since 1.6

clutter_timeline_get_auto_reverse ()

gboolean            clutter_timeline_get_auto_reverse   (ClutterTimeline *timeline);

Retrieves the value set by clutter_timeline_set_auto_reverse().

Since 1.6

enum ClutterAnimationMode

typedef enum {
  CLUTTER_CUSTOM_MODE = 0,

  /* linear */
  CLUTTER_LINEAR,

  /* quadratic */
  CLUTTER_EASE_IN_QUAD,
  CLUTTER_EASE_OUT_QUAD,
  CLUTTER_EASE_IN_OUT_QUAD,

  /* cubic */
  CLUTTER_EASE_IN_CUBIC,
  CLUTTER_EASE_OUT_CUBIC,
  CLUTTER_EASE_IN_OUT_CUBIC,

  /* quartic */
  CLUTTER_EASE_IN_QUART,
  CLUTTER_EASE_OUT_QUART,
  CLUTTER_EASE_IN_OUT_QUART,

  /* quintic */
  CLUTTER_EASE_IN_QUINT,
  CLUTTER_EASE_OUT_QUINT,
  CLUTTER_EASE_IN_OUT_QUINT,

  /* sinusoidal */
  CLUTTER_EASE_IN_SINE,
  CLUTTER_EASE_OUT_SINE,
  CLUTTER_EASE_IN_OUT_SINE,

  /* exponential */
  CLUTTER_EASE_IN_EXPO,
  CLUTTER_EASE_OUT_EXPO,
  CLUTTER_EASE_IN_OUT_EXPO,

  /* circular */
  CLUTTER_EASE_IN_CIRC,
  CLUTTER_EASE_OUT_CIRC,
  CLUTTER_EASE_IN_OUT_CIRC,

  /* elastic */
  CLUTTER_EASE_IN_ELASTIC,
  CLUTTER_EASE_OUT_ELASTIC,
  CLUTTER_EASE_IN_OUT_ELASTIC,

  /* overshooting cubic */
  CLUTTER_EASE_IN_BACK,
  CLUTTER_EASE_OUT_BACK,
  CLUTTER_EASE_IN_OUT_BACK,

  /* exponentially decaying parabolic */
  CLUTTER_EASE_IN_BOUNCE,
  CLUTTER_EASE_OUT_BOUNCE,
  CLUTTER_EASE_IN_OUT_BOUNCE,

  /* step functions (see css3-transitions) */
  CLUTTER_STEPS,
  CLUTTER_STEP_START, /* steps(1, start) */
  CLUTTER_STEP_END, /* steps(1, end) */

  /* cubic bezier (see css3-transitions) */
  CLUTTER_CUBIC_BEZIER,
  CLUTTER_EASE,
  CLUTTER_EASE_IN,
  CLUTTER_EASE_OUT,
  CLUTTER_EASE_IN_OUT,

  /* guard, before registered alpha functions */
  CLUTTER_ANIMATION_LAST
} ClutterAnimationMode;

The animation modes used by ClutterAlpha and ClutterAnimation. This enumeration can be expanded in later versions of Clutter.

Figure 8. Easing modes provided by Clutter

Every global alpha function registered using clutter_alpha_register_func() or clutter_alpha_register_closure() will have a logical id greater than CLUTTER_ANIMATION_LAST.

Since 1.0

enum ClutterStepMode

typedef enum {
  CLUTTER_STEP_MODE_START,
  CLUTTER_STEP_MODE_END
} ClutterStepMode;

Change the value transition of a step function.

See clutter_timeline_set_step_progress().

Since 1.12

clutter_timeline_set_progress_mode ()

void                clutter_timeline_set_progress_mode  (ClutterTimeline *timeline,
                                                         ClutterAnimationMode mode);

Sets the progress function using a value from the ClutterAnimationMode enumeration. The mode cannot be CLUTTER_CUSTOM_MODE or bigger than CLUTTER_ANIMATION_LAST.

Since 1.10

clutter_timeline_get_progress_mode ()

ClutterAnimationMode clutter_timeline_get_progress_mode (ClutterTimeline *timeline);

Retrieves the progress mode set using clutter_timeline_set_progress_mode() or clutter_timeline_set_progress_func().

Since 1.10

clutter_timeline_set_cubic_bezier_progress ()

void                clutter_timeline_set_cubic_bezier_progress
                                                        (ClutterTimeline *timeline,
                                                         const ClutterPoint *c_1,
                                                         const ClutterPoint *c_2);

Sets the "progress-mode" of timeline to CLUTTER_CUBIC_BEZIER, and sets the two control points for the cubic bezier.

The cubic bezier curve is between (0, 0) and (1, 1). The X coordinate of the two control points must be in the [ 0, 1 ] range, while the Y coordinate of the two control points can exceed this range.

Since 1.12

clutter_timeline_get_cubic_bezier_progress ()

gboolean            clutter_timeline_get_cubic_bezier_progress
                                                        (ClutterTimeline *timeline,
                                                         ClutterPoint *c_1,
                                                         ClutterPoint *c_2);

Retrieves the control points for the cubic bezier progress mode.

Since 1.12

clutter_timeline_set_step_progress ()

void                clutter_timeline_set_step_progress  (ClutterTimeline *timeline,
                                                         gint n_steps,
                                                         ClutterStepMode step_mode);

Sets the "progress-mode" of the timeline to CLUTTER_STEPS and provides the parameters of the step function.

Since 1.12

clutter_timeline_get_step_progress ()

gboolean            clutter_timeline_get_step_progress  (ClutterTimeline *timeline,
                                                         gint *n_steps,
                                                         ClutterStepMode *step_mode);

Retrieves the parameters of the step progress mode used by timeline.

Since 1.12

ClutterTimelineProgressFunc ()

gdouble             (*ClutterTimelineProgressFunc)      (ClutterTimeline *timeline,
                                                         gdouble elapsed,
                                                         gdouble total,
                                                         gpointer user_data);

A function for defining a custom progress.

Since 1.10

clutter_timeline_set_progress_func ()

void                clutter_timeline_set_progress_func  (ClutterTimeline *timeline,
                                                         ClutterTimelineProgressFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Sets a custom progress function for timeline. The progress function will be called by clutter_timeline_get_progress() and will be used to compute the progress value based on the elapsed time and the total duration of the timeline.

If func is not NULL, the "progress-mode" property will be set to CLUTTER_CUSTOM_MODE.

If func is NULL, any previously set progress function will be unset, and the "progress-mode" property will be set to CLUTTER_LINEAR.

Since 1.10

clutter_timeline_get_duration_hint ()

gint64              clutter_timeline_get_duration_hint  (ClutterTimeline *timeline);

Retrieves the full duration of the timeline, taking into account the current value of the "repeat-count" property.

If the "repeat-count" property is set to -1, this function will return G_MAXINT64.

The returned value is to be considered a hint, and it's only valid as long as the timeline hasn't been changed.

Since 1.10

clutter_timeline_get_current_repeat ()

gint                clutter_timeline_get_current_repeat (ClutterTimeline *timeline);

Retrieves the current repeat for a timeline.

Repeats start at 0.

Since 1.10

clutter_timeline_set_loop ()

void                clutter_timeline_set_loop           (ClutterTimeline *timeline,
                                                         gboolean loop);

Sets whether timeline should loop.

This function is equivalent to calling clutter_timeline_set_repeat_count() with -1 if loop is TRUE, and with 0 if loop is FALSE.

clutter_timeline_get_loop ()

gboolean            clutter_timeline_get_loop           (ClutterTimeline *timeline);

Gets whether timeline is looping

clutter_timeline_start ()

void                clutter_timeline_start              (ClutterTimeline *timeline);

Starts the ClutterTimeline playing.

clutter_timeline_pause ()

void                clutter_timeline_pause              (ClutterTimeline *timeline);

Pauses the ClutterTimeline on current frame

clutter_timeline_stop ()

void                clutter_timeline_stop               (ClutterTimeline *timeline);

Stops the ClutterTimeline and moves to frame 0

clutter_timeline_rewind ()

void                clutter_timeline_rewind             (ClutterTimeline *timeline);

Rewinds ClutterTimeline to the first frame if its direction is CLUTTER_TIMELINE_FORWARD and the last frame if it is CLUTTER_TIMELINE_BACKWARD.

clutter_timeline_skip ()

void                clutter_timeline_skip               (ClutterTimeline *timeline,
                                                         guint msecs);

Advance timeline by the requested time in milliseconds

clutter_timeline_advance ()

void                clutter_timeline_advance            (ClutterTimeline *timeline,
                                                         guint msecs);

Advance timeline to the requested point. The point is given as a time in milliseconds since the timeline started.

clutter_timeline_get_elapsed_time ()

guint               clutter_timeline_get_elapsed_time   (ClutterTimeline *timeline);

Request the current time position of the timeline.

clutter_timeline_get_delta ()

guint               clutter_timeline_get_delta          (ClutterTimeline *timeline);

Retrieves the amount of time elapsed since the last ClutterTimeline::new-frame signal.

This function is only useful inside handlers for the ::new-frame signal, and its behaviour is undefined if the timeline is not playing.

Since 0.6

clutter_timeline_get_progress ()

gdouble             clutter_timeline_get_progress       (ClutterTimeline *timeline);

The position of the timeline in a normalized [-1, 2] interval.

The return value of this function is determined by the progress mode set using clutter_timeline_set_progress_mode(), or by the progress function set using clutter_timeline_set_progress_func().

Since 0.6

clutter_timeline_is_playing ()

gboolean            clutter_timeline_is_playing         (ClutterTimeline *timeline);

Queries state of a ClutterTimeline.

clutter_timeline_add_marker ()

void                clutter_timeline_add_marker         (ClutterTimeline *timeline,
                                                         const gchar *marker_name,
                                                         gdouble progress);

Adds a named marker that will be hit when the timeline has reached the specified progress.

Markers are unique string identifiers for a given position on the timeline. Once timeline reaches the given progress of its duration, if will emit a ::marker-reached signal for each marker attached to that particular point.

A marker can be removed with clutter_timeline_remove_marker(). The timeline can be advanced to a marker using clutter_timeline_advance_to_marker().

See also: clutter_timeline_add_marker_at_time()

Since 1.14

clutter_timeline_add_marker_at_time ()

void                clutter_timeline_add_marker_at_time (ClutterTimeline *timeline,
                                                         const gchar *marker_name,
                                                         guint msecs);

Adds a named marker that will be hit when the timeline has been running for msecs milliseconds.

Markers are unique string identifiers for a given position on the timeline. Once timeline reaches the given msecs, it will emit a ::marker-reached signal for each marker attached to that position.

A marker can be removed with clutter_timeline_remove_marker(). The timeline can be advanced to a marker using clutter_timeline_advance_to_marker().

See also: clutter_timeline_add_marker()

Since 0.8

clutter_timeline_has_marker ()

gboolean            clutter_timeline_has_marker         (ClutterTimeline *timeline,
                                                         const gchar *marker_name);

Checks whether timeline has a marker set with the given name.

Since 0.8

clutter_timeline_list_markers ()

gchar **            clutter_timeline_list_markers       (ClutterTimeline *timeline,
                                                         gint msecs,
                                                         gsize *n_markers);

Retrieves the list of markers at time msecs. If msecs is a negative integer, all the markers attached to timeline will be returned.

Since 0.8

clutter_timeline_remove_marker ()

void                clutter_timeline_remove_marker      (ClutterTimeline *timeline,
                                                         const gchar *marker_name);

Removes marker_name, if found, from timeline.

Since 0.8

clutter_timeline_advance_to_marker ()

void                clutter_timeline_advance_to_marker  (ClutterTimeline *timeline,
                                                         const gchar *marker_name);

Advances timeline to the time of the given marker_name.

Since 0.8

The "auto-reverse" property

  "auto-reverse"             gboolean              : Read / Write

If the direction of the timeline should be automatically reversed when reaching the end.

Default value: FALSE

Since 1.6

The "delay" property

  "delay"                    guint                 : Read / Write

A delay, in milliseconds, that should be observed by the timeline before actually starting.

Default value: 0

Since 0.4

The "direction" property

  "direction"                ClutterTimelineDirection  : Read / Write

The direction of the timeline, either CLUTTER_TIMELINE_FORWARD or CLUTTER_TIMELINE_BACKWARD.

Default value: CLUTTER_TIMELINE_FORWARD

Since 0.6

The "duration" property

  "duration"                 guint                 : Read / Write

Duration of the timeline in milliseconds, depending on the ClutterTimeline:fps value.

Default value: 1000

Since 0.6

The "loop" property

  "loop"                     gboolean              : Read / Write

Whether the timeline should automatically rewind and restart.

As a side effect, setting this property to TRUE will set the "repeat-count" property to -1, while setting this property to FALSE will set the "repeat-count" property to 0.

Default value: FALSE

The "progress-mode" property

  "progress-mode"            ClutterAnimationMode  : Read / Write

Controls the way a ClutterTimeline computes the normalized progress.

Default value: CLUTTER_LINEAR

Since 1.10

The "repeat-count" property

  "repeat-count"             gint                  : Read / Write

Defines how many times the timeline should repeat.

If the repeat count is 0, the timeline does not repeat.

If the repeat count is set to -1, the timeline will repeat until it is stopped.

Allowed values: >= G_MAXULONG

Default value: 0

Since 1.10

The "completed" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gpointer         user_data)      : Run Last

The "completed" signal is emitted when the timeline's elapsed time reaches the value of the "duration" property.

This signal will be emitted even if the ClutterTimeline is set to be repeating.

If you want to get notification on whether the ClutterTimeline has been stopped or has finished its run, including its eventual repeats, you should use the "stopped" signal instead.

The "marker-reached" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gchar           *marker_name,
                                                        gint             msecs,
                                                        gpointer         user_data)        : No Hooks

The ::marker-reached signal is emitted each time a timeline reaches a marker set with clutter_timeline_add_marker_at_time(). This signal is detailed with the name of the marker as well, so it is possible to connect a callback to the ::marker-reached signal for a specific marker with:

1
2
3
4
5
6
7
8
9

clutter_timeline_add_marker_at_time (timeline, "foo", 500);
clutter_timeline_add_marker_at_time (timeline, "bar", 750);

g_signal_connect (timeline, "marker-reached",
                  G_CALLBACK (each_marker_reached), NULL);
g_signal_connect (timeline, "marker-reached::foo",
                  G_CALLBACK (foo_marker_reached), NULL);
g_signal_connect (timeline, "marker-reached::bar",
                  G_CALLBACK (bar_marker_reached), NULL);

In the example, the first callback will be invoked for both the "foo" and "bar" marker, while the second and third callbacks will be invoked for the "foo" or "bar" markers, respectively.

Since 0.8

The "new-frame" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gint             msecs,
                                                        gpointer         user_data)      : Run Last

The ::new-frame signal is emitted for each timeline running timeline before a new frame is drawn to give animations a chance to update the scene.

The "paused" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gpointer         user_data)      : Run Last

The ::paused signal is emitted when clutter_timeline_pause() is invoked.

The "started" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gpointer         user_data)      : Run Last

The ::started signal is emitted when the timeline starts its run. This might be as soon as clutter_timeline_start() is invoked or after the delay set in the ClutterTimeline:delay property has expired.

The "stopped" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gboolean         is_finished,
                                                        gpointer         user_data)        : Run Last

The "stopped" signal is emitted when the timeline has been stopped, either because clutter_timeline_stop() has been called, or because it has been exhausted.

This is different from the "completed" signal, which gets emitted after every repeat finishes.

If the ClutterTimeline has is marked as infinitely repeating, this signal will never be emitted.

Since 1.12