Data Structures | Typedefs | Enumerations | Functions
Entry

Data Structures

struct  _Elm_Entry_Anchor_Info
 The info sent in the callback for the "anchor,clicked" signals emitted by entries. More...
 
struct  _Elm_Entry_Anchor_Hover_Info
 The info sent in the callback for "anchor,clicked" signals emitted by the Anchor_Hover widget. More...
 
struct  _Elm_Entry_Filter_Limit_Size
 Data for the elm_entry_filter_limit_size() entry filter. More...
 
struct  _Elm_Entry_Filter_Accept_Set
 Data for the elm_entry_filter_accept_set() entry filter. More...
 

Typedefs

typedef struct _Elm_Entry_Anchor_Info Elm_Entry_Anchor_Info
 The info sent in the callback for the "anchor,clicked" signals emitted by entries.
 
typedef struct _Elm_Entry_Anchor_Hover_Info Elm_Entry_Anchor_Hover_Info
 The info sent in the callback for "anchor,clicked" signals emitted by the Anchor_Hover widget.
 
typedef struct _Elm_Entry_Context_Menu_Item Elm_Entry_Context_Menu_Item
 Type of contextual item that can be added in to long press menu. More...
 
typedef Evas_Object *(* Elm_Entry_Item_Provider_Cb) (void *data, Evas_Object *entry, const char *item)
 This callback type is used to provide items. More...
 
typedef void(* Elm_Entry_Filter_Cb) (void *data, Evas_Object *entry, char **text)
 This callback type is used by entry filters to modify text. More...
 
typedef Edje_Entry_Change_Info Elm_Entry_Change_Info
 This corresponds to Edje_Entry_Change_Info. More...
 
typedef struct _Elm_Entry_Filter_Limit_Size Elm_Entry_Filter_Limit_Size
 Data for the elm_entry_filter_limit_size() entry filter.
 
typedef struct _Elm_Entry_Filter_Accept_Set Elm_Entry_Filter_Accept_Set
 Data for the elm_entry_filter_accept_set() entry filter.
 

Enumerations

Functions

Eina_Bool elm_config_context_menu_disabled_get (void)
 Get enable status of context menu disabled. More...
 
void elm_config_context_menu_disabled_set (Eina_Bool disabled)
 Enable or disable the context menu in entries. More...
 
EINA_DEPRECATED void elm_entry_scrollbar_policy_set (Evas_Object *obj, Elm_Scroller_Policy h, Elm_Scroller_Policy v)
 This sets the entry's scrollbar policy (i.e. More...
 
EINA_DEPRECATED void elm_entry_bounce_set (Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce)
 This enables/disables bouncing within the entry. More...
 
EINA_DEPRECATED void elm_entry_bounce_get (const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce)
 Get the bounce mode. More...
 
char * elm_entry_markup_to_utf8 (const char *s)
 This converts a markup (HTML-like) string into UTF-8. More...
 
char * elm_entry_utf8_to_markup (const char *s)
 This converts a UTF-8 string into markup (HTML-like). More...
 
void elm_entry_filter_limit_size (void *data, Evas_Object *entry, char **text)
 Filter inserted text based on user defined character and byte limits. More...
 
void elm_entry_filter_accept_set (void *data, Evas_Object *entry, char **text)
 Filter inserted text based on accepted or rejected sets of characters. More...
 
const char * elm_entry_context_menu_item_label_get (const Elm_Entry_Context_Menu_Item *item)
 Get the text of the contextual menu item of entry. More...
 
void elm_entry_context_menu_item_icon_get (const Elm_Entry_Context_Menu_Item *item, const char **icon_file, const char **icon_group, Elm_Icon_Type *icon_type)
 Get the icon object packed in the contextual menu item of entry. More...
 
Evas_Object * elm_entry_add (Evas_Object *parent)
 This adds an entry to parent object. More...
 
void elm_entry_entry_set (Evas_Object *obj, const char *entry)
 This sets the text displayed within the entry to entry. More...
 
