## ClutterTimeline

ClutterTimeline — A class for time-based events

## Synopsis

    struct              ClutterTimeline;
    struct              ClutterTimelineClass;
    ClutterTimeline *   clutter_timeline_new                (guint msecs);
    ClutterTimeline *   clutter_timeline_clone              (ClutterTimeline *timeline);

    void                clutter_timeline_set_duration       (ClutterTimeline *timeline,
                                                             guint msecs);
    guint               clutter_timeline_get_duration       (ClutterTimeline *timeline);
    void                clutter_timeline_set_loop           (ClutterTimeline *timeline,
                                                             gboolean loop);
    gboolean            clutter_timeline_get_loop           (ClutterTimeline *timeline);
    void                clutter_timeline_set_delay          (ClutterTimeline *timeline,
                                                             guint msecs);
    guint               clutter_timeline_get_delay          (ClutterTimeline *timeline);
    enum                ClutterTimelineDirection;
    void                clutter_timeline_set_direction      (ClutterTimeline *timeline,
                                                             ClutterTimelineDirection direction);
    ClutterTimelineDirection clutter_timeline_get_direction (ClutterTimeline *timeline);
    void                clutter_timeline_set_auto_reverse   (ClutterTimeline *timeline,
                                                             gboolean reverse);
    gboolean            clutter_timeline_get_auto_reverse   (ClutterTimeline *timeline);

    void                clutter_timeline_start              (ClutterTimeline *timeline);
    void                clutter_timeline_pause              (ClutterTimeline *timeline);
    void                clutter_timeline_stop               (ClutterTimeline *timeline);
    void                clutter_timeline_rewind             (ClutterTimeline *timeline);
    void                clutter_timeline_skip               (ClutterTimeline *timeline,
                                                             guint msecs);
    void                clutter_timeline_advance            (ClutterTimeline *timeline,
                                                             guint msecs);
    guint               clutter_timeline_get_elapsed_time   (ClutterTimeline *timeline);
    guint               clutter_timeline_get_delta          (ClutterTimeline *timeline);
    gdouble             clutter_timeline_get_progress       (ClutterTimeline *timeline);
    gboolean            clutter_timeline_is_playing         (ClutterTimeline *timeline);

    void                clutter_timeline_add_marker_at_time (ClutterTimeline *timeline,
                                                             const gchar *marker_name,
                                                             guint msecs);
    gboolean            clutter_timeline_has_marker         (ClutterTimeline *timeline,
                                                             const gchar *marker_name);
    gchar **            clutter_timeline_list_markers       (ClutterTimeline *timeline,
                                                             gint msecs,
                                                             gsize *n_markers);
    void                clutter_timeline_remove_marker      (ClutterTimeline *timeline,
                                                             const gchar *marker_name);
    void                clutter_timeline_advance_to_marker  (ClutterTimeline *timeline,
                                                             const gchar *marker_name);

## Object Hierarchy

      GObject
       +----ClutterTimeline

## Properties

      "auto-reverse"             gboolean              : Read / Write
      "delay"                    guint                 : Read / Write
      "direction"                ClutterTimelineDirection  : Read / Write
      "duration"                 guint                 : Read / Write
      "loop"                     gboolean              : Read / Write

## Signals

      "completed"                                      : Run Last
      "marker-reached"                                 : No Hooks
      "new-frame"                                      : Run Last
      "paused"                                         : Run Last
      "started"                                        : Run Last

## Description

ClutterTimeline is a base class for managing time based events such as animations.

## Details

### struct ClutterTimeline

    struct 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);
    };

The ClutterTimelineClass structure contains only private data

`started` () | handler for the "started" signal
`completed` () | handler for the "completed" signal
`paused` () | handler for the "paused" signal
`new_frame` () | handler for the "new-frame" signal
`marker_reached` () | handler for the "marker-reached" signal

Since 0.2

### clutter_timeline_new ()

    ClutterTimeline *   clutter_timeline_new                (guint msecs);

Creates a new ClutterTimeline with a duration of `msecs`.

`msecs` : | Duration of the timeline in milliseconds
Returns : | the newly created ClutterTimeline instance. Use `g_object_unref()` when done using it

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 `timeline`: you will have to start it with `clutter_timeline_start()`.

`timeline` : | ClutterTimeline to duplicate.
Returns : | a new ClutterTimeline, cloned from `timeline`. [transfer full]

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.

`timeline` : | a ClutterTimeline
`msecs` : | duration of the timeline in milliseconds

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

`timeline` : | a ClutterTimeline
Returns : | the duration of the timeline, in milliseconds.

Since 0.6

### clutter_timeline_set_loop ()

    void                clutter_timeline_set_loop           (ClutterTimeline *timeline,
                                                             gboolean loop);

Sets whether `timeline` should loop.

`timeline` : | a ClutterTimeline
`loop` : | `TRUE` for enable looping

### clutter_timeline_get_loop ()

    gboolean            clutter_timeline_get_loop           (ClutterTimeline *timeline);

Gets whether `timeline` is looping

`timeline` : | a ClutterTimeline
Returns : | `TRUE` if the timeline is looping

