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 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 as the system default language.
  96
  97 ~~~{.cpp}
  98 // C++
  99
 100 label.SetProperty( TextLabel::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 | END alignment and MATCH_SYSTEM_LANGUAGE_DIRECTION set to TRUE. | END alignment and MATCH_SYSTEM_LANGUAGE_DIRECTION set to FALSE (default). |
 113 | ![ ](HelloWorld-System-END.png) | ![ ](HelloWorld-Default-END.png) |
 114
 115
 116 The examples above assume that the TextLabel size greater than the minimum required.
 117 The next section provides details about the other size related options.
 118
 119 ## Negotiating size
 120
 121 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
 122
 123 There are several resize policies which are commonly used with TextLabels.
 124
 125 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:
 126
 127 ### Using natural size
 128
 129 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.
 130 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.
 131
 132 ~~~{.cpp}
 133 // C++
 134
 135 TextLabel label = TextLabel::New( "Hello World" );
 136 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 137 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
 138 label.SetBackgroundColor( Color::BLUE );
 139 Stage::GetCurrent().Add( label );
 140 ~~~
 141
 142 ~~~{.js}
 143 // JavaScript
 144
 145 var label = new dali.Textlabel;
 146 label.text = "Hello World";
 147 label.anchorPoint = dali.TOP_LEFT;
 148
 149 label.widthResizePolicy = "USE_NATURAL_SIZE";
 150 label.heightResizePolicy = "USE_NATURAL_SIZE";
 151
 152 label.textColor = dali.COLOR_WHITE;
 153 // background color not available as it's currently not a property of control
 154 dali.stage.add( label );
 155 ~~~
 156
 157
 158  ![ ](../assets/img/text-controls/HelloWorld-NaturalSize.png)
 159  ![ ](HelloWorld-NaturalSize.png)
 160
 161
 162 ### Height-for-width negotiation
 163
 164 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.
 165 Each TextLabel will then report a desired height for the given width.
 166 Here is an example of this behavior using TableView as the parent:
 167
 168 ~~~{.cpp}
 169 // C++
 170 TableView parent = TableView::New( 3, 1 );
 171 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 172 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
 173 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 174 Stage::GetCurrent().Add( parent );
 175
 176 TextLabel label = TextLabel::New( "Hello World" );
 177 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 178 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 179 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 180 label.SetBackgroundColor( Color::BLUE );
 181 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
 182 parent.SetFitHeight( 0 );
 183
 184 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
 185 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 186 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 187 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 188 label.SetBackgroundColor( Color::GREEN );
 189 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 190 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
 191 parent.SetFitHeight( 1 );
 192
 193 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
 194 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 195 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 196 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 197 label.SetBackgroundColor( Color::BLUE );
 198 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 199 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
 200 parent.SetFitHeight( 2 );
 201 ~~~
 202
 203  ![ ](../assets/img/text-controls/HelloWorld-HeightForWidth.png)
 204  ![ ](HelloWorld-HeightForWidth.png)
 205
 206
 207 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
 208
 209 ### TextLabel Decorations
 210
 211 #### Color
 212
 213 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
 214 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.
 215
 216 ~~~{.cpp}
 217 // C++
 218 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
 219 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
 220 ~~~
 221
 222 ~~~{.js}
 223 // JavaScript
 224
 225 label.text = "Red Text";
 226 label.textColor = dali.COLOR_RED;
 227 ~~~
 228
 229  ![ ](../assets/img/text-controls/RedText.png)
 230  ![ ](RedText.png)
 231
 232 #### Drop Shadow
 233
 234 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.
 235
 236 ~~~{.cpp}
 237  // C++
 238
 239 stage.SetBackgroundColor( Color::BLUE );
 240
 241 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
 242
 243 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
 244 label2.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"black\"}" );
 245
 246 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
 247 label3.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"2 2\",\"color\":\"black\"}" );
 248
 249 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
 250
 251 Property::Map shadow;
 252 shadow.Insert( "offset", Vector2(1.0f, 1.0f) );
 253 shadow.Insert( "color", Color::RED );
 254 shadow.Insert( "blurRadius", 2.0f ); // A value of 0 indicates no blur. The bigger the radius, the more blurry.
 255 label4.SetProperty( TextLabel::Property::SHADOW, shadow );
 256
 257 ~~~
 258
 259 ~~~{.js}
 260 // JavaScript
 261
 262 dali.stage.setBackgroundColor( dali.COLOR_BLUE );
 263
 264 label1.text = "Plain Text";
 265
 266
 267 label2.text = "Text with Shadow";
 268 label2.shadow = "{\"offset\":\"1 1\",\"color\":\"black\"}";
 269
 270 label3.text = "Text with Bigger Shadow";
 271 label3.shadow = "{\"offset\":\"2 2\",\"color\":\"black\"}";
 272
 273 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
 274 var shadow = {
 275     "offset" : [ 1.0, 1.0 ],
 276     "color" : dali.COLOR_RED;
 277     "blurRadius" : 2.0
 278 };
 279 label4.shadow = shadow;
 280
 281 ~~~
 282
 283
 284 ![ ](../assets/img/text-controls/PlainText.png)
 285 ![ ](PlainText.png)
 286
 287
 288 ![ ](../assets/img/text-controls/TextWithShadow.png)
 289 ![ ](TextWithShadow.png)
 290
 291 ![ ](../assets/img/text-controls/TextWithBiggerShadow.png)
 292 ![ ](TextWithBiggerShadow.png)
 293
 294
 295 ![ ](../assets/img/text-controls/TextWithColorShadow.png)
 296 ![ ](TextWithColorShadow.png)
 297
 298
 299 #### Underline
 300
 301 The text can be underlined by setting UNDERLINE_ENABLED.
 302 The color can also be selected using the UNDERLINE_COLOR property.
 303
 304 ~~~{.cpp}
 305 // C++
 306 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
 307 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 308
 309 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
 310 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 311 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
 312 ~~~
 313 ~~~{.js}
 314 // JavaScript
 315 label1.Text = "Text with Underline";
 316 label1.underlineEnabled = true;
 317
 318 label2.Text = "Text with Color Underline";
 319 label2.underlineEnabled = true;
 320 label2.underlineColor = dali.COLOR_GREEN;
 321 ~~~
 322
 323
 324 ![ ](../assets/img/text-controls/TextWithUnderline.png)
 325 ![ ](TextWithUnderline.png)
 326
 327
 328 ![ ](../assets/img/text-controls/TextWithColorUnderline.png)
 329 ![ ](TextWithColorUnderline.png)
 330
 331 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
 332
 333 ~~~{.cpp}
 334 // C++
 335
 336 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
 337 ~~~
 338
 339 ~~~{.js}
 340 // JavaScript
 341
 342 label1.underlineHeight = 1;
 343 ~~~
 344
 345 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
 346 ![ ](TextWith1pxUnderline.png)
 347
 348 ### Auto Scrolling
 349
 350 ![ ](../assets/img/text-controls/AutoScroll.gif)
 351 ![ ](AutoScroll.gif)
 352
 353 The \link text-auto-scrolling Auto text scrolling \endlink section details how to scroll text automatically.
 354
 355 ### Text Label Properties
 356
 357 The properties used by TextLabel are listed [here](@ref TextLabelProperties)
 358
 359 @class TextLabel
 360
 361 */