![]() |
![]() |
![]() |
Clutter 0.9.3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
ClutterTimeline; ClutterTimelineClass; ClutterTimeline * clutter_timeline_new (guint msecs); ClutterTimeline * clutter_timeline_clone (ClutterTimeline *timeline); void clutter_timeline_set_duration (ClutterTimeline *timeline, guint msecs); guint clutter_timeline_get_duration (ClutterTimeline *timeline); void clutter_timeline_set_loop (ClutterTimeline *timeline, gboolean loop); gboolean clutter_timeline_get_loop (ClutterTimeline *timeline); void clutter_timeline_set_delay (ClutterTimeline *timeline, guint msecs); guint clutter_timeline_get_delay (ClutterTimeline *timeline); enum ClutterTimelineDirection; void clutter_timeline_set_direction (ClutterTimeline *timeline, ClutterTimelineDirection direction); ClutterTimelineDirection clutter_timeline_get_direction (ClutterTimeline *timeline); void clutter_timeline_start (ClutterTimeline *timeline); void clutter_timeline_pause (ClutterTimeline *timeline); void clutter_timeline_stop (ClutterTimeline *timeline); void clutter_timeline_rewind (ClutterTimeline *timeline); void clutter_timeline_skip (ClutterTimeline *timeline, guint msecs); void clutter_timeline_advance (ClutterTimeline *timeline, guint msecs); guint clutter_timeline_get_elapsed_time (ClutterTimeline *timeline); guint clutter_timeline_get_delta (ClutterTimeline *timeline); gdouble clutter_timeline_get_progress (ClutterTimeline *timeline); CoglFixed clutter_timeline_get_progressx (ClutterTimeline *timeline); gboolean clutter_timeline_is_playing (ClutterTimeline *timeline); void clutter_timeline_add_marker_at_time (ClutterTimeline *timeline, const gchar *marker_name, guint msecs); gboolean clutter_timeline_has_marker (ClutterTimeline *timeline, const gchar *marker_name); gchar ** clutter_timeline_list_markers (ClutterTimeline *timeline, gint msecs, gsize *n_markers); void clutter_timeline_remove_marker (ClutterTimeline *timeline, const gchar *marker_name); void clutter_timeline_advance_to_marker (ClutterTimeline *timeline, const gchar *marker_name);
"delay" guint : Read / Write "direction" ClutterTimelineDirection : Read / Write "duration" guint : Read / Write "loop" gboolean : Read / Write
"completed" : Run Last "marker-reached" : Run Last / No Recursion / Has Details / No Hooks "new-frame" : Run Last "paused" : Run Last "started" : Run Last
ClutterTimeline is a base class for managing time based events such as animations.
Every timeline shares the same ClutterTimeoutPool 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 will be initialized so that the current
frame, as returned by clutter_timeline_get_current_frame()
, will be 0.
After starting a timeline, the first timeout is for frame number one (notably it isn't zero since there is a delay before the first "new-frame" signal, so re-asserting the frame number zero wouldn't make sense).
This implies that actors you intend to be affected by the timeline's progress should be manually primed or positioned for frame zero 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 the number
of frames in the timeline, as returned by clutter_timeline_get_n_frames()
.
For a looping timeline the timeout for the last frame would be followed by a timeout for frame number 1.
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 the last frame will always be signaled, but notably frame number 1 can be interpolated past and thus never signaled.
typedef struct _ClutterTimeline ClutterTimeline;
The ClutterTimeline structure contains only private data and should be accessed using the provided API
Since 0.2
typedef struct { void (*started) (ClutterTimeline *timeline); void (*completed) (ClutterTimeline *timeline); void (*paused) (ClutterTimeline *timeline); void (*new_frame) (ClutterTimeline *timeline, gint frame_num); void (*marker_reached) (ClutterTimeline *timeline, const gchar *marker_name, gint frame_num); } ClutterTimelineClass;
The ClutterTimelineClass structure contains only private data
|
handler for the "started" signal |
|
handler for the "completed" signal |
|
handler for the "paused" signal |
|
handler for the "new-frame" signal |
|
handler for the "marker-reached" signal |
Since 0.2
ClutterTimeline * clutter_timeline_clone (ClutterTimeline *timeline);
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
timeline
: you will have to start it with clutter_timeline_start()
.
|
ClutterTimeline to duplicate. |
Returns : |
a new ClutterTimeline, cloned from timeline
|
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.
|
a ClutterTimeline |
|
duration of the timeline in milliseconds |
Since 0.6
guint clutter_timeline_get_duration (ClutterTimeline *timeline);
Retrieves the duration of a ClutterTimeline in milliseconds.
See clutter_timeline_set_duration()
.
|
a ClutterTimeline |
Returns : |
the duration of the timeline, in milliseconds. |
Since 0.6
void clutter_timeline_set_loop (ClutterTimeline *timeline, gboolean loop);
Sets whether timeline
should loop.
|
a ClutterTimeline |
|
TRUE for enable looping
|
gboolean clutter_timeline_get_loop (ClutterTimeline *timeline);
Gets whether timeline
is looping
|
a ClutterTimeline |
Returns : |
TRUE if the timeline is looping
|
void clutter_timeline_set_delay (ClutterTimeline *timeline, guint msecs);
Sets the delay, in milliseconds, before timeline
should start.
|
a ClutterTimeline |
|
delay in milliseconds |
Since 0.4
guint clutter_timeline_get_delay (ClutterTimeline *timeline);
Retrieves the delay set using clutter_timeline_set_delay()
.
|
a ClutterTimeline |
Returns : |
the delay in milliseconds. |
Since 0.4
typedef enum { CLUTTER_TIMELINE_FORWARD, CLUTTER_TIMELINE_BACKWARD } ClutterTimelineDirection;
The direction of a ClutterTimeline
forward direction for a timeline | |
backward direction for a timeline |
Since 0.6
void clutter_timeline_set_direction (ClutterTimeline *timeline, ClutterTimelineDirection direction);
Sets the direction of timeline
, either CLUTTER_TIMELINE_FORWARD
or
CLUTTER_TIMELINE_BACKWARD
.
|
a ClutterTimeline |
|
the direction of the timeline |
Since 0.6
ClutterTimelineDirection clutter_timeline_get_direction (ClutterTimeline *timeline);
Retrieves the direction of the timeline set with
clutter_timeline_set_direction()
.
|
a ClutterTimeline |
Returns : |
the direction of the timeline |
Since 0.6
void clutter_timeline_start (ClutterTimeline *timeline);
Starts the ClutterTimeline playing.
|
A ClutterTimeline |
void clutter_timeline_pause (ClutterTimeline *timeline);
Pauses the ClutterTimeline on current frame
|
A ClutterTimeline |
void clutter_timeline_stop (ClutterTimeline *timeline);
Stops the ClutterTimeline and moves to frame 0
|
A ClutterTimeline |
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
.
|
A ClutterTimeline |
void clutter_timeline_skip (ClutterTimeline *timeline, guint msecs);
Advance timeline by the requested time in milliseconds
|
A ClutterTimeline |
|
Amount of time to skip |
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.
|
A ClutterTimeline |
|
Time to advance to |
guint clutter_timeline_get_elapsed_time (ClutterTimeline *timeline);
Request the current time position of the timeline.
|
A ClutterTimeline |
Returns : |
current elapsed time in milliseconds. |
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.
|
a ClutterTimeline |
Returns : |
the amount of time in milliseconds elapsed since the last frame |
Since 0.6
gdouble clutter_timeline_get_progress (ClutterTimeline *timeline);
The position of the timeline in a [0, 1] interval.
|
a ClutterTimeline |
Returns : |
the position of the timeline. |
Since 0.6
CoglFixed clutter_timeline_get_progressx (ClutterTimeline *timeline);
Fixed point version of clutter_timeline_get_progress()
.
|
a ClutterTimeline |
Returns : |
the position of the timeline as a fixed point value |
Since 0.6
gboolean clutter_timeline_is_playing (ClutterTimeline *timeline);
Queries state of a ClutterTimeline.
|
A ClutterTimeline |
Returns : |
TRUE if timeline is currently playing
|
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 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()
.
|
a ClutterTimeline |
|
the unique name for this marker |
|
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.
|
a ClutterTimeline |
|
the name of the marker |
Returns : |
TRUE if the marker was found
|
Since 0.8
gchar ** clutter_timeline_list_markers (ClutterTimeline *timeline, gint msecs, gsize *n_markers);
Retrieves the list of markers at time msecs
. If frame_num
is a
negative integer, all the markers attached to timeline
will be
returned.
|
a ClutterTimeline |
|
the time to check, or -1 |
|
the number of markers returned |
Returns : |
array zero-terminated=1 length=n_markers. 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
.
|
a ClutterTimeline |
|
the name of the marker to remove |
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
.
|
a ClutterTimeline |
|
the name of the marker |
Since 0.8
"delay"
property"delay" guint : Read / Write
A delay, in milliseconds, that should be observed by the timeline before actually starting.
Default value: 0
Since 0.4
"direction"
property"direction" ClutterTimelineDirection : Read / Write
The direction of the timeline, either CLUTTER_TIMELINE_FORWARD
or
CLUTTER_TIMELINE_BACKWARD
.
Default value: CLUTTER_TIMELINE_FORWARD
Since 0.6
"duration"
property"duration" guint : Read / Write
Duration of the timeline in milliseconds, depending on the ClutterTimeline:fps value.
Default value: 1000
Since 0.6
"loop"
property"loop" gboolean : Read / Write
Whether the timeline should automatically rewind and restart.
Default value: FALSE
"completed"
signalvoid user_function (ClutterTimeline *timeline, gpointer user_data) : Run Last
The ::completed signal is emitted when the timeline reaches the number of frames specified by the ClutterTimeline:num-frames property.
|
the ClutterTimeline which received the signal |
|
user data set when the signal handler was connected. |
"marker-reached"
signalvoid user_function (ClutterTimeline *timeline, gchar *marker_name, gint msecs, gpointer user_data) : Run Last / No Recursion / Has Details / No Hooks
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.
|
the ClutterTimeline which received the signal |
|
the name of the marker reached |
|
the elapsed time |
|
user data set when the signal handler was connected. |
Since 0.8
"new-frame"
signalvoid user_function (ClutterTimeline *timeline, gint msecs, gpointer user_data) : Run Last
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.
|
the timeline which received the signal |
|
the elapsed time between 0 and duration |
|
user data set when the signal handler was connected. |
"paused"
signalvoid user_function (ClutterTimeline *timeline, gpointer user_data) : Run Last
The ::paused signal is emitted when clutter_timeline_pause()
is invoked.
|
the ClutterTimeline which received the signal |
|
user data set when the signal handler was connected. |
"started"
signalvoid user_function (ClutterTimeline *timeline, gpointer user_data) : Run Last
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.
|
the ClutterTimeline which received the signal |
|
user data set when the signal handler was connected. |