[clutter-tutorial] Improve the preferred-height ClutterText

[Murray Cumming <murrayc src gnome org>]

commit 2b1fa9bf5ca0077e1825028da2905cc061271ae7
Author: Murray Cumming <murrayc murrayc com>
Date:   Tue May 5 17:21:33 2009 +0200

    Improve the preferred-height ClutterText
    explanation and example.
---
 ChangeLog                     |    6 ++++++
 docs/tutorial/clutter-tut.xml |   14 ++++----------
 examples/text/main.c          |   15 +++++++++++----
 3 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c72e854..219f8ae 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2009-05-05  Murray Cumming  <murrayc murrayc com>
+
+	* docs/tutorial/clutter-tut.xml:
+	* examples/text/main.c (main): Improve the preferred-height ClutterText 
+	explanation and example. 
+
 2009-05-05  Johannes Schmid <jschmid openismus com>
 
 	* docs/tutorial/clutter-tut.xml
diff --git a/docs/tutorial/clutter-tut.xml b/docs/tutorial/clutter-tut.xml
index e96bf73..7b03f45 100644
--- a/docs/tutorial/clutter-tut.xml
+++ b/docs/tutorial/clutter-tut.xml
@@ -832,20 +832,14 @@ There are three ways you might use a <classname>ClutterText</classname> actor:
 
 <note>
 <para>
-When you want the <classname>ClutterText</classname> to be editable, you must give it key focus using <function>clutter_stage_set_key_focus()</function>.
+When you want the <classname>ClutterText</classname> to be editable you must give it key focus using <function>clutter_stage_set_key_focus()</function>.
 </para>
 </note>
 
 <sect2>
-<title>Size management</title>
+<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.
+To discover the size needed by the text inside a <classname>ClutterText</classname> actor, you may call will the <function>clutter_actor_get_preferred_height()</function> function. This will provide the vertical space necessary to display all of the text at the currently specified width. Alternatively, you could call <function>clutter_actor_get_preferred_width()</function> to discover the horizontal space necessary for the text at the currently specified height.
 </para>
 </sect2>
 
diff --git a/examples/text/main.c b/examples/text/main.c
index 0a8b816..43e67b6 100644
--- a/examples/text/main.c
+++ b/examples/text/main.c
@@ -22,8 +22,6 @@ 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: */
@@ -42,9 +40,14 @@ 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);
+  
+  /* Discover the preferred height and use that height: */
+  ClutterUnit min_height = 0;
+  ClutterUnit natural_height = 0;
   clutter_actor_get_preferred_height (text, 750, &min_height,
-                                      &natural_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);
@@ -67,9 +70,13 @@ int main(int argc, char *argv[])
   clutter_text_set_editable (CLUTTER_TEXT (text), TRUE);
   clutter_text_set_line_wrap (CLUTTER_TEXT (text), TRUE);
 
+  /* Discover the preferred height and use that height: */
+  min_height = 0;
+  natural_height = 0;
   clutter_actor_get_preferred_height (text, 750, &min_height,
-                                      &natural_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);