TextLabel

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.

Figure: Text label example, positioned to top left

Text label example, positioned to top left

Creating a Text Label

To create a text label:

  1. Create an instance of the Tizen.NUI.BaseComponents.TextLabel 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 its Text property:

    TextLabel label = new TextLabel();
    label.Text = "Hello World";
    
    Note To display properly, the Text property must be a UTF-8 string. Any CR+LF new line characters are replaced by LF.
  2. Define the label position on-screen with the ParentOrigin property of the Tizen.NUI.BaseComponents.TextLabel class:
    label.ParentOrigin = ParentOrigin.TopLeft;
    
  3. 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 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 include condensed, semiCondensed, normal, semiExpanded, and expanded.
    • The weight key defines the thickness or darkness of the glyphs. Some commonly-used values include thin, light, normal, regular, medium, and bold.
    • The slant key defines whether to use italics. Some commonly-used values include normal or roman, italic, and oblique.

      Usually italic is a separate font, while oblique is generated by applying a slant to the normal font.

  • PointSize is a float with the font size in points. To calculate the point size from the height in pixels, use the following formula, where vertical_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 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 class:

    label.MultiLine = true;
    
  • To align the text horizontally to the beginning, center, or end of the available area, set the HorizontalAlignment property of the Tizen.NUI.BaseComponents.TextLabel class with the corresponding value of the Tizen.NUI.HorizontalAlignment 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 Latin script aligned to beginning Arabic script aligned to beginning
    Center Latin script aligned to center Arabic script aligned to center
    End Latin script aligned to end Arabic script aligned to 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 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

    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)

    Text with drop shadow

    Text with bigger shadow

    Text with color shadow

    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

    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

    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 to true:
    label.EnableAutoScroll = true;
    

    Once enabled, scrolling continues until the loop count is reached, or EnableAutoScroll is set to false. When EnableAutoScroll is set to false, the text completes its current scrolling loop before stopping.

    Figure: Auto-scrolling text

    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 until EnableAutoScroll is set to false.

      Setting EnableAutoScroll to false 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 class to true:

TextLabel label = new TextLabel("Hello World");
label.EnableMarkup = true;
Note The markup processor does not check for markup validity, and styles are rendered in a priority order. Incorrect or incompatible elements can cause the text to be badly rendered.

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 are red, green, blue, yellow, magenta, cyan, white, black, and transparent. Web colors and colors defined in 32-bit hexadecimal 0xAARRGGBB 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 name
    • size: Font size in points
    • weight: Font weight
    • width: Font width
    • slant: 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>";