Next: , Previous: ClutterTexture, Up: Top

36 ClutterTimeline

A class for time-based events

36.1 Overview

<clutter-timeline> is a base class for managing time based events such as animations.

Every timeline shares the same <clutter-timeout-pool> to decrease the possibility of starving the main loop when using many timelines at the same time; this might cause problems if you are also using a library making heavy use of threads with no GLib main loop integration.

In that case you might disable the common timeline pool by setting the ‘CLUTTER_TIMELINE’=no-pool environment variable prior to launching your application.

One way to visualise a timeline is as a path with marks along its length. When creating a timeline of n-frames via clutter-timeline-new, then the number of frames can be seen as the paths length, and each unit of length (each frame) is delimited by a mark.

For a non looping timeline there will be (n_frames + 1) marks along its length. For a looping timeline, the two ends are joined with one mark. Technically this mark represents two discrete frame numbers, but for a looping timeline the start and end frame numbers are considered equivalent.

When you create a timeline it starts with clutter-timeline-get-current-frame == 0.

After starting a timeline, the first timeout is for current_frame_num == 1 (Notably it isn't 0 since there is a delay before the first timeout signals so re-asserting the starting frame (0) wouldn't make sense.) Notably, this implies that actors you intend to be affected by the timeline's progress, should be manually primed/positioned for frame 0 which will be displayed before the first timeout. (If you are not careful about this point you will likely see flashes of incorrect actor state in your program)

For a non looping timeline the last timeout would be for current_frame_num == n-frames

For a looping timeline the timeout for current_frame_num == n-frames would be followed by a timeout for current_frame_num == 1 (remember frame 0 is considered == frame (n-frames)).

There may be times when a system is not able to meet the frame rate requested for a timeline, and in this case the frame number will be interpolated at the next timeout event. The interpolation is calculated from the time that the timeline was started, not from the time of the last timeout, so a given timeline should basically elapse in the same - real world - time on any given system. An invariable here though is that current_frame_num == n-frames will always be signaled, but notably frame 1 can be interpolated past and so never signaled.

36.2 Usage

— Class: <clutter-timeline>

Derives from <gobject>.

This class defines the following slots:

fps
Timeline frames per second
num-frames
Timelines total number of frames
loop
Should the timeline automatically restart
delay
Delay before start
duration
Duration of the timeline in milliseconds
direction
Direction of the timeline
— Signal on <clutter-timeline>: new-frame (arg0 <gint>)

The ::new-frame signal is emitted each time a new frame in the timeline is reached.

— Signal on <clutter-timeline>: completed

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

— Signal on <clutter-timeline>: started

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.

— Signal on <clutter-timeline>: paused

The ::paused signal is emitted when clutter-timeline-pause is invoked.

— Signal on <clutter-timeline>: marker-reached (arg0 <gchararray>) (arg1 <gint>)

The ::marker-reached signal is emitted each time a timeline reaches a marker set with clutter-timeline-add-marker-at-frame or 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: 

          
            clutter_timeline_add_marker_at_frame (timeline, "foo", 24);
            clutter_timeline_add_marker_at_frame (timeline, "bar", 48);
          
            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

— Function: clutter-timeline-new (n_frames unsigned-int) (fps unsigned-int)   (ret <clutter-timeline>)

Create a new <clutter-timeline> instance.

n-frames
the number of frames
fps
the number of frames per second
ret
a new <clutter-timeline>
— Function: clutter-timeline-new-for-duration (msecs unsigned-int)   (ret <clutter-timeline>)

Creates a new <clutter-timeline> with a duration of msecs using the value of the ClutterTimeline:fps property to compute the equivalent number of frames.

msecs
Duration of the timeline in milliseconds
ret
the newly created <clutter-timeline>

Since 0.6

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

Create a new <clutter-timeline> 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
<clutter-timeline> to duplicate.
ret
a new <clutter-timeline>, cloned from timeline Since 0.4
— Function: clutter-timeline-set-speed (self <clutter-timeline>) (fps unsigned-int)
— Method: set-speed

Set the speed in frames per second of the timeline.

timeline
A <clutter-timeline>
fps
New speed of timeline as frames per second
— Function: clutter-timeline-get-speed (self <clutter-timeline>)   (ret unsigned-int)
— Method: get-speed

Gets the frames per second played by timeline

timeline
a <clutter-timeline>
ret
the number of frames per second.
— 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-loop (self <clutter-timeline>) (loop bool)
— Method: set-loop

Sets whether timeline should loop.

timeline
a <clutter-timeline>
loop
‘#t’ for enable looping
— Function: clutter-timeline-get-loop (self <clutter-timeline>)   (ret bool)
— Method: get-loop

Gets whether timeline is looping

timeline
a <clutter-timeline>
ret
‘#t’ if the timeline is looping
— Function: clutter-timeline-set-n-frames (self <clutter-timeline>) (n_frames unsigned-int)
— Method: set-n-frames

Sets the total number of frames for timeline

timeline
a <clutter-timeline>
n-frames
the number of frames
— Function: clutter-timeline-get-n-frames (self <clutter-timeline>)   (ret unsigned-int)
— Method: get-n-frames

Request the total number of frames for the <clutter-timeline>.

timeline
A <clutter-timeline>
ret
Number of frames for this <clutter-timeline>.
— 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-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>) (n_frames unsigned-int)
— Method: skip

Advance timeline by requested number of frames.

timeline
A <clutter-timeline>
n-frames
Number of frames to skip
— Function: clutter-timeline-advance (self <clutter-timeline>) (frame_num unsigned-int)
— Method: advance

Advance timeline to requested frame number

timeline
A <clutter-timeline>
frame-num
Frame number to advance to
— Function: clutter-timeline-get-current-frame (self <clutter-timeline>)   (ret int)
— Method: get-current-frame

Request the current frame number of the timeline.

timeline
A <clutter-timeline>
ret
current frame number
— Function: clutter-timeline-get-delta (self <clutter-timeline>)   (ret unsigned-int) (msecs unsigned-int)
— Method: get-delta

Retrieves the number of frames and 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>
msecs
return location for the milliseconds elapsed since the last frame, or ‘#f’
ret
the amount of frames elapsed since the last one

Since 0.6

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

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

timeline
a <clutter-timeline>
ret
the position of the timeline.

Since 0.6

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

Query state of a <clutter-timeline> instance.

timeline
A <clutter-timeline>
ret
TRUE if timeline is currently playing, FALSE if not.
— Function: clutter-timeline-add-marker-at-time (self <clutter-timeline>) (marker_name mchars) (msecs unsigned-int)
— Method: add-marker-at-time

Time-based variant of clutter-timeline-add-marker-at-frame.

Adds a named marker at msecs.

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 frame of the given marker-name.

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

Since 0.8