const char * elm_entry_entry_get (const Evas_Object *obj)
 This returns the text currently shown in object entry. More...
 
Eina_Bool elm_entry_file_set (Evas_Object *obj, const char *file, Elm_Text_Format format)
 This sets the file (and implicitly loads it) for the text to display and then edit. More...
 
void elm_entry_file_get (const Evas_Object *obj, const char **file, Elm_Text_Format *format)
 Get the file being edited by the entry. More...
 

Detailed Description

entry_inheritance_tree.png
preview-00.png
preview-01.png
preview-02.png
preview-03.png

An entry is a convenience widget which shows a box that the user can enter text into. Entries by default don't scroll, so they grow to accommodate the entire text, resizing the parent window as needed. This can be changed with the elm_entry_scrollable_set() function.

They can also be single line or multi line (the default) and when set to multi line mode they support text wrapping in any of the modes indicated by #Elm_Wrap_Type.

Other features include password mode, filtering of inserted text with elm_entry_markup_filter_append() and related functions, inline "items" and formatted markup text.

This widget inherits from the Layout one, so that all the functions acting on it also work for entry objects (since 1.8).

This widget implements the elm-scrollable-interface interface, so that all (non-deprecated) functions for the base Scroller widget also work for entries (since 1.8).

Some calls on the entry's API are marked as deprecated, as they just wrap the scrollable widgets counterpart functions. Use the ones we point you to, for each case of deprecation here, instead – eventually the deprecated ones will be discarded (next major release).

Formatted 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 responsable of applying the correct tag to code blocks. The default theme define the following tags:

Special markups

Besides those used to format text, entries support two special markup tags used to insert click-able portions of text or items inlined within the text.

Anchors

Anchors are similar to HTML anchors. Text can be surrounded by <a> and </a> tags and an event will be generated when this text is clicked, like this:

This text is outside <a href=anc-01>but this one is an anchor</a>

The href attribute in the opening tag gives the name that will be used to identify the anchor and it can be any valid utf8 string.

When an anchor is clicked, an "anchor,clicked" signal is emitted with an Elm_Entry_Anchor_Info in the event_info parameter for the callback function. The same applies for "anchor,in" (mouse in), "anchor,out" (mouse out), "anchor,down" (mouse down), and "anchor,up" (mouse up) events on an anchor.

Items

Inlined in the text, any other Evas_Object can be inserted by using <item> tags this way:

<item size=16x16 vsize=full href=emoticon/haha></item>

Just like with anchors, the href identifies each item, but these need, in addition, to indicate their size, which is done using any one of size, absize or relsize attributes. These attributes take their value in the WxH format, where W is the width and H the height of the item.

Besides their size, items are specified a vsize value that affects how their final size and position are calculated. The possible values are:

The next image shows different configurations of items and how the previously mentioned options affect their sizes. In all cases, the green line indicates the ascent, blue for the baseline and red for the descent.

entry_item.png

And another one to show how size differs from absize. In the first one, the scale value is set to 1.0, while the second one is using one of 2.0.

entry_item_scale.png

After the size for an item is calculated, the entry will request an object to place in its space. For this, the functions set with elm_entry_item_provider_append() and related functions will be called in order until one of them returns a non-NULL value. If no providers are available, or all of them return NULL, then the entry falls back to one of the internal defaults, provided the name matches with one of them.

All of the following are currently supported:

Alternatively, an item may reference an image by its path, using the URI form file:///path/to/an/image.png and the entry will then use that image for the item.

Setting entry's style

There are 2 major ways to change the entry's style:

You should modify the theme when you would like to change the style for aesthetic reasons. While the user style should be changed when you would like to change the style to something specific defined at run-time, e.g, setting font or font size in a text editor.

Loading and saving files

