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 and order 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 and ordered as the system default language.
100 label.SetProperty( Toolkit::DevelTextLabel::Property::MATCH_SYSTEM_LANGUAGE_DIRECTION, true );
106 label.matchSystemLanguageDirection = true;
111 | Current system language direction left-to-right | |
112 | MATCH_SYSTEM_LANGUAGE_DIRECTION set to TRUE. | MATCH_SYSTEM_LANGUAGE_DIRECTION set to FALSE (default). |
113 | BEGIN alignment | BEGIN alignment |
114 | ![ ](../assets/img/text-controls/HelloWorld-System-BEGIN.png) ![ ](HelloWorld-System-BEGIN.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-BEGIN.png) ![ ](HelloWorld-Default-BEGIN.png) |
115 | CENTER alignment | CENTER alignment |
116 | ![ ](../assets/img/text-controls/HelloWorld-System-CENTER.png) ![ ](HelloWorld-System-CENTER.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-CENTER.png) ![ ](HelloWorld-Default-CENTER.png) |
117 | END alignment | END alignment |
118 | ![ ](../assets/img/text-controls/HelloWorld-System-END.png) ![ ](HelloWorld-System-END.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-END.png) ![ ](HelloWorld-Default-END.png) |
123 | Current system language direction left-to-right | Current system language direction right-to-left |
124 | ![ ](../assets/img/text-controls/LTR_order.png) ![ ](LTR_order.png) | ![ ](../assets/img/text-controls/RTL_order.png) ![ ](RTL_order.png) |
127 The examples above assume that the TextLabel size greater than the minimum required.
128 The next section provides details about the other size related options.
132 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
134 There are several resize policies which are commonly used with TextLabels.
136 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:
138 ### Using natural size
140 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.
141 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.
146 TextLabel label = TextLabel::New( "Hello World" );
147 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
148 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
149 label.SetBackgroundColor( Color::BLUE );
150 Stage::GetCurrent().Add( label );
156 var label = new dali.Textlabel;
157 label.text = "Hello World";
158 label.anchorPoint = dali.TOP_LEFT;
160 label.widthResizePolicy = "USE_NATURAL_SIZE";
161 label.heightResizePolicy = "USE_NATURAL_SIZE";
163 label.textColor = dali.COLOR_WHITE;
164 // background color not available as it's currently not a property of control
165 dali.stage.add( label );
169 ![ ](../assets/img/text-controls/HelloWorld-NaturalSize.png)
170 ![ ](HelloWorld-NaturalSize.png)
173 ### Height-for-width negotiation
175 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.
176 Each TextLabel will then report a desired height for the given width.
177 Here is an example of this behavior using TableView as the parent:
181 TableView parent = TableView::New( 3, 1 );
182 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
183 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
184 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
185 Stage::GetCurrent().Add( parent );
187 TextLabel label = TextLabel::New( "Hello World" );
188 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
189 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
190 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
191 label.SetBackgroundColor( Color::BLUE );
192 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
193 parent.SetFitHeight( 0 );
195 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
196 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
197 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
198 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
199 label.SetBackgroundColor( Color::GREEN );
200 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
201 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
202 parent.SetFitHeight( 1 );
204 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
205 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
206 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
207 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
208 label.SetBackgroundColor( Color::BLUE );
209 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
210 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
211 parent.SetFitHeight( 2 );
214 ![ ](../assets/img/text-controls/HelloWorld-HeightForWidth.png)
215 ![ ](HelloWorld-HeightForWidth.png)
218 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
220 ### TextLabel Decorations
224 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
225 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.
229 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
230 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
236 label.text = "Red Text";
237 label.textColor = dali.COLOR_RED;
240 ![ ](../assets/img/text-controls/RedText.png)
245 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.
250 stage.SetBackgroundColor( Color::BLUE );
252 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
254 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
255 label2.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"black\"}" );
257 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
258 label3.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"2 2\",\"color\":\"black\"}" );
260 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
262 Property::Map shadow;
263 shadow.Insert( "offset", Vector2(1.0f, 1.0f) );
264 shadow.Insert( "color", Color::RED );
265 shadow.Insert( "blurRadius", 2.0f ); // A value of 0 indicates no blur. The bigger the radius, the more blurry.
266 label4.SetProperty( TextLabel::Property::SHADOW, shadow );
273 dali.stage.setBackgroundColor( dali.COLOR_BLUE );
275 label1.text = "Plain Text";
278 label2.text = "Text with Shadow";
279 label2.shadow = "{\"offset\":\"1 1\",\"color\":\"black\"}";
281 label3.text = "Text with Bigger Shadow";
282 label3.shadow = "{\"offset\":\"2 2\",\"color\":\"black\"}";
284 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
286 "offset" : [ 1.0, 1.0 ],
287 "color" : dali.COLOR_RED;
290 label4.shadow = shadow;
295 ![ ](../assets/img/text-controls/PlainText.png)
299 ![ ](../assets/img/text-controls/TextWithShadow.png)
300 ![ ](TextWithShadow.png)
302 ![ ](../assets/img/text-controls/TextWithBiggerShadow.png)
303 ![ ](TextWithBiggerShadow.png)
306 ![ ](../assets/img/text-controls/TextWithColorShadow.png)
307 ![ ](TextWithColorShadow.png)
312 The text can be underlined by setting UNDERLINE_ENABLED.
313 The color can also be selected using the UNDERLINE_COLOR property.
317 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
318 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
320 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
321 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
322 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
326 label1.Text = "Text with Underline";
327 label1.underlineEnabled = true;
329 label2.Text = "Text with Color Underline";
330 label2.underlineEnabled = true;
331 label2.underlineColor = dali.COLOR_GREEN;
335 ![ ](../assets/img/text-controls/TextWithUnderline.png)
336 ![ ](TextWithUnderline.png)
339 ![ ](../assets/img/text-controls/TextWithColorUnderline.png)
340 ![ ](TextWithColorUnderline.png)
342 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
347 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
353 label1.underlineHeight = 1;
356 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
357 ![ ](TextWith1pxUnderline.png)
361 ![ ](../assets/img/text-controls/AutoScroll.gif)
364 The \link text-auto-scrolling Auto text scrolling \endlink section details how to scroll text automatically.
366 ### Text Label Properties
368 The properties used by TextLabel are listed [here](@ref TextLabelProperties)