Text-related Programming guide updates

Change-Id: I474917bd30af46ad58b389c5c8c3e4469578c606

diff --git a/dali-toolkit/internal/text/rendering/atlas/text-atlas-renderer.cpp b/dali-toolkit/internal/text/rendering/atlas/text-atlas-renderer.cpp
index 7891391..b82b07b 100644 (file)
--- a/dali-toolkit/internal/text/rendering/atlas/text-atlas-renderer.cpp
+++ b/dali-toolkit/internal/text/rendering/atlas/text-atlas-renderer.cpp
@@ -21,6 +21,7 @@
 // EXTERNAL INCLUDES
 #include <dali/dali.h>
 #include <dali/integration-api/debug.h>
 // EXTERNAL INCLUDES
 #include <dali/dali.h>
 #include <dali/integration-api/debug.h>

+#include <dali/public-api/text-abstraction/text-abstraction.h>

 
 // INTERNAL INCLUDES
 #include <dali-toolkit/internal/atlas-manager/atlas-manager.h>
 
 // INTERNAL INCLUDES
 #include <dali-toolkit/internal/atlas-manager/atlas-manager.h>


@@ -722,4 +723,4 @@ AtlasRenderer::AtlasRenderer()
 AtlasRenderer::~AtlasRenderer()
 {
   delete mImpl;
 AtlasRenderer::~AtlasRenderer()
 {
   delete mImpl;

-}
\ No newline at end of file
+}

diff --git a/docs/content/example-code/property-example.cpp b/docs/content/example-code/property-example.cpp
index 35e7869..e0f40e6 100644 (file)
--- a/docs/content/example-code/property-example.cpp
+++ b/docs/content/example-code/property-example.cpp
@@ -101,7 +101,7 @@ class PropertyButtonsController: public ConnectionTracker
     }
 
     // Create the last selected button text view.
     }
 
     // Create the last selected button text view.

-    mTagText = Toolkit::TextView::New( "None selected" );
+    mTagText = Toolkit::TextLabel::New( "None selected" );

     mTagText.SetParentOrigin( ParentOrigin::BOTTOM_CENTER );
     mTagText.SetAnchorPoint( AnchorPoint::BOTTOM_CENTER );
     mTagText.SetPosition( Vector3( 0.0f, -30.0f, 0.0f ) );
     mTagText.SetParentOrigin( ParentOrigin::BOTTOM_CENTER );
     mTagText.SetAnchorPoint( AnchorPoint::BOTTOM_CENTER );
     mTagText.SetPosition( Vector3( 0.0f, -30.0f, 0.0f ) );


@@ -121,14 +121,14 @@ class PropertyButtonsController: public ConnectionTracker
     // Property::Index index = button.GetPropertyIndex( TAG_PROPERTY_NAME );
     valueText << "Selected: " << button.GetProperty< float >( mTagPropertyIndex );
 
     // Property::Index index = button.GetPropertyIndex( TAG_PROPERTY_NAME );
     valueText << "Selected: " << button.GetProperty< float >( mTagPropertyIndex );
 

-    mTagText.SetText( valueText.str() );
+    mTagText.SetProperty( TextLabel::Property::TEXT, valueText.str() );

 
     return true;
   }
 
   private:
 
 
     return true;
   }
 
   private:
 

-  Toolkit::TextView mTagText;        ///< A text label used to show the last button pressed.
+  Toolkit::TextLabel mTagText;        ///< A text label used to show the last button pressed.

   Property::Index mTagPropertyIndex; ///< A cached property index of our custom tag property.
 };
 
   Property::Index mTagPropertyIndex; ///< A cached property index of our custom tag property.
 };
 

diff --git a/docs/content/images/actors/Text-Actor.png b/docs/content/images/actors/Text-Actor.png
deleted file mode 100644 (file)
index 6bba38e..0000000
Binary files a/docs/content/images/actors/Text-Actor.png and /dev/null differ

diff --git a/docs/content/images/actors/Text-Label.png b/docs/content/images/actors/Text-Label.png
new file mode 100644 (file)
index 0000000..cc2dc30
Binary files /dev/null and b/docs/content/images/actors/Text-Label.png differ