Entries have convenience functions to load text from a file and save changes back to it after a short delay. The automatic saving is enabled by default, but can be disabled with elm_entry_autosave_set() and files can be loaded directly as plain text or have any markup in them recognized. See elm_entry_file_set() for more details.

Emitted signals

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

Default content parts of the entry items that you can use for are:

Default text parts of the entry that you can use for are:

Supported elm_object common APIs.

entry-examples

An overview of the Entry API can be seen in Entry - Example of simple editing

Typedef Documentation

typedef Edje_Entry_Change_Info Elm_Entry_Change_Info

This corresponds to Edje_Entry_Change_Info.

Includes information about a change in the entry.

typedef struct _Elm_Entry_Context_Menu_Item Elm_Entry_Context_Menu_Item

Type of contextual item that can be added in to long press menu.

Since
1.8
typedef void(* Elm_Entry_Filter_Cb) (void *data, Evas_Object *entry, char **text)

This callback type is used by entry filters to modify text.

Parameters
dataThe data specified as the last param when adding the filter
entryThe entry object
textA pointer to the location of the text being filtered. The type of text is always markup. This data can be modified, but any additional allocations must be managed by the user.
See also
elm_entry_markup_filter_append
elm_entry_markup_filter_prepend
elm_entry_markup_filter_remove
typedef Evas_Object*(* Elm_Entry_Item_Provider_Cb) (void *data, Evas_Object *entry, const char *item)

This callback type is used to provide items.

If it returns an object handle other than NULL (it should create an object to do this), then this object is used to replace the current item. If not the next provider is called until one provides an item object, or the default provider in entry does.

Parameters
dataThe data specified as the last param when adding the provider
entryThe entry object
textA pointer to the item href string in the text
Returns
The object to be placed in the entry like an icon, or other element
See also
elm_entry_item_provider_append
elm_entry_item_provider_prepend
elm_entry_item_provider_remove

Enumeration Type Documentation

anonymous enum
Enumerator
ELM_INPUT_PANEL_LAYOUT_NORMAL_VARIATION_NORMAL 

The plain normal layout.

Since
1.12
ELM_INPUT_PANEL_LAYOUT_NORMAL_VARIATION_FILENAME 

Filename layout.

Symbols such as '/' should be disabled.

Since
1.12
ELM_INPUT_PANEL_LAYOUT_NORMAL_VARIATION_PERSON_NAME 

The name of a person.

Since
1.12
anonymous enum
Enumerator
ELM_INPUT_PANEL_LAYOUT_NUMBERONLY_VARIATION_NORMAL 

The plain normal number layout.

Since
1.8
ELM_INPUT_PANEL_LAYOUT_NUMBERONLY_VARIATION_SIGNED 

The number layout to allow a positive or negative sign at the start.

Since
1.8
ELM_INPUT_PANEL_LAYOUT_NUMBERONLY_VARIATION_DECIMAL 

The number layout to allow decimal point to provide fractional value.

Since
1.8
ELM_INPUT_PANEL_LAYOUT_NUMBERONLY_VARIATION_SIGNED_AND_DECIMAL 

The number layout to allow decimal point and negative sign.

Since
1.8
anonymous enum
Enumerator
ELM_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NORMAL 

The normal password layout.

Since
1.12
ELM_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NUMBERONLY 

The password layout to allow only number.

Since
1.12

Enum of entry's copy & paste policy.

See also
elm_entry_cnp_mode_set()
elm_entry_cnp_mode_get()
Enumerator
ELM_CNP_MODE_MARKUP 

copy & paste text with markup tag

ELM_CNP_MODE_NO_IMAGE 

copy & paste text without item(image) tag

ELM_CNP_MODE_PLAINTEXT 

copy & paste text without markup tag

Function Documentation

Eina_Bool elm_config_context_menu_disabled_get ( void  )

Get enable status of context menu disabled.

See also
elm_config_context_menu_disabled_set()
Since
1.17
void elm_config_context_menu_disabled_set ( Eina_Bool  disabled)

Enable or disable the context menu in entries.

