Text

There are three Text components to display and edit text on the screen:

• The TextLabel displays a short text string.

• The TextField is to edit a single line text.

• The TextEditor is to edit multi-line text.

TextLabel

TextLabel is a class that displays a short text string. The Tizen.NUI.BaseComponents namespace contains the class.

The TextLabel class is lightweight, non-editable, and do not respond to user input. Text labels support multiple languages and scripts including right-to-left scripts such as Arabic. For more information on how to display a text using a text label, see NUI Hello World Tutorial.

Figure: Text label positioned to top left

Create TextLabel

To create a text label:

1. Create an instance of the TextLabel class and define the label text as a parameter. To make text visible, set the TextColor property to Color.White:

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   TextLabel label = new TextLabel("Hello World");
   label.TextColor = Color.White;
   Window.Instance.Add(label);
   

   You can also create the TextLabel class instance separately and define the label text by setting its Text property:

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   TextLabel label = new TextLabel();
   label.Text = "Hello World";
   

   Caution

   To display the label 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 TextLabel class:

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   TextLabel label = new TextLabel("Hello World");
   label.ParentOrigin = ParentOrigin.TopLeft;
   

Set font of TextLabel

You can request a specific font using the FontFamily, the FontStyle, and the PointSize properties of the TextLabel class:

• FontFamily is a string with the font family name, such as 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 width occupied by each glyph. 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, roman, italic, and oblique.

    Note

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

• PointSize is a type float. To calculate the point size from the height in pixels, use the following formula, where vertical_dpi is the vertical resolution of a device in dots per inch:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  point_size = 72 * pixels / vertical_dpi;
  

The following example code specifies the font properties:

Figure: Text with specifed font properties

                
C#
                

                    
Copy
                    

                
            
TextLabel label = new TextLabel("Hello world");
label.TextColor = Color.White;

label.FontFamily = "FreeSerif";
PropertyMap fontStyle = new PropertyMap();
fontStyle.Add("width", new PropertyValue("expanded"));
fontStyle.Add("weight", new PropertyValue("bold"));
fontStyle.Add("slant", new PropertyValue("italic"));
label.FontStyle = fontStyle;
label.PointSize = 12.0f;

Window.Instance.Add(label);

If no font is specified, default styles are used, and a suitable font for displaying the text label is automatically selected from the platform. However, the automatically-selected font may not render all the characters contained within the text label. For example, Latin fonts often do not provide Arabic glyphs.

Set font styles of TextLabel

Setting a font size programmatically is not ideal for applications that support multiple screen resolutions, and for platforms that support multiple logical font sizes. In addition, making systemwide changes to your font settings override the font sizes that have been programmatically set.

A more flexible approach is to prepare various JSON stylesheets and request a different style for each platform. To change the font style for standard text controls, create the theme.json file in the resources directory and use the following JSON syntax:

                
C#
                

                    
Copy
                    

                
            
{
    "styles": {
      "CustomLabel": {
        "fontFamily": "FreeSerif",
        "fontStyle": {
          "width": "expanded",
          "weight": "bold",
          "slant": "italic"
        },
        "pointSize": 12,
        "textColor": [ 1, 1, 1, 1 ]
      }
    }
}

StyleManager provides the ApplyTheme method, where path to stylesheet is passed. Since stylesheet is loaded, CustomLabel style can be used on the created label by using the SetStyleName method of TextLabel:

                
C#
                

                    
Copy
                    

                
            
Tizen.NUI.StyleManager.Get().ApplyTheme(DirectoryInfo.Resource + "/theme.json");
TextLabel label = new TextLabel("Hello World");
label.SetStyleName("CustomLabel");
Window.Instance.Add(label);

However, the same pointSize is unlikely to be suitable for all text controls in an application. To define custom styles for existing controls, 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.

Align text in TextLabel

To align the text in a text label:

• To enable text wrapping, use the MultiLine property of the TextLabel class:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  label.MultiLine = true;
  

