Table of Contents

Widgets Menu

Entry Widgets

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

Table of Contents

Adding an Entry

The entry widget is created with the elm_entry_add() function, and the text inside the entry can be set with elm_entry_entry_set(). 

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

By default, entries are:

Using Text Edition

We can also append text to the end of existing content, 

elm_entry_entry_append(entry, "END");

or insert text at the current cursor position. 

elm_entry_entry_insert(entry, "CURSOR");
Eina_Bool Empty = elm_entry_is_empty(entry);

Call elm_entry_is_empty() to see whether the entry is empty. Here, the boolean variable Empty will return EINA_FALSE.

By default, the user can enter text in the entry widget when it is in the focus. We can prevent the user from editing text if needed. 

elm_entry_editable_set(entry, EINA_FALSE);
It is still possible to use the previous functions to modify the text of a non-editable entry.

Setting 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 widget has two line modes:

First, we set the entry in 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.

When the entry is set to multiline mode (single line off), 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, elm_entry_line_wrap_set() provides a way to cut the text implicitly into a new line when it reaches the far edge of the widget. The following wrap modes are available:

Selecting Text

Text selections can be made with different functions. This selects all the content of the entry widget. 

elm_entry_select_all(entry);

We can drop the current selection with 

elm_entry_select_none(entry);

To select part of the text, use elm_entry_select_region_set(). The code below selects the first twenty characters of the entry content. 

elm_entry_select_region_set(entry, 0, 20);

Current selected text within the entry can be retrieved like this. 

const char *selection;
 
selection = elm_entry_selection_get(entry);

If the entry text is empty, elm_entry_selection_get() will return NULL.

We can copy or cut the selection to the clipboard. (There is an example of a cut below.) 

elm_entry_selection_cut(entry);

This selection can be pasted in the same or a different entry. 

elm_entry_selection_paste(entry);

Controlling Cursor

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

It can be moved to the beginning of the entry, 

elm_entry_cursor_begin_set(entry);

or to the end. 

elm_entry_cursor_end_set(entry);

It can be moved one line down or up. 

elm_entry_cursor_down(entry);
elm_entry_cursor_up(entry);

It can also be moved one character to the left or right, 

elm_entry_cursor_prev(entry);
elm_entry_cursor_next(entry);

or set at a specific position (15th character, for example). 

elm_entry_cursor_pos_set(entry, 15);

We can start a selection at the current cursor position, move five 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

The markup tags supported by the Entry are defined by the theme, but even when writing new themes or extensions it's a good idea to stick to a sane default, to maintain coherency and avoid application breakages. Currently defined by the default theme are the following tags:

Entry also support tags for code syntax highlight. Note that this does not mean that the entry will automatically perform code highlight, application are responsible of applying the correct tag to code blocks. The default theme define the following tags:

Using Special Markups

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

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 widget, it is possible to override parts of the theme style to the textblock object by using elm_entry_text_style_user_push(). 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 elm_entry_text_style_user_pop().

Filtering Text

Text within an entry can be filtered in size. Here we set the maximum number of characters allowed in the entry to eight. 

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 will be 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);

Content can be filtered by passing an Elm_Entry_Filter_Accept_Set structure. This structure contains the accepted characters and rejected characters. In the example below we 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);

File Load/Save

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

// Set the file in which the entry text will be 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 we 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

Two content parts of the default theme are available: “icon” and “end”. Here we 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:

This is how to set the placeholder text of the entry to “Hello World”. 

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

Using Entry Callbacks

Entry widget emits the following signals, besides the ones sent from Layout:

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

As an example, we 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
static void
_focused_cb(void *data, Evas_Object *obj, void *event_info)
{
  printf("Entry focused\n");
}


A Simple Editing example

Widgets Menu