docs/content/programming-guide/text-label.h

   1 /*! \page text-label Text Label
   2  *
   3 \section overview Overview
   4 The Dali::Toolkit::TextLabel is a Dali::Toolkit::Control which renders a short text string.\n
   5 Text labels are lightweight, non-editable and do not respond to user input.
   6
   7 \subsection basictextlabelusage Basic usage
   8
   9 To display a TextLabel the TEXT property must be set using a UTF-8 string.
  10
  11 \code
  12 TextLabel label = TextLabel::New();
  13 label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
  14 Stage::GetCurrent().Add( label );
  15 \endcode
  16
  17 The label must also be added to the stage, or to an actor which is on the stage.\n
  18 In this example the text-label will be automatically given a natural size i.e. large enough to fit the text.\n
  19 The position of the label on-screen is dependent on the parent-origin and anchor-point properties:
  20
  21 <table border=0 cellpadding=10>
  22 <tr>
  23   <td>
  24   \image html TextLabelTopLeft.png
  25   </td>
  26   <td>
  27   \image html TextLabelCenter.png
  28   </td>
  29 </tr>
  30 <tr>
  31   <td>
  32   (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT)
  33   </td>
  34   <td>
  35   (ParentOrigin::CENTER, AnchorPoint::CENTER)
  36   </td>
  37 </tr>
  38 </table>
  39
  40 \subsection fontselection Font Selection
  41
  42 By default TextLabel will automatically select a suitable font from the platform.\n
  43 Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.\n
  44 Therefore you should expect TextLabel to select different fonts for each script.
  45
  46 Alternatively a font may be requested using eiter or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
  47 \code
  48 label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
  49 label.SetProperty( TextLabel::Property::FONT_STYLE,  "Regular" );
  50 label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
  51 \endcode
  52 However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
  53
  54 \subsection fontselection Text Alignment
  55
  56 Wrapping can be enabled using the MULTI_LINE property:\n
  57 \code
  58 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
  59 \endcode
  60
  61 The text can be either aligned to the start, end, or center of the available area:
  62 \code
  63 label.SetProperty( TextLabel::Property::ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  64 \endcode
  65
  66 <table border=0 cellpadding=10>
  67 <tr>
  68   <td>
  69   Here is the "BEGIN" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
  70   </td>
  71 </tr>
  72 <tr>
  73   <td>
  74   \image html LatinBegin.png
  75   </td>
  76   <td>
  77   \image html ArabicBegin.png
  78   </td>
  79 </tr>
  80 <tr>
  81   <td>
  82   Here is the "CENTER" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
  83   </td>
  84 </tr>
  85 <tr>
  86   <td>
  87   \image html LatinCenter.png
  88   </td>
  89   <td>
  90   \image html ArabicCenter.png
  91   </td>
  92 </tr>
  93 <tr>
  94   <td>
  95   Here is the "END" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
  96   </td>
  97 </tr>
  98 <tr>
  99   <td>
 100   \image html LatinEnd.png
 101   </td>
 102   <td>
 103   \image html ArabicEnd.png
 104   </td>
 105 </tr>
 106 </table>
 107
 108 */