[clutter-tutorial] Added section about timeline markers to the tutorial

[Johannes Schmid <jhs src gnome org>]

commit 1d656ebeade9dcc33d99f5d1cf1d620e1aa1c4df
Author: Johannes Schmid <jhs gnome org>
Date:   Tue Apr 21 09:19:26 2009 +0200

    Added section about timeline markers to the tutorial
    
    Timeline markers are a new API in clutter-0.8 and are now covered including an
    updated timeline example.
---
 docs/tutorial/clutter-tut.xml |   11 +++++++++++
 examples/timeline/main.c      |   11 +++++++++++
 2 files changed, 22 insertions(+), 0 deletions(-)

diff --git a/docs/tutorial/clutter-tut.xml b/docs/tutorial/clutter-tut.xml
index 0c3d2e0..d35bb29 100644
--- a/docs/tutorial/clutter-tut.xml
+++ b/docs/tutorial/clutter-tut.xml
@@ -548,6 +548,17 @@ timeline's <literal>completed</literal> signal.</para>
 <para><ulink url="&url_refdocs_base_clutter;Timeline.html">Reference</ulink></para>
 </sect1>
 
+<sect1 id="timeline-markers"><title>Markers</title>
+<para>
+In many cases you want an action to happen at a specfic point in the timeline. Instead of polling this point by using
+<function>clutter_timeline_get_progress()</function> you should instead use timeline markers. Timeline markers can be added
+using <function>clutter_timeline_add_marker_at_frame()</function> or <function>clutter_timeline_add_marker_at_time()</function>. 
+Once you added the marker, connect to the <literal>marker-reached</literal> to start the appropriate action there or to
+<literal>marker-reached::my_marker</liternal> when the signal should only catch the marker <literal>my_marker</literal>. 
+You can also use markers to navigate through the timeline using <function>clutter_timeline_advance_to_marker</function>.
+</para>
+</sect1>
+
 <sect1 id="timeline-example"><title>Example</title>
 <para>
 The following example demonstrates the use of a timeline to rotate a rectangle around the x axis while changing its color:
diff --git a/examples/timeline/main.c b/examples/timeline/main.c
index f86f284..ead1cfd 100644
--- a/examples/timeline/main.c
+++ b/examples/timeline/main.c
@@ -53,6 +53,15 @@ on_timeline_new_frame (ClutterTimeline *timeline,
   }
 }
 
+void
+on_timeline_marker_reached (ClutterTimeline* timeline,
+                            gchar*           marker_name,
+                            gint             frame_num,
+                            gpointer         user_data)
+{
+  printf ("Reached marker %s at frame %d!\n",
+          marker_name, frame_num);
+}
 
 int main(int argc, char *argv[])
 {
@@ -77,7 +86,9 @@ int main(int argc, char *argv[])
   clutter_actor_show (stage);
 
   ClutterTimeline *timeline = clutter_timeline_new(10 /* frames */, 120 /* frames per second. */);
+  clutter_timeline_add_marker_at_frame (timeline, "clutter-tutorial", 5);
   g_signal_connect (timeline, "new-frame", G_CALLBACK (on_timeline_new_frame), NULL);
+  g_signal_connect (timeline, "marker-reached", G_CALLBACK (on_timeline_marker_reached), NULL);
   clutter_timeline_set_loop(timeline, TRUE); 
   clutter_timeline_start(timeline);