diff --git a/docs/content/images/text-controls/HelloWorld-HeightForWidth.png b/docs/content/images/text-controls/HelloWorld-HeightForWidth.png
new file mode 100644 (file)
index 0000000..915862c
Binary files /dev/null and b/docs/content/images/text-controls/HelloWorld-HeightForWidth.png differ

diff --git a/docs/content/images/text-controls/HelloWorld-NaturalSize.png b/docs/content/images/text-controls/HelloWorld-NaturalSize.png
new file mode 100644 (file)
index 0000000..28d24d1
Binary files /dev/null and b/docs/content/images/text-controls/HelloWorld-NaturalSize.png differ

diff --git a/docs/content/images/text-controls/PlainText.png b/docs/content/images/text-controls/PlainText.png
new file mode 100644 (file)
index 0000000..5ef9ff1
Binary files /dev/null and b/docs/content/images/text-controls/PlainText.png differ

diff --git a/docs/content/images/text-controls/RedText.png b/docs/content/images/text-controls/RedText.png
new file mode 100644 (file)
index 0000000..f2fe9fe
Binary files /dev/null and b/docs/content/images/text-controls/RedText.png differ

diff --git a/docs/content/images/text-controls/TextWith1pxUnderline.png b/docs/content/images/text-controls/TextWith1pxUnderline.png
new file mode 100644 (file)
index 0000000..082d19e
Binary files /dev/null and b/docs/content/images/text-controls/TextWith1pxUnderline.png differ

diff --git a/docs/content/images/text-controls/TextWithBiggerShadow.png b/docs/content/images/text-controls/TextWithBiggerShadow.png
new file mode 100644 (file)
index 0000000..921f745
Binary files /dev/null and b/docs/content/images/text-controls/TextWithBiggerShadow.png differ

diff --git a/docs/content/images/text-controls/TextWithColorShadow.png b/docs/content/images/text-controls/TextWithColorShadow.png
new file mode 100644 (file)
index 0000000..a82635d
Binary files /dev/null and b/docs/content/images/text-controls/TextWithColorShadow.png differ

diff --git a/docs/content/images/text-controls/TextWithColorUnderline.png b/docs/content/images/text-controls/TextWithColorUnderline.png
new file mode 100644 (file)
index 0000000..42ec4ff
Binary files /dev/null and b/docs/content/images/text-controls/TextWithColorUnderline.png differ

diff --git a/docs/content/images/text-controls/TextWithShadow.png b/docs/content/images/text-controls/TextWithShadow.png
new file mode 100644 (file)
index 0000000..1cde8d2
Binary files /dev/null and b/docs/content/images/text-controls/TextWithShadow.png differ

diff --git a/docs/content/images/text-controls/TextWithUnderline.png b/docs/content/images/text-controls/TextWithUnderline.png
new file mode 100644 (file)
index 0000000..530920a
Binary files /dev/null and b/docs/content/images/text-controls/TextWithUnderline.png differ

diff --git a/docs/content/programming-guide/hello-world.h b/docs/content/programming-guide/hello-world.h
index 8031d99..2065659 100644 (file)
--- a/docs/content/programming-guide/hello-world.h
+++ b/docs/content/programming-guide/hello-world.h
@@ -12,56 +12,71 @@ Let's take a look at the code for this test application.
 
 <h2 class="pg"> Example code </h2>
 \code
 
 <h2 class="pg"> Example code </h2>
 \code

-#include <dali/dali.h>

 
 

-using namespace Dali;
+#include <dali-toolkit/dali-toolkit.h>

 
 

-/******************************************************
- * Demonstrates how to display "Hello World" on screen
- ******************************************************/
+using namespace Dali;
+using Dali::Toolkit::TextLabel;

 
 

