Top | ![]() |
![]() |
![]() |
![]() |
gboolean | auto-reverse | Read / Write |
guint | delay | Read / Write |
ClutterTimelineDirection | direction | Read / Write |
guint | duration | Read / Write |
gboolean | loop | Read / Write |
ClutterAnimationMode | progress-mode | Read / Write |
int | repeat-count | Read / Write |
ClutterTimeline | |
struct | ClutterTimelineClass |
enum | ClutterTimelineDirection |
enum | ClutterAnimationMode |
enum | ClutterStepMode |
ClutterTimeline is a base class for managing time-based event that cause Clutter to redraw a stage, such as animations.
Each ClutterTimeline 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 ClutterTimeline 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 ClutterTimeline 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 “stopped” signal. The ClutterTimeline guarantees the emission of at least a single “new-frame” signal, as well as the emission of the “completed” signal every time the ClutterTimeline reaches its “duration”.
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 at each repeat. If you want to be notified of the end of the last
repeat, use the “stopped” signal.
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 ClutterAnimation, ClutterAnimator, and ClutterState.
A ClutterTimeline can be described in ClutterScript 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:
1 2 3 4 5 6 7 8 9 |
{ "type" : "ClutterTimeline", "duration" : 1000, "markers" : [ { "name" : "quarter", "time" : 250 }, { "name" : "half-time", "time" : 500 }, { "name" : "three-quarters", "time" : 750 } ] } |
ClutterTimeline *
clutter_timeline_new (guint msecs
);
Creates a new ClutterTimeline with a duration of msecs
.
Since: 0.6
ClutterTimeline *
clutter_timeline_clone (ClutterTimeline *timeline
);
clutter_timeline_clone
has been deprecated since version 1.10 and should not be used in newly-written code.
Use clutter_timeline_new()
or g_object_new()
instead
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
the original timeline
: you will have to start it with
clutter_timeline_start()
.
The only cloned properties are:
Since: 0.4
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.
Since: 0.6
guint
clutter_timeline_get_duration (ClutterTimeline *timeline
);
Retrieves the duration of a ClutterTimeline in milliseconds.
See clutter_timeline_set_duration()
.
Since: 0.6
void clutter_timeline_set_repeat_count (ClutterTimeline *timeline
,gint 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.
Since: 1.10
gint
clutter_timeline_get_repeat_count (ClutterTimeline *timeline
);
Retrieves the number set using clutter_timeline_set_repeat_count()
.
Since: 1.10
void clutter_timeline_set_delay (ClutterTimeline *timeline
,guint msecs
);
Sets the delay, in milliseconds, before timeline
should start.
Since: 0.4
guint
clutter_timeline_get_delay (ClutterTimeline *timeline
);
Retrieves the delay set using clutter_timeline_set_delay()
.
Since: 0.4
void clutter_timeline_set_direction (ClutterTimeline *timeline
,ClutterTimelineDirection direction
);
Sets the direction of timeline
, either CLUTTER_TIMELINE_FORWARD
or
CLUTTER_TIMELINE_BACKWARD
.
Since: 0.6
ClutterTimelineDirection
clutter_timeline_get_direction (ClutterTimeline *timeline
);
Retrieves the direction of the timeline set with
clutter_timeline_set_direction()
.
Since: 0.6
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_repeat_count (timeline, -1); 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_repeat_count (timeline, -1); clutter_timeline_set_auto_reverse (timeline); |
Since: 1.6
gboolean
clutter_timeline_get_auto_reverse (ClutterTimeline *timeline
);
Retrieves the value set by clutter_timeline_set_auto_reverse()
.
Since: 1.6
void clutter_timeline_set_progress_mode (ClutterTimeline *timeline
,ClutterAnimationMode mode
);
Sets the progress function using a value from the ClutterAnimationMode
enumeration. The mode
cannot be CLUTTER_CUSTOM_MODE
or bigger than
CLUTTER_ANIMATION_LAST
.
Since: 1.10
ClutterAnimationMode
clutter_timeline_get_progress_mode (ClutterTimeline *timeline
);
Retrieves the progress mode set using clutter_timeline_set_progress_mode()
or clutter_timeline_set_progress_func()
.
Since: 1.10
void clutter_timeline_set_cubic_bezier_progress (ClutterTimeline *timeline
,const ClutterPoint *c_1
,const ClutterPoint *c_2
);
Sets the “progress-mode” of timeline
to CLUTTER_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.
timeline |
||
c_1 |
the first control point for the cubic bezier |
|
c_2 |
the second control point for the cubic bezier |
Since: 1.12
gboolean clutter_timeline_get_cubic_bezier_progress (ClutterTimeline *timeline
,ClutterPoint *c_1
,ClutterPoint *c_2
);
Retrieves the control points for the cubic bezier progress mode.
Since: 1.12
void clutter_timeline_set_step_progress (ClutterTimeline *timeline
,gint n_steps
,ClutterStepMode step_mode
);
Sets the “progress-mode” of the timeline
to CLUTTER_STEPS
and provides the parameters of the step function.
timeline |
||
n_steps |
the number of steps |
|
step_mode |
whether the change should happen at the start or at the end of the step |
Since: 1.12
gboolean clutter_timeline_get_step_progress (ClutterTimeline *timeline
,gint *n_steps
,ClutterStepMode *step_mode
);
Retrieves the parameters of the step progress mode used by timeline
.
Since: 1.12
gdouble (*ClutterTimelineProgressFunc) (ClutterTimeline *timeline
,gdouble elapsed
,gdouble total
,gpointer user_data
);
A function for defining a custom progress.
timeline |
||
elapsed |
the elapsed time, in milliseconds |
|
total |
the total duration of the timeline, in milliseconds, |
|
user_data |
data passed to the function |
Since: 1.10
void clutter_timeline_set_progress_func (ClutterTimeline *timeline
,ClutterTimelineProgressFunc func
,gpointer data
,GDestroyNotify notify
);
Sets a custom progress function for timeline
. 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 NULL
, the “progress-mode” property will
be set to CLUTTER_CUSTOM_MODE
.
If func
is NULL
, any previously set progress function will be unset, and
the “progress-mode” property will be set to CLUTTER_LINEAR
.
timeline |
||
func |
a progress function, or |
[scope notified][allow-none] |
data |
data to pass to |
[closure] |
notify |
a function to be called when the progress function is removed or the timeline is disposed |
Since: 1.10
gint64
clutter_timeline_get_duration_hint (ClutterTimeline *timeline
);
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.
Since: 1.10
gint
clutter_timeline_get_current_repeat (ClutterTimeline *timeline
);
Retrieves the current repeat for a timeline.
Repeats start at 0.
Since: 1.10
void clutter_timeline_set_loop (ClutterTimeline *timeline
,gboolean loop
);
clutter_timeline_set_loop
has been deprecated since version 1.10 and should not be used in newly-written code.
Use clutter_timeline_set_repeat_count()
instead.
Sets whether timeline
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
.
gboolean
clutter_timeline_get_loop (ClutterTimeline *timeline
);
clutter_timeline_get_loop
has been deprecated since version 1.10 and should not be used in newly-written code.
Use clutter_timeline_get_repeat_count()
instead.
Gets whether timeline
is looping
void
clutter_timeline_start (ClutterTimeline *timeline
);
Starts the ClutterTimeline playing.
void
clutter_timeline_pause (ClutterTimeline *timeline
);
Pauses the ClutterTimeline on current frame
void
clutter_timeline_stop (ClutterTimeline *timeline
);
Stops the ClutterTimeline and moves to frame 0
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
.
void clutter_timeline_skip (ClutterTimeline *timeline
,guint msecs
);
Advance timeline by the requested time in milliseconds
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.
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.
guint
clutter_timeline_get_elapsed_time (ClutterTimeline *timeline
);
Request the current time position of the timeline.
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.
Since: 0.6
gdouble
clutter_timeline_get_progress (ClutterTimeline *timeline
);
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()
.
Since: 0.6
gboolean
clutter_timeline_is_playing (ClutterTimeline *timeline
);
Queries state of a ClutterTimeline.
void clutter_timeline_add_marker (ClutterTimeline *timeline
,const gchar *marker_name
,gdouble progress
);
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 timeline
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()
.
See also: clutter_timeline_add_marker_at_time()
timeline |
||
marker_name |
the unique name for this marker |
|
progress |
the normalized value of the position of the martke |
Since: 1.14
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 position on the
timeline. Once timeline
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()
.
See also: clutter_timeline_add_marker()
timeline |
||
marker_name |
the unique name for this marker |
|
msecs |
position of the marker in milliseconds |
Since: 0.8
gboolean clutter_timeline_has_marker (ClutterTimeline *timeline
,const gchar *marker_name
);
Checks whether timeline
has a marker set with the given name.
Since: 0.8
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.
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
void clutter_timeline_remove_marker (ClutterTimeline *timeline
,const gchar *marker_name
);
Removes marker_name
, if found, from timeline
.
Since: 0.8
void clutter_timeline_advance_to_marker (ClutterTimeline *timeline
,const gchar *marker_name
);
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
.
Since: 0.8
typedef struct _ClutterTimeline ClutterTimeline;
The ClutterTimeline structure contains only private data and should be accessed using the provided API
Since: 0.2
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); void (*stopped) (ClutterTimeline *timeline, gboolean is_finished); };
The ClutterTimelineClass structure contains only private data
class handler for the “started” signal |
||
class handler for the “completed” signal |
||
class handler for the “paused” signal |
||
class handler for the “new-frame” signal |
||
class handler for the “marker-reached” signal |
||
class handler for the “stopped” signal |
Since: 0.2
The animation modes used by ClutterAlpha and ClutterAnimation. This enumeration can be expanded in later versions of Clutter.
Every global alpha function registered using clutter_alpha_register_func()
or clutter_alpha_register_closure()
will have a logical id greater than
CLUTTER_ANIMATION_LAST
.
custom progress function |
||
linear tweening |
||
quadratic tweening |
||
quadratic tweening, inverse of
|
||
quadratic tweening, combininig
|
||
cubic tweening |
||
cubic tweening, invers of
|
||
cubic tweening, combining
|
||
quartic tweening |
||
quartic tweening, inverse of
|
||
quartic tweening, combining
|
||
quintic tweening |
||
quintic tweening, inverse of
|
||
fifth power tweening, combining
|
||
sinusoidal tweening |
||
sinusoidal tweening, inverse of
|
||
sine wave tweening, combining
|
||
exponential tweening |
||
exponential tweening, inverse of
|
||
exponential tweening, combining
|
||
circular tweening |
||
circular tweening, inverse of
|
||
circular tweening, combining
|
||
elastic tweening, with offshoot on start |
||
elastic tweening, with offshoot on end |
||
elastic tweening with offshoot on both ends |
||
overshooting cubic tweening, with backtracking on start |
||
overshooting cubic tweening, with backtracking on end |
||
overshooting cubic tweening, with backtracking on both ends |
||
exponentially decaying parabolic (bounce) tweening, with bounce on start |
||
exponentially decaying parabolic (bounce) tweening, with bounce on end |
||
exponentially decaying parabolic (bounce) tweening, with bounce on both ends |
||
parametrized step function; see |
||
equivalent to |
||
equivalent to |
||
cubic bezier between (0, 0) and (1, 1) with two
control points; see |
||
equivalent to |
||
equivalent to |
||
equivalent to |
||
equivalent to |
||
last animation mode, used as a guard for registered global alpha functions |
Since: 1.0
Change the value transition of a step function.
See clutter_timeline_set_step_progress()
.
Since: 1.12
“auto-reverse”
property“auto-reverse” gboolean
If the direction of the timeline should be automatically reversed when reaching the end.
Owner: ClutterTimeline
Flags: Read / Write
Default value: FALSE
Since: 1.6
“delay”
property“delay” guint
A delay, in milliseconds, that should be observed by the timeline before actually starting.
Owner: ClutterTimeline
Flags: Read / Write
Default value: 0
Since: 0.4
“direction”
property“direction” ClutterTimelineDirection
The direction of the timeline, either CLUTTER_TIMELINE_FORWARD
or
CLUTTER_TIMELINE_BACKWARD
.
Owner: ClutterTimeline
Flags: Read / Write
Default value: CLUTTER_TIMELINE_FORWARD
Since: 0.6
“duration”
property“duration” guint
Duration of the timeline in milliseconds, depending on the ClutterTimeline:fps value.
Owner: ClutterTimeline
Flags: Read / Write
Default value: 1000
Since: 0.6
“loop”
property“loop” gboolean
Whether the timeline should automatically rewind and restart.
As a side effect, setting this property to TRUE
will set the
“repeat-count” property to -1, while setting this
property to FALSE
will set the “repeat-count”
property to 0.
ClutterTimeline:loop
has been deprecated since version 1.10 and should not be used in newly-written code.
Use the “repeat-count” property instead.
Owner: ClutterTimeline
Flags: Read / Write
Default value: FALSE
“progress-mode”
property“progress-mode” ClutterAnimationMode
Controls the way a ClutterTimeline computes the normalized progress.
Owner: ClutterTimeline
Flags: Read / Write
Default value: CLUTTER_LINEAR
Since: 1.10
“repeat-count”
property “repeat-count” int
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.
Owner: ClutterTimeline
Flags: Read / Write
Allowed values: >= -1
Default value: 0
Since: 1.10
“completed”
signalvoid user_function (ClutterTimeline *timeline, gpointer user_data)
The “completed” signal is emitted when the timeline's elapsed time reaches the value of the “duration” property.
This signal will be emitted even if the ClutterTimeline is set to be repeating.
If you want to get notification on whether the ClutterTimeline has been stopped or has finished its run, including its eventual repeats, you should use the “stopped” signal instead.
timeline |
the ClutterTimeline which received the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“marker-reached”
signalvoid user_function (ClutterTimeline *timeline, char *marker_name, int msecs, gpointer user_data)
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 9 |
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. |
Flags: No Hooks
Since: 0.8
“new-frame”
signalvoid user_function (ClutterTimeline *timeline, int msecs, gpointer user_data)
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. |
Flags: Run Last
“paused”
signalvoid user_function (ClutterTimeline *timeline, gpointer user_data)
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. |
Flags: Run Last
“started”
signalvoid user_function (ClutterTimeline *timeline, gpointer user_data)
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. |
Flags: Run Last
“stopped”
signalvoid user_function (ClutterTimeline *timeline, gboolean is_finished, gpointer user_data)
The “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 “completed” signal, which gets emitted after every repeat finishes.
If the ClutterTimeline has is marked as infinitely repeating, this signal will never be emitted.
timeline |
the ClutterTimeline that emitted the signal |
|
is_finished |
|
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
Since: 1.12