• To align the text horizontally to the beginning, center, or end of the available area, set the HorizontalAlignment property of the TextLabel class with the corresponding value of the HorizontalAlignment enumeration:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  label.HorizontalAlignment = HorizontalAlignment.Begin;
  label.HorizontalAlignment = HorizontalAlignment.Center;
  label.HorizontalAlignment = HorizontalAlignment.End;
  

  The following table summarizes the available values of the HorizontalAlignment enumeration for both left-to-right (Latin) and right-to-left (Arabic) script. In addition, for the illustrated examples, it is assumed that the label size is greater than the minimum required size:

  You can scroll this table.

  Alignment	Left-to-right script example	Right-to-left script example
  Begin
  Center
  End

UTF16 or UTF32 character encoding

The text property can accept UTF16 or UTF32 character encoding:

                
C#
                

                    
Copy
                    

                
            
TextLabel title = new TextLabel();
title.Text = "\U0001f601";      //UTF-32
title.Text += "\ud83d\ude01";   //UTF-16

Use decorations for TextLabel

To use the text-decoration, set the applicable property:

• To add a drop shadow to the text, set the Shadow property:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  TextLabel label = new TextLabel("Text with Color Shadow");
  label.TextColor = Color.White;
  PropertyMap shadow = new PropertyMap();
  shadow.Add("offset", new PropertyValue(new Vector2(2, 2)));
  shadow.Add("color", new PropertyValue(Color.Red));
  label.Shadow = shadow;
  Window.Instance.Add(label);
  

  Figure: Text with red shadow

  

  Shadow parameters can also be set using a JSON string.

• To underline the text label, set the Underline property:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  TextLabel label = new TextLabel("Text with Underline");
  label.TextColor = Color.White;
  PropertyMap underline = new PropertyMap();
  underline.Add("enable", new PropertyValue("true"));
  label.Underline = underline;
  Window.Instance.Add(label);
  

  By default, the underline height is based on the font metrics and the minimum height is one pixel. The underline color is based on the text color. For example, the following text figures are in one pixel height and the color is the same as the text color:

  Figure: Text with underline

  

  You can set the underline color and height using a property map:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  TextLabel label = new TextLabel("Text with Color Underline");
  label.TextColor = Color.White;
  PropertyMap underline = new PropertyMap();
  underline.Add("enable", new PropertyValue("true"));
  underline.Add("color", new PropertyValue(Color.Green));
  underline.Add("height", new PropertyValue(2.0f)); /// 2-pixel height
  label.Underline = underline;
  Window.Instance.Add(label);
  

  Figure: Text with colored underline

  

• To outline the text label, set the Outline property:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  TextLabel label = new TextLabel("Text with Color Outline");
  label.TextColor = Color.White;
  PropertyMap outline = new PropertyMap();
  outline.Add("color", new PropertyValue(Color.Red));
  outline.Add("width", new PropertyValue(2.0f)); /// 2-pixel width
  label.Outline = outline;
  Window.Instance.Add(label);
  

  Figure: Text with red outline

  

• To enable text scrolling, set the EnableAutoScroll property to true:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  label.EnableAutoScroll = true;
  

  After scrolling is 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 it stops scrolling.

  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 always scrolls right.

  You can set the scroll speed, gap, and loop count in the stylesheet or using the following properties:

  • AutoScrollSpeed property defines the scrolling speed in pixels per second.
  • AutoScrollLoopCount property specifies the number of times the text completes a full scroll cycle. For example, if this property is set to 3, the text scrolls across the control three times and then stops. If this property is set to 0, the text scroll continues until EnableAutoScroll is set to false.
    • If EnableAutoScroll is set to false, the text stops to scroll and maintains the original loop count value for the next start.
  • AutoScrollGap property specifies the amount of whitespace in pixels. The whitespace gets displayed before the scrolling text appears again. This gap automatically increases, if the given value is not large enough to prevent the same part of the text from appearing twice at the same time.

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  TextLabel label = new TextLabel("Hello World");
  label.EnableAutoScroll = true;
  label.AutoScrollSpeed = 100; // 100px per second
  label.AutoScrollLoopCount = 0; //infite loop
  label.AutoScrollGap = 250;
  label.TextColor = Color.White;
  Window.Instance.Add(label);
  

  Auto-scrolling does not work with multi-line text; it is shown with the Begin alignment instead.

