docs/content/shared-javascript-and-cpp-documentation/text-label.md

   1 <!--
   2 /**-->
   3
   4 # Text Label {#text-label}
   5
   6 ## Overview
   7
   8 The Dali::Toolkit::TextLabel is a Dali::Toolkit::Control which renders a short text string.
   9 Text labels are lightweight, non-editable and do not respond to user input.
  10
  11 ### Basic usage
  12
  13 To display a TextLabel the TEXT property must be set using a UTF-8 string.
  14
  15 ~~~{.cpp}
  16 // C++
  17
  18 TextLabel label = TextLabel::New();
  19 label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
  20 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
  21 Stage::GetCurrent().Add( label );
  22 ~~~
  23
  24 ~~~{.js}
  25 // JavaScript
  26
  27 var label = new dali.TextLabel();
  28
  29 label.text = "Hello World";
  30 label.anchorPoint = dali.TOP_LEFT;
  31
  32 dali.stage.add( label );
  33 ~~~
  34
  35 The label must also be added to the stage, or to an actor which is on the stage.
  36 The position of the label on-screen is dependent on the parent-origin and anchor-point properties.
  37
  38 |  |  |
  39 |--|--|
  40 | (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT) | ![ ](../assets/img/text-controls/TextLabelTopLeft.png) ![ ](TextLabelTopLeft.png)   |
  41
  42 ### Font Selection
  43
  44 By default TextLabel will automatically select a suitable font from the platform.
  45 Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.
  46 Therefore you should expect TextLabel to select different fonts for each script.
  47
  48 Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
  49
  50 ~~~{.cpp}
  51 // C++
  52
  53 label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
  54 label.SetProperty( TextLabel::Property::FONT_STYLE,  "Regular" );
  55 label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
  56 ~~~
  57
  58 ~~~{.js}
  59 // JavaScript
  60
  61 label.fontFamily = "HelveticaNue";
  62 label.fontStyle = "Regular";
  63 label.pointSize = 12;
  64 ~~~
  65
  66 However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
  67
  68 ### Font Styles
  69
  70 Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.
  71 A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:
  72
  73 ~~~{.cpp}
  74 // C++
  75 StyleManager styleManager = StyleManager::Get();
  76 styleManager.RequestThemeChange( "example-path/example.json" );
  77 ~~~
  78
  79 To change the font for standard text labels, this JSON syntax can be used:
  80
  81 ~~~{.json}
  82 {
  83   "styles":
  84   {
  85     "textlabel":
  86     {
  87       "font-family":"Arial",
  88       "font-style":"Regular",
  89       "point-size":8
  90     }
  91   }
  92 }
  93 ~~~
  94
  95 However the same point-size is unlikely to be suitable for all labels in an application.
  96 To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
  97
  98 ~~~{.cpp}
  99   // C++
 100
 101   label.SetProperty( Control::Property::STYLE_NAME, "custom" );
 102 ~~~
 103 ~~~{.js}
 104   // JavaScript
 105
 106   label.styleName = "custom"';
 107 ~~~
 108
 109 ~~~{.json}
 110 {
 111   "styles":
 112   {
 113     "textlabel":
 114     {
 115       "font-family":"Arial",
 116       "font-style":"Regular",
 117       "point-size":8
 118     },
 119
 120     "custom":
 121     {
 122       "point-size":10
 123     }
 124   }
 125 }
 126 ~~~
 127
 128 In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.
 129
 130 ### Text Alignment
 131
 132 Wrapping can be enabled using the MULTI_LINE property:
 133
 134 ~~~{.cpp}
 135 // C++
 136
 137 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 138 ~~~
 139
 140 ~~~{.js}
 141 // JavaScript
 142
 143 label.mutliLine = true;
 144 ~~~
 145
 146 The text can be either aligned horizontally to the beginning, end, or center of the available area:
 147
 148 ~~~{.cpp}
 149 // C++
 150
 151 label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
 152 ~~~
 153
 154 ~~~{.js}
 155 // JavaScript
 156
 157 label.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
 158 ~~~
 159
 160 |  |  |
 161 |--|--|
 162 | Here is the "BEGIN" alignment shown for left-to-right (Latin)   |  right-to-left (Arabic) scripts |
 163 | ![ ](../assets/img/text-controls/LatinBegin.png) ![ ](LatinBegin.png) | ![ ](../assets/img/text-controls/ArabicBegin.png) ![ ](ArabicBegin.png) |
 164 | Here is the "CENTER" alignment shown for left-to-right (Latin)  | right-to-left (Arabic) scripts:|
 165 | ![ ](../assets/img/text-controls/LatinCenter.png) ![ ](LatinCenter.png) | ![ ](../assets/img/text-controls/ArabicCenter.png) ![ ](ArabicCenter.png) |
 166 | Here is the "END" alignment shown for left-to-right (Latin)  | right-to-left (Arabic) scripts:|
 167 | ![ ](../assets/img/text-controls/LatinEnd.png) ![ ](LatinEnd.png) | ![ ](../assets/img/text-controls/ArabicEnd.png) ![ ](ArabicEnd.png) |
 168
 169
 170 The examples above assume that the TextLabel size greater than the minimum required.
 171 The next section provides details about the other size related options.
 172
 173 ## Negotiating size
 174
 175 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
 176
 177 There are several resize policies which are commonly used with TextLabels.
 178
 179 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:
 180
 181 ### Using natural size
 182
 183 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.
 184 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.
 185
 186 ~~~{.cpp}
 187 // C++
 188
 189 TextLabel label = TextLabel::New( "Hello World" );
 190 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 191 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
 192 label.SetBackgroundColor( Color::BLUE );
 193 Stage::GetCurrent().Add( label );
 194 ~~~
 195
 196 ~~~{.js}
 197 // JavaScript
 198
 199 var label = new dali.Textlabel;
 200 label.text = "Hello World";
 201 label.anchorPoint = dali.TOP_LEFT;
 202
 203 label.widthResizePolicy = "USE_NATURAL_SIZE";
 204 label.heightResizePolicy = "USE_NATURAL_SIZE";
 205
 206 label.textColor = dali.COLOR_WHITE;
 207 // background color not available as it's currently not a property of control
 208 dali.stage.add( label );
 209 ~~~
 210
 211
 212  ![ ](../assets/img/text-controls/HelloWorld-NaturalSize.png)
 213  ![ ](HelloWorld-NaturalSize.png)
 214
 215
 216 ### Height-for-width negotiation
 217
 218 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.
 219 Each TextLabel will then report a desired height for the given width.
 220 Here is an example of this behavior using TableView as the parent:
 221
 222 ~~~{.cpp}
 223 // C++
 224 TableView parent = TableView::New( 3, 1 );
 225 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 226 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
 227 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 228 Stage::GetCurrent().Add( parent );
 229
 230 TextLabel label = TextLabel::New( "Hello World" );
 231 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 232 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 233 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 234 label.SetBackgroundColor( Color::BLUE );
 235 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
 236 parent.SetFitHeight( 0 );
 237
 238 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
 239 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 240 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 241 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 242 label.SetBackgroundColor( Color::GREEN );
 243 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 244 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
 245 parent.SetFitHeight( 1 );
 246
 247 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
 248 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 249 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 250 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 251 label.SetBackgroundColor( Color::BLUE );
 252 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 253 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
 254 parent.SetFitHeight( 2 );
 255 ~~~
 256
 257  ![ ](../assets/img/text-controls/HelloWorld-HeightForWidth.png)
 258  ![ ](HelloWorld-HeightForWidth.png)
 259
 260
 261 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
 262
 263 ### TextLabel Decorations
 264
 265 #### Color
 266
 267 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
 268 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.
 269
 270 ~~~{.cpp}
 271 // C++
 272 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
 273 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
 274 ~~~
 275
 276 ~~~{.js}
 277 // JavaScript
 278
 279 label.text = "Red Text";
 280 label.textColor = dali.COLOR_RED;
 281 ~~~
 282
 283  ![ ](../assets/img/text-controls/RedText.png)
 284  ![ ](RedText.png)
 285
 286 #### Drop Shadow
 287
 288 To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.
 289 The color can also be selected using the SHADOW_COLOR property.
 290
 291 ~~~{.cpp}
 292  // C++
 293
 294 stage.SetBackgroundColor( Color::BLUE );
 295
 296 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
 297
 298 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
 299 label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
 300 label2.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
 301
 302 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
 303 label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) );
 304 label3.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
 305
 306 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
 307 label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
 308 label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED );
 309 ~~~
 310
 311 ~~~{.js}
 312 // JavaScript
 313
 314 dali.stage.setBackgroundColor( dali.COLOR_BLUE );
 315
 316 label1.text = "Plain Text";
 317
 318
 319 label2.text = "Text with Shadow";
 320 label2.shadowOffset = [1, 1];
 321 label2.shadowColor = dali.COLOR_BLACK;
 322
 323 label3.text = "Text with Bigger Shadow";
 324 label3.shadowOffset = [2, 2];
 325 label3.shadowColor = dali.COLOR_BLACK;
 326
 327 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
 328 label3.shadowOffset = [1, 1];
 329 label3.shadowColor = dali.COLOR_RED;
 330 ~~~
 331
 332
 333 ![ ](../assets/img/text-controls/PlainText.png)
 334 ![ ](PlainText.png)
 335
 336
 337 ![ ](../assets/img/text-controls/TextWithShadow.png)
 338 ![ ](TextWithShadow.png)
 339
 340 ![ ](../assets/img/text-controls/TextWithBiggerShadow.png)
 341 ![ ](TextWithBiggerShadow.png)
 342
 343
 344 ![ ](../assets/img/text-controls/TextWithColorShadow.png)
 345 ![ ](TextWithColorShadow.png)
 346
 347
 348 #### Underline
 349
 350 The text can be underlined by setting UNDERLINE_ENABLED.
 351 The color can also be selected using the UNDERLINE_COLOR property.
 352
 353 ~~~{.cpp}
 354 // C++
 355 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
 356 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 357
 358 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
 359 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 360 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
 361 ~~~
 362 ~~~{.js}
 363 // JavaScript
 364 label1.Text = "Text with Underline";
 365 label1.underlineEnabled = true;
 366
 367 label2.Text = "Text with Color Underline";
 368 label2.underlineEnabled = true;
 369 label2.underlineColor = dali.COLOR_GREEN;
 370 ~~~
 371
 372
 373 ![ ](../assets/img/text-controls/TextWithUnderline.png)
 374 ![ ](TextWithUnderline.png)
 375
 376
 377 ![ ](../assets/img/text-controls/TextWithColorUnderline.png)
 378 ![ ](TextWithColorUnderline.png)
 379
 380 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
 381
 382 ~~~{.cpp}
 383 // C++
 384
 385 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
 386 ~~~
 387
 388 ~~~{.js}
 389 // JavaScript
 390
 391 label1.underlineHeight = 1;
 392 ~~~
 393
 394 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
 395 ![ ](TextWith1pxUnderline.png)
 396
 397 ### Text Label Properties
 398
 399  Name (JavaScript)   |  Name (C++)         |  Type        | Writable     | Animatable
 400 ---------------------|---------------------|--------------|--------------|-----------
 401  renderingBackend    | RENDERING_BACKEND   |  INTEGER     | O            | X
 402  text                | TEXT                |  STRING      | O            | X
 403  fontFamily          | FONT_FAMILY         |  STRING      | O            | X
 404  fontStyle           | FONT_STYLE          |  STRING      | O            | X
 405  pointSize           | POINT_SIZE          |  FLOAT       | O            | X
 406  multiLine           | MULTI_LINE          |  BOOLEAN     | O            | X
 407  horizontalAlignment | HORIZONTAL_ALIGNMENT|  STRING      | O            | X
 408  verticalAlignment   | VERTICAL_ALIGNMENT  |  STRING      | O            | X
 409  textColor           | TEXT_COLOR          |  VECTOR4     | O            | X
 410  shadowOffset        | SHADOW_OFFSET       |  VECTOR2     | O            | X
 411  shadowColor         | SHADOW_COLOR        |  VECTOR4     | O            | X
 412  underlineEnabled    | UNDERLINE_ENABLED   |  BOOLEAN     | O            | X
 413  underlineColor      | UNDERLINE_COLOR     |  VECTOR4     | O            | X
 414  underlineHeight     | UNDERLINE_HEIGHT    |  FLOAT       | O            | X
 415
 416
 417
 418 @class TextLabel
 419
 420 */