Dali 3D User Interface Engine
text-label

Text Label

Overview

The Dali::Toolkit::TextLabel is a Dali::Toolkit::Control which renders a short text string. Text labels are lightweight, non-editable and do not respond to user input.

Basic usage

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.

// C++
label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
Stage::GetCurrent().Add( label );
// JavaScript
var label = new dali.TextLabel();
label.text = "Hello World";
label.anchorPoint = dali.TOP_LEFT;
dali.stage.add( label );

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 parentOrigin and anchorPoint properties.

(ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT)
TextLabelTopLeft.png

Font Selection

By default TextLabel will automatically select a suitable font from the platform. However, a different font could be selected. See the Font Selection section for more details.

Mark-up Style

Mark-up tags can be used to change the style of the text. See the Mark-up Style section for more details.

Text Alignment

Wrapping can be enabled using the MULTI_LINE property:

// C++
label.SetProperty( TextLabel::Property::MULTI_LINE, true );
// JavaScript
label.mutliLine = true;

The text can be either aligned horizontally to the beginning, end, or center of the available area:

// C++
label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
// JavaScript
label.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
Here is the "BEGIN" alignment shown for left-to-right (Latin) right-to-left (Arabic) scripts
LatinBegin.png
ArabicBegin.png
Here is the "CENTER" alignment shown for left-to-right (Latin) right-to-left (Arabic) scripts:
LatinCenter.png
ArabicCenter.png
Here is the "END" alignment shown for left-to-right (Latin) right-to-left (Arabic) scripts:
LatinEnd.png
ArabicEnd.png

The examples above assume that the TextLabel size greater than the minimum required. The next section provides details about the other size related options.

Negotiating size

Size negotiation is a layouting feature supported by UI controls such as TextLabel.

There are several resize policies which are commonly used with TextLabels.

The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:

Using natural size

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. Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.

// C++
TextLabel label = TextLabel::New( "Hello World" );
label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
label.SetBackgroundColor( Color::BLUE );
Stage::GetCurrent().Add( label );
// JavaScript
var label = new dali.Textlabel;
label.text = "Hello World";
label.anchorPoint = dali.TOP_LEFT;
label.widthResizePolicy = "USE_NATURAL_SIZE";
label.heightResizePolicy = "USE_NATURAL_SIZE";
label.textColor = dali.COLOR_WHITE;
// background color not available as it's currently not a property of control
dali.stage.add( label );
HelloWorld-NaturalSize.png

Height-for-width negotiation

To layout text labels vertically, a fixed (maximum) width should be provided by the parent control. Each TextLabel will then report a desired height for the given width. Here is an example of this behavior using TableView as the parent:

// C++
TableView parent = TableView::New( 3, 1 );
parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
Stage::GetCurrent().Add( parent );
TextLabel label = TextLabel::New( "Hello World" );
label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
label.SetBackgroundColor( Color::BLUE );
parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
parent.SetFitHeight( 0 );
label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
label.SetBackgroundColor( Color::GREEN );
label.SetProperty( TextLabel::Property::MULTI_LINE, true );
parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
parent.SetFitHeight( 1 );
label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
label.SetBackgroundColor( Color::BLUE );
label.SetProperty( TextLabel::Property::MULTI_LINE, true );
parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
parent.SetFitHeight( 2 );
HelloWorld-HeightForWidth.png

Note that the "Hello World" text label (above) has been given the full width, not the natural width.

TextLabel Decorations

Color

To change the color of the text, the recommended way is to use the TEXT_COLOR property. Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.

// C++
label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
// JavaScript
label.text = "Red Text";
label.textColor = dali.COLOR_RED;
RedText.png

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.

// C++
stage.SetBackgroundColor( Color::BLUE );
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 );
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 );
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 );
// JavaScript
dali.stage.setBackgroundColor( dali.COLOR_BLUE );
label1.text = "Plain Text";
label2.text = "Text with Shadow";
label2.shadowOffset = [1, 1];
label2.shadowColor = dali.COLOR_BLACK;
label3.text = "Text with Bigger Shadow";
label3.shadowOffset = [2, 2];
label3.shadowColor = dali.COLOR_BLACK;
label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
label3.shadowOffset = [1, 1];
label3.shadowColor = dali.COLOR_RED;
PlainText.png
TextWithShadow.png
TextWithBiggerShadow.png
TextWithColorShadow.png

Underline

The text can be underlined by setting UNDERLINE_ENABLED. The color can also be selected using the UNDERLINE_COLOR property.

// C++
label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
// JavaScript
label1.Text = "Text with Underline";
label1.underlineEnabled = true;
label2.Text = "Text with Color Underline";
label2.underlineEnabled = true;
label2.underlineColor = dali.COLOR_GREEN;
TextWithUnderline.png
TextWithColorUnderline.png

By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:

// C++
label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
// JavaScript
label1.underlineHeight = 1;
TextWith1pxUnderline.png

Text Label Properties

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
enableMarkup ENABLE_MARKUP BOOLEAN O X
Dali Docs Home
Read more about Dali