1 /*! \page text-label Text Label
3 \section overview Overview
4 The Dali::Toolkit::TextLabel is a Dali::Toolkit::Control which renders a short text string.\n
5 Text labels are lightweight, non-editable and do not respond to user input.
7 \subsection basictextlabelusage Basic usage
9 To display a TextLabel the TEXT property must be set using a UTF-8 string.
12 TextLabel label = TextLabel::New();
13 label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
14 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
15 Stage::GetCurrent().Add( label );
18 The label must also be added to the stage, or to an actor which is on the stage.\n
19 The position of the label on-screen is dependent on the parent-origin and anchor-point properties.\n
21 <table border=0 cellpadding=10>
24 \image html TextLabelTopLeft.png
29 (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT)
34 \subsection fontSelection Font Selection
36 By default TextLabel will automatically select a suitable font from the platform.\n
37 Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.\n
38 Therefore you should expect TextLabel to select different fonts for each script.
40 Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
42 label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
43 label.SetProperty( TextLabel::Property::FONT_STYLE, "Regular" );
44 label.SetProperty( TextLabel::Property::POINT_SIZE, 12.0f );
46 However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
48 \subsection fontStyles Font Styles
50 Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.\n
51 A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:\n
54 StyleManager styleManager = StyleManager::Get();
55 styleManager.RequestThemeChange( "example-path/example.json" );
58 To change the font for standard text labels, this JSON syntax can be used:
66 "font-family":"Arial",
67 "font-style":"Regular",
74 However the same point-size is unlikely to be suitable for all labels in an application.\n
75 To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
78 label.SetProperty( Control::Property::STYLE_NAME, "custom" );
87 "font-family":"Arial",
88 "font-style":"Regular",
100 In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.\n
102 \subsection textAlignment Text Alignment
104 Wrapping can be enabled using the MULTI_LINE property:\n
106 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
109 The text can be either aligned horizontally to the beginning, end, or center of the available area:
111 label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
114 <table border=0 cellpadding=10>
117 Here is the "BEGIN" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
122 \image html LatinBegin.png
125 \image html ArabicBegin.png
130 Here is the "CENTER" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
135 \image html LatinCenter.png
138 \image html ArabicCenter.png
143 Here is the "END" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
148 \image html LatinEnd.png
151 \image html ArabicEnd.png
156 The examples above assume that the TextLabel size greater than the minimum required.\n
157 The next section provides details about the other size related options.
159 \subsection negotiatingSize Negotiating size
161 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.\n
162 There are several resize policies which are commonly used with TextLabels.\n
163 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:\n
165 <h3>Using natural size</h3>
167 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.\n
168 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.\n
171 TextLabel label = TextLabel::New( "Hello World" );
172 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
173 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
174 label.SetBackgroundColor( Color::BLUE );
175 Stage::GetCurrent().Add( label );
178 <table border=0 cellpadding=10>
181 \image html HelloWorld-NaturalSize.png
186 <h3>Height-for-width negotiation</h3>
188 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.\n
189 Each TextLabel will then report a desired height for the given width.\n
190 Here is an example of this behavior using TableView as the parent:
193 TableView parent = TableView::New( 3, 1 );
194 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
195 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
196 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
197 Stage::GetCurrent().Add( parent );
199 TextLabel label = TextLabel::New( "Hello World" );
200 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
201 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
202 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
203 label.SetBackgroundColor( Color::BLUE );
204 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
205 parent.SetFitHeight( 0 );
207 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
208 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
209 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
210 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
211 label.SetBackgroundColor( Color::GREEN );
212 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
213 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
214 parent.SetFitHeight( 1 );
216 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
217 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
218 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
219 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
220 label.SetBackgroundColor( Color::BLUE );
221 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
222 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
223 parent.SetFitHeight( 2 );
226 <table border=0 cellpadding=10>
229 \image html HelloWorld-HeightForWidth.png
234 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
236 \subsection textLabelDecorations TextLabel Decorations
240 To change the color of the text, the recommended way is to use the TEXT_COLOR property.\n
241 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.\n
244 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
245 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
248 <table border=0 cellpadding=10>
251 \image html RedText.png
258 To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.\n
259 The color can also be selected using the SHADOW_COLOR property.\n
262 stage.SetBackgroundColor( Color::BLUE );
264 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
266 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
267 label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
268 label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
270 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
271 label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) );
272 label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
274 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
275 label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
276 label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED );
279 <table border=0 cellpadding=10>
282 \image html PlainText.png
287 \image html TextWithShadow.png
292 \image html TextWithBiggerShadow.png
297 \image html TextWithColorShadow.png
304 The text can be underlined by setting UNDERLINE_ENABLED.\n
305 The color can also be selected using the UNDERLINE_COLOR property.\n
308 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
309 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
311 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
312 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
313 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
316 <table border=0 cellpadding=10>
319 \image html TextWithUnderline.png
324 \image html TextWithColorUnderline.png
329 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
332 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
335 <table border=0 cellpadding=10>
338 \image html TextWith1pxUnderline.png