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. | |
Functions | |
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... | |
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).
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:
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 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:
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.
Inlined in the text, any other Evas_Object
can be inserted by using <item> tags this way:
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.
absize
, but it's adjusted to the scale value set for the object. Besides their size, items are specified a vsize
value that affects how their final size and position are calculated. The possible values are:
size
and absize
items, the descent value will be added to the total line height to make them fit. relsize
items will be adjusted to fit within this space. 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.
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.
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.
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.
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.
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.
An overview of the Entry API can be seen in Entry - Example of simple editing
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.
typedef void(* Elm_Entry_Filter_Cb) (void *data, Evas_Object *entry, char **text) |
This callback type is used by entry filters to modify text.
data | The data specified as the last param when adding the filter |
entry | The entry object |
text | A 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. |
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.
data | The data specified as the last param when adding the provider |
entry | The entry object |
text | A pointer to the item href string in the text |
anonymous enum |
anonymous enum |
anonymous enum |
enum Elm_Cnp_Mode |
Evas_Object* elm_entry_add | ( | Evas_Object * | parent | ) |
This adds an entry to parent
object.
By default, entries are:
parent | The parent object |
EINA_DEPRECATED void elm_entry_bounce_get | ( | const Evas_Object * | obj, |
Eina_Bool * | h_bounce, | ||
Eina_Bool * | v_bounce | ||
) |
Get the bounce mode.
obj | The Entry object |
h_bounce | Allow bounce horizontally |
v_bounce | Allow bounce vertically |
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.
obj | The entry object |
h_bounce | The horizontal bounce state |
v_bounce | The vertical bounce state |
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.
item | The item to get the icon from |
icon_file | The image file path on disk used for the icon or standard icon name |
icon_group | The edje group used if icon_file is an edje file. NULL if the icon is not an edje file |
icon_type | The icon type |
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.
item | The item to get the label |
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().
obj | The entry object |
void elm_entry_entry_set | ( | Evas_Object * | obj, |
const char * | entry | ||
) |
This sets the text displayed within the entry to entry
.
obj | The entry object |
entry | The text to be displayed |
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.
[out] | file | The path to the file to load and save |
[out] | format | The file format |
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.
EINA_TRUE
on success, EINA_FALSE
otherwise[in] | file | The path to the file to load and save |
[in] | format | The 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.
s | The string (in markup) to be converted |
Referenced by elm_entry_filter_accept_set(), and elm_entry_filter_limit_size().
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.
obj | The entry object |
h | The horizontal scrollbar policy to apply |
v | The vertical scrollbar policy to apply |
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.
s | The string (in UTF-8) to be converted |
For example, passing "<align=center>hello</align>>" will return "<align=center>hello</align> &gt;". This is useful when you want to display "&" in label, entry, and some widgets which use textblock internally.