Clutter.Timeline¶

Subclasses:: Clutter.Transition

Methods¶

Inherited:: GObject.Object (37), Clutter.Scriptable (4)
Structs:: GObject.ObjectClass (5)

class	`new` (msecs)
	`add_marker` (marker_name, progress)
	`add_marker_at_time` (marker_name, msecs)
	`advance` (msecs)
	`advance_to_marker` (marker_name)
	`clone` ()
	`get_auto_reverse` ()
	`get_cubic_bezier_progress` ()
	`get_current_repeat` ()
	`get_delay` ()
	`get_delta` ()
	`get_direction` ()
	`get_duration` ()
	`get_duration_hint` ()
	`get_elapsed_time` ()
	`get_loop` ()
	`get_progress` ()
	`get_progress_mode` ()
	`get_repeat_count` ()
	`get_step_progress` ()
	`has_marker` (marker_name)
	`is_playing` ()
	`list_markers` (msecs)
	`pause` ()
	`remove_marker` (marker_name)
	`rewind` ()
	`set_auto_reverse` (reverse)
	`set_cubic_bezier_progress` (c_1, c_2)
	`set_delay` (msecs)
	`set_direction` (direction)
	`set_duration` (msecs)
	`set_loop` (loop)
	`set_progress_func` (func, *data)
	`set_progress_mode` (mode)
	`set_repeat_count` (count)
	`set_step_progress` (n_steps, step_mode)
	`skip` (msecs)
	`start` ()
	`stop` ()

Virtual Methods¶

Inherited:: GObject.Object (7), Clutter.Scriptable (4)

	`do_completed` ()
	`do_marker_reached` (marker_name, msecs)
	`do_new_frame` (msecs)
	`do_paused` ()
	`do_started` ()
	`do_stopped` (is_finished)

Properties¶

Name	Type	Flags	Short Description
`auto-reverse`	`bool`	r/w	Whether the direction should be reversed when reaching the end
`delay`	`int`	r/w	Delay before start
`direction`	`Clutter.TimelineDirection`	r/w	Direction of the timeline
`duration`	`int`	r/w	Duration of the timeline in milliseconds
`loop`	`bool`	d/r/w	Should the timeline automatically restart `deprecated`
`progress-mode`	`Clutter.AnimationMode`	r/w	How the timeline should compute the progress
`repeat-count`	`int`	r/w	How many times the timeline should repeat

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`completed`	The `Clutter.Timeline` `::completed` signal is emitted when the timeline’s elapsed time reaches the value of the `Clutter.Timeline` `:duration` property.
`marker-reached`	The `::marker-reached` signal is emitted each time a timeline reaches a marker set with `Clutter.Timeline.add_marker_at_time`().
`new-frame`	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.
`paused`	The `::paused` signal is emitted when `Clutter.Timeline.pause`() is invoked.
`started`	The `::started` signal is emitted when the timeline starts its run.
`stopped`	The `Clutter.Timeline` `::stopped` signal is emitted when the timeline has been stopped, either because `Clutter.Timeline.stop`() has been called, or because it has been exhausted.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Clutter.Timeline(**kwargs)¶

Bases:: GObject.Object, Clutter.Scriptable
Abstract:: No
Structure:: Clutter.TimelineClass

The Clutter.Timeline structure contains only private data and should be accessed using the provided API

New in version 0.2.

classmethod new(msecs)¶

Parameters:: msecs (int) – Duration of the timeline in milliseconds
Returns:: the newly created Clutter.Timeline instance. Use GObject.Object.unref() when done using it
Return type:: Clutter.Timeline

Creates a new Clutter.Timeline with a duration of msecs.

New in version 0.6.

add_marker(marker_name, progress)¶

Parameters:

marker_name (str) – the unique name for this marker
progress (float) – the normalized value of the position of the martke

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

New in version 1.14.

add_marker_at_time(marker_name, msecs)¶

Parameters:

marker_name (str) – the unique name for this marker
msecs (int) – position of the marker in milliseconds

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

New in version 0.8.

advance(msecs)¶

Parameters:: msecs (int) – Time to advance to

Advance timeline to the requested point. The point is given as a time in milliseconds since the timeline started.

