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