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 }
  ]
}

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().

The only cloned properties are:

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

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

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.

The timeline will not emit the “new-frame” signal for the given time. The first ::new-frame signal after the call to clutter_timeline_advance() will be emit the skipped markers.

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 .

Like clutter_timeline_advance(), this function will not emit the “new-frame” for the time where marker_name is set, nor it will emit “marker-reached” for marker_name .

Since 0.8

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

enum ClutterTimelineDirection

The direction of a ClutterTimeline

Since 0.6

enum ClutterAnimationMode

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

<figure id="easing-modes"> <title>Easing modes provided by Clutter</title> <graphic fileref="easing-modes.png" format="PNG"/> </figure>

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

Change the value transition of a step function.

See clutter_timeline_set_step_progress().

Since 1.12

The “auto-reverse” property

  “auto-reverse”             gboolean

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

Flags: Read / Write

Default value: FALSE

Since 1.6

The “delay” property

  “delay”                    guint

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

Flags: Read / Write

Default value: 0

Since 0.4

The “direction” property

  “direction”                ClutterTimelineDirection

The direction of the timeline, either CLUTTER_TIMELINE_FORWARD or CLUTTER_TIMELINE_BACKWARD.

Flags: Read / Write

Default value: CLUTTER_TIMELINE_FORWARD

Since 0.6

The “duration” property

  “duration”                 guint

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

Flags: Read / Write

Default value: 1000

Since 0.6

The “loop” property

  “loop”                     gboolean

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.

Flags: Read / Write

Default value: FALSE

The “progress-mode” property

  “progress-mode”            ClutterAnimationMode

Controls the way a ClutterTimeline computes the normalized progress.

Flags: Read / Write

Default value: CLUTTER_LINEAR

Since 1.10

The “repeat-count” property

  “repeat-count”             gint

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.

Flags: Read / Write

Allowed values: >= -1

Default value: 0

Since 1.10

The “completed” signal

void
user_function (ClutterTimeline *timeline,
               gpointer         user_data)

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.

Flags: Run Last

The “marker-reached” signal

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

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:

<informalexample><programlisting> 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); </programlisting></informalexample>

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.

Flags: No Hooks

Since 0.8

The “new-frame” signal

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

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.

Flags: Run Last

The “paused” signal

void
user_function (ClutterTimeline *timeline,
               gpointer         user_data)

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

Flags: Run Last

The “started” signal

void
user_function (ClutterTimeline *timeline,
               gpointer         user_data)

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.

Flags: Run Last

The “stopped” signal

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

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.

Flags: Run Last

Since 1.12