Entry

This feature is supported in wearable applications only.

The entry component is a box where the user can enter text. It supports the following features:

Text wrapping
Multiline
Scrolling
Formatted markup text
Password mode
Filtering text
Read/write from a file
Theme style overrides

For more information, see the Entry API.

Figure: Entry component

Entry component

Figure: Entry component

Entry component

Figure: Entry hierarchy

Entry hierarchy

Adding an Entry Component

Create the entry component with the elm_entry_add() function, and set the text inside it with the elm_entry_entry_set() function:

Evas_Object *entry, *parent;

entry = elm_entry_add(parent);
elm_entry_entry_set(entry, "A short text.");

Using the Text Editor

To use the text editor:

Append text to the end of existing content:
```
elm_entry_entry_append(entry, "END");
```
Insert text at the current cursor position:
```
elm_entry_entry_insert(entry, "CURSOR");
Eina_Bool Empty = elm_entry_is_empty(entry);
```
Call the elm_entry_is_empty() function to see whether the entry is empty. Here, the boolean variable Empty returns EINA_FALSE.
Make the entry uneditable by the user. By default, the user can enter text in the entry component when it is in focus.
```
elm_entry_editable_set(entry, EINA_FALSE);
```
Note

It is still possible to use the previous functions to modify the text of a non-editable entry.

Note
It is still possible to use the previous functions to modify the text of a non-editable entry.

Setting the Password Mode

When dealing with password content, the password mode activates to hide what the user is typing. In this mode, the display of any text is replaced by asterisks (*), and the entry is single line (there is no line wrap).

elm_entry_password_set(entry, EINA_TRUE);

Entry Line Modes and Wrapping

The entry component has 2 line modes:

Single line mode
Multiline mode

To use entry line modes:

Set the entry to the single line mode:
```
elm_entry_single_line_set(entry, EINA_TRUE);
```
In this mode, the text does not wrap when reaching the edge, but the entry grows horizontally instead. Pressing the Enter key in this mode generates an activate event instead of adding a new line.
Set the entry to the multiline mode (single line off), and the text wraps at the end of the entry and pressing Enter creates a new line:
```
elm_entry_single_line_set(entry, EINA_FALSE);
elm_entry_line_wrap_set(entry, ELM_WRAP_WORD);
```
In multiline entries, the elm_entry_line_wrap_set() function provides a way to cut the text implicitly into a new line when it reaches the far edge of the UI component. The following wrap modes are available:
- ELM_WRAP_NONE: No wrap
- ELM_WRAP_CHAR: Wrap between characters
- ELM_WRAP_WORD: Wrap in allowed wrapping points (as defined in the unicode standard)
- ELM_WRAP_MIXED: Word wrap, and if that fails, char wrap

Selecting Text

To select text:

Select all the content of the entry component:
```
elm_entry_select_all(entry);
```
Deselect the current selection:
```
elm_entry_select_none(entry);
```
Select part of the text with the elm_entry_select_region_set() function. The following code selects the first 20 characters of the entry content.
```
elm_entry_select_region_set(entry, 0, 20);
```

Retrieve the currently selected text in an entry:

const char *selection;

selection = elm_entry_selection_get(entry);

If the entry text is empty, the elm_entry_selection_get() function returns NULL.

To manage the selection:

Copy or cut the selection to the clipboard.
```
elm_entry_selection_cut(entry);
```
Paste the selection in the same or a different entry.
```
elm_entry_selection_paste(entry);
```

Controlling the Cursor

The cursor represents the current position in the entry, where the next action, for example, text insertion or deletion, is done. Usually, the cursor is represented as a blinking character, but its appearance depends on the theme configuration. The cursor position can be modified by using several functions.

Move the cursor to the beginning of the entry:
```
elm_entry_cursor_begin_set(entry);
```
Move the cursor to the end of the entry:
```
elm_entry_cursor_end_set(entry);
```

Move the cursor 1 line down or up:

elm_entry_cursor_down(entry);
elm_entry_cursor_up(entry);

Move the cursor 1 character to the left or right:

elm_entry_cursor_prev(entry);
elm_entry_cursor_next(entry);

Set the cursor at a specific position (15th character, for example):
```
elm_entry_cursor_pos_set(entry, 15);
```

The following example shows how to start a selection at the current cursor position, move 5 characters to the right and end the selection.

elm_entry_cursor_selection_begin(entry);

for (i = 0; i < 5; i++)
{
   elm_entry_cursor_next(entry);
}

elm_entry_cursor_selection_end(entry);

Formatting Text

Text within an entry can be formatted by using markups tags that are defined in the theme. The following markups are available in the default theme:

: Inserts a line break.
<ps>: Inserts a paragraph separator. This is preferred over line breaks.
<tab>: Inserts a tab.
...: Emphasis. Sets the oblique style for the enclosed text.
...: Sets the bold style for the enclosed text.
<link>...</link>: Underlines the enclosed text.
<hilight>...</hilight>: Highlights the enclosed text.