-class ExampleApp
+// This example shows how to create and display Hello World! using a simple TextActor
+//
+class HelloWorldController : public ConnectionTracker

 {
 public:
 {
 public:

-  ExampleApp(Application &app)
-  : mApp(app)
+
+  HelloWorldController( Application& application )
+  : mApplication( application )

   {
   {

-    // Connect to Dali::Application init signal. Do not make calls to Dali before this signal is received.
-    app.SignalInit().Connect(this, &ExampleApp::Create);
+    // Connect to the Application's Init signal
+    mApplication.InitSignal().Connect( this, &HelloWorldController::Create );

   }
 
   }
 

-  ~ExampleApp()
+  ~HelloWorldController()

   {
   {

-    // Remove Hello World TextActor from stage
-    Stage::GetCurrent().Remove(mTextActor);
+    // Remove Hello World actor from stage
+    Stage::GetCurrent().Remove(mTextLabel);

   }
 
   }
 

-public:
-
-  void Create(Application& app)
+  // The Init signal is received once (only) during the Application lifetime
+  void Create( Application& application )

   {
   {

-    // Initialize the actor
-    mTextActor = TextActor::New("Hello World");
+    // Get a handle to the stage
+    Stage stage = Stage::GetCurrent();
+
+    mTextLabel = TextLabel::New( "Hello World" );
+    mTextLabel.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+    stage.Add( mTextLabel );

 
 

-    // Center the actor. Note: default anchor point is CENTER
-    mTextActor.SetParentOrigin(ParentOrigin::CENTER);
+    // Respond to a click anywhere on the stage
+    stage.GetRootLayer().TouchedSignal().Connect( this, &HelloWorldController::OnTouch );
+  }

 
 

-    // Display the actor on the stage
-    Stage::GetCurrent().Add(mTextActor);
+  bool OnTouch( Actor actor, const TouchEvent& touch )
+  {
+    // quit the application
+    mApplication.Quit();
+    return true;

   }
 
 private:
   }
 
 private:

-  Application& mApp;
-  TextActor mTextActor;
+  Application&  mApplication;
+  TextLabel mTextLabel;

 };
 
 };
 

-int
-main(int argc, char **argv)
+void RunTest( Application& application )
+{
+  HelloWorldController test( application );
+
+  application.MainLoop();
+}
+
+// Entry point for Linux & Tizen applications
+//
+int main( int argc, char **argv )

 {
 {

-  Application daliApp(&argc, &argv);
+  Application application = Application::New( &argc, &argv );

 
 

-  ExampleApp helloApp (daliApp);
-  daliApp.MainLoop();
+  RunTest( application );

 
   return 0;
 }
 
   return 0;
 }


@@ -85,10 +100,10 @@ main(int argc, char **argv)
  That's why we store the Actor's handle:
  \code
    ...
  That's why we store the Actor's handle:
  \code
    ...

-   mTextActor = TextActor::New("Hello World");
+   mTextLabel = TextLabel::New("Hello World");

    ...
  \endcode
    ...
  \endcode

- Even if the TextActor is removed from the stage, it will be kept alive through our reference.\n
+ Even if the TextLabel is removed from the stage, it will be kept alive through our reference.\n

  You can read more about implicit smart-pointer semantics in chapter \link handle-body-idiom Handle – body\endlink.
 
  <h2 class="pg"> Main loop </h2>
  You can read more about implicit smart-pointer semantics in chapter \link handle-body-idiom Handle – body\endlink.
 
  <h2 class="pg"> Main loop </h2>


@@ -107,6 +122,12 @@ main(int argc, char **argv)
 
  After running './hello' this should be visible on the screen:
 
 
  After running './hello' this should be visible on the screen:
 

- \image html Text-Actor.png "Hello world example"
+<table border=0 cellpadding=10>
+<tr>
+  <td>
+  \image html Text-Label.png "Hello world example"
+  </td>
+</tr>
+</table>

 
 */
 
 */

diff --git a/docs/content/programming-guide/properties.h b/docs/content/programming-guide/properties.h
index 8838e78..0a85d51 100644 (file)
--- a/docs/content/programming-guide/properties.h
+++ b/docs/content/programming-guide/properties.h
@@ -244,7 +244,7 @@ This is a basic example of a button defined in JSON by setting the default prope
         }
       },
       "label-actor": {
         }
       },
       "label-actor": {

-        "type": "TextView",
+        "type": "TextLabel",

         "text": "Normal"
       }
     }
         "text": "Normal"
       }
     }

diff --git a/docs/content/programming-guide/script-hello.h b/docs/content/programming-guide/script-hello.h
index 837e022..3bb5ece 100644 (file)
--- a/docs/content/programming-guide/script-hello.h
+++ b/docs/content/programming-guide/script-hello.h
@@ -6,19 +6,13 @@
  *
  * @code
  * {
  *
  * @code
  * {

- *     "fonts":
- *     {
- *         "freesans": {"name": "FreeSans", "point-size": 12.0, "weight": "WEIGHT_REGULAR" }
- *     },
- *     "actors":
- *     [
- *         {"name":"text-actor",
- *          "type":"Text",
- *          "text":"Hello World",
- *          "font":"freesans",
- *          "parent-origin":"CENTER"
- *         }
- *     ]
+ *  // a tree of actors
+ *  "stage": [{
+ *    "name": "text-label",
+ *    "type": "TextLabel",
+ *    "text": "Hello World",
+ *    "parent-origin": "CENTER"
+ *  }]

  * }
  * @endcode
  *
  * }
  * @endcode
  *