The self will not emit the Clutter.Timeline ::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.

advance_to_marker(marker_name)¶

Parameters:: marker_name (str) – the name of the marker

Advances self to the time of the given marker_name.

Like Clutter.Timeline.advance(), this function will not emit the Clutter.Timeline ::new-frame for the time where marker_name is set, nor it will emit Clutter.Timeline ::marker-reached for marker_name.

New in version 0.8.

clone()¶

Returns:: a new Clutter.Timeline, cloned from self
Return type:: Clutter.Timeline

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 the original self: you will have to start it with Clutter.Timeline.start().

The only cloned properties are:

Clutter.Timeline :duration
Clutter.Timeline :loop
Clutter.Timeline :delay
Clutter.Timeline :direction

New in version 0.4.

Deprecated since version 1.10: Use Clutter.Timeline.new() or g_object_new() instead

get_auto_reverse()¶

Returns:: True if the timeline should automatically reverse, and False otherwise
Return type:: bool

Retrieves the value set by Clutter.Timeline.set_auto_reverse().

New in version 1.6.

get_cubic_bezier_progress()¶

Returns:

True if the self is using a cubic bezier progress more, and False otherwise

c_1:: return location for the first control point of the cubic bezier, or None
c_2:: return location for the second control point of the cubic bezier, or None

Return type:

(bool, c_1: Clutter.Point, c_2: Clutter.Point)

Retrieves the control points for the cubic bezier progress mode.

New in version 1.12.

get_current_repeat()¶

Returns:: the current repeat
Return type:: int

Retrieves the current repeat for a timeline.

Repeats start at 0.

New in version 1.10.

get_delay()¶

Returns:: the delay in milliseconds.
Return type:: int

Retrieves the delay set using Clutter.Timeline.set_delay().

New in version 0.4.

get_delta()¶

Returns:: the amount of time in milliseconds elapsed since the last frame
Return type:: int

Retrieves the amount of time elapsed since the last Clutter.Timeline ::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.

New in version 0.6.

get_direction()¶

Returns:: the direction of the timeline
Return type:: Clutter.TimelineDirection

Retrieves the direction of the timeline set with Clutter.Timeline.set_direction().

New in version 0.6.

get_duration()¶

Returns:: the duration of the timeline, in milliseconds.
Return type:: int

Retrieves the duration of a Clutter.Timeline in milliseconds. See Clutter.Timeline.set_duration().

New in version 0.6.

get_duration_hint()¶

Returns:: the full duration of the Clutter.Timeline
Return type:: int

Retrieves the full duration of the self, taking into account the current value of the Clutter.Timeline :repeat-count property.

If the Clutter.Timeline :repeat-count property is set to -1, this function will return GObject.G_MAXINT64.

The returned value is to be considered a hint, and it’s only valid as long as the self hasn’t been changed.

New in version 1.10.

get_elapsed_time()¶

Returns:: current elapsed time in milliseconds.
Return type:: int

Request the current time position of the timeline.

get_loop()¶

Returns:: True if the timeline is looping
Return type:: bool

Gets whether self is looping

Deprecated since version 1.10: Use Clutter.Timeline.get_repeat_count() instead.

get_progress()¶

Returns:: the normalized current position in the timeline.
Return type:: float

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

New in version 0.6.

get_progress_mode()¶

Returns:: a Clutter.AnimationMode
Return type:: Clutter.AnimationMode

Retrieves the progress mode set using Clutter.Timeline.set_progress_mode() or Clutter.Timeline.set_progress_func().

New in version 1.10.

get_repeat_count()¶

Returns:: the number of repeats
Return type:: int

Retrieves the number set using Clutter.Timeline.set_repeat_count().

New in version 1.10.

get_step_progress()¶

Returns:

True if the self is using a step progress mode, and False otherwise

n_steps:: return location for the number of steps, or None
step_mode:: return location for the value change policy, or None

Return type:

(bool, n_steps: int, step_mode: Clutter.StepMode)

Retrieves the parameters of the step progress mode used by self.

New in version 1.12.

has_marker(marker_name)¶