### clutter_timeline_set_delay ()

    void                clutter_timeline_set_delay          (ClutterTimeline *timeline,
                                                             guint msecs);

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

`timeline` : | a ClutterTimeline
`msecs` : | delay in milliseconds

Since 0.4

### clutter_timeline_get_delay ()

    guint               clutter_timeline_get_delay          (ClutterTimeline *timeline);

Retrieves the delay set using `clutter_timeline_set_delay()`.

`timeline` : | a ClutterTimeline
Returns : | the delay in milliseconds.

Since 0.4

### enum ClutterTimelineDirection

    typedef enum {
      CLUTTER_TIMELINE_FORWARD,
      CLUTTER_TIMELINE_BACKWARD
    } ClutterTimelineDirection;

The direction of a ClutterTimeline

`CLUTTER_TIMELINE_FORWARD` | forward direction for a timeline
`CLUTTER_TIMELINE_BACKWARD` | backward direction for a timeline

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

`timeline` : | a ClutterTimeline
`direction` : | the direction of the timeline

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

`timeline` : | a ClutterTimeline
Returns : | the direction of the timeline

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_loop (timeline);
      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_loop (timeline);
    clutter_timeline_set_auto_reverse (timeline);

`timeline` : | a ClutterTimeline
`reverse` : | `TRUE` if the `timeline` should reverse the direction

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

`timeline` : | a ClutterTimeline
Returns : | `TRUE` if the timeline should automatically reverse, and `FALSE` otherwise

Since 1.6

### clutter_timeline_start ()

    void                clutter_timeline_start              (ClutterTimeline *timeline);

Starts the ClutterTimeline playing.

`timeline` : | A ClutterTimeline

### clutter_timeline_pause ()

    void                clutter_timeline_pause              (ClutterTimeline *timeline);

Pauses the ClutterTimeline on current frame

`timeline` : | A ClutterTimeline

### clutter_timeline_stop ()

    void                clutter_timeline_stop               (ClutterTimeline *timeline);

Stops the ClutterTimeline and moves to frame 0

`timeline` : | A ClutterTimeline

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

`timeline` : | A ClutterTimeline

### clutter_timeline_skip ()

    void                clutter_timeline_skip               (ClutterTimeline *timeline,
                                                             guint msecs);

Advance timeline by the requested time in milliseconds

`timeline` : | A ClutterTimeline
`msecs` : | Amount of time to skip

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

### Note

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.

`timeline` : | A ClutterTimeline
`msecs` : | Time to advance to

### clutter_timeline_get_elapsed_time ()

    guint               clutter_timeline_get_elapsed_time   (ClutterTimeline *timeline);

Request the current time position of the timeline.

`timeline` : | A ClutterTimeline
Returns : | current elapsed time in milliseconds.

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

`timeline` : | a ClutterTimeline
Returns : | the amount of time in milliseconds elapsed since the last frame

Since 0.6

### clutter_timeline_get_progress ()

    gdouble             clutter_timeline_get_progress       (ClutterTimeline *timeline);

The position of the timeline in a [0, 1] interval.

`timeline` : | a ClutterTimeline
Returns : | the position of the timeline.

Since 0.6

### clutter_timeline_is_playing ()

    gboolean            clutter_timeline_is_playing         (ClutterTimeline *timeline);

Queries state of a ClutterTimeline.

`timeline` : | A ClutterTimeline
Returns : | `TRUE` if timeline is currently playing

### 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 time. Once `timeline` reaches `msecs`, it will emit a ::marker-reached signal for each marker attached to that time.

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

`timeline` : | a ClutterTimeline
`marker_name` : | the unique name for this marker
`msecs` : | position of the marker in milliseconds

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.

`timeline` : | a ClutterTimeline
`marker_name` : | the name of the marker
Returns : | `TRUE` if the marker was found

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.

`timeline` : | a ClutterTimeline
`msecs` : | the time to check, or -1
`n_markers` : | the number of markers returned
Returns : | a newly allocated, `NULL` terminated string array containing the names of the markers. Use `g_strfreev()` when done. [transfer full][array zero-terminated=1 length=n_markers]

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

`timeline` : | a ClutterTimeline
`marker_name` : | the name of the marker to remove

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

### Note

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

`timeline` : | a ClutterTimeline
`marker_name` : | the name of the marker

Since 0.8

## Property Details

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

Default value: FALSE

## Signal Details

### The `"completed"` signal

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

The ::completed signal is emitted when the timeline reaches the number of frames specified by the ClutterTimeline:num-frames property.

`timeline` : | the ClutterTimeline which received the signal
`user_data` : | user data set when the signal handler was connected.

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

    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.

`timeline` : | the ClutterTimeline which received the signal
`marker_name` : | the name of the marker reached
`msecs` : | the elapsed time
`user_data` : | user data set when the signal handler was connected.

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.

`timeline` : | the timeline which received the signal
`msecs` : | the elapsed time between 0 and duration
`user_data` : | user data set when the signal handler was connected.

### The `"paused"` signal

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

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

`timeline` : | the ClutterTimeline which received the signal
`user_data` : | user data set when the signal handler was connected.

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

`timeline` : | the ClutterTimeline which received the signal
`user_data` : | user data set when the signal handler was connected.