Parameters
disableddisable context menu if EINA_TRUE, enable otherwise
See also
elm_config_context_menu_disabled_get()
Since
1.17
Evas_Object* elm_entry_add ( Evas_Object *  parent)

This adds an entry to parent object.

By default, entries are:

  • not scrolled
  • multi-line
  • word wrapped
  • autosave is enabled
Parameters
parentThe parent object
Returns
The new object or NULL if it cannot be created

References ELM_CNP_MODE_MARKUP, ELM_CNP_MODE_NO_IMAGE, elm_drop_target_add(), and elm_drop_target_del().

EINA_DEPRECATED void elm_entry_bounce_get ( const Evas_Object *  obj,
Eina_Bool *  h_bounce,
Eina_Bool *  v_bounce 
)

Get the bounce mode.

Parameters
objThe Entry object
h_bounceAllow bounce horizontally
v_bounceAllow bounce vertically
Deprecated:
Use elm_scroller_bounce_get() instead.

References elm_entry_entry_get(), and elm_entry_entry_set().

EINA_DEPRECATED void elm_entry_bounce_set ( Evas_Object *  obj,
Eina_Bool  h_bounce,
Eina_Bool  v_bounce 
)

This enables/disables bouncing within the entry.

This function sets whether the entry will bounce when scrolling reaches the end of the contained entry.

Parameters
objThe entry object
h_bounceThe horizontal bounce state
v_bounceThe vertical bounce state
Deprecated:
Use elm_scroller_bounce_set() instead.
void elm_entry_context_menu_item_icon_get ( const Elm_Entry_Context_Menu_Item item,
const char **  icon_file,
const char **  icon_group,
Elm_Icon_Type *  icon_type 
)

Get the icon object packed in the contextual menu item of entry.

Parameters
itemThe item to get the icon from
icon_fileThe image file path on disk used for the icon or standard icon name
icon_groupThe edje group used if icon_file is an edje file. NULL if the icon is not an edje file
icon_typeThe icon type
See also
elm_entry_context_menu_item_add()
Since
1.8
const char* elm_entry_context_menu_item_label_get ( const Elm_Entry_Context_Menu_Item item)

Get the text of the contextual menu item of entry.

Parameters
itemThe item to get the label
Returns
The text of contextual menu item
See also
elm_entry_context_menu_item_add()
Since
1.8
const char* elm_entry_entry_get ( const Evas_Object *  obj)

This returns the text currently shown in object entry.

See also elm_entry_entry_set().

Parameters
objThe entry object
Returns
The currently displayed text or NULL on failure

References elm_drop_target_add(), and elm_drop_target_del().

Referenced by elm_entry_bounce_get().

void elm_entry_entry_set ( Evas_Object *  obj,
const char *  entry 
)

This sets the text displayed within the entry to entry.

Parameters
objThe entry object
entryThe text to be displayed
Note
Using this function bypasses text filters

Referenced by elm_entry_bounce_get().

void elm_entry_file_get ( const Evas_Object *  obj,
const char **  file,
Elm_Text_Format *  format 
)

Get the file being edited by the entry.

This function can be used to retrieve any file set on the entry for edition, along with the format used to load and save it.

Parameters
[out]fileThe path to the file to load and save
[out]formatThe file format

References ELM_CNP_MODE_MARKUP, ELM_CNP_MODE_NO_IMAGE, ELM_CNP_MODE_PLAINTEXT, elm_drop_target_add(), elm_drop_target_del(), elm_layout_content_get(), ELM_SEL_FORMAT_IMAGE, ELM_SEL_FORMAT_MARKUP, and ELM_SEL_FORMAT_TEXT.

Eina_Bool elm_entry_file_set ( Evas_Object *  obj,
const char *  file,
Elm_Text_Format  format 
)

This sets the file (and implicitly loads it) for the text to display and then edit.

All changes are written back to the file after a short delay if the entry object is set to autosave (which is the default).

