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 Note *CR+LF* new line characters are replaced by a *LF* one.
  16
  17 ~~~{.cpp}
  18 // C++
  19
  20 TextLabel label = TextLabel::New();
  21 label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
  22 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
  23 Stage::GetCurrent().Add( label );
  24 ~~~
  25
  26 ~~~{.js}
  27 // JavaScript
  28
  29 var label = new dali.TextLabel();
  30
  31 label.text = "Hello World";
  32 label.anchorPoint = dali.TOP_LEFT;
  33
  34 dali.stage.add( label );
  35 ~~~
  36
  37 The label must also be added to the stage, or to an actor which is on the stage.
  38 The position of the label on-screen is dependent on the parentOrigin and anchorPoint properties.
  39
  40 |  |  |
  41 |--|--|
  42 | (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT) | ![ ](../assets/img/text-controls/TextLabelTopLeft.png) ![ ](TextLabelTopLeft.png)   |
  43
  44 ### Font Selection
  45
  46 By default TextLabel will automatically select a suitable font from the platform. However, a different font could be selected. See the [Font Selection](@ref font-selection) section for more details.
  47
  48 ### Mark-up Style
  49
  50 Mark-up tags can be used to change the style of the text. See the [Mark-up Style](@ref markup-style) section for more details.
  51
  52 ### Text Alignment
  53
  54 Wrapping can be enabled using the MULTI_LINE property:
  55
  56 ~~~{.cpp}
  57 // C++
  58
  59 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
  60 ~~~
  61
  62 ~~~{.js}
  63 // JavaScript
  64
  65 label.mutliLine = true;
  66 ~~~
  67
  68 The text can be either aligned horizontally to the beginning, end, or center of the available area:
  69
  70 ~~~{.cpp}
  71 // C++
  72
  73 label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  74 ~~~
  75
  76 ~~~{.js}
  77 // JavaScript
  78
  79 label.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
  80 ~~~
  81
  82 |  |  |
  83 |--|--|
  84 | Here is the "BEGIN" alignment shown for left-to-right (Latin)   |  right-to-left (Arabic) scripts |
  85 | ![ ](../assets/img/text-controls/LatinBegin.png) ![ ](LatinBegin.png) | ![ ](../assets/img/text-controls/ArabicBegin.png) ![ ](ArabicBegin.png) |
  86 | Here is the "CENTER" alignment shown for left-to-right (Latin)  | right-to-left (Arabic) scripts:|
  87 | ![ ](../assets/img/text-controls/LatinCenter.png) ![ ](LatinCenter.png) | ![ ](../assets/img/text-controls/ArabicCenter.png) ![ ](ArabicCenter.png) |
  88 | Here is the "END" alignment shown for left-to-right (Latin)  | right-to-left (Arabic) scripts:|
  89 | ![ ](../assets/img/text-controls/LatinEnd.png) ![ ](LatinEnd.png) | ![ ](../assets/img/text-controls/ArabicEnd.png) ![ ](ArabicEnd.png) |
  90
  91
  92
  93 The text's alignment and order can be modified to match the direction of the system language.
  94
  95 If the MATCH_SYSTEM_LANGUAGE_DIRECTION property is set to true then the direction of the text is ignored, instead the text is aligned and ordered as the system default language.
  96
  97 ~~~{.cpp}
  98 // C++
  99
 100 label.SetProperty( Toolkit::DevelTextLabel::Property::MATCH_SYSTEM_LANGUAGE_DIRECTION, true );
 101 ~~~
 102
 103 ~~~{.js}
 104 // JavaScript
 105
 106 label.matchSystemLanguageDirection = true;
 107 ~~~
 108
 109 |  |  |
 110 |--|--|
 111 | Current system language direction left-to-right | |
 112 | MATCH_SYSTEM_LANGUAGE_DIRECTION set to TRUE. | MATCH_SYSTEM_LANGUAGE_DIRECTION set to FALSE (default). |
 113 | BEGIN alignment | BEGIN alignment  |
 114 | ![ ](../assets/img/text-controls/HelloWorld-System-BEGIN.png) ![ ](HelloWorld-System-BEGIN.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-BEGIN.png) ![ ](HelloWorld-Default-BEGIN.png) |
 115 | CENTER alignment | CENTER alignment  |
 116 | ![ ](../assets/img/text-controls/HelloWorld-System-CENTER.png) ![ ](HelloWorld-System-CENTER.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-CENTER.png) ![ ](HelloWorld-Default-CENTER.png) |
 117 | END alignment | END alignment  |
 118 | ![ ](../assets/img/text-controls/HelloWorld-System-END.png) ![ ](HelloWorld-System-END.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-END.png) ![ ](HelloWorld-Default-END.png) |
 119
 120
 121 |  |  |
 122 |--|--|
 123 | Current system language direction left-to-right | Current system language direction right-to-left |
 124 | ![ ](../assets/img/text-controls/LTR_order.png) ![ ](LTR_order.png)  | ![ ](../assets/img/text-controls/RTL_order.png) ![ ](RTL_order.png) |
 125
 126
 127 The examples above assume that the TextLabel size greater than the minimum required.
 128 The next section provides details about the other size related options.
 129
 130 ## Negotiating size
 131
 132 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
 133
 134 There are several resize policies which are commonly used with TextLabels.
 135
 136 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:
 137
 138 ### Using natural size
 139
 140 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.
 141 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.
 142
 143 ~~~{.cpp}
 144 // C++
 145
 146 TextLabel label = TextLabel::New( "Hello World" );
 147 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 148 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
 149 label.SetBackgroundColor( Color::BLUE );
 150 Stage::GetCurrent().Add( label );
 151 ~~~
 152
 153 ~~~{.js}
 154 // JavaScript
 155
 156 var label = new dali.Textlabel;
 157 label.text = "Hello World";
 158 label.anchorPoint = dali.TOP_LEFT;
 159
 160 label.widthResizePolicy = "USE_NATURAL_SIZE";
 161 label.heightResizePolicy = "USE_NATURAL_SIZE";
 162
 163 label.textColor = dali.COLOR_WHITE;
 164 // background color not available as it's currently not a property of control
 165 dali.stage.add( label );
 166 ~~~
 167
 168
 169  ![ ](../assets/img/text-controls/HelloWorld-NaturalSize.png)
 170  ![ ](HelloWorld-NaturalSize.png)
 171
 172
 173 ### Height-for-width negotiation
 174
 175 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.
 176 Each TextLabel will then report a desired height for the given width.
 177 Here is an example of this behavior using TableView as the parent:
 178
 179 ~~~{.cpp}
 180 // C++
 181 TableView parent = TableView::New( 3, 1 );
 182 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 183 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
 184 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 185 Stage::GetCurrent().Add( parent );
 186
 187 TextLabel label = TextLabel::New( "Hello World" );
 188 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 189 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 190 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 191 label.SetBackgroundColor( Color::BLUE );
 192 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
 193 parent.SetFitHeight( 0 );
 194
 195 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
 196 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 197 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 198 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 199 label.SetBackgroundColor( Color::GREEN );
 200 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 201 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
 202 parent.SetFitHeight( 1 );
 203
 204 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
 205 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 206 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 207 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 208 label.SetBackgroundColor( Color::BLUE );
 209 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 210 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
 211 parent.SetFitHeight( 2 );
 212 ~~~
 213
 214  ![ ](../assets/img/text-controls/HelloWorld-HeightForWidth.png)
 215  ![ ](HelloWorld-HeightForWidth.png)
 216
 217
 218 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
 219
 220 ### TextLabel Decorations
 221
 222 #### Color
 223
 224 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
 225 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.
 226
 227 ~~~{.cpp}
 228 // C++
 229 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
 230 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
 231 ~~~
 232
 233 ~~~{.js}
 234 // JavaScript
 235
 236 label.text = "Red Text";
 237 label.textColor = dali.COLOR_RED;
 238 ~~~
 239
 240  ![ ](../assets/img/text-controls/RedText.png)
 241  ![ ](RedText.png)
 242
 243 #### Drop Shadow
 244
 245 To add a drop-shadow to the text, simply set the SHADOW property. Shadow parameters can be set through a json string or through a property map, see the examples below.
 246
 247 ~~~{.cpp}
 248  // C++
 249
 250 stage.SetBackgroundColor( Color::BLUE );
 251
 252 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
 253
 254 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
 255 label2.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"black\"}" );
 256
 257 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
 258 label3.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"2 2\",\"color\":\"black\"}" );
 259
 260 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
 261
 262 Property::Map shadow;
 263 shadow.Insert( "offset", Vector2(1.0f, 1.0f) );
 264 shadow.Insert( "color", Color::RED );
 265 shadow.Insert( "blurRadius", 2.0f ); // A value of 0 indicates no blur. The bigger the radius, the more blurry.
 266 label4.SetProperty( TextLabel::Property::SHADOW, shadow );
 267
 268 ~~~
 269
 270 ~~~{.js}
 271 // JavaScript
 272
 273 dali.stage.setBackgroundColor( dali.COLOR_BLUE );
 274
 275 label1.text = "Plain Text";
 276
 277
 278 label2.text = "Text with Shadow";
 279 label2.shadow = "{\"offset\":\"1 1\",\"color\":\"black\"}";
 280
 281 label3.text = "Text with Bigger Shadow";
 282 label3.shadow = "{\"offset\":\"2 2\",\"color\":\"black\"}";
 283
 284 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
 285 var shadow = {
 286     "offset" : [ 1.0, 1.0 ],
 287     "color" : dali.COLOR_RED;
 288     "blurRadius" : 2.0
 289 };
 290 label4.shadow = shadow;
 291
 292 ~~~
 293
 294
 295 ![ ](../assets/img/text-controls/PlainText.png)
 296 ![ ](PlainText.png)
 297
 298
 299 ![ ](../assets/img/text-controls/TextWithShadow.png)
 300 ![ ](TextWithShadow.png)
 301
 302 ![ ](../assets/img/text-controls/TextWithBiggerShadow.png)
 303 ![ ](TextWithBiggerShadow.png)
 304
 305
 306 ![ ](../assets/img/text-controls/TextWithColorShadow.png)
 307 ![ ](TextWithColorShadow.png)
 308
 309
 310 #### Underline
 311
 312 The text can be underlined by setting UNDERLINE_ENABLED.
 313 The color can also be selected using the UNDERLINE_COLOR property.
 314
 315 ~~~{.cpp}
 316 // C++
 317 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
 318 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 319
 320 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
 321 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 322 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
 323 ~~~
 324 ~~~{.js}
 325 // JavaScript
 326 label1.Text = "Text with Underline";
 327 label1.underlineEnabled = true;
 328
 329 label2.Text = "Text with Color Underline";
 330 label2.underlineEnabled = true;
 331 label2.underlineColor = dali.COLOR_GREEN;
 332 ~~~
 333
 334
 335 ![ ](../assets/img/text-controls/TextWithUnderline.png)
 336 ![ ](TextWithUnderline.png)
 337
 338
 339 ![ ](../assets/img/text-controls/TextWithColorUnderline.png)
 340 ![ ](TextWithColorUnderline.png)
 341
 342 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
 343
 344 ~~~{.cpp}
 345 // C++
 346
 347 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
 348 ~~~
 349
 350 ~~~{.js}
 351 // JavaScript
 352
 353 label1.underlineHeight = 1;
 354 ~~~
 355
 356 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
 357 ![ ](TextWith1pxUnderline.png)
 358
 359 ### Auto Scrolling
 360
 361 ![ ](../assets/img/text-controls/AutoScroll.gif)
 362 ![ ](AutoScroll.gif)
 363
 364 The \link text-auto-scrolling Auto text scrolling \endlink section details how to scroll text automatically.
 365
 366 ### Text Label Properties
 367
 368 The properties used by TextLabel are listed [here](@ref TextLabelProperties)
 369
 370 @class TextLabel
 371
 372 */