Use markup styling to style TextLabel

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 TextLabel class to true:

                
C#
                

                    
Copy
                    

                
            
TextLabel label = new TextLabel();
label.EnableMarkup = true;

Note

The markup processor does not check for markup validity, and styles are rendered in priority order. Incorrect or incompatible elements can cause the text to be rendered incorrectly.

The following markup elements are currently supported:

• <color>

  Sets the color for the characters inside the element. Use 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 represented in 32-bit hexadecimal 0xAARRGGBB format are also supported.

  The following examples show text in red color:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  label.Text = "<color value='red'>Red Text</color>"; /// Color coded with a text constant
  

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  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 Select Font.

  The following example sets the font family and weight:

  
                  
  C#
                  
  
                      
  Copy
                      
  
                  
              
  label.Text = "<font family='SamsungSans' weight='bold'>Hello world</font>";
  

Use markup to represent encoded characters

Markup text is not allowed to contain some characters unless they are representing tags or entities such as “<”, “>” or “&”. To include these characters as a part of the text, you must use reserved entities such as <, >, or &. The following example uses reserved entities:

                
C#
                

                    
Copy
                    

                
            
TextLabel label = new TextLabel();
label.EnableMarkup = true;
label.Text = "<>"; //less-than greater-than

Markup text can include character with UTF32 representation as entities contain decimal or hexadecimal values. To represent decimal value, you can use: &# + utf32_decimal_value + ; To represent hexadecimal value, you can use: &#x + utf32_hexadecimal_value + ; The following example uses UTF32 entities:

                
C#
                

                    
Copy
                    

                
            
TextLabel label = new TextLabel();
label.EnableMarkup = true;
label.Text = "☺ ☺"; //smile-face

TextLabel properties

For text decorations, the TextLabel class provides several properties. All the properties are editable and none of them are animatable:

TextField

The TextField class provides a control that allows single line editable text field.

Figure: TextField

TextField events

The following table lists the basic signals provided by the TextField class:

Create TextField

Before the text is entered, the TextField class displays a placeholder text. An alternative placeholder is displayed when TextField gets the keyboard focus. For example, the TextField that is used to enter a username initially displays the text Unknown Name and then the text Enter Name, when the cursor is visible.

The following example illustrates the creation of a TextField object:

                
C#
                

                    
Copy
                    

                
            
Window window = Window.Instance;
TextField field = new TextField();
field.BackgroundColor = Color.White;
field.PlaceholderText = "Unknown Name";
field.PlaceholderTextFocused = "Enter Name";
window.Add(field);

When the TextField is tapped, it automatically gets the keyboard focus. Key events correspond to entering the text. Additionally, the placeholder text is removed as soon as the text is entered. The text entered can be retrieved by using the Text property:

                
C#
                

                    
Copy
                    

                
            
string fieldTextString = field.Text;

Use Placeholder property in TextField

If you want to decorate the placeholder text in more detail, you can use Placeholder property:

                
C#
                

                    
Copy
                    

                
            
TextField field = new TextField();
field.BackgroundColor = Color.White;
PropertyMap placeholder = new PropertyMap();
placeholder.Add("text", new PropertyValue("Placeholder TextField"));
placeholder.Add("textFocused", new PropertyValue("Placeholder TextField Focused"));
placeholder.Add("color", new PropertyValue(Color.CadetBlue));
placeholder.Add("fontFamily", new PropertyValue("Serif"));
placeholder.Add("pointSize", new PropertyValue(25.0f));
field.Placeholder = placeholder;

Align text in TextField

The TextField class displays a single line of text that scrolls in either of the following case:

• If there is not enough space for the text to get displayed.

• If there is enough space, the text is aligned horizontally to the beginning, end, or center of the available area.

The following example illustrates text alignment:

                
C#
                

                    
Copy
                    

                
            