Parameters:: marker_name (str) – the name of the marker
Returns:: True if the marker was found
Return type:: bool

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

New in version 0.8.

is_playing()¶

Returns:: True if timeline is currently playing
Return type:: bool

Queries state of a Clutter.Timeline.

list_markers(msecs)¶

Parameters:: msecs (int) – the time to check, or -1
Returns:: a newly allocated, None terminated string array containing the names of the markers. Use GLib.strfreev() when done.
Return type:: [str]

Retrieves the list of markers at time msecs. If msecs is a negative integer, all the markers attached to self will be returned.

New in version 0.8.

pause()¶: Pauses the Clutter.Timeline on current frame

remove_marker(marker_name)¶

Parameters:: marker_name (str) – the name of the marker to remove

Removes marker_name, if found, from self.

New in version 0.8.

rewind()¶: Rewinds Clutter.Timeline to the first frame if its direction is Clutter.TimelineDirection.FORWARD and the last frame if it is Clutter.TimelineDirection.BACKWARD.

set_auto_reverse(reverse)¶

Parameters:: reverse (bool) – True if the self should reverse the direction

Sets whether self should reverse the direction after the emission of the Clutter.Timeline ::completed signal.

Setting the Clutter.Timeline :auto-reverse property to True is the equivalent of connecting a callback to the Clutter.Timeline ::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);

New in version 1.6.

set_cubic_bezier_progress(c_1, c_2)¶

Parameters:

c_1 (Clutter.Point) – the first control point for the cubic bezier
c_2 (Clutter.Point) – the second control point for the cubic bezier

Sets the Clutter.Timeline :progress-mode of self to Clutter.AnimationMode.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.

New in version 1.12.

set_delay(msecs)¶

Parameters:: msecs (int) – delay in milliseconds

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

New in version 0.4.

set_direction(direction)¶

Parameters:: direction (Clutter.TimelineDirection) – the direction of the timeline

Sets the direction of self, either Clutter.TimelineDirection.FORWARD or Clutter.TimelineDirection.BACKWARD.

New in version 0.6.

set_duration(msecs)¶

Parameters:: msecs (int) – duration of the timeline in milliseconds

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

New in version 0.6.

set_loop(loop)¶

Parameters:: loop (bool) – True for enable looping

Sets whether self 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.

Deprecated since version 1.10: Use Clutter.Timeline.set_repeat_count() instead.

set_progress_func(func, *data)¶

Parameters:

func (Clutter.TimelineProgressFunc or None) – a progress function, or None
data (object or None) – data to pass to func

Sets a custom progress function for self. 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 None, the Clutter.Timeline :progress-mode property will be set to Clutter.AnimationMode.CUSTOM_MODE.

If func is None, any previously set progress function will be unset, and the Clutter.Timeline :progress-mode property will be set to Clutter.AnimationMode.LINEAR.

New in version 1.10.

set_progress_mode(mode)¶

Parameters:: mode (Clutter.AnimationMode) – the progress mode, as a Clutter.AnimationMode

Sets the progress function using a value from the Clutter.AnimationMode enumeration. The mode cannot be Clutter.AnimationMode.CUSTOM_MODE or bigger than Clutter.AnimationMode.ANIMATION_LAST.

New in version 1.10.

set_repeat_count(count)¶

Parameters:: count (int) – the number of times the timeline should repeat

Sets the number of times the self should repeat.

If count is 0, the timeline never repeats.

If count is -1, the timeline will always repeat until it’s stopped.

New in version 1.10.

set_step_progress(n_steps, step_mode)¶

Parameters:

n_steps (int) – the number of steps
step_mode (Clutter.StepMode) – whether the change should happen at the start or at the end of the step

Sets the Clutter.Timeline :progress-mode of the self to Clutter.AnimationMode.STEPS and provides the parameters of the step function.

New in version 1.12.

skip(msecs)¶

Parameters:: msecs (int) – Amount of time to skip

Advance timeline by the requested time in milliseconds

start()¶: Starts the Clutter.Timeline playing.

stop()¶: Stops the Clutter.Timeline and moves to frame 0

do_completed() virtual¶

do_marker_reached(marker_name, msecs) virtual¶

Parameters:

