The Dali::Toolkit::TextField class is a control providing a single-line editable text field.

Figure: TextField


In this tutorial, the following subjects are covered:

TextField events

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

Table: Dali::Toolkit::TextField input signals

Input signal Description
TextChangedSignal() Emitted when the text changes.
MaxLengthReachedSignal() Emitted when inserted text exceeds the maximum character limit.
InputStyleChangedSignal() Emitted when the input style is updated as a consequence of a change in the cursor position.

Creating a TextField

Before text has been entered, the Dali::Toolkit::TextField class can display a placeholder text. An alternative placeholder can be displayed when the TextField has keyboard focus. For example, a TextField used to enter a username can initially show the text Unknown Name, and the text Enter Name. when the cursor is visible.

TextField field = TextField::New();
Property::Map propertyMap;
propertyMap[ Text::PlaceHolder::Property::TEXT ] = "Unnamed Name";
propertyMap[ Text::PlaceHolder::Property::TEXT_FOCUSED ] = "Enter Name.";
field.SetProperty( TextField::Property::PLACEHOLDER, propertyMap );
Stage::GetCurrent().Add( field );

When the TextField is tapped, it automatically gets the keyboard focus. Key events enter the text, and the placeholder text is removed. After text has been entered, it can be retrieved from the TEXT property.

Property::Value fieldText = field.GetProperty( TextField::Property::TEXT );
std::string fieldTextString = fieldText.Get< std::string >();

Aligning Text

The Dali::Toolkit::TextField class displays a single-line of text, which scrolls if there is not enough space for the text displayed. If there is enough space, the text can be aligned horizontally to the beginning, end, or center of the available area:

// "CENTER" or "END"
field.SetProperty( TextField::Property::HORIZONTAL_ALIGNMENT, "BEGIN" );

TextField Properties

Using Decorations

For text decorations, the following TextField class properties are available. All properties are writable and none are animatable.

Table: TextField properties

Property Type Description
RENDERING_BACKEND INTEGER The type or rendering e.g. bitmap-based
TEXT STRING The text to display in UTF-8 format
PLACEHOLDER_TEXT STRING The text to display when the TextField is empty and inactive
PLACEHOLDER_TEXT_FOCUSED STRING The text to display when the TextField is empty with key-input focus
FONT_FAMILY STRING The requested font family
FONT_STYLE STRING or MAP The requested font style
POINT_SIZE FLOAT The size of font in points
MAX_LENGTH INTEGER The maximum number of characters that can be inserted
EXCEED_POLICY INTEGER Specifies how the text is truncated when it does not fit
HORIZONTAL_ALIGNMENT STRING The line horizontal alignment
VERTICAL_ALIGNMENT STRING The line vertical alignment
TEXT_COLOR VECTOR4 The text color
PLACEHOLDER_TEXT_COLOR VECTOR4 The placeholder-text color
PRIMARY_CURSOR_COLOR VECTOR4 The color to apply to the primary cursor
SECONDARY_CURSOR_COLOR VECTOR4 The color to apply to the secondary cursor
ENABLE_CURSOR_BLINK BOOLEAN Whether the cursor should blink or not
CURSOR_BLINK_INTERVAL FLOAT The time interval in seconds between cursor on/off states
CURSOR_BLINK_DURATION FLOAT The cursor will stop blinking after this number of seconds
GRAB_HANDLE_IMAGE STRING The image to display for the grab handle
GRAB_HANDLE_PRESSED_IMAGE STRING The image to display when the grab handle is pressed
SCROLL_THRESHOLD FLOAT Horizontal scrolling will occur if the cursor is this close to the control border
SCROLL_SPEED FLOAT The scroll speed in pixels per second
SELECTION_HANDLE_IMAGE_LEFT MAP The image to display for the left selection handle
SELECTION_HANDLE_IMAGE_RIGHT MAP The image to display for the right selection handle
SELECTION_HANDLE_PRESSED_IMAGE_LEFT MAP The image to display for the left selection handle marker
SELECTION_HANDLE_PRESSED_IMAGE_RIGHT MAP The image to display for the right selection handle marker
SELECTION_HANDLE_MARKER_IMAGE_LEFT MAP The image to display for the left selection handle marker
SELECTION_HANDLE_MARKER_IMAGE_RIGHT MAP The image to display for the right selection handle marker
SELECTION_HIGHLIGHT_COLOR VECTOR4 The color of the selection highlight
DECORATION_BOUNDING_BOX RECTANGLE The decorations (handles etc) will positioned within this area on-screen
INPUT_METHOD_SETTINGS MAP The settings to relating to the System's Input Method, Key and Value
INPUT_COLOR VECTOR4 The color of the new input text
ENABLE_MARKUP BOOLEAN Whether the mark-up processing is enabled
INPUT_FONT_FAMILY STRING The font's family of the new input text
INPUT_FONT_STYLE MAP The font's style of the new input text
INPUT_POINT_SIZE FLOAT The font's size of the new input text in points
UNDERLINE MAP The default underline parameters
INPUT_UNDERLINE MAP The underline parameters of the new input text
SHADOW MAP The default shadow parameters
INPUT_SHADOW MAP The shadow parameters of the new input text
EMBOSS MAP The default emboss parameters
INPUT_EMBOSS MAP The emboss parameters of the new input text
OUTLINE MAP The default outline parameters
INPUT_OUTLINE MAP The outline parameters of the new input text
HIDDEN_INPUT_SETTINGS MAP Hides the input characters and instead shows a default character for password or pin entry
PIXEL_SIZE FLOAT The size of font in pixels
PLACEHOLDER MAP Sets the placeholder : text, color, font family, font style, point size, and pixel size
ELLIPSIS BOOLEAN Whether we should show the ellipsis if it is required

To change the color of the text, use the TEXT_COLOR property. An alternative color can be used for placeholder text by setting the PLACEHOLDER_TEXT_COLOR property. Unlike the Actor::COLOR property, these properties do not affect child actors added to the TextField.

field.SetProperty( TextField::Property::TEXT_COLOR, Color::CYAN );
field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_COLOR, Color::BLACK );