[clutter-tutorial] ClutterText corrections.

[Murray Cumming <murrayc src gnome org>]

commit 3786aa70cd2a7dd79966c25262a22ca1871d8a01
Author: Murray Cumming <murrayc murrayc com>
Date:   Fri May 1 10:13:48 2009 +0200

    ClutterText corrections.
    
    * docs/tutorial/clutter-tut.xml: ClutterText section: Correct/Improve the
    text.
    * examples/text/main.c (main): Add a second ClutterText so we have one
    non-editable and one editable multi-line editable.
---
 ChangeLog                     |    9 ++++++++
 docs/tutorial/clutter-tut.xml |   45 +++++++++++++++++-----------------------
 examples/text/main.c          |   35 ++++++++++++++++++++++++++-----
 3 files changed, 57 insertions(+), 32 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 20d2d62..0fae971 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2009-05-01  Murray Cumming  <murrayc murrayc com>
+
+	ClutterText corrections.
+	
+	* docs/tutorial/clutter-tut.xml: ClutterText section: Correct/Improve the 
+	text.
+	* examples/text/main.c (main): Add a second ClutterText so we have one 
+	non-editable and one editable multi-line editable.
+
 2009-04-30  Murray Cumming  <murrayc murrayc com>
 
 	Fix the build.
diff --git a/docs/tutorial/clutter-tut.xml b/docs/tutorial/clutter-tut.xml
index fddcfa8..863633c 100644
--- a/docs/tutorial/clutter-tut.xml
+++ b/docs/tutorial/clutter-tut.xml
@@ -778,52 +778,45 @@ This simply moves the rectangle from the top-left to the bottom-right of the can
 <title>Text editing</title>
 <sect1 id="clutter-text"><title>ClutterText</title>
 <para>
-Clutter contains a powerful widget to display and edit text. It doesn't support
-all the fancy things that <classname>GtkTextView</classname> supports but it is
-enough for displaying all kind of information and for simple text inserting operations.
-The use-case of this widget is to act like a <classname>GtkLabel</classname> or an 
-extended <classname>GtkEntry</classname> that support multi line editing
+&clutter;'s <classname>ClutterText</classname> actor can display text and allow it to be edited. It doesn't have as much functionality as, for instance, GTK+'s <classname>GtkTextView</classname> widget, but it is enough for displaying information and for simple text entry. Therefore it serves the same purposes as GTK+'s <classname>GtkLabel</classname> or <classname>GtkEntry</classname> widgets, with the addition of multi line editing.
 </para>
+
+<para>
+There are three ways you might use a <classname>ClutterText</classname> actor:
+</para>
+
 <para>
-There are three things you can use a <classname>ClutterText</classname> actor for:
 <itemizedlist>
   <listitem>
-  <para>
-  As a simple label use <function>clutter_text_new_with_text()</function> or
-  <function>clutter_text_set_markup()</function> to display text. To make it non-editable
-  use <function>clutter_text_set_editable()</function>.
+  <para>For a simple label, use <function>clutter_text_new_with_text()</function> or <function>clutter_text_set_markup()</function>. To make it non-editable use <function>clutter_text_set_editable()</function>.
   </para>
   </listitem>
+  
   <listitem>
-  <para>
-  For use-cases where you would use a <classname>GtkEntry</classname> in a normal
-  &gtk; application, create a <classname>ClutterText</classname> using 
-  <function>clutter_text_new()</function> and <function>clutter_text_set_single_line_mode()
-  </function>. In this case it could be interesting to use <function>clutter_text_set_activatable()</function>
-  and connect to the <literal>activate</literal> signal which will be emitted when
-  the user presses <literal>Enter</literal>.
+  <para>For single line text entry, similar to a  <classname>GtkEntry</classname> in a normal &gtk; application, create a <classname>ClutterText</classname> using  <function>clutter_text_new()</function> and <function>clutter_text_set_single_line_mode()</function>. You may call <function>clutter_text_set_activatable()</function> and connect to the <literal>activate</literal> signal to react when the user presses <literal>Enter</literal>.
   </para>
   </listitem>