marker_name (str) –
msecs (int) –

do_new_frame(msecs) virtual¶

Parameters:: msecs (int) –

do_paused() virtual¶

do_started() virtual¶

do_stopped(is_finished) virtual¶

Parameters:: is_finished (bool) –

Signal Details¶

Clutter.Timeline.signals.completed(timeline)¶

Signal Name:: completed
Flags:: RUN_LAST
Parameters:: timeline (Clutter.Timeline) – The object which received the signal

The Clutter.Timeline ::completed signal is emitted when the timeline’s elapsed time reaches the value of the Clutter.Timeline :duration property.

This signal will be emitted even if the Clutter.Timeline is set to be repeating.

If you want to get notification on whether the Clutter.Timeline has been stopped or has finished its run, including its eventual repeats, you should use the Clutter.Timeline ::stopped signal instead.

Clutter.Timeline.signals.marker_reached(timeline, marker_name, msecs)¶

Signal Name:

marker-reached

Flags:

RUN_LAST, NO_RECURSE, DETAILED, NO_HOOKS

Parameters:

timeline (Clutter.Timeline) – The object which received the signal
marker_name (str) – the name of the marker reached
msecs (int) – the elapsed time

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:

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.

New in version 0.8.

Clutter.Timeline.signals.new_frame(timeline, msecs)¶

Signal Name:

new-frame

Flags:

RUN_LAST

Parameters:

timeline (Clutter.Timeline) – The object which received the signal
msecs (int) – the elapsed time between 0 and duration

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.

Clutter.Timeline.signals.paused(timeline)¶

Signal Name:: paused
Flags:: RUN_LAST
Parameters:: timeline (Clutter.Timeline) – The object which received the signal

The ::paused signal is emitted when Clutter.Timeline.pause() is invoked.

Clutter.Timeline.signals.started(timeline)¶

Signal Name:: started
Flags:: RUN_LAST
Parameters:: timeline (Clutter.Timeline) – The object which received the signal

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 Clutter.Timeline :delay property has expired.

Clutter.Timeline.signals.stopped(timeline, is_finished)¶

Signal Name:

stopped

Flags:

RUN_LAST

Parameters:

timeline (Clutter.Timeline) – The object which received the signal
is_finished (bool) – True if the signal was emitted at the end of the timeline.

The Clutter.Timeline ::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 Clutter.Timeline ::completed signal, which gets emitted after every repeat finishes.

If the Clutter.Timeline has is marked as infinitely repeating, this signal will never be emitted.

New in version 1.12.

Property Details¶

Clutter.Timeline.props.auto_reverse¶

Name:: auto-reverse
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

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

New in version 1.6.

Clutter.Timeline.props.delay¶

Name:: delay
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

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

New in version 0.4.

Clutter.Timeline.props.direction¶

Name:: direction
Type:: Clutter.TimelineDirection
Default Value:: Clutter.TimelineDirection.FORWARD
Flags:: READABLE, WRITABLE

The direction of the timeline, either Clutter.TimelineDirection.FORWARD or Clutter.TimelineDirection.BACKWARD.

New in version 0.6.

Clutter.Timeline.props.duration¶

Name:: duration
Type:: int
Default Value:: 1000
Flags:: READABLE, WRITABLE

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

New in version 0.6.

Clutter.Timeline.props.loop¶

Name:: loop
Type:: bool
Default Value:: False
Flags:: DEPRECATED, READABLE, WRITABLE

Whether the timeline should automatically rewind and restart.

As a side effect, setting this property to True will set the Clutter.Timeline :repeat-count property to -1, while setting this property to False will set the Clutter.Timeline :repeat-count property to 0.

Deprecated since version 1.10: Use the Clutter.Timeline :repeat-count property instead.

Clutter.Timeline.props.progress_mode¶

Name:: progress-mode
Type:: Clutter.AnimationMode
Default Value:: Clutter.AnimationMode.LINEAR
Flags:: READABLE, WRITABLE

Controls the way a Clutter.Timeline computes the normalized progress.

New in version 1.10.

Clutter.Timeline.props.repeat_count¶

Name:: repeat-count
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

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.

New in version 1.10.