[clutter-tutorial] Added section about size management for ClutterText

[Johannes Schmid <jhs src gnome org>]

commit 1d3516280e450fe2d94a8ca3b027a30ce91756f0
Author: Johannes Schmid <jhs gnome org>
Date:   Tue May 5 13:17:34 2009 +0200

    Added section about size management for ClutterText
    
    The natural size algorithms from clutter can be used to determine the correct size.
    Also updated the example to show how this works.
---
 ChangeLog                     |    7 +++++++
 docs/tutorial/clutter-tut.xml |   13 +++++++++++++
 examples/text/main.c          |   13 +++++++++----
 3 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 811bfd1..c72e854 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2009-05-05  Johannes Schmid <jschmid openismus com>
 
+	* docs/tutorial/clutter-tut.xml
+	* docs/examples/text/main.c:
+	Added a section about size management of ClutterText actors and updated the
+	example.
+
+2009-05-05  Johannes Schmid <jschmid openismus com>
+
 	* docs/tutorial/figures/gtk_scrolling.png:
 	* docs/tutorial/figures/text.png:
 	Use Clearlooks for screenshots
diff --git a/docs/tutorial/clutter-tut.xml b/docs/tutorial/clutter-tut.xml
index 76b8b76..e96bf73 100644
--- a/docs/tutorial/clutter-tut.xml
+++ b/docs/tutorial/clutter-tut.xml
@@ -836,6 +836,19 @@ When you want the <classname>ClutterText</classname> to be editable, you must gi
 </para>
 </note>
 
+<sect2>
+<title>Size management</title>
+<para>
+It is often a unpredictable which size a <classname>ClutterText</classname> actor will
+need to display all its text. In this case the <function>clutter_actor_get_preferred_height()</function>
+method becomes handy. Usually you will know the maximum width you can assign an actor
+because of screen limitation and this method will give you the correct height
+for the choosen text length and font. Of course you could also use 
+<function>clutter_actor_get_preferred_width()</function> in case you want to calculate
+the size the other way round.
+</para>
+</sect2>
+
 <para><ulink url="&url_refdocs_base_clutter;Text.html">ClutterText Reference</ulink></para>
 </sect1>
 
diff --git a/examples/text/main.c b/examples/text/main.c
index c68f0cd..0a8b816 100644
--- a/examples/text/main.c
+++ b/examples/text/main.c
@@ -22,11 +22,13 @@ int main(int argc, char *argv[])
   ClutterColor stage_color = { 0x00, 0x00, 0x00, 0xff };
   ClutterColor actor_color = { 0xff, 0xff, 0xcc, 0xff };
 
+  ClutterUnit min_height, natural_height;
+
   clutter_init (&argc, &argv);
 
   /* Get the stage and set its size and color: */
   ClutterActor *stage = clutter_stage_get_default ();
-  clutter_actor_set_size (stage, 600, 200);
+  clutter_actor_set_size (stage, 800, 200);
   clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_color);
 
 
@@ -40,8 +42,9 @@ int main(int argc, char *argv[])
   clutter_text_set_font_name (CLUTTER_TEXT (text), "Sans 12");
   clutter_text_set_editable (CLUTTER_TEXT (text), FALSE);
   clutter_text_set_line_wrap (CLUTTER_TEXT (text), FALSE);
-
-  clutter_actor_set_size (text, 590, 100);
+  clutter_actor_get_preferred_height (text, 750, &min_height,
+                                      &natural_height);
+  clutter_actor_set_size (text, 750, natural_height);
   clutter_actor_set_position (text, 5, 5);
   clutter_container_add_actor (CLUTTER_CONTAINER (stage), text);
   clutter_actor_show (text);
@@ -64,7 +67,9 @@ int main(int argc, char *argv[])
   clutter_text_set_editable (CLUTTER_TEXT (text), TRUE);
   clutter_text_set_line_wrap (CLUTTER_TEXT (text), TRUE);
 
-  clutter_actor_set_size (text, 590, 100);
+  clutter_actor_get_preferred_height (text, 750, &min_height,
+                                      &natural_height);
+  clutter_actor_set_size (text, 750, natural_height);
   clutter_actor_set_position (text, 5, 50);
   clutter_container_add_actor (CLUTTER_CONTAINER (stage), text);
   clutter_actor_show (text);