## ClutterScore

ClutterScore — Controller for multiple timelines

## Synopsis

    struct              ClutterScore;
    struct              ClutterScoreClass;
    ClutterScore *      clutter_score_new                   (void);
    void                clutter_score_set_loop              (ClutterScore *score,
                                                             gboolean loop);
    gboolean            clutter_score_get_loop              (ClutterScore *score);

    gulong              clutter_score_append                (ClutterScore *score,
                                                             ClutterTimeline *parent,
                                                             ClutterTimeline *timeline);
    gulong              clutter_score_append_at_marker      (ClutterScore *score,
                                                             ClutterTimeline *parent,
                                                             const gchar *marker_name,
                                                             ClutterTimeline *timeline);
    void                clutter_score_remove                (ClutterScore *score,
                                                             gulong id);
    void                clutter_score_remove_all            (ClutterScore *score);
    ClutterTimeline *   clutter_score_get_timeline          (ClutterScore *score,
                                                             gulong id);
    GSList *            clutter_score_list_timelines        (ClutterScore *score);

    void                clutter_score_start                 (ClutterScore *score);
    void                clutter_score_pause                 (ClutterScore *score);
    void                clutter_score_stop                  (ClutterScore *score);
    gboolean            clutter_score_is_playing            (ClutterScore *score);
    void                clutter_score_rewind                (ClutterScore *score);

## Object Hierarchy

      GObject
       +----ClutterScore

## Properties

      "loop"                     gboolean              : Read / Write

## Signals

      "completed"                                      : Run Last
      "paused"                                         : Run Last
      "started"                                        : Run Last
      "timeline-completed"                             : Run Last
      "timeline-started"                               : Run Last

## Description

ClutterScore is a base class for sequencing multiple timelines in order. Using ClutterScore it is possible to start multiple timelines at the same time or launch multiple timelines when a particular timeline has emitted the ClutterTimeline::completed signal.

Each time a ClutterTimeline is started and completed, a signal will be emitted.

For example, this code will start two ClutterTimelines after a third timeline terminates:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14

    ClutterTimeline *timeline_1, *timeline_2, *timeline_3;
    ClutterScore *score;

    timeline_1 = clutter_timeline_new_for_duration (1000);
    timeline_2 = clutter_timeline_new_for_duration (500);
    timeline_3 = clutter_timeline_new_for_duration (500);

    score = clutter_score_new ();

    clutter_score_append (score, NULL,       timeline_1);
    clutter_score_append (score, timeline_1, timeline_2);
    clutter_score_append (score, timeline_1, timeline_3);

    clutter_score_start (score);

A ClutterScore takes a reference on the timelines it manages, so timelines can be safely unreferenced after being appended.

New timelines can be appended to the ClutterScore using `clutter_score_append()` and removed using `clutter_score_remove()`.

Timelines can also be appended to a specific marker on the parent timeline, using `clutter_score_append_at_marker()`.

The score can be cleared using `clutter_score_remove_all()`.

The list of timelines can be retrieved using `clutter_score_list_timelines()`.

The score state is controlled using `clutter_score_start()`, `clutter_score_pause()`, `clutter_score_stop()` and `clutter_score_rewind()`. The state can be queried using `clutter_score_is_playing()`.

ClutterScore is available since Clutter 0.6

## Details

### struct ClutterScore

    struct ClutterScore;

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

Since 0.6

### struct ClutterScoreClass

    struct ClutterScoreClass {
      void (* timeline_started)   (ClutterScore    *score,
                                   ClutterTimeline *timeline);
      void (* timeline_completed) (ClutterScore    *score,
                                   ClutterTimeline *timeline);

      void (* started)            (ClutterScore    *score);
      void (* completed)          (ClutterScore    *score);
      void (* paused)             (ClutterScore    *score);
    };

The ClutterScoreClass structure contains only private data

`timeline_started` () | handler for the "timeline-started" signal
`timeline_completed` () | handler for the "timeline-completed" signal
`started` () | handler for the "started" signal
`completed` () | handler for the "completed" signal
`paused` () | handler for the "paused" signal

Since 0.6

### clutter_score_new ()

    ClutterScore *      clutter_score_new                   (void);

Creates a new ClutterScore. A ClutterScore is an object that can hold multiple ClutterTimelines in a sequential order.

Returns : | the newly created ClutterScore. Use `g_object_unref()` when done.

Since 0.6

### clutter_score_set_loop ()

    void                clutter_score_set_loop              (ClutterScore *score,
                                                             gboolean loop);

Sets whether `score` should loop. A looping ClutterScore will start from its initial state after the ::complete signal has been fired.

`score` : | a ClutterScore
`loop` : | `TRUE` for enable looping

Since 0.6

### clutter_score_get_loop ()

    gboolean            clutter_score_get_loop              (ClutterScore *score);

Gets whether `score` is looping

`score` : | a ClutterScore
Returns : | `TRUE` if the score is looping

Since 0.6

