-/**
- *
+<!--
+/**-->
# Text Label {#text-label}
To display a TextLabel the TEXT property must be set using a UTF-8 string.
+Note *CR+LF* new line characters are replaced by a *LF* one.
+
~~~{.cpp}
// C++
~~~
The label must also be added to the stage, or to an actor which is on the stage.
-The position of the label on-screen is dependent on the parent-origin and anchor-point properties.
+The position of the label on-screen is dependent on the parentOrigin and anchorPoint properties.
| | |
|--|--|
### Font Selection
-By default TextLabel will automatically select a suitable font from the platform.
-Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.
-Therefore you should expect TextLabel to select different fonts for each script.
-
-Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
-
-~~~{.cpp}
-// C++
+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.
-label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
-label.SetProperty( TextLabel::Property::FONT_STYLE, "Regular" );
-label.SetProperty( TextLabel::Property::POINT_SIZE, 12.0f );
-~~~
-
-~~~{.js}
-// JavaScript
+### Mark-up Style
-label.fontFamily = "HelveticaNue";
-label.fontStyle = "Regular";
-label.pointSize = 12;
-~~~
-
-However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
-
-### Font Styles
-
-Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.
-A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:
-
-~~~{.cpp}
-// C++
-StyleManager styleManager = StyleManager::Get();
-styleManager.RequestThemeChange( "example-path/example.json" );
-~~~
-
-To change the font for standard text labels, this JSON syntax can be used:
-
-~~~{.json}
-{
- "styles":
- {
- "textlabel":
- {
- "font-family":"Arial",
- "font-style":"Regular",
- "point-size":8
- }
- }
-}
-~~~
-
-However the same point-size is unlikely to be suitable for all labels in an application.
-To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
-
-~~~{.cpp}
- // C++
-
- label.SetProperty( Control::Property::STYLE_NAME, "custom" );
-~~~
-~~~{.js}
- // JavaScript
-
- label.styleName = "custom"';
-~~~
-
-~~~{.json}
-{
- "styles":
- {
- "textlabel":
- {
- "font-family":"Arial",
- "font-style":"Regular",
- "point-size":8
- },
-
- "custom":
- {
- "point-size":10
- }
- }
-}
-~~~
-
-In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.
+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.
### Text Alignment
#### Drop Shadow
-To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.
-The color can also be selected using the SHADOW_COLOR property.
+To add a drop-shadow to the text, simply set the SHADOW property. Shadow parameters can be set through a json string, see the examples below.
~~~{.cpp}
// C++
label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
-label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
-label2.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
+label2.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"black\"}" );
label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
-label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) );
-label3.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
+label3.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"2 2\",\"color\":\"black\"}" );
label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
-label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
-label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED );
+label4.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"red\"}" );
~~~
~~~{.js}
label2.text = "Text with Shadow";
-label2.shadowOffset = [1, 1];
-label2.shadowColor = dali.COLOR_BLACK;
+label2.shadow = "{\"offset\":\"1 1\",\"color\":\"black\"}";
label3.text = "Text with Bigger Shadow";
-label3.shadowOffset = [2, 2];
-label3.shadowColor = dali.COLOR_BLACK;
+label3.shadow = "{\"offset\":\"2 2\",\"color\":\"black\"}";
label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
-label3.shadowOffset = [1, 1];
-label3.shadowColor = dali.COLOR_RED;
+label3.shadow = "{\"offset\":\"1 1\",\"color\":\"red\"}";
~~~
![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
![ ](TextWith1pxUnderline.png)
-### Text Label Properties
+### Auto Scrolling
- Name (JavaScript) | Name (C++) | Type | Writable | Animatable
----------------------|---------------------|--------------|--------------|-----------
- renderingBackend | RENDERING_BACKEND | INTEGER | O | X
- text | TEXT | STRING | O | X
- fontFamily | FONT_FAMILY | STRING | O | X
- fontStyle | FONT_STYLE | STRING | O | X
- pointSize | POINT_SIZE | FLOAT | O | X
- multiLine | MULTI_LINE | BOOLEAN | O | X
- horizontalAlignment | HORIZONTAL_ALIGNMENT| STRING | O | X
- verticalAlignment | VERTICAL_ALIGNMENT | STRING | O | X
- textColor | TEXT_COLOR | VECTOR4 | O | X
- shadowOffset | SHADOW_OFFSET | VECTOR2 | O | X
- shadowColor | SHADOW_COLOR | VECTOR4 | O | X
- underlineEnabled | UNDERLINE_ENABLED | BOOLEAN | O | X
- underlineColor | UNDERLINE_COLOR | VECTOR4 | O | X
- underlineHeight | UNDERLINE_HEIGHT | FLOAT | O | X
+![ ](../assets/img/text-controls/AutoScroll.gif)
+![ ](AutoScroll.gif)
+The \link text-auto-scrolling Auto text scrolling \endlink section details how to scroll text automatically.
+
+### Text Label Properties
+The properties used by TextLabel are listed [here](@ref TextLabelProperties)
@class TextLabel