@@ -31,7 +25,7 @@
  *
  * builder.LoadFromString(json_data);
  *
  *
  * builder.LoadFromString(json_data);
  *

- * Actor actor = builder.GetActor("text-actor");
+ * Actor actor = builder.GetActor("text-label");

  *
  * Stage::GetCurrent().Add(actor);
  * @endcode
  *
  * Stage::GetCurrent().Add(actor);
  * @endcode


@@ -46,15 +40,15 @@
  * daliscript hello-world.js
  * @endcode
  *
  * daliscript hello-world.js
  * @endcode
  *

- * The TextActor control to display Hello World can be constructed using Javascript dot notation accessing Dali Actor Properties.
+ * The TextLabel control to display Hello World can be constructed using Javascript dot notation accessing Dali Actor Properties.

  *
  * @code
  *
  * @code

- * var textActor = Dali.TextActor();
+ * var textLabel = Dali.TextLabel();

  *
  *

- * textActor.text          = "Hello World";
- * textActor.font          = "FreeSans";
- * textActor.font-weight   = "WEIGHT_REGULAR";
- * textActor.parent-origin = "CENTER";
+ * textLabel.text          = "Hello World";
+ * textLabel.font-family   = "FreeSans";
+ * textLabel.font-style    = "Regular";
+ * textLabel.parent-origin = "CENTER";

  *
  * Dali.Run();
  * @endcode
  *
  * Dali.Run();
  * @endcode

diff --git a/docs/content/programming-guide/size-negotiation.h b/docs/content/programming-guide/size-negotiation.h
index 8259359..2f64d83 100644 (file)
--- a/docs/content/programming-guide/size-negotiation.h
+++ b/docs/content/programming-guide/size-negotiation.h
@@ -92,8 +92,7 @@ Dimension::WIDTH then there is a height-for-width dependency in effect. The clas
 is a text view that wraps its text. The following example snippet shows a text view that expands its width to the size of its parent, wraps its
 contents and then determines its height based on the width.
 @code
 is a text view that wraps its text. The following example snippet shows a text view that expands its width to the size of its parent, wraps its
 contents and then determines its height based on the width.
 @code

-TextView text = TextView::New( "Example" );
-text.SetMultilinePolicy( SplitByWord );
+TextLabel text = TextLabel::New( "Example" );

 text.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 text.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 @endcode
 text.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 text.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 @endcode


@@ -140,11 +139,7 @@ content.SetFitHeight( 1 );
 content.SetPadding( Padding( 20.0f, 20.0f, 20.0f, 0.0f ) );
 
 // Text
 content.SetPadding( Padding( 20.0f, 20.0f, 20.0f, 0.0f ) );
 
 // Text

-Toolkit::TextView text = Toolkit::TextView::New();
-text.SetText( "Do you really want to quit?" );
-text.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
-text.SetWidthExceedPolicy( Toolkit::TextView::Split );
-text.SetLineJustification( Toolkit::TextView::Left );
+Toolkit::TextLabel text = Toolkit::TextLabel::New( "Do you really want to quit?" );

 text.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 text.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 
 text.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 text.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 


@@ -174,9 +169,7 @@ checkBox.SetSize( Vector2( 48, 48 ) );
 
 root.AddChild( checkBox, Toolkit::TableView::CellPosition( 0, 0 ) );
 
 
 root.AddChild( checkBox, Toolkit::TableView::CellPosition( 0, 0 ) );
 

-Toolkit::TextView text2 = Toolkit::TextView::New();
-text2.SetText( "Don't show again" );
-text2.SetLineJustification( Toolkit::TextView::Left );
+Toolkit::TextLabel text2 = Toolkit::TextLabel::New( "Don't show again" );

 text2.SetPadding( Padding( 20.0f, 0.0f, 0.0f, 10.0f ) );
 
 root.AddChild( text2, Toolkit::TableView::CellPosition( 0, 1 ) );
 text2.SetPadding( Padding( 20.0f, 0.0f, 0.0f, 10.0f ) );
 
 root.AddChild( text2, Toolkit::TableView::CellPosition( 0, 1 ) );

