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) |
92 The examples above assume that the TextLabel size greater than the minimum required.
93 The next section provides details about the other size related options.
97 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
99 There are several resize policies which are commonly used with TextLabels.
101 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:
103 ### Using natural size
105 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.
106 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.
111 TextLabel label = TextLabel::New( "Hello World" );
112 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
113 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
114 label.SetBackgroundColor( Color::BLUE );
115 Stage::GetCurrent().Add( label );
121 var label = new dali.Textlabel;
122 label.text = "Hello World";
123 label.anchorPoint = dali.TOP_LEFT;
125 label.widthResizePolicy = "USE_NATURAL_SIZE";
126 label.heightResizePolicy = "USE_NATURAL_SIZE";
128 label.textColor = dali.COLOR_WHITE;
129 // background color not available as it's currently not a property of control
130 dali.stage.add( label );
134 ![ ](../assets/img/text-controls/HelloWorld-NaturalSize.png)
135 ![ ](HelloWorld-NaturalSize.png)
138 ### Height-for-width negotiation
140 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.
141 Each TextLabel will then report a desired height for the given width.
142 Here is an example of this behavior using TableView as the parent:
146 TableView parent = TableView::New( 3, 1 );
147 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
148 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
149 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
150 Stage::GetCurrent().Add( parent );
152 TextLabel label = TextLabel::New( "Hello World" );
153 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
154 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
155 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
156 label.SetBackgroundColor( Color::BLUE );
157 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
158 parent.SetFitHeight( 0 );
160 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
161 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
162 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
163 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
164 label.SetBackgroundColor( Color::GREEN );
165 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
166 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
167 parent.SetFitHeight( 1 );
169 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
170 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
171 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
172 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
173 label.SetBackgroundColor( Color::BLUE );
174 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
175 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
176 parent.SetFitHeight( 2 );
179 ![ ](../assets/img/text-controls/HelloWorld-HeightForWidth.png)
180 ![ ](HelloWorld-HeightForWidth.png)
183 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
185 ### TextLabel Decorations
189 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
190 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.
194 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
195 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
201 label.text = "Red Text";
202 label.textColor = dali.COLOR_RED;
205 ![ ](../assets/img/text-controls/RedText.png)
210 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.
215 stage.SetBackgroundColor( Color::BLUE );
217 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
219 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
220 label2.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"black\"}" );
222 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
223 label3.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"2 2\",\"color\":\"black\"}" );
225 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
227 Property::Map shadow;
228 shadow.Insert( "offset", Vector2(1.0f, 1.0f) );
229 shadow.Insert( "color", Color::RED );
230 shadow.Insert( "blurRadius", 2.0f ); // A value of 0 indicates no blur. The bigger the radius, the more blurry.
231 label4.SetProperty( TextLabel::Property::SHADOW, shadow );
238 dali.stage.setBackgroundColor( dali.COLOR_BLUE );
240 label1.text = "Plain Text";
243 label2.text = "Text with Shadow";
244 label2.shadow = "{\"offset\":\"1 1\",\"color\":\"black\"}";
246 label3.text = "Text with Bigger Shadow";
247 label3.shadow = "{\"offset\":\"2 2\",\"color\":\"black\"}";
249 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
251 "offset" : [ 1.0, 1.0 ],
252 "color" : dali.COLOR_RED;
255 label4.shadow = shadow;
260 ![ ](../assets/img/text-controls/PlainText.png)
264 ![ ](../assets/img/text-controls/TextWithShadow.png)
265 ![ ](TextWithShadow.png)
267 ![ ](../assets/img/text-controls/TextWithBiggerShadow.png)
268 ![ ](TextWithBiggerShadow.png)
271 ![ ](../assets/img/text-controls/TextWithColorShadow.png)
272 ![ ](TextWithColorShadow.png)
277 The text can be underlined by setting UNDERLINE_ENABLED.
278 The color can also be selected using the UNDERLINE_COLOR property.
282 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
283 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
285 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
286 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
287 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
291 label1.Text = "Text with Underline";
292 label1.underlineEnabled = true;
294 label2.Text = "Text with Color Underline";
295 label2.underlineEnabled = true;
296 label2.underlineColor = dali.COLOR_GREEN;
300 ![ ](../assets/img/text-controls/TextWithUnderline.png)
301 ![ ](TextWithUnderline.png)
304 ![ ](../assets/img/text-controls/TextWithColorUnderline.png)
305 ![ ](TextWithColorUnderline.png)
307 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
312 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
318 label1.underlineHeight = 1;
321 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
322 ![ ](TextWith1pxUnderline.png)
326 ![ ](../assets/img/text-controls/AutoScroll.gif)
329 The \link text-auto-scrolling Auto text scrolling \endlink section details how to scroll text automatically.
331 ### Text Label Properties
333 The properties used by TextLabel are listed [here](@ref TextLabelProperties)