If the entry had any other file set previously, any changes made to it will be saved if the autosave feature is enabled, otherwise, the file will be silently discarded and any non-saved changes will be lost.

Returns
EINA_TRUE on success, EINA_FALSE otherwise
Parameters
[in]fileThe path to the file to load and save
[in]formatThe file format
void elm_entry_filter_accept_set ( void *  data,
Evas_Object *  entry,
char **  text 
)

Filter inserted text based on accepted or rejected sets of characters.

Add this filter to an entry to restrict the set of accepted characters based on the sets in the provided Elm_Entry_Filter_Accept_Set. This structure contains both accepted and rejected sets, but they are mutually exclusive. This structure must be available for as long as the entry is alive AND the elm_entry_filter_accept_set is being used.

The accepted set takes preference, so if it is set, the filter will only work based on the accepted characters, ignoring anything in the rejected value. If accepted is NULL, then rejected is used.

In both cases, the function filters by matching utf8 characters to the raw markup text, so it can be used to remove formatting tags.

This filter, like any others, does not apply when setting the entry text directly with elm_object_text_set()

References _Elm_Entry_Filter_Accept_Set::accepted, elm_entry_markup_to_utf8(), and _Elm_Entry_Filter_Accept_Set::rejected.

void elm_entry_filter_limit_size ( void *  data,
Evas_Object *  entry,
char **  text 
)

Filter inserted text based on user defined character and byte limits.

Add this filter to an entry to limit the characters that it will accept based the contents of the provided Elm_Entry_Filter_Limit_Size. The function works on the UTF-8 representation of the string, converting it from the set markup, thus not accounting for any format in it.

The user must create an Elm_Entry_Filter_Limit_Size structure and pass it as data when setting the filter. In it, it's possible to set limits by character count or bytes (any of them is disabled if 0), and both can be set at the same time. In that case, it first checks for characters, then bytes. The Elm_Entry_Filter_Limit_Size structure must be alive and valid for as long as the entry is alive AND the elm_entry_filter_limit_size filter is set.

The function will cut the inserted text in order to allow only the first number of characters that are still allowed. The cut is made in characters, even when limiting by bytes, in order to always contain valid ones and avoid half unicode characters making it in.

This filter, like any others, does not apply when setting the entry text directly with elm_object_text_set().

References elm_entry_markup_to_utf8().

char* elm_entry_markup_to_utf8 ( const char *  s)

This converts a markup (HTML-like) string into UTF-8.

The returned string is a malloc'ed buffer and it should be freed when not needed anymore.

Parameters
sThe string (in markup) to be converted
Returns
The converted string (in UTF-8). It should be freed.

Referenced by elm_entry_filter_accept_set(), elm_entry_filter_limit_size(), and elm_fileselector_entry_path_get().

EINA_DEPRECATED void elm_entry_scrollbar_policy_set ( Evas_Object *  obj,
Elm_Scroller_Policy  h,
Elm_Scroller_Policy  v 
)

This sets the entry's scrollbar policy (i.e.

enabling/disabling them).

Setting an entry to single-line mode with elm_entry_single_line_set() will automatically disable the display of scrollbars when the entry moves inside its scroller.

Parameters
objThe entry object
hThe horizontal scrollbar policy to apply
vThe vertical scrollbar policy to apply
Deprecated:
Use elm_scroller_policy_set() instead.
char* elm_entry_utf8_to_markup ( const char *  s)

This converts a UTF-8 string into markup (HTML-like).

The returned string is a malloc'ed buffer and it should be freed when not needed anymore.

Parameters
sThe string (in UTF-8) to be converted
Returns
The converted string (in markup). It should be freed.

For example, passing "<align=center>hello</align>&gt;" will return "&lt;align=center&gt;hello&lt;/align&gt; &amp;gt;". This is useful when you want to display "&" in label, entry, and some widgets which use textblock internally.

Referenced by elm_fileselector_entry_path_set().