docs/content/programming-guide/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 The label must also be added to the stage, or to an actor which is on the stage.
  27 The position of the label on-screen is dependent on the parentOrigin and anchorPoint properties.
  28
  29 |  |  |
  30 |--|--|
  31 | (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT) | ![ ](TextLabelTopLeft.png)   |
  32
  33 ### Font Selection
  34
  35 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.
  36
  37 ### Mark-up Style
  38
  39 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.
  40
  41 ### Text Alignment
  42
  43 Wrapping can be enabled using the MULTI_LINE property:
  44
  45 ~~~{.cpp}
  46 // C++
  47
  48 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
  49 ~~~
  50
  51 The text can be either aligned horizontally to the beginning, end, or center of the available area:
  52
  53 ~~~{.cpp}
  54 // C++
  55
  56 label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  57 ~~~
  58
  59 |  |  |
  60 |--|--|
  61 | Here is the "BEGIN" alignment shown for left-to-right (Latin)   |  right-to-left (Arabic) scripts |
  62 | ![ ](LatinBegin.png) | ![ ](ArabicBegin.png) |
  63 | Here is the "CENTER" alignment shown for left-to-right (Latin)  | right-to-left (Arabic) scripts:|
  64 | ![ ](LatinCenter.png) | ![ ](ArabicCenter.png) |
  65 | Here is the "END" alignment shown for left-to-right (Latin)  | right-to-left (Arabic) scripts:|
  66 | ![ ](LatinEnd.png) | ![ ](ArabicEnd.png) |
  67
  68
  69
  70 The text's alignment and order can be modified to match the direction of the system language.
  71
  72 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.
  73
  74 ~~~{.cpp}
  75 // C++
  76
  77 label.SetProperty( Toolkit::DevelTextLabel::Property::MATCH_SYSTEM_LANGUAGE_DIRECTION, true );
  78 ~~~
  79
  80 |  |  |
  81 |--|--|
  82 | Current system language direction left-to-right | |
  83 | MATCH_SYSTEM_LANGUAGE_DIRECTION set to TRUE. | MATCH_SYSTEM_LANGUAGE_DIRECTION set to FALSE (default). |
  84 | BEGIN alignment | BEGIN alignment  |
  85 | ![ ](HelloWorld-System-BEGIN.png) | ![ ](HelloWorld-Default-BEGIN.png) |
  86 | CENTER alignment | CENTER alignment  |
  87 | ![ ](HelloWorld-System-CENTER.png) | ![ ](HelloWorld-Default-CENTER.png) |
  88 | END alignment | END alignment  |
  89 | ![ ](HelloWorld-System-END.png) | ![ ](HelloWorld-Default-END.png) |
  90
  91
  92 |  |  |
  93 |--|--|
  94 | Current system language direction left-to-right | Current system language direction right-to-left |
  95 | ![ ](LTR_order.png)  | ![ ](RTL_order.png) |
  96
  97
  98 The examples above assume that the TextLabel size greater than the minimum required.
  99 The next section provides details about the other size related options.
 100
 101 ## Negotiating size
 102
 103 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
 104
 105 There are several resize policies which are commonly used with TextLabels.
 106
 107 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:
 108
 109 ### Using natural size
 110
 111 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.
 112 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.
 113
 114 ~~~{.cpp}
 115 // C++
 116
 117 TextLabel label = TextLabel::New( "Hello World" );
 118 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 119 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
 120 label.SetBackgroundColor( Color::BLUE );
 121 Stage::GetCurrent().Add( label );
 122 ~~~
 123
 124
 125  ![ ](HelloWorld-NaturalSize.png)
 126
 127
 128 ### Height-for-width negotiation
 129
 130 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.
 131 Each TextLabel will then report a desired height for the given width.
 132 Here is an example of this behavior using TableView as the parent:
 133
 134 ~~~{.cpp}
 135 // C++
 136 TableView parent = TableView::New( 3, 1 );
 137 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 138 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
 139 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 140 Stage::GetCurrent().Add( parent );
 141
 142 TextLabel label = TextLabel::New( "Hello World" );
 143 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 144 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 145 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 146 label.SetBackgroundColor( Color::BLUE );
 147 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
 148 parent.SetFitHeight( 0 );
 149
 150 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
 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::GREEN );
 155 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 156 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
 157 parent.SetFitHeight( 1 );
 158
 159 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
 160 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
 161 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
 162 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
 163 label.SetBackgroundColor( Color::BLUE );
 164 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
 165 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
 166 parent.SetFitHeight( 2 );
 167 ~~~
 168
 169  ![ ](HelloWorld-HeightForWidth.png)
 170
 171
 172 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
 173
 174 ### TextLabel Decorations
 175
 176 #### Color
 177
 178 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
 179 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.
 180
 181 ~~~{.cpp}
 182 // C++
 183 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
 184 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
 185 ~~~
 186
 187  ![ ](RedText.png)
 188
 189 #### Drop Shadow
 190
 191 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.
 192
 193 ~~~{.cpp}
 194  // C++
 195
 196 stage.SetBackgroundColor( Color::BLUE );
 197
 198 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
 199
 200 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
 201 label2.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"black\"}" );
 202
 203 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
 204 label3.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"2 2\",\"color\":\"black\"}" );
 205
 206 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
 207
 208 Property::Map shadow;
 209 shadow.Insert( "offset", Vector2(1.0f, 1.0f) );
 210 shadow.Insert( "color", Color::RED );
 211 shadow.Insert( "blurRadius", 2.0f ); // A value of 0 indicates no blur. The bigger the radius, the more blurry.
 212 label4.SetProperty( TextLabel::Property::SHADOW, shadow );
 213
 214 ~~~
 215
 216 ![ ](PlainText.png)
 217
 218
 219 ![ ](TextWithShadow.png)
 220
 221 ![ ](TextWithBiggerShadow.png)
 222
 223
 224 ![ ](TextWithColorShadow.png)
 225
 226
 227 #### Underline
 228
 229 The text can be underlined by setting UNDERLINE_ENABLED.
 230 The color can also be selected using the UNDERLINE_COLOR property.
 231
 232 ~~~{.cpp}
 233 // C++
 234 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
 235 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 236
 237 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
 238 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
 239 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
 240 ~~~
 241
 242 ![ ](TextWithUnderline.png)
 243
 244
 245 ![ ](TextWithColorUnderline.png)
 246
 247 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
 248
 249 ~~~{.cpp}
 250 // C++
 251
 252 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
 253 ~~~
 254
 255 ![ ](TextWith1pxUnderline.png)
 256
 257 ### Auto Scrolling
 258
 259 ![ ](AutoScroll.gif)
 260
 261 The \link text-auto-scrolling Auto text scrolling \endlink section details how to scroll text automatically.
 262
 263 ### Text Label Properties
 264
 265 The properties used by TextLabel are listed [here](@ref TextLabelProperties)
 266
 267
 268 */