Using Special Markups

Special markups can be added within the text of the entry:

<a href = ..>...</a>: Anchors
<item size = .. vsize = .. href = ..>...</item>: Items

The anchors generate an anchor,clicked signal when the user clicks on them. The href attribute is used to identify the anchor. It also reacts to the anchor,in (mouse in), anchor,out (mouse out), anchor,down (mouse down), and anchor,up (mouse up) events.

The item markup provides a way to insert any Evas_Object in the text. The Evas_Object name has to be specified in the href attribute.

Overriding Style

To tweak the style of the text within the entry component, it is possible to override parts of the theme style to the textblock object using the elm_entry_text_style_user_push() function. This function pushes a new style on top of the user style stack that overrides the current style. Remove the style in the top of user style stack with the elm_entry_text_style_user_pop() function.

Filtering Text

Text within an entry can be filtered in size. The following example sets the maximum number of characters allowed in the entry to 8.

static Elm_Entry_Filter_Limit_Size 
limit_size = 
{
   .max_char_count = 8,
   .max_byte_count = 0
};

// Append a new callback to the list, this function is called each time
// a text is inserted in the entry. Pass the limit_size struct previously
// created to set the maximum number of characters allowed to 8
 
elm_entry_markup_filter_append(entry, elm_entry_filter_limit_size, limit_size);

The content can be filtered by passing an Elm_Entry_Filter_Accept_Set structure. This structure contains the accepted characters and rejected characters. The following example shows how to reject the '+', '-', '*', and '/' characters.

static Elm_Entry_Filter_Accept_Set 
accept_set = 
{
   .accepted = NULL,
   .rejected = "+*-/"
};

elm_entry_markup_filter_append(entry, elm_entry_filter_accept_set, accept_set);

Loading and Saving Files

The entry content can be saved to a file (/tmp/test.txt, for example).

// Set the file in which the entry text is saved. This function
// implicitly loads the existing file content 
elm_entry_file_set(entry, "/tmp/test.txt", ELM_TEXT_FORMAT_MARKUP_UTF8);

Autosave is activated by default and changes are written back to the file after a short delay. This feature can be deactivated and you can manually save the content when needed.

// Disable autosaving 
elm_entry_autosave_set(entry, EINA_FALSE);

// Trigger saving when needed 
elm_entry_file_save(entry);

Using Entry Theme Content

2 content parts of the default theme are available: icon and end. The following example shows how to set an icon in the end content part.

Evas_Object *icon;

ic = elm_icon_add(entry);
elm_image_file_set(ic, "icon.png", NULL);
elm_object_part_content_set(entry, "end", icon);

Using Entry Theme Texts

The default theme allows the use of the following text parts:

elm.text: Text of the entry
elm.guide: Placeholder of the entry

The following example shows how to set the placeholder text of the entry to Hello World.

elm_object_part_text_set(entry, "elm.guide", "Hello World");

Using Entry Callbacks

The entry component emits the following signals:

aborted: The escape key is pressed on a single line entry.
activated: The enter key is pressed on a single line entry.
anchor,clicked: An anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
anchor,down: Mouse button is pressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
anchor,hover,opened: The anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
anchor,in: Mouse cursor is moved into an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
anchor,out: Mouse cursor is moved out of an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
anchor,up: Mouse button is unpressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
changed: The text within the entry is changed.
changed,user: The text within the entry is changed because of user interaction. event_info points to an object of the type Edje_Entry_Change_Info.
clicked: The entry is clicked (mouse press and release).
clicked,double: The entry is double clicked.
clicked,triple: The entry is triple clicked.
cursor,changed: The cursor position is changed.
cursor,changed,manual: The cursor position is changed manually.
focused: The entry receives focus. event_info points to an object of the type Elm_Focus_Info.
unfocused: The entry loses focus.
language,changed: Program language is changed.
longpressed: A mouse button is pressed and held for a couple of seconds.
maxlength,reached: A maximum length is reached.
preedit,changed: The preedit string is changed.
press: A mouse button is pressed on the entry.
redo,request: The request is redone.
selection,changed: The current selection is changed.
selection,cleared: The current selection is cleared.
selection,copy: A copy of the selected text into the clipboard is requested.
selection,cut: A cut of the selected text into the clipboard is requested.
selection,paste: A paste of the clipboard contents is requested.
selection,start: A selection is begun and no previous selection exists.
text,set,done: The whole text is set to the entry.
theme,changed: The theme is changed.
undo,request: The request is undone.

For signals, where event_info has not been explicitly described, it is set to NULL.

The following example shows how to register a callback to the focused signal.

{
   evas_object_smart_callback_add(entry, "focused", focused_cb, data);
}

// Callback function for the "focused" signal
// This callback is called when the entry receive the focus
void 
focused_cb(void *data, Evas_Object *obj, void *event_info)
{
   dlog_print(DLOG_INFO, LOG_TAG, "Entry focused\n");
}

Note
Except as noted, this content is licensed under LGPLv2.1+.