### clutter_score_append ()

    gulong              clutter_score_append                (ClutterScore *score,
                                                             ClutterTimeline *parent,
                                                             ClutterTimeline *timeline);

Appends a timeline to another one existing in the score; the newly appended timeline will be started when `parent` is complete.

If `parent` is `NULL`, the new ClutterTimeline will be started when `clutter_score_start()` is called.

ClutterScore will take a reference on `timeline`.

`score` : | a ClutterScore
`parent` : | a ClutterTimeline in the score, or `NULL`. [allow-none]
`timeline` : | a ClutterTimeline
Returns : | the id of the ClutterTimeline inside the score, or 0 on failure. The returned id can be used with `clutter_score_remove()` or `clutter_score_get_timeline()`.

Since 0.6

### clutter_score_append_at_marker ()

    gulong              clutter_score_append_at_marker      (ClutterScore *score,
                                                             ClutterTimeline *parent,
                                                             const gchar *marker_name,
                                                             ClutterTimeline *timeline);

Appends `timeline` at the given `marker_name` on the `parent` ClutterTimeline.

If you want to append `timeline` at the end of `parent`, use `clutter_score_append()`.

The ClutterScore will take a reference on `timeline`.

`score` : | a ClutterScore
`parent` : | the parent ClutterTimeline
`marker_name` : | the name of the marker to use
`timeline` : | the ClutterTimeline to append
Returns : | the id of the ClutterTimeline inside the score, or 0 on failure. The returned id can be used with `clutter_score_remove()` or `clutter_score_get_timeline()`.

Since 0.8

### clutter_score_remove ()

    void                clutter_score_remove                (ClutterScore *score,
                                                             gulong id);

Removes the ClutterTimeline with the given id inside `score`. If the timeline has other timelines attached to it, those are removed as well.

`score` : | a ClutterScore
`id` : | the id of the timeline to remove

Since 0.6

### clutter_score_remove_all ()

    void                clutter_score_remove_all            (ClutterScore *score);

Removes all the timelines inside `score`.

`score` : | a ClutterScore

Since 0.6

### clutter_score_get_timeline ()

    ClutterTimeline *   clutter_score_get_timeline          (ClutterScore *score,
                                                             gulong id);

Retrieves the ClutterTimeline for `id` inside `score`.

`score` : | a ClutterScore
`id` : | the id of the timeline
Returns : | the requested timeline, or `NULL`. This function does not increase the reference count on the returned ClutterTimeline. [transfer none]

Since 0.6

### clutter_score_list_timelines ()

    GSList *            clutter_score_list_timelines        (ClutterScore *score);

Retrieves a list of all the ClutterTimelines managed by `score`.

`score` : | a ClutterScore
Returns : | a GSList containing all the timelines in the score. This function does not increase the reference count of the returned timelines. Use `g_slist_free()` on the returned list to deallocate its resources. [transfer container][element-type Clutter.Timeline]

Since 0.6

### clutter_score_start ()

    void                clutter_score_start                 (ClutterScore *score);

Starts the score.

`score` : | A ClutterScore

Since 0.6

### clutter_score_pause ()

    void                clutter_score_pause                 (ClutterScore *score);

Pauses a playing score `score`.

`score` : | a ClutterScore

Since 0.6

### clutter_score_stop ()

    void                clutter_score_stop                  (ClutterScore *score);

Stops and rewinds a playing ClutterScore instance.

`score` : | A ClutterScore

Since 0.6

### clutter_score_is_playing ()

    gboolean            clutter_score_is_playing            (ClutterScore *score);

Query state of a ClutterScore instance.

`score` : | A ClutterScore
Returns : | `TRUE` if score is currently playing

Since 0.6

### clutter_score_rewind ()

    void                clutter_score_rewind                (ClutterScore *score);

Rewinds a ClutterScore to its initial state.

`score` : | A ClutterScore

Since 0.6

## Property Details

### The `"loop"` property

      "loop"                     gboolean              : Read / Write

Whether the ClutterScore should restart once finished.

Default value: FALSE

Since 0.6

## Signal Details

### The `"completed"` signal

    void                user_function                      (ClutterScore *score,
                                                            gpointer      user_data)      : Run Last

The ::completed signal is emitted each time a ClutterScore terminates.

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

Since 0.6

### The `"paused"` signal

    void                user_function                      (ClutterScore *score,
                                                            gpointer      user_data)      : Run Last

The ::paused signal is emitted each time a ClutterScore is paused.

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

Since 0.6

### The `"started"` signal

    void                user_function                      (ClutterScore *score,
                                                            gpointer      user_data)      : Run Last

The ::started signal is emitted each time a ClutterScore starts playing.

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

Since 0.6

### The `"timeline-completed"` signal

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

The ::timeline-completed signal is emitted each time a timeline inside a ClutterScore terminates.

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

Since 0.6

### The `"timeline-started"` signal

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

The ::timeline-started signal is emitted each time a new timeline inside a ClutterScore starts playing.

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

Since 0.6