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