The Dali::Toolkit::TextLabel class provides a control that renders a short text string. The text labels are lightweight, non-editable, and do not respond to user input.

Figure: TextLabel

In this tutorial, the following subjects are covered:

• Creating a TextLabel
• Selecting Fonts
• Aligning Text
• Managing the Layout
• TextLabel Properties

Creating a TextLabel

The following example shows how to create a TextLabel instance:

TextLabel label = TextLabel::New();
label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
Stage::GetCurrent().Add( label );

Selecting Fonts

By default, the TextLabel automatically selects a suitable font from the platform. Note that the selected font may not support all characters in your input text. For example, Latin fonts often do not provide Arabic glyphs.

Alternatively, you can request a font using the FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:

label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
label.SetProperty( TextLabel::Property::FONT_STYLE, "Regular" );
label.SetProperty( TextLabel::Property::POINT_SIZE, 12.0f );

The TextLabel falls back to using the default font if the requested font does not support the required scripts.

Aligning Text

Wrapping can be enabled using the MULTI_LINE property:

label.SetProperty( TextLabel::Property::MULTI_LINE, true );

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

// "CENTER" or "END"
label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" );

Managing the Layout

There are several resize policies commonly used with TextLabels. The following examples show the actual size by setting a colored background, whilst the black area represents the size of the parent control.

Natural Size Policy

In its natural size, the TextLabel is large enough to display the text without wrapping, and does not have extra space to align the text within. In the following example, the same result is displayed regardless of the alignment or multi-line properties:

TextLabel label = TextLabel::New( "Hello World" );
label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
label.SetBackgroundColor( Color::BLUE );
Stage::GetCurrent().Add( label );

Height-for-width Policy

To lay out text labels vertically, a fixed (maximum) width must be provided by the parent control. Each TextLabel reports the desired height for the given width. The following example uses TableView as the parent:

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 );

In the example, the “Hello World” text label has been given the full width, not the natural width.

TextLabel Properties

Using Decorations

For text decorations, TextLabel provides several properties. All properties are writable and none are animatable.

Table: TextLabel properties

Color

To change the color of the text, use the TEXT_COLOR property. Unlike the Actor::COLOR property, this does not affect child actors added to the TextLabel.

label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );

Drop Shadow

To add a drop shadow and put a color to the text, set the SHADOW property with a non-zero values.

stage.SetBackgroundColor( Color::BLUE );
label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
Property::Map shadowMap2;
shadowMap2.Insert( "offset", Vector2( 1.0f, 1.0f ) );
shadowMap2.Insert( "color", Color::BLACK );
label2.SetProperty( TextLabel::Property::SHADOW, shadowMap2 );

label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
Property::Map shadowMap3;
shadowMap3.Insert( "offset", Vector2( 2.0f, 2.0f ) );
shadowMap3.Insert( "color", Color::BLACK );
label3.SetProperty( TextLabel::Property::SHADOW, shadowMap3 );

label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
Property::Map shadowMap4;
shadowMap4.Insert( "offset", Vector2( 1.0f, 1.0f ) );
shadowMap4.Insert( "color", Color::RED );
shadowMap4.Insert( "blurRadius", 2.0f );
label4.SetProperty( TextLabel::Property::SHADOW, shadowMap4 );

Underlining

The text can be underlined by setting the UNDERLINE property. By default, the underline height is based on the font metrics. This can be overridden using ‘UNDERLINE’ property, too.

label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
Property::Map underlineMap;
underlineMap.Insert( "enable", "true" );
label1.SetProperty( TextLabel::Property::UNDERLINE, underlineMap );

label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
Property::Map underlineMap2;
underlineMap2.Insert( "enable", "true" );
underlineMap2.Insert( "color", "green" );
underlineMap2.Insert( "height", "1" );
label2.SetProperty( TextLabel::Property::UNDERLINE, underlineMap2 );