TextLabel
PUBLISHED
A text label is a NUI control that displays a short text string. It is implemented through the Tizen.NUI.BaseComponents.TextLabel
class.
Text labels are lightweight, non-editable, and do not respond to user input. They can support multiple languages and scripts, including right-to-left scripts, such as Arabic. For an example of displaying text using a text label, see NUI Hello World Tutorial [1].
Figure: Text label example, positioned to top left
Creating a Text Label
To create a text label:
- Create an instance of the Tizen.NUI.BaseComponents.TextLabel [2] class and define the label text as a parameter:
TextLabel label = new TextLabel("Hello World");
You can also create the
Tizen.NUI.BaseComponents.TextLabel
class instance separately and define the label text by setting itsText
property:TextLabel label = new TextLabel(); label.Text = "Hello World";
Note To display properly, theText
property must be a UTF-8 string. AnyCR+LF
new line characters are replaced byLF
. - Define the label position on-screen with the
ParentOrigin
property of theTizen.NUI.BaseComponents.TextLabel
class:
label.ParentOrigin = ParentOrigin.TopLeft;
- Add the text label control to a window:
Window window = Window.Instance; window.Add(label);
Note A text label control can only be added to a window, or to a view that is on a window.
Selecting Fonts
You can request a specific font using the FontFamily
, the FontStyle
, and the PointSize
properties of the Tizen.NUI.BaseComponents.TextLabel [2] class:
FontFamily
is a string with the font family name, for example, FreeSerif.FontStyle
is a JSON-formatted string with the font style. The following list describes some possible keys and common values for them:- The
width
key defines the spacing between glyphs. Some commonly-used values includecondensed
,semiCondensed
,normal
,semiExpanded
, andexpanded
. - The
weight
key defines the thickness or darkness of the glyphs. Some commonly-used values includethin
,light
,normal
,regular
,medium
, andbold
. - The
slant
key defines whether to use italics. Some commonly-used values includenormal
orroman
,italic
, andoblique
.Usually
italic
is a separate font, whileoblique
is generated by applying a slant to thenormal
font.
- The
PointSize
is a float with the font size in points. To calculate the point size from the height in pixels, use the following formula, wherevertical_dpi
is the device's vertical resolution in dots per inch:
point_size = 72 * pixels / vertical_dpi
The following example code specifies font properties:
label.FontFamily = "FreeSerif"; PropertyMap fontStyle = new PropertyMap(); fontStyle.Add("weight", new PropertyValue("bold")); fontStyle.Add("slant", new PropertyValue("italic")); label.FontStyle = fontStyle; label.PointSize = 12.0f;
If no font is specified, styling defaults are used, and a suitable font for displaying the text label is automatically selected from the platform. However, it is possible that the automatically-selected font cannot render all the characters contained within the text label. For example, Latin fonts often do not provide Arabic glyphs.
Font Styles
Setting a font size programmatically is not ideal for applications which support multiple screen resolutions, and for platforms which support multiple logical font sizes. Also, any changes made to the platform font settings override sizes that have been programmatically set.
A more flexible approach is to prepare various JSON stylesheets and request a different style for each platform. The Tizen.NUI.NUIApplication [3] class has constructors which take a stylesheet argument:
class Example : NUIApplication Example example = new Example("example-path/example.json");
To change the font for standard text controls, the following JSON syntax can be used:
{ "styles": { "textlabel": { "fontFamily": "FreeSerif", "fontStyle": { "weight": "bold", "slant": "italic" }, "pointSize": 8 } } }
However, the same pointSize
is unlikely to be suitable for all text controls in an application. To define custom styles for existing controls, simply set a style name for each case, and provide a style override in a JSON stylesheet.
You can provide further flexibility for the various screens by mapping the logical size to a physical size in the stylesheet.
Aligning Text
To align the text in a text label:
- To enable text wrapping, use the
MultiLine
property of the Tizen.NUI.BaseComponents.TextLabel [2] class:label.MultiLine = true;
- To align the text horizontally to the beginning, center, or end of the available area, set the
HorizontalAlignment
property of theTizen.NUI.BaseComponents.TextLabel
class with the corresponding value of the Tizen.NUI.HorizontalAlignment [4] enumeration:
label.HorizontalAlignment = HorizontalAlignmentType.Begin; label.HorizontalAlignment = HorizontalAlignmentType.Center; label.HorizontalAlignment = HorizontalAlignmentType.End;
The following table illustrates the available values of the
Tizen.NUI.HorizontalAlignment
enumeration for both left-to-right (Latin) and right-to-left (Arabic) script.Alignment Left-to-right script example Right-to-left script example Begin
Center
End
The above examples assume that the label size is greater than the minimum required.
Using Decorations
For text decorations, the Tizen.NUI.BaseComponents.TextLabel [2] class provides several properties. All properties are writable and none are animatable.
Table: Text label properties
Property | Type | Description |
---|---|---|
Text |
string |
Text to display in UTF-8 forma. |
FontFamily |
string |
To use the font family. |
FontStyle |
Map |
To use the font style. |
PointSize |
float |
The font size in points. |
MultiLine |
bool |
Whether to use the multi line layout option. |
HorizontalAlignment |
string |
The horizontal line alignment. |
VerticalAlignment |
string |
The vertical line alignment. |
TextColor |
Color |
The color of the text. |
EnableMarkup |
bool |
Enable the Markup string, to process text within the Markup tags using DALi application. Note: By default, the Markup string is disabled. |
EnableAutoScroll |
bool |
Enable or disable the auto scrolling. |
AutoScrollSpeed |
int |
The scrolling speed is in pixels per second. |
AutoScrollLoopCount |
int |
Number of complete loops to scroll, when scrolling is enabled. |
AutoScrollGap |
float |
The gap before scrolling wraps. |
LineSpacing |
float |
The default spacing between lines in points. |
Underline |
Map |
The default underline parameters. |
Shadow |
Map |
The default shadow parameters. |
Emboss |
Map |
The default emboss parameters. |
Outline |
Map |
The default outline parameters. |
PixelSize |
float |
The size of font in pixels. |
Ellipsis |
bool |
Enable or disable ellipsis, if required. |
AutoScrollLoopDelay |
float |
Auto scroll loop delay. |
AutoScrollStopMode |
AutoScrollStopMode |
Auto-scroll stop mode. |
MatchSystemLanguageDirection |
bool |
The text alignment to match the direction of the system language. |
To use the decorations, simply set the applicable property:
- To change the color of the text, use the
TextColor
property:label.Text = "Red Text"; label.TextColor = Color.Red;
Figure: Colored text
- To add a drop shadow to the text, set the
Shadow
property:
window.BackgroundColor(Color.Blue); label1.Text = "Plain Text"; label2.Text = "Text with Shadow"; PropertyMap shadow = new PropertyMap(); shadow.Add("offset", new PropertyValue("1 1")); shadow.Add("color", new PropertyValue("black")); pixelLabel.Shadow = shadow; label3.Text = "Text with Bigger Shadow"; PropertyMap shadow = new PropertyMap(); shadow.Add("offset", new PropertyValue("2 2")); shadow.Add("color", new PropertyValue("black")); label3.Shadow = shadow; label4.Text = "Text with Color Shadow"; PropertyMap shadow = new PropertyMap(); shadow.Add("offset", new PropertyValue("1 1")); shadow.Add("color", new PropertyValue("red")); label4.Shadow = shadow;
Figure: Text with drop shadow (top), bigger shadow (middle), and color shadow (bottom)
Shadow parameters can also be set using a JSON string.
- To underline the text label, set the
Underline
property:
label1.Text = "Text with Underline"; PropertyMap textStyle = new PropertyMap(); textStyle.Add("enable", new PropertyValue("true")); label1.Underline = textStyle;
Figure: Text with underline
You can set the underline color and height using a property map:
label2.Text = "Text with Color Underline"; PropertyMap textStyle = new PropertyMap(); textStyle.Add("enable", new PropertyValue("true")); textStyle.Add("color", new PropertyValue(Color.Green)); label2.Underline = textStyle;
Figure: Text with color underline
By default, the underline height is based on the font metrics. For example, the underline text figures above have a 1 pixel height. You can also specify the height you want:
PropertyMap textStyle = new PropertyMap(); textStyle.Add("enable", new PropertyValue("true")); textStyle.Add("height", new PropertyValue(2.0f)); /// 2-pixel height label1.Underline = textStyle;
- To enable text scrolling, set the
EnableAutoScroll
property totrue
:
label.EnableAutoScroll = true;
Once enabled, scrolling continues until the loop count is reached, or
EnableAutoScroll
is set tofalse
. WhenEnableAutoScroll
is set tofalse
, the text completes its current scrolling loop before stopping.Figure: Auto-scrolling text
Auto-scrolling enables text to scroll within the text table. You can use it to show the full content, if the text exceeds the boundary of the control. You can also scroll text that is smaller than the control. To ensure that the same part of the text is not visible in more than one place at the same time, you can configure the gap between repetitions. The left-to-right text always scrolls left and the right-to-left text scrolls right.
The scroll speed, gap, and loop count can be set in the stylesheet, or through the following properties:
AutoScrollSpeed
property defines the scrolling speed in pixels/second.AutoScrollLoopCount
property specifies how many times the text completes a full scroll cycle. For example, if this property is 3, the text scrolls across the control 3 times and then stops. If this property is 0, scrolling continues untilEnableAutoScroll
is set tofalse
.Setting
EnableAutoScroll
tofalse
stops scrolling, whilst maintaining the original loop count value for the next start.AutoScrollGap
property specifies the amount of whitespace, in pixels, to display before the scrolling text is shown again. This gap is automatically increased if the given value is not large enough to prevent the same part of the text from being visible twice at the same time.
Auto-scrolling does not work with multi-line text; it is shown with the
Begin
alignment instead.
Using Markup Styling
You can use markup elements to change the style of the text. Since the text controls do not process markup elements by default, you must first set the EnableMarkup
property of the Tizen.NUI.BaseComponents.TextLabel [2] class to true
:
TextLabel label = new TextLabel("Hello World"); label.EnableMarkup = true;
The following markup elements are currently supported:
<color>
Sets the color for the characters inside the element, using the
value
attribute to define the color. The supported attribute values arered
,green
,blue
,yellow
,magenta
,cyan
,white
,black
, andtransparent
. Web colors and colors defined in 32-bit hexadecimal0xAARRGGBB
format are also supported.The following examples both create text in red:
label.Text = "<color value='red'>Red Text</color>"; /// Color coded with a text constant
label.Text = "<color value='0xFFFF0000'>Red Text</color>"); /// Color packed inside an ARGB hexadecimal value
<font>
Sets the font values for the characters inside the element.
The following attributes are supported:
family
: Font namesize
: Font size in pointsweight
: Font weightwidth
: Font widthslant
: Font slant
For more information on the attribute values, see Selecting Fonts.
The following example sets the font family and weight:
label.Text = "<font family='SamsungSans' weight='bold'>Hello world</font>";