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 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
  15 Stage::GetCurrent().Add( label );
  16 \endcode
  17
  18 The label must also be added to the stage, or to an actor which is on the stage.\n
  19 The position of the label on-screen is dependent on the parent-origin and anchor-point properties.\n
  20
  21 <table border=0 cellpadding=10>
  22 <tr>
  23   <td>
  24   \image html TextLabelTopLeft.png
  25   </td>
  26 </tr>
  27 <tr>
  28   <td>
  29   (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT)
  30   </td>
  31 </tr>
  32 </table>
  33
  34 \subsection fontSelection Font Selection
  35
  36 By default TextLabel will automatically select a suitable font from the platform.\n
  37 Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.\n
  38 Therefore you should expect TextLabel to select different fonts for each script.
  39
  40 Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
  41 \code
  42 label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
  43 label.SetProperty( TextLabel::Property::FONT_STYLE,  "Regular" );
  44 label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
  45 \endcode
  46 However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
  47
  48 \subsection fontStyles Font Styles
  49
  50 Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.\n
  51 A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:\n
  52
  53 \code
  54 StyleManager styleManager = StyleManager::Get();
  55 styleManager.RequestThemeChange( "example-path/example.json" );
  56 \endcode
  57
  58 To change the font for standard text labels, this JSON syntax can be used:
  59
  60 \code
  61 {
  62   "styles":
  63   {
  64     "textlabel":
  65     {
  66       "font-family":"Arial",
  67       "font-style":"Regular",
  68       "point-size":8
  69     }
  70   }
  71 }
  72 \endcode
  73
  74 However the same point-size is unlikely to be suitable for all labels in an application.\n
  75 To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
  76
  77 \code
  78   label.SetProperty( Control::Property::STYLE_NAME, "custom" );
  79 \endcode
  80
  81 \code
  82 {
  83   "styles":
  84   {
  85     "textlabel":
  86     {
  87       "font-family":"Arial",
  88       "font-style":"Regular",
  89       "point-size":8
  90     },
  91
  92     "custom":
  93     {
  94       "point-size":10
  95     }
  96   }
  97 }
  98 \endcode
  99
 100 In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.\n
 101
 102 \subsection textAlignment Text Alignment
 103
 104 Wrapping can be enabled using the MULTI_LINE property:\n
 105 \code
 106 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 107 \endcode
 108
 109 The text can be either aligned horizontally to the beginning, end, or center of the available area:
 110 \code
 111 label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
 112 \endcode
 113
 114 <table border=0 cellpadding=10>
 115 <tr>
 116   <td>
 117   Here is the "BEGIN" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
 118   </td>
 119 </tr>
 120 <tr>
 121   <td>
 122   \image html LatinBegin.png
 123   </td>
 124   <td>
 125   \image html ArabicBegin.png
 126   </td>
 127 </tr>
 128 <tr>
 129   <td>
 130   Here is the "CENTER" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
 131   </td>
 132 </tr>
 133 <tr>
 134   <td>
 135   \image html LatinCenter.png
 136   </td>
 137   <td>
 138   \image html ArabicCenter.png
 139   </td>
 140 </tr>
 141 <tr>
 142   <td>
 143   Here is the "END" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
 144   </td>
 145 </tr>
 146 <tr>
 147   <td>
 148   \image html LatinEnd.png
 149   </td>
 150   <td>
 151   \image html ArabicEnd.png
 152   </td>
 153 </tr>
 154 </table>
 155
 156 The examples above assume that the TextLabel size greater than the minimum required.\n
 157 The next section provides details about the other size related options.
 158
 159 \subsection negotiatingSize Negotiating size
 160
 161 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.\n
 162 There are several resize policies which are commonly used with TextLabels.\n
 163 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:\n
 164
 165 <h3>Using natural size</h3>
 166
 167 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
 168 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.\n
 169
 170 \code
 171 TextLabel label = TextLabel::New( "Hello World" );
 172 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 173 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
 174 label.SetBackgroundColor( Color::BLUE );
 175 Stage::GetCurrent().Add( label );
 176 \endcode
 177
 178 <table border=0 cellpadding=10>
 179 <tr>
 180   <td>
 181   \image html HelloWorld-NaturalSize.png
 182   </td>
 183 </tr>
 184 </table>
 185
 186 <h3>Height-for-width negotiation</h3>
 187
 188 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.\n
 189 Each TextLabel will then report a desired height for the given width.\n
 190 Here is an example of this behavior using TableView as the parent:
 191
 192 \code
 193 TableView parent = TableView::New( 3, 1 );
 194 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 195 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
 196 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 197 Stage::GetCurrent().Add( parent );
 198
 199 TextLabel label = TextLabel::New( "Hello World" );
 200 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 201 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 202 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 203 label.SetBackgroundColor( Color::BLUE );
 204 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
 205 parent.SetFitHeight( 0 );
 206
 207 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
 208 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 209 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 210 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 211 label.SetBackgroundColor( Color::GREEN );
 212 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 213 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
 214 parent.SetFitHeight( 1 );
 215
 216 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
 217 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 218 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 219 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 220 label.SetBackgroundColor( Color::BLUE );
 221 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 222 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
 223 parent.SetFitHeight( 2 );
 224 \endcode
 225
 226 <table border=0 cellpadding=10>
 227 <tr>
 228   <td>
 229   \image html HelloWorld-HeightForWidth.png
 230   </td>
 231 </tr>
 232 </table>
 233
 234 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
 235
 236 \subsection textLabelDecorations TextLabel Decorations
 237
 238 <h3>Color</h3>
 239
 240 To change the color of the text, the recommended way is to use the TEXT_COLOR property.\n
 241 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.\n
 242
 243 \code
 244 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
 245 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
 246 \endcode
 247
 248 <table border=0 cellpadding=10>
 249 <tr>
 250   <td>
 251   \image html RedText.png
 252   </td>
 253 </tr>
 254 </table>
 255
 256 <h3>Drop Shadow</h3>
 257
 258 To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.\n
 259 The color can also be selected using the SHADOW_COLOR property.\n
 260
 261 \code
 262 stage.SetBackgroundColor( Color::BLUE );
 263
 264 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
 265
 266 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
 267 label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
 268 label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
 269
 270 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
 271 label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) );
 272 label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
 273
 274 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
 275 label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
 276 label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED );
 277 \endcode
 278
 279 <table border=0 cellpadding=10>
 280 <tr>
 281   <td>
 282   \image html PlainText.png
 283   </td>
 284 </tr>
 285 <tr>
 286   <td>
 287   \image html TextWithShadow.png
 288   </td>
 289 </tr>
 290 <tr>
 291   <td>
 292   \image html TextWithBiggerShadow.png
 293   </td>
 294 </tr>
 295 <tr>
 296   <td>
 297   \image html TextWithColorShadow.png
 298   </td>
 299 </tr>
 300 </table>
 301
 302 <h3>Underline</h3>
 303
 304 The text can be underlined by setting UNDERLINE_ENABLED.\n
 305 The color can also be selected using the UNDERLINE_COLOR property.\n
 306
 307 \code
 308 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
 309 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 310
 311 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
 312 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 313 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
 314 \endcode
 315
 316 <table border=0 cellpadding=10>
 317 <tr>
 318   <td>
 319   \image html TextWithUnderline.png
 320   </td>
 321 </tr>
 322 <tr>
 323   <td>
 324   \image html TextWithColorUnderline.png
 325   </td>
 326 </tr>
 327 </table>
 328
 329 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
 330
 331 \code
 332 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
 333 \endcode
 334
 335 <table border=0 cellpadding=10>
 336 <tr>
 337   <td>
 338   \image html TextWith1pxUnderline.png
 339   </td>
 340 </tr>
 341 </table>
 342
 343 */