// Begin, Center, or End
field.HorizontalAlignment = HorizontalAlignment.Begin;

Use HiddenInputSettings property in TextField

The TextField class can substitute the input text using the HiddenInputSettings property.

To set the HiddenInputSettings for detailed options, you can use HiddenInputProperty and HiddenInputModeType.

The following example illustrates how to use the HiddenInputSettings property in a TextField:

                
C#
                

                    
Copy
                    

                
            
TextField field = new TextField();
field.PlaceholderText = "Input Password";
field.BackgroundColor = Color.White;
PropertyMap hiddenInputSettings = new PropertyMap();
hiddenInputSettings.Add(HiddenInputProperty.Mode, new PropertyValue((int)HiddenInputModeType.ShowLastCharacter));
hiddenInputSettings.Add(HiddenInputProperty.ShowLastCharacterDuration, new PropertyValue(500));
hiddenInputSettings.Add(HiddenInputProperty.SubstituteCharacter, new PropertyValue(0x2A));
field.HiddenInputSettings = hiddenInputSettings;

Figure: HiddenInputSettings

Use Input properties in TextField

To change the text settings for new input text, you can use the Input properties of the TextField class, such as InputColor, InputPointSize, and so on.

To use these properties there are some specific conditions. For instance, you can use these properties either when the TextChanged event occurs or when the Clicked event of button occurs.

The following example illustrates how to use the InputColor property in a TextField:

                
C#
                

                    
Copy
                    

                
            
TextField field = new TextField();
field.TextChanged += (obj, e) => {
    e.TextField.InputColor = Color.Yellow;
};

Decoration of grab handle and selection handle

To decorate the grab handle and selection handle, you can use the GrabHandleImage, SelectionHandleImageLeft, and SelectionHandleImageRight properties.

Also, you can change the color of the handle using the GrabHandleColor property.

The following example illustrates how to decorate the grab handle and selection handle in a TextField:

                
C#
                

                    
Copy
                    

                
            
TextField field = new TextField();
field.Text = "TextField Selection";
field.BackgroundColor = Color.White;
field.GrabHandleImage = "handle_down.png"; /// Set your Image path
field.GrabHandleColor = Color.Red;
PropertyMap leftImage = new PropertyMap();
leftImage.Add("filename", new PropertyValue("handle_downleft.png")); /// Set your Image path
field.SelectionHandleImageLeft = leftImage;
PropertyMap rightImage = new PropertyMap();
rightImage.Add("filename", new PropertyValue("handle_downright.png")); /// Set your Image path
field.SelectionHandleImageRight = rightImage;

Images of other properties can also change in the same way as in example, such as SelectionHandlePressedImageLeft, SelectionHandleMarkerImageLeft, and so on.

Figure: Decoration of SelectionHandle

TextField properties

To change the look and feel of the text and text related elements, use the TextField properties.

Use decorations for TextField

For text decorations, the following TextField class properties are available. All properties are editable and none of them are animatable:

TextEditor

The TextEditor class provides a control that allows multi-line text editing. It is similar to the TextField control, where different formatting can be applied to different parts of the text. For example, you can change the font color, font style, point size, and font family.

The TextEditor also supports markup, and text can be scrolled vertically within it.

Figure: TextEditor

TextEditor events

The following table lists the basic signals provided by the TextEditor class:

Create TextEditor

The following example shows how to create a TextEditor object:

                
C#
                

                    
Copy
                    

                
            
// Create a TextEditor instance
TextEditor editor = new TextEditor();
editor.Position2D = new Position2D(10, 10);
editor.Size2D = new Size2D(400, 400);
editor.BackgroundColor = Color.Red;
editor.PointSize = 10;
editor.TextColor = Color.White;
editor.Text = "This is a multiline text.\n I can write several lines.\n";
Window.Instance.Add(editor);

TextEditor properties

You can modify the TextEditor appearance and behavior using its properties.

The following table lists the available TextEditor properties:

Related information

• Examples
  • TvTextSample
• Dependencies
  • Tizen 4.0 and Higher