+  
   <listitem>
-  <para>
-  The third use case is a full-features multi-line text editing widget. <classname>ClutterText</classname>
-  gives you access to the cursor position using <function>clutter_text_get/set_cursor_*()</function> and to
-  the selection using <function>clutter_text_get/set_selection*()</function>. You can also add and
-  remove text at any position.
+  <para>For full-featured multi-line text editing, <classname>ClutterText</classname> gives you access to the cursor position using the <function>clutter_text_get/set_cursor_*()</function> functions and to the selection using the <function>clutter_text_get/set_selection*()</function> functions. You can also add and remove text at any position.
   </para>
   </listitem>
 </itemizedlist>
-When you want to have an editable <classname>ClutterText</classname> it is important
-to give it key focus using <function>clutter_stage_set_key_focus()</function>.
 </para>
 
+<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>.
+</para>
+</note>
+
 <para><ulink url="&url_refdocs_base_clutter;Text.html">ClutterText Reference</ulink></para>
 </sect1>
 
 <sect1 id="text-example"><title>Example</title>
 <para>
-This is a very basic example showing how to implement a multi-line text
-editing widget.
+This is a very basic example showing how to use a <classname>ClutterText</classname> for information display or multi-line text
+editing.
 </para>
 
 <figure id="figure-text-example">
diff --git a/examples/text/main.c b/examples/text/main.c
index 120ac10..23ab662 100644
--- a/examples/text/main.c
+++ b/examples/text/main.c
@@ -17,8 +17,6 @@
 #include <clutter/clutter.h>
 #include <stdlib.h>
 
-ClutterActor *text = NULL;
-
 int main(int argc, char *argv[])
 {
   ClutterColor stage_color = { 0x00, 0x00, 0x00, 0xff };
@@ -31,24 +29,49 @@ int main(int argc, char *argv[])
   clutter_actor_set_size (stage, 600, 200);
   clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_color);
 
-  /* Add a text actor to the stage: */
+
+  /* Add a non-editable text actor to the stage: */
+  ClutterActor *text = clutter_text_new ();
+
+	/* Setup text properties */
+  clutter_text_set_color (CLUTTER_TEXT (text), &actor_color);
+  clutter_text_set_text (CLUTTER_TEXT (text), 
+    "Non-editable text: Wizard imps and sweat sock pimps, interstellar mongrel nymphs.");
+  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_set_position (text, 5, 5);
+	clutter_container_add_actor (CLUTTER_CONTAINER (stage), text);
+  clutter_actor_show (text);
+  
+  
+   /* Add a multi-line editable text actor to the stage: */
   text = clutter_text_new ();
 
 	/* Setup text properties */
   clutter_text_set_color (CLUTTER_TEXT (text), &actor_color);
   clutter_text_set_text (CLUTTER_TEXT (text), 
-    "Wizard imps and sweat sock pimps, interstellar mongrel nymphs.");
+    "Editable text: And as I sat there brooding on the old, unknown world, I thought of "
+     "Gatsby's wonder when he first picked out the green light at the end of "
+     "Daisy's dock. He had come a long way to this blue lawn and his dream "
+     "must have seemed so close that he could hardly fail to grasp it. He did "
+     "not know that it was already behind him, somewhere back in that vast "
+     "obscurity beyond the city, where the dark fields of the republic rolled "
+     "on under the night.");
   clutter_text_set_font_name (CLUTTER_TEXT (text), "Sans 12");
 	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_set_position (text, 5, 5);
+  //clutter_actor_set_size (text, 590, 100);
+  clutter_actor_set_position (text, 5, 30);
 	clutter_container_add_actor (CLUTTER_CONTAINER (stage), text);
   clutter_actor_show (text);
 
   /* Set focus to handle key presses on the stage: */
   clutter_stage_set_key_focus (CLUTTER_STAGE (stage), text);
+  
 
   /* Show the stage: */
   clutter_actor_show (stage);