4 # Text Label {#text-label}
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.
13 To display a TextLabel the TEXT property must be set using a UTF-8 string.
15 Note *CR+LF* new line characters are replaced by a *LF* one.
20 TextLabel label = TextLabel::New();
21 label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
22 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
23 Stage::GetCurrent().Add( label );
29 var label = new dali.TextLabel();
31 label.text = "Hello World";
32 label.anchorPoint = dali.TOP_LEFT;
34 dali.stage.add( label );
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.
42 | (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT) | ![ ](../assets/img/text-controls/TextLabelTopLeft.png) ![ ](TextLabelTopLeft.png) |
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.
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.
54 Wrapping can be enabled using the MULTI_LINE property:
59 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
65 label.mutliLine = true;
68 The text can be either aligned horizontally to the beginning, end, or center of the available area:
73 label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
79 label.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
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) |
93 The text's alignment can be modified to match the direction of the system language.
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.
100 label.SetProperty( TextLabel::Property::MATCH_SYSTEM_LANGUAGE_DIRECTION, true );
106 label.matchSystemLanguageDirection = true;
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) |
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.
121 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
123 There are several resize policies which are commonly used with TextLabels.
125 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:
127 ### Using natural size
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.
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 );
145 var label = new dali.Textlabel;
146 label.text = "Hello World";
147 label.anchorPoint = dali.TOP_LEFT;
149 label.widthResizePolicy = "USE_NATURAL_SIZE";
150 label.heightResizePolicy = "USE_NATURAL_SIZE";
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 );
158 ![ ](../assets/img/text-controls/HelloWorld-NaturalSize.png)
159 ![ ](HelloWorld-NaturalSize.png)
162 ### Height-for-width negotiation
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:
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 );
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 );
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 );
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 );
203 ![ ](../assets/img/text-controls/HelloWorld-HeightForWidth.png)
204 ![ ](HelloWorld-HeightForWidth.png)
207 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
209 ### TextLabel Decorations
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.
218 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
219 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
225 label.text = "Red Text";
226 label.textColor = dali.COLOR_RED;
229 ![ ](../assets/img/text-controls/RedText.png)
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.
239 stage.SetBackgroundColor( Color::BLUE );
241 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
243 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
244 label2.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"black\"}" );
246 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
247 label3.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"2 2\",\"color\":\"black\"}" );
249 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
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 );
262 dali.stage.setBackgroundColor( dali.COLOR_BLUE );
264 label1.text = "Plain Text";
267 label2.text = "Text with Shadow";
268 label2.shadow = "{\"offset\":\"1 1\",\"color\":\"black\"}";
270 label3.text = "Text with Bigger Shadow";
271 label3.shadow = "{\"offset\":\"2 2\",\"color\":\"black\"}";
273 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
275 "offset" : [ 1.0, 1.0 ],
276 "color" : dali.COLOR_RED;
279 label4.shadow = shadow;
284 ![ ](../assets/img/text-controls/PlainText.png)
288 ![ ](../assets/img/text-controls/TextWithShadow.png)
289 ![ ](TextWithShadow.png)
291 ![ ](../assets/img/text-controls/TextWithBiggerShadow.png)
292 ![ ](TextWithBiggerShadow.png)
295 ![ ](../assets/img/text-controls/TextWithColorShadow.png)
296 ![ ](TextWithColorShadow.png)
301 The text can be underlined by setting UNDERLINE_ENABLED.
302 The color can also be selected using the UNDERLINE_COLOR property.
306 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
307 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
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 );
315 label1.Text = "Text with Underline";
316 label1.underlineEnabled = true;
318 label2.Text = "Text with Color Underline";
319 label2.underlineEnabled = true;
320 label2.underlineColor = dali.COLOR_GREEN;
324 ![ ](../assets/img/text-controls/TextWithUnderline.png)
325 ![ ](TextWithUnderline.png)
328 ![ ](../assets/img/text-controls/TextWithColorUnderline.png)
329 ![ ](TextWithColorUnderline.png)
331 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
336 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
342 label1.underlineHeight = 1;
345 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
346 ![ ](TextWith1pxUnderline.png)
350 ![ ](../assets/img/text-controls/AutoScroll.gif)
353 The \link text-auto-scrolling Auto text scrolling \endlink section details how to scroll text automatically.
355 ### Text Label Properties
357 The properties used by TextLabel are listed [here](@ref TextLabelProperties)