diff --git a/docs/content/programming-guide/text-label.h b/docs/content/programming-guide/text-label.h
index 35754de..24f8b1b 100644 (file)
--- a/docs/content/programming-guide/text-label.h
+++ b/docs/content/programming-guide/text-label.h
@@ -11,39 +11,33 @@ To display a TextLabel the TEXT property must be set using a UTF-8 string.
 \code
 TextLabel label = TextLabel::New();
 label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
 \code
 TextLabel label = TextLabel::New();
 label.SetProperty( TextLabel::Property::TEXT, "Hello World" );

+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );

 Stage::GetCurrent().Add( label );
 \endcode
 
 The label must also be added to the stage, or to an actor which is on the stage.\n
 Stage::GetCurrent().Add( label );
 \endcode
 
 The label must also be added to the stage, or to an actor which is on the stage.\n

-In this example the text-label will be automatically given a natural size i.e. large enough to fit the text.\n
-The position of the label on-screen is dependent on the parent-origin and anchor-point properties:
+The position of the label on-screen is dependent on the parent-origin and anchor-point properties.\n

 
 <table border=0 cellpadding=10>
 <tr>
   <td>
   \image html TextLabelTopLeft.png
   </td>
 
 <table border=0 cellpadding=10>
 <tr>
   <td>
   \image html TextLabelTopLeft.png
   </td>

-  <td>
-  \image html TextLabelCenter.png
-  </td>

 </tr>
 <tr>
   <td>
   (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT)
   </td>
 </tr>
 <tr>
   <td>
   (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT)
   </td>

-  <td>
-  (ParentOrigin::CENTER, AnchorPoint::CENTER)
-  </td>

 </tr>
 </table>
 
 </tr>
 </table>
 

-\subsection fontselection Font Selection
+\subsection fontSelection Font Selection

 
 By default TextLabel will automatically select a suitable font from the platform.\n
 Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.\n
 Therefore you should expect TextLabel to select different fonts for each script.
 
 
 By default TextLabel will automatically select a suitable font from the platform.\n
 Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.\n
 Therefore you should expect TextLabel to select different fonts for each script.
 

-Alternatively a font may be requested using eiter or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
+Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:

 \code
 label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
 label.SetProperty( TextLabel::Property::FONT_STYLE,  "Regular" );
 \code
 label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
 label.SetProperty( TextLabel::Property::FONT_STYLE,  "Regular" );


@@ -51,16 +45,70 @@ label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
 \endcode
 However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
 
 \endcode
 However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
 

-\subsection fontselection Text Alignment
+\subsection fontStyles Font Styles
+
+Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.\n
+A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:\n
+
+\code
+StyleManager styleManager = StyleManager::Get();
+styleManager.RequestThemeChange( "example-path/example.json" );
+\endcode
+
+To change the font for standard text labels, this JSON syntax can be used:
+
+\code
+{
+  "styles":
+  {
+    "textlabel":
+    {
+      "font-family":"Arial",
+      "font-style":"Regular",
+      "point-size":8
+    }
+  }
+}
+\endcode
+
+However the same point-size is unlikely to be suitable for all labels in an application.\n
+To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
+
+\code
+  label.SetProperty( Control::Property::STYLE_NAME, "custom" );
+\endcode
+
+\code
+{
+  "styles":
+  {
+    "textlabel":
+    {
+      "font-family":"Arial",
+      "font-style":"Regular",
+      "point-size":8
+    },
+
+    "custom":
+    {
+      "point-size":10
+    }
+  }
+}
+\endcode
+
+In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.\n
+
+\subsection textAlignment Text Alignment

 
 Wrapping can be enabled using the MULTI_LINE property:\n
 \code
 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 \endcode
 
 
 Wrapping can be enabled using the MULTI_LINE property:\n
 \code
 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 \endcode
 

-The text can be either aligned to the start, end, or center of the available area:
+The text can be either aligned horizontally to the beginning, end, or center of the available area:

 \code
 \code

-label.SetProperty( TextLabel::Property::ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
+label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"

 \endcode
 
 <table border=0 cellpadding=10>
 \endcode
 
 <table border=0 cellpadding=10>


@@ -105,4 +153,191 @@ label.SetProperty( TextLabel::Property::ALIGNMENT, "BEGIN" ); // "CENTER" or "EN
 </tr>
 </table>
 
 </tr>
 </table>
 

+The examples above assume that the TextLabel size greater than the minimum required.\n
+The next section provides details about the other size related options.
+
+\subsection negotiatingSize Negotiating size
+
+\link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.\n
+There are several resize policies which are commonly used with TextLabels.\n
+The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:\n
+
+<h3>Using natural size</h3>
+
+With a "natural" size TextLabel will be large enough to display the text without wrapping, and will not have extra space to align the text within.\n
+Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.\n
+
+\code
+TextLabel label = TextLabel::New( "Hello World" );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
+label.SetBackgroundColor( Color::BLUE );
+Stage::GetCurrent().Add( label );
+\endcode
+
+<table border=0 cellpadding=10>
+<tr>
+  <td>
+  \image html HelloWorld-NaturalSize.png
+  </td>
+</tr>
+</table>
+
+<h3>Height-for-width negotiation</h3>
+
+To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.\n
+Each TextLabel will then report a desired height for the given width.\n
+Here is an example of this behavior using TableView as the parent:
+
+\code
+TableView parent = TableView::New( 3, 1 );
+parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
+parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
+parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+Stage::GetCurrent().Add( parent );
+
+TextLabel label = TextLabel::New( "Hello World" );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
+label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
+label.SetBackgroundColor( Color::BLUE );
+parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
+parent.SetFitHeight( 0 );
+
+label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
+label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
+label.SetBackgroundColor( Color::GREEN );
+label.SetProperty( TextLabel::Property::MULTI_LINE, true );
+parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
+parent.SetFitHeight( 1 );
+
+label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
+label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
+label.SetBackgroundColor( Color::BLUE );
+label.SetProperty( TextLabel::Property::MULTI_LINE, true );
+parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
+parent.SetFitHeight( 2 );
+\endcode
+
+<table border=0 cellpadding=10>
+<tr>
+  <td>
+  \image html HelloWorld-HeightForWidth.png
+  </td>
+</tr>
+</table>
+
+Note that the "Hello World" text label (above) has been given the full width, not the natural width.
+
+\subsection textLabelDecorations TextLabel Decorations
+
+<h3>Color</h3>
+
+To change the color of the text, the recommended way is to use the TEXT_COLOR property.\n
+Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.\n
+
+\code
+label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
+label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
+\endcode
+
+<table border=0 cellpadding=10>
+<tr>
+  <td>
+  \image html RedText.png
+  </td>
+</tr>
+</table>
+
+<h3>Drop Shadow</h3>
+
+To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.\n
+The color can also be selected using the SHADOW_COLOR property.\n
+
+\code
+stage.SetBackgroundColor( Color::BLUE );
+
+label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
+
+label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
+label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
+label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
+
+label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
+label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) );
+label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
+
+label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
+label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
+label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED );
+\endcode
+
+<table border=0 cellpadding=10>
+<tr>
+  <td>
+  \image html PlainText.png
+  </td>
+</tr>
+<tr>
+  <td>
+  \image html TextWithShadow.png
+  </td>
+</tr>
+<tr>
+  <td>
+  \image html TextWithBiggerShadow.png
+  </td>
+</tr>
+<tr>
+  <td>
+  \image html TextWithColorShadow.png
+  </td>
+</tr>
+</table>
+
+<h3>Underline</h3>
+
+The text can be underlined by setting UNDERLINE_ENABLED.\n
+The color can also be selected using the UNDERLINE_COLOR property.\n
+
+\code
+label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
+label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
+
+label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
+label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
+label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
+\endcode
+
+<table border=0 cellpadding=10>
+<tr>
+  <td>
+  \image html TextWithUnderline.png
+  </td>
+</tr>
+<tr>
+  <td>
+  \image html TextWithColorUnderline.png
+  </td>
+</tr>
+</table>
+
+By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
+
+\code
+label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
+\endcode
+
+<table border=0 cellpadding=10>
+<tr>
+  <td>
+  \image html TextWith1pxUnderline.png
+  </td>
+</tr>
+</table>
+

 */
 */