Next: , Previous: ClutterTexture, Up: Top

69 ClutterTimeline

A class for time-based events

69.1 Overview

<clutter-timeline> is a base class for managing time-based event that cause Clutter to redraw a stage, such as animations.

Each <clutter-timeline> instance has a duration: once a timeline has been started, using clutter-timeline-start, it will emit a signal that can be used to update the state of the actors.

It is important to note that <clutter-timeline> is not a generic API for calling closures after an interval; each Timeline is tied into the master clock used to drive the frame cycle. If you need to schedule a closure after an interval, see clutter-threads-add-timeout instead.

Users of <clutter-timeline> should connect to the <"new-frame"> signal, which is emitted each time a timeline is advanced during the maste clock iteration. The <"new-frame"> signal provides the time elapsed since the beginning of the timeline, in milliseconds. A normalized progress value can be obtained by calling clutter-timeline-get-progress. By using clutter-timeline-get-delta it is possible to obtain the wallclock time elapsed since the last emission of the <"new-frame"> signal.

Initial state can be set up by using the <"started"> signal, while final state can be set up by using the <"completed"> signal. The <clutter-timeline> guarantees the emission of at least a single <"new-frame"> signal, as well as the emission of the <"completed"> signal.

It is possible to connect to specific points in the timeline progress by adding markers using clutter-timeline-add-marker-at-time and connecting to the <"marker-reached"> signal.

Timelines can be made to loop once they reach the end of their duration, by using clutter-timeline-set-repeat-count; a looping timeline will still emit the <"completed"> signal once it reaches the end of its duration.

Timelines have a <"direction">: the default direction is ‘CLUTTER_TIMELINE_FORWARD’, and goes from 0 to the duration; it is possible to change the direction to ‘CLUTTER_TIMELINE_BACKWARD’, and have the timeline go from the duration to 0. The direction can be automatically reversed when reaching completion by using the <"auto-reverse"> property.

Timelines are used in the Clutter animation framework by classes like <clutter-animation>, <clutter-animator>, and <clutter-state>.

69.2 Defining Timelines in ClutterScript

A <clutter-timeline> can be described in <clutter-script> 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: 

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

69.3 Usage

— Function: clutter-timeline-new (msecs unsigned-int) ⇒  (ret <clutter-timeline>)

Creates a new <clutter-timeline> with a duration of msecs.

msecs
Duration of the timeline in milliseconds
ret
the newly created <clutter-timeline> instance. Use g-object-unref when done using it

Since 0.6

— Function: clutter-timeline-set-duration (self <clutter-timeline>) (msecs unsigned-int)
— Method: set-duration

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

timeline
a <clutter-timeline>
msecs
duration of the timeline in milliseconds

Since 0.6

— Function: clutter-timeline-get-duration (self <clutter-timeline>) ⇒  (ret unsigned-int)
— Method: get-duration

Retrieves the duration of a <clutter-timeline> in milliseconds. See clutter-timeline-set-duration.

timeline
a <clutter-timeline>
ret
the duration of the timeline, in milliseconds.

Since 0.6

— Function: clutter-timeline-set-repeat-count (self <clutter-timeline>) (count int)
— Method: set-repeat-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.

timeline
a <clutter-timeline>
count
the number of times the timeline should repeat

Since 1.10

— Function: clutter-timeline-get-repeat-count (self <clutter-timeline>) ⇒  (ret int)
— Method: get-repeat-count

Retrieves the number set using clutter-timeline-set-repeat-count.

timeline
a <clutter-timeline>
ret
the number of repeats

Since 1.10

— Function: clutter-timeline-set-delay (self <clutter-timeline>) (msecs unsigned-int)
— Method: set-delay

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

timeline
a <clutter-timeline>
msecs
delay in milliseconds

Since 0.4

— Function: clutter-timeline-get-delay (self <clutter-timeline>) ⇒  (ret unsigned-int)
— Method: get-delay

Retrieves the delay set using clutter-timeline-set-delay.

timeline
a <clutter-timeline>
ret
the delay in milliseconds.

Since 0.4

— Function: clutter-timeline-set-direction (self <clutter-timeline>) (direction <clutter-timeline-direction>)
— Method: set-direction

Sets the direction of timeline, either ‘CLUTTER_TIMELINE_FORWARD’ or ‘CLUTTER_TIMELINE_BACKWARD’.

timeline
a <clutter-timeline>
direction
the direction of the timeline

Since 0.6

— Function: clutter-timeline-get-direction (self <clutter-timeline>) ⇒  (ret <clutter-timeline-direction>)
— Method: get-direction

Retrieves the direction of the timeline set with clutter-timeline-set-direction.

timeline
a <clutter-timeline>
ret
the direction of the timeline

Since 0.6

— Function: clutter-timeline-set-auto-reverse (self <clutter-timeline>) (reverse bool)
— Method: set-auto-reverse

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

Setting the <"auto-reverse"> property to ‘#t’ 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: 

          
          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: 

          
            timeline = clutter_timeline_new (1000);
            clutter_timeline_set_repeat_count (timeline, -1);
            clutter_timeline_set_auto_reverse (timeline);
timeline
a <clutter-timeline>
reverse
‘#t’ if the timeline should reverse the direction

Since 1.6

— Function: clutter-timeline-get-auto-reverse (self <clutter-timeline>) ⇒  (ret bool)
— Method: get-auto-reverse

Retrieves the value set by clutter-timeline-set-auto-reverse.

timeline
a <clutter-timeline>
ret
‘#t’ if the timeline should automatically reverse, and ‘#f’ otherwise

Since 1.6

— Function: clutter-timeline-set-progress-mode (self <clutter-timeline>) (mode <clutter-animation-mode>)
— Method: set-progress-mode

Sets the progress function using a value from the <clutter-animation-mode> enumeration. The mode cannot be ‘CLUTTER_CUSTOM_MODE’ or bigger than ‘CLUTTER_ANIMATION_LAST’.

timeline
a <clutter-timeline>
mode
the progress mode, as a <clutter-animation-mode>

Since 1.10

— Function: clutter-timeline-get-progress-mode (self <clutter-timeline>) ⇒  (ret <clutter-animation-mode>)
— Method: get-progress-mode

Retrieves the progress mode set using clutter-timeline-set-progress-mode or clutter-timeline-set-progress-func.

timeline
a <clutter-timeline>
ret
a <clutter-animation-mode>

Since 1.10

— Function: clutter-timeline-get-duration-hint (self <clutter-timeline>) ⇒  (ret int64)
— Method: get-duration-hint

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.

timeline
a <clutter-timeline>
ret
the full duration of the <clutter-timeline>

Since 1.10

— Function: clutter-timeline-get-current-repeat (self <clutter-timeline>) ⇒  (ret int)
— Method: get-current-repeat

Retrieves the current repeat for a timeline.

Repeats start at 0.

timeline
a <clutter-timeline>
ret
the current repeat

Since 1.10

— Function: clutter-timeline-start (self <clutter-timeline>)
— Method: start

Starts the <clutter-timeline> playing.

timeline
A <clutter-timeline>
— Function: clutter-timeline-pause (self <clutter-timeline>)
— Method: pause

Pauses the <clutter-timeline> on current frame

timeline
A <clutter-timeline>
— Function: clutter-timeline-stop (self <clutter-timeline>)
— Method: stop

Stops the <clutter-timeline> and moves to frame 0

timeline
A <clutter-timeline>
— Function: clutter-timeline-rewind (self <clutter-timeline>)
— Method: rewind

Rewinds <clutter-timeline> to the first frame if its direction is ‘CLUTTER_TIMELINE_FORWARD’ and the last frame if it is ‘CLUTTER_TIMELINE_BACKWARD’.

timeline
A <clutter-timeline>
— Function: clutter-timeline-skip (self <clutter-timeline>) (msecs unsigned-int)
— Method: skip

Advance timeline by the requested time in milliseconds

timeline
A <clutter-timeline>
msecs
Amount of time to skip
— Function: clutter-timeline-advance (self <clutter-timeline>) (msecs unsigned-int)
— Method: advance

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.

timeline
A <clutter-timeline>
msecs
Time to advance to
— Function: clutter-timeline-get-elapsed-time (self <clutter-timeline>) ⇒  (ret unsigned-int)
— Method: get-elapsed-time

Request the current time position of the timeline.

timeline
A <clutter-timeline>
ret
current elapsed time in milliseconds.
— Function: clutter-timeline-get-delta (self <clutter-timeline>) ⇒  (ret unsigned-int)
— Method: get-delta

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 <clutter-timeline>
ret
the amount of time in milliseconds elapsed since the last frame

Since 0.6

— Function: clutter-timeline-get-progress (self <clutter-timeline>) ⇒  (ret double)
— Method: get-progress

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.

timeline
a <clutter-timeline>
ret
the normalized current position in the timeline.

Since 0.6

— Function: clutter-timeline-is-playing (self <clutter-timeline>) ⇒  (ret bool)
— Method: is-playing

Queries state of a <clutter-timeline>.

timeline
A <clutter-timeline>
ret
‘#t’ if timeline is currently playing
— Function: clutter-timeline-add-marker-at-time (self <clutter-timeline>) (marker_name mchars) (msecs unsigned-int)
— Method: add-marker-at-time

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 <clutter-timeline>
marker-name
the unique name for this marker
msecs
position of the marker in milliseconds

Since 0.8

— Function: clutter-timeline-has-marker (self <clutter-timeline>) (marker_name mchars) ⇒  (ret bool)
— Method: has-marker

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

timeline
a <clutter-timeline>
marker-name
the name of the marker
ret
‘#t’ if the marker was found

Since 0.8

— Function: clutter-timeline-remove-marker (self <clutter-timeline>) (marker_name mchars)
— Method: remove-marker

Removes marker-name, if found, from timeline.

timeline
a <clutter-timeline>
marker-name
the name of the marker to remove

Since 0.8

— Function: clutter-timeline-advance-to-marker (self <clutter-timeline>) (marker_name mchars)
— Method: advance-to-marker

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.

timeline
a <clutter-timeline>
marker-name
the name of the marker

Since 0.8