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