Merge "IMF event fixes" into tizen
[platform/core/uifw/dali-toolkit.git] / docs / content / shared-javascript-and-cpp-documentation / 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 ~~~{.cpp}
16 // C++
17
18 TextLabel label = TextLabel::New();
19 label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
20 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
21 Stage::GetCurrent().Add( label );
22 ~~~
23
24 ~~~{.js}
25 // JavaScript
26
27 var label = new dali.TextLabel();
28
29 label.text = "Hello World";
30 label.anchorPoint = dali.TOP_LEFT;
31
32 dali.stage.add( label );
33 ~~~
34
35 The label must also be added to the stage, or to an actor which is on the stage.  
36 The position of the label on-screen is dependent on the parent-origin and anchor-point properties.  
37
38 |  |  |
39 |--|--|
40 | (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT) | ![ ](../assets/img/text-controls/TextLabelTopLeft.png) ![ ](TextLabelTopLeft.png)   |
41
42 ### Font Selection
43
44 By default TextLabel will automatically select a suitable font from the platform.  
45 Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.  
46 Therefore you should expect TextLabel to select different fonts for each script.
47
48 Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
49
50 ~~~{.cpp}
51 // C++
52
53 label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
54 label.SetProperty( TextLabel::Property::FONT_STYLE,  "Regular" );
55 label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
56 ~~~
57
58 ~~~{.js}
59 // JavaScript
60
61 label.fontFamily = "HelveticaNue";
62 label.fontStyle = "Regular";
63 label.pointSize = 12;
64 ~~~
65
66 However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
67
68 ### Font Styles
69
70 Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.  
71 A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:  
72
73 ~~~{.cpp}
74 // C++
75 StyleManager styleManager = StyleManager::Get();
76 styleManager.RequestThemeChange( "example-path/example.json" );
77 ~~~
78
79 To change the font for standard text labels, this JSON syntax can be used:
80
81 ~~~{.json}
82 {
83   "styles":
84   {
85     "textlabel":
86     {
87       "font-family":"Arial",
88       "font-style":"Regular",
89       "point-size":8
90     }
91   }
92 }
93 ~~~
94
95 However the same point-size is unlikely to be suitable for all labels in an application.  
96 To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
97
98 ~~~{.cpp}
99   // C++
100
101   label.SetProperty( Control::Property::STYLE_NAME, "custom" );
102 ~~~
103 ~~~{.js}
104   // JavaScript
105
106   label.styleName = "custom"';
107 ~~~
108
109 ~~~{.json}
110 {
111   "styles":
112   {
113     "textlabel":
114     {
115       "font-family":"Arial",
116       "font-style":"Regular",
117       "point-size":8
118     },
119
120     "custom":
121     {
122       "point-size":10
123     }
124   }
125 }
126 ~~~
127
128 In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.  
129
130 ### Text Alignment
131
132 Wrapping can be enabled using the MULTI_LINE property:
133
134 ~~~{.cpp}
135 // C++
136
137 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
138 ~~~
139
140 ~~~{.js}
141 // JavaScript
142
143 label.mutliLine = true;
144 ~~~
145
146 The text can be either aligned horizontally to the beginning, end, or center of the available area:
147
148 ~~~{.cpp}
149 // C++
150
151 label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
152 ~~~
153
154 ~~~{.js}
155 // JavaScript
156
157 label.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
158 ~~~
159
160 |  |  |
161 |--|--|
162 | Here is the "BEGIN" alignment shown for left-to-right (Latin)   |  right-to-left (Arabic) scripts |
163 | ![ ](../assets/img/text-controls/LatinBegin.png) ![ ](LatinBegin.png) | ![ ](../assets/img/text-controls/ArabicBegin.png) ![ ](ArabicBegin.png) |
164 | Here is the "CENTER" alignment shown for left-to-right (Latin)  | right-to-left (Arabic) scripts:|
165 | ![ ](../assets/img/text-controls/LatinCenter.png) ![ ](LatinCenter.png) | ![ ](../assets/img/text-controls/ArabicCenter.png) ![ ](ArabicCenter.png) |
166 | Here is the "END" alignment shown for left-to-right (Latin)  | right-to-left (Arabic) scripts:|
167 | ![ ](../assets/img/text-controls/LatinEnd.png) ![ ](LatinEnd.png) | ![ ](../assets/img/text-controls/ArabicEnd.png) ![ ](ArabicEnd.png) |
168
169
170 The examples above assume that the TextLabel size greater than the minimum required.  
171 The next section provides details about the other size related options.
172
173 ## Negotiating size
174
175 \link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
176   
177 There are several resize policies which are commonly used with TextLabels.
178   
179 The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:  
180
181 ### Using natural size
182
183 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.  
184 Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.  
185
186 ~~~{.cpp}
187 // C++
188
189 TextLabel label = TextLabel::New( "Hello World" );
190 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
191 label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
192 label.SetBackgroundColor( Color::BLUE );
193 Stage::GetCurrent().Add( label );
194 ~~~
195
196 ~~~{.js}
197 // JavaScript
198
199 var label = new dali.Textlabel;
200 label.text = "Hello World";
201 label.anchorPoint = dali.TOP_LEFT;
202
203 label.widthResizePolicy = "USE_NATURAL_SIZE";
204 label.heightResizePolicy = "USE_NATURAL_SIZE";
205
206 label.textColor = dali.COLOR_WHITE;
207 // background color not available as it's currently not a property of control
208 dali.stage.add( label );
209 ~~~
210
211
212  ![ ](../assets/img/text-controls/HelloWorld-NaturalSize.png)
213  ![ ](HelloWorld-NaturalSize.png)
214
215
216 ### Height-for-width negotiation
217
218 To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.  
219 Each TextLabel will then report a desired height for the given width.  
220 Here is an example of this behavior using TableView as the parent:
221
222 ~~~{.cpp}
223 // C++
224 TableView parent = TableView::New( 3, 1 );
225 parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
226 parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
227 parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
228 Stage::GetCurrent().Add( parent );
229
230 TextLabel label = TextLabel::New( "Hello World" );
231 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
232 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
233 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
234 label.SetBackgroundColor( Color::BLUE );
235 parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
236 parent.SetFitHeight( 0 );
237
238 label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
239 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
240 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
241 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
242 label.SetBackgroundColor( Color::GREEN );
243 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
244 parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
245 parent.SetFitHeight( 1 );
246
247 label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
248 label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
249 label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
250 label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
251 label.SetBackgroundColor( Color::BLUE );
252 label.SetProperty( TextLabel::Property::MULTI_LINE, true );
253 parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
254 parent.SetFitHeight( 2 );
255 ~~~
256
257  ![ ](../assets/img/text-controls/HelloWorld-HeightForWidth.png)
258  ![ ](HelloWorld-HeightForWidth.png)
259
260
261 Note that the "Hello World" text label (above) has been given the full width, not the natural width.
262
263 ### TextLabel Decorations
264
265 #### Color
266
267 To change the color of the text, the recommended way is to use the TEXT_COLOR property.  
268 Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.  
269
270 ~~~{.cpp}
271 // C++
272 label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
273 label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
274 ~~~
275
276 ~~~{.js}
277 // JavaScript
278
279 label.text = "Red Text";
280 label.textColor = dali.COLOR_RED;
281 ~~~
282
283  ![ ](../assets/img/text-controls/RedText.png)
284  ![ ](RedText.png)
285
286 #### Drop Shadow
287
288 To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.  
289 The color can also be selected using the SHADOW_COLOR property.  
290
291 ~~~{.cpp}
292  // C++
293
294 stage.SetBackgroundColor( Color::BLUE );
295
296 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
297
298 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
299 label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
300 label2.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
301
302 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
303 label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) );
304 label3.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
305
306 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
307 label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
308 label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED );
309 ~~~
310
311 ~~~{.js}
312 // JavaScript
313
314 dali.stage.setBackgroundColor( dali.COLOR_BLUE );
315
316 label1.text = "Plain Text";
317
318
319 label2.text = "Text with Shadow";
320 label2.shadowOffset = [1, 1];
321 label2.shadowColor = dali.COLOR_BLACK;
322
323 label3.text = "Text with Bigger Shadow";
324 label3.shadowOffset = [2, 2];
325 label3.shadowColor = dali.COLOR_BLACK;
326
327 label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
328 label3.shadowOffset = [1, 1];
329 label3.shadowColor = dali.COLOR_RED;
330 ~~~
331
332
333 ![ ](../assets/img/text-controls/PlainText.png)
334 ![ ](PlainText.png)
335
336
337 ![ ](../assets/img/text-controls/TextWithShadow.png)
338 ![ ](TextWithShadow.png)
339
340 ![ ](../assets/img/text-controls/TextWithBiggerShadow.png)
341 ![ ](TextWithBiggerShadow.png)
342
343
344 ![ ](../assets/img/text-controls/TextWithColorShadow.png)
345 ![ ](TextWithColorShadow.png)
346
347
348 #### Underline
349
350 The text can be underlined by setting UNDERLINE_ENABLED.  
351 The color can also be selected using the UNDERLINE_COLOR property.  
352
353 ~~~{.cpp}
354 // C++
355 label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
356 label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
357
358 label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
359 label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
360 label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
361 ~~~
362 ~~~{.js}
363 // JavaScript
364 label1.Text = "Text with Underline";
365 label1.underlineEnabled = true;
366
367 label2.Text = "Text with Color Underline";
368 label2.underlineEnabled = true;
369 label2.underlineColor = dali.COLOR_GREEN;
370 ~~~
371
372
373 ![ ](../assets/img/text-controls/TextWithUnderline.png)
374 ![ ](TextWithUnderline.png)
375
376
377 ![ ](../assets/img/text-controls/TextWithColorUnderline.png)
378 ![ ](TextWithColorUnderline.png)
379
380 By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
381
382 ~~~{.cpp}
383 // C++
384
385 label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
386 ~~~
387
388 ~~~{.js}
389 // JavaScript
390
391 label1.underlineHeight = 1;
392 ~~~
393
394 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
395 ![ ](TextWith1pxUnderline.png)
396
397 ### Text Label Properties
398
399  Name (JavaScript)   |  Name (C++)         |  Type        | Writable     | Animatable
400 ---------------------|---------------------|--------------|--------------|-----------
401  renderingBackend    | RENDERING_BACKEND   |  INTEGER     | ✔     | ✘
402  text                | TEXT                |  STRING      | ✔     | ✘
403  fontFamily          | FONT_FAMILY         |  STRING      | ✔     | ✘
404  fontStyle           | FONT_STYLE          |  STRING      | ✔     | ✘
405  pointSize           | POINT_SIZE          |  FLOAT       | ✔     | ✘
406  multiLine           | MULTI_LINE          |  BOOLEAN     | ✔     | ✘
407  horizontalAlignment | HORIZONTAL_ALIGNMENT|  STRING      | ✔     | ✘
408  verticalAlignment   | VERTICAL_ALIGNMENT  |  STRING      | ✔     | ✘
409  textColor           | TEXT_COLOR          |  VECTOR4     | ✔     | ✘
410  shadowOffset        | SHADOW_OFFSET       |  VECTOR2     | ✔     | ✘
411  shadowColor         | SHADOW_COLOR        |  VECTOR4     | ✔     | ✘
412  underlineEnabled    | UNDERLINE_ENABLED   |  BOOLEAN     | ✔     | ✘
413  underlineColor      | UNDERLINE_COLOR     |  VECTOR4     | ✔     | ✘
414  underlineHeight     | UNDERLINE_HEIGHT    |  FLOAT       | ✔     | ✘
415
416
417
418 @class TextLabel
419
420 */