2 * @defgroup Entry Entry
4 * @image html img/widget/entry/preview-00.png
5 * @image latex img/widget/entry/preview-00.eps width=\textwidth
6 * @image html img/widget/entry/preview-01.png
7 * @image latex img/widget/entry/preview-01.eps width=\textwidth
8 * @image html img/widget/entry/preview-02.png
9 * @image latex img/widget/entry/preview-02.eps width=\textwidth
10 * @image html img/widget/entry/preview-03.png
11 * @image latex img/widget/entry/preview-03.eps width=\textwidth
13 * An entry is a convenience widget which shows a box that the user can
14 * enter text into. Entries by default don't scroll, so they grow to
15 * accommodate the entire text, resizing the parent window as needed. This
16 * can be changed with the elm_entry_scrollable_set() function.
18 * They can also be single line or multi line (the default) and when set
19 * to multi line mode they support text wrapping in any of the modes
20 * indicated by #Elm_Wrap_Type.
22 * Other features include password mode, filtering of inserted text with
23 * elm_entry_markup_filter_append() and related functions, inline "items" and
24 * formatted markup text.
26 * @section entry-markup Formatted text
28 * The markup tags supported by the Entry are defined by the theme, but
29 * even when writing new themes or extensions it's a good idea to stick to
30 * a sane default, to maintain coherency and avoid application breakages.
31 * Currently defined by the default theme are the following tags:
32 * @li \<br\>: Inserts a line break.
33 * @li \<ps\>: Inserts a paragraph separator. This is preferred over line
35 * @li \<tab\>: Inserts a tab.
36 * @li \<em\>...\</em\>: Emphasis. Sets the @em oblique style for the
38 * @li \<b\>...\</b\>: Sets the @b bold style for the enclosed text.
39 * @li \<link\>...\</link\>: Underlines the enclosed text.
40 * @li \<hilight\>...\</hilight\>: Highlights the enclosed text.
42 * @section entry-special Special markups
44 * Besides those used to format text, entries support two special markup
45 * tags used to insert click-able portions of text or items inlined within
48 * @subsection entry-anchors Anchors
50 * Anchors are similar to HTML anchors. Text can be surrounded by \<a\> and
51 * \</a\> tags and an event will be generated when this text is clicked,
55 * This text is outside <a href=anc-01>but this one is an anchor</a>
58 * The @c href attribute in the opening tag gives the name that will be
59 * used to identify the anchor and it can be any valid utf8 string.
61 * When an anchor is clicked, an @c "anchor,clicked" signal is emitted with
62 * an #Elm_Entry_Anchor_Info in the @c event_info parameter for the
63 * callback function. The same applies for "anchor,in" (mouse in), "anchor,out"
64 * (mouse out), "anchor,down" (mouse down), and "anchor,up" (mouse up) events on
67 * @subsection entry-items Items
69 * Inlined in the text, any other @c Evas_Object can be inserted by using
70 * \<item\> tags this way:
73 * <item size=16x16 vsize=full href=emoticon/haha></item>
76 * Just like with anchors, the @c href identifies each item, but these need,
77 * in addition, to indicate their size, which is done using any one of
78 * @c size, @c absize or @c relsize attributes. These attributes take their
79 * value in the WxH format, where W is the width and H the height of the
82 * @li absize: Absolute pixel size for the item. Whatever value is set will
83 * be the item's size regardless of any scale value the object may have
84 * been set to. The final line height will be adjusted to fit larger items.
85 * @li size: Similar to @c absize, but it's adjusted to the scale value set
87 * @li relsize: Size is adjusted for the item to fit within the current
90 * Besides their size, items are specified a @c vsize value that affects
91 * how their final size and position are calculated. The possible values
93 * @li ascent: Item will be placed within the line's baseline and its
94 * ascent. That is, the height between the line where all characters are
95 * positioned and the highest point in the line. For @c size and @c absize
96 * items, the descent value will be added to the total line height to make
97 * them fit. @c relsize items will be adjusted to fit within this space.
98 * @li full: Items will be placed between the descent and ascent, or the
99 * lowest point in the line and its highest.
101 * The next image shows different configurations of items and how
102 * the previously mentioned options affect their sizes. In all cases,
103 * the green line indicates the ascent, blue for the baseline and red for
106 * @image html entry_item.png
107 * @image latex entry_item.eps width=\textwidth
109 * And another one to show how size differs from absize. In the first one,
110 * the scale value is set to 1.0, while the second one is using one of 2.0.
112 * @image html entry_item_scale.png
113 * @image latex entry_item_scale.eps width=\textwidth
115 * After the size for an item is calculated, the entry will request an
116 * object to place in its space. For this, the functions set with
117 * elm_entry_item_provider_append() and related functions will be called
118 * in order until one of them returns a @c non-NULL value. If no providers
119 * are available, or all of them return @c NULL, then the entry falls back
120 * to one of the internal defaults, provided the name matches with one of
123 * All of the following are currently supported:
126 * - emoticon/angry-shout
127 * - emoticon/crazy-laugh
128 * - emoticon/evil-laugh
130 * - emoticon/goggle-smile
132 * - emoticon/grumpy-smile
134 * - emoticon/guilty-smile
136 * - emoticon/half-smile
137 * - emoticon/happy-panting
139 * - emoticon/indifferent
141 * - emoticon/knowing-grin
143 * - emoticon/little-bit-sorry
144 * - emoticon/love-lots
146 * - emoticon/minimal-smile
147 * - emoticon/not-happy
148 * - emoticon/not-impressed
150 * - emoticon/opensmile
153 * - emoticon/squint-laugh
154 * - emoticon/surprised
155 * - emoticon/suspicious
156 * - emoticon/tongue-dangling
157 * - emoticon/tongue-poke
160 * - emoticon/very-sorry
166 * Alternatively, an item may reference an image by its path, using
167 * the URI form @c file:///path/to/an/image.png and the entry will then
168 * use that image for the item.
170 * @section entry-files Loading and saving files
172 * Entries have convenience functions to load text from a file and save
173 * changes back to it after a short delay. The automatic saving is enabled
174 * by default, but can be disabled with elm_entry_autosave_set() and files
175 * can be loaded directly as plain text or have any markup in them
176 * recognized. See elm_entry_file_set() for more details.
178 * @section entry-signals Emitted signals
180 * This widget emits the following signals:
182 * @li "changed": The text within the entry was changed.
183 * @li "changed,user": The text within the entry was changed because of user interaction.
184 * @li "activated": The enter key was pressed on a single line entry.
185 * @li "press": A mouse button has been pressed on the entry.
186 * @li "longpressed": A mouse button has been pressed and held for a couple
188 * @li "clicked": The entry has been clicked (mouse press and release).
189 * @li "clicked,double": The entry has been double clicked.
190 * @li "clicked,triple": The entry has been triple clicked.
191 * @li "focused": The entry has received focus.
192 * @li "unfocused": The entry has lost focus.
193 * @li "selection,paste": A paste of the clipboard contents was requested.
194 * @li "selection,copy": A copy of the selected text into the clipboard was
196 * @li "selection,cut": A cut of the selected text into the clipboard was
198 * @li "selection,start": A selection has begun and no previous selection
200 * @li "selection,changed": The current selection has changed.
201 * @li "selection,cleared": The current selection has been cleared.
202 * @li "cursor,changed": The cursor has changed position.
203 * @li "anchor,clicked": An anchor has been clicked. The event_info
204 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
205 * @li "anchor,in": Mouse cursor has moved into an anchor. The event_info
206 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
207 * @li "anchor,out": Mouse cursor has moved out of an anchor. The event_info
208 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
209 * @li "anchor,up": Mouse button has been unpressed on an anchor. The event_info
210 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
211 * @li "anchor,down": Mouse button has been pressed on an anchor. The event_info
212 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
213 * @li "preedit,changed": The preedit string has changed.
214 * @li "language,changed": Program language changed.
216 * Default content parts of the entry items that you can use for are:
217 * @li "icon" - An icon in the entry
218 * @li "end" - A content in the end of the entry
220 * Default text parts of the entry that you can use for are:
221 * @li "default" - text of the entry
223 * Supported elm_object common APIs.
224 * @li elm_object_signal_emit
225 * @li elm_object_part_text_set
226 * @li elm_object_part_text_get
227 * @li elm_object_part_content_set
228 * @li elm_object_part_content_get
229 * @li elm_object_part_content_unset
230 * @li elm_object_signal_callback_add
231 * @li elm_object_signal_callback_del
232 * @li elm_object_disabled_set
233 * @li elm_object_disabled_get
235 * @section entry-examples
237 * An overview of the Entry API can be seen in @ref entry_example_01
243 * @enum _Elm_Text_Format
244 * @typedef Elm_Text_Format
248 * @see elm_entry_file_set()
252 ELM_TEXT_FORMAT_PLAIN_UTF8, /**< Plain UTF8 type */
253 ELM_TEXT_FORMAT_MARKUP_UTF8 /**< Markup UTF8 type */
257 * @enum _Elm_Wrap_Type
258 * @typedef Elm_Wrap_Type
260 * Line wrapping types.
262 * @see elm_entry_line_wrap_set()
266 ELM_WRAP_NONE = 0, /**< No wrap - value is zero */
267 ELM_WRAP_CHAR, /**< Char wrap - wrap between characters */
268 ELM_WRAP_WORD, /**< Word wrap - wrap in allowed wrapping points (as defined in the unicode standard) */
269 ELM_WRAP_MIXED, /**< Mixed wrap - Word wrap, and if that fails, char wrap. */
271 } Elm_Wrap_Type; /**< Type of word or character wrapping to use */
274 * @enum _Elm_Input_Panel_Layout
275 * @typedef Elm_Input_Panel_Layout
277 * Input panel (virtual keyboard) layout types.
279 * @see elm_entry_input_panel_layout_set()
283 ELM_INPUT_PANEL_LAYOUT_NORMAL, /**< Default layout */
284 ELM_INPUT_PANEL_LAYOUT_NUMBER, /**< Number layout */
285 ELM_INPUT_PANEL_LAYOUT_EMAIL, /**< Email layout */
286 ELM_INPUT_PANEL_LAYOUT_URL, /**< URL layout */
287 ELM_INPUT_PANEL_LAYOUT_PHONENUMBER, /**< Phone Number layout */
288 ELM_INPUT_PANEL_LAYOUT_IP, /**< IP layout */
289 ELM_INPUT_PANEL_LAYOUT_MONTH, /**< Month layout */
290 ELM_INPUT_PANEL_LAYOUT_NUMBERONLY, /**< Number Only layout */
291 ELM_INPUT_PANEL_LAYOUT_INVALID, /**< Never use this */
292 ELM_INPUT_PANEL_LAYOUT_HEX, /**< Hexadecimal layout */
293 ELM_INPUT_PANEL_LAYOUT_TERMINAL, /**< Command-line terminal layout */
294 ELM_INPUT_PANEL_LAYOUT_PASSWORD /**< Like normal, but no auto-correct, no auto-capitalization etc. */
295 } Elm_Input_Panel_Layout; /**< Type of input panel (virtual keyboard) to use - this is a hint and may not provide exactly what is desired. */
298 * @enum _Elm_Input_Panel_Lang
299 * @typedef Elm_Input_Panel_Lang
301 * Input panel (virtual keyboard) language modes.
303 * @see elm_entry_input_panel_language_set()
307 ELM_INPUT_PANEL_LANG_AUTOMATIC, /**< Automatic */
308 ELM_INPUT_PANEL_LANG_ALPHABET /**< Alphabet */
309 } Elm_Input_Panel_Lang;
312 * @enum _Elm_Autocapital_Type
313 * @typedef Elm_Autocapital_Type
315 * Autocapitalization Types.
317 * @see elm_entry_autocapital_type_set()
321 ELM_AUTOCAPITAL_TYPE_NONE, /**< No auto-capitalization when typing */
322 ELM_AUTOCAPITAL_TYPE_WORD, /**< Autocapitalize each word typed */
323 ELM_AUTOCAPITAL_TYPE_SENTENCE, /**< Autocapitalize the start of each sentence */
324 ELM_AUTOCAPITAL_TYPE_ALLCHARACTER, /**< Autocapitalize all letters */
325 } Elm_Autocapital_Type; /**< Choose method of auto-capitalization */
328 * @enum _Elm_Input_Panel_Return_Key_Type
329 * @typedef Elm_Input_Panel_Return_Key_Type
331 * "Return" Key types on the input panel (virtual keyboard).
333 * @see elm_entry_input_panel_return_key_type_set()
337 ELM_INPUT_PANEL_RETURN_KEY_TYPE_DEFAULT, /**< Default */
338 ELM_INPUT_PANEL_RETURN_KEY_TYPE_DONE, /**< Done */
339 ELM_INPUT_PANEL_RETURN_KEY_TYPE_GO, /**< Go */
340 ELM_INPUT_PANEL_RETURN_KEY_TYPE_JOIN, /**< Join */
341 ELM_INPUT_PANEL_RETURN_KEY_TYPE_LOGIN, /**< Login */
342 ELM_INPUT_PANEL_RETURN_KEY_TYPE_NEXT, /**< Next */
343 ELM_INPUT_PANEL_RETURN_KEY_TYPE_SEARCH, /**< Search string or magnifier icon */
344 ELM_INPUT_PANEL_RETURN_KEY_TYPE_SEND /**< Send */
345 } Elm_Input_Panel_Return_Key_Type;
348 * @typedef Elm_Entry_Anchor_Info
350 * The info sent in the callback for the "anchor,clicked" signals emitted
353 typedef struct _Elm_Entry_Anchor_Info Elm_Entry_Anchor_Info;
356 * @struct _Elm_Entry_Anchor_Info
358 * The info sent in the callback for the "anchor,clicked" signals emitted
361 struct _Elm_Entry_Anchor_Info
363 const char *name; /**< The name of the anchor, as stated in its href */
364 int button; /**< The mouse button used to click on it */
365 Evas_Coord x, /**< Anchor geometry, relative to canvas */
366 y, /**< Anchor geometry, relative to canvas */
367 w, /**< Anchor geometry, relative to canvas */
368 h; /**< Anchor geometry, relative to canvas */
372 * @typedef Elm_Entry_Filter_Cb
373 * This callback type is used by entry filters to modify text.
374 * @param data The data specified as the last param when adding the filter
375 * @param entry The entry object
376 * @param text A pointer to the location of the text being filtered. The type of text is always markup. This data can be modified,
377 * but any additional allocations must be managed by the user.
378 * @see elm_entry_markup_filter_append
379 * @see elm_entry_markup_filter_prepend
381 typedef void (*Elm_Entry_Filter_Cb)(void *data, Evas_Object *entry, char **text);
384 * @typedef Elm_Entry_Change_Info
385 * This corresponds to Edje_Entry_Change_Info. Includes information about
386 * a change in the entry.
388 typedef Edje_Entry_Change_Info Elm_Entry_Change_Info;
391 * This adds an entry to @p parent object.
393 * By default, entries are:
397 * @li autosave is enabled
399 * @param parent The parent object
400 * @return The new object or NULL if it cannot be created
402 EAPI Evas_Object *elm_entry_add(Evas_Object *parent);
405 * Sets the entry to single line mode.
407 * In single line mode, entries don't ever wrap when the text reaches the
408 * edge, and instead they keep growing horizontally. Pressing the @c Enter
409 * key will generate an @c "activate" event instead of adding a new line.
411 * When @p single_line is @c EINA_FALSE, line wrapping takes effect again
412 * and pressing enter will break the text into a different line
413 * without generating any events.
415 * @param obj The entry object
416 * @param single_line If true, the text in the entry
417 * will be on a single line.
419 EAPI void elm_entry_single_line_set(Evas_Object *obj, Eina_Bool single_line);
422 * Gets whether the entry is set to be single line.
424 * @param obj The entry object
425 * @return single_line If true, the text in the entry is set to display
428 * @see elm_entry_single_line_set()
430 EAPI Eina_Bool elm_entry_single_line_get(const Evas_Object *obj);
433 * Sets the entry to password mode.
435 * In password mode, entries are implicitly single line and the display of
436 * any text in them is replaced with asterisks (*).
438 * @param obj The entry object
439 * @param password If true, password mode is enabled.
441 EAPI void elm_entry_password_set(Evas_Object *obj, Eina_Bool password);
444 * Gets whether the entry is set to password mode.
446 * @param obj The entry object
447 * @return If true, the entry is set to display all characters
450 * @see elm_entry_password_set()
452 EAPI Eina_Bool elm_entry_password_get(const Evas_Object *obj);
455 * This sets the text displayed within the entry to @p entry.
457 * @param obj The entry object
458 * @param entry The text to be displayed
460 * @note Using this function bypasses text filters
462 EAPI void elm_entry_entry_set(Evas_Object *obj, const char *entry);
465 * This returns the text currently shown in object @p entry.
466 * See also elm_entry_entry_set().
468 * @param obj The entry object
469 * @return The currently displayed text or NULL on failure
471 EAPI const char *elm_entry_entry_get(const Evas_Object *obj);
474 * Appends @p entry to the text of the entry.
476 * Adds the text in @p entry to the end of any text already present in the
479 * The appended text is subject to any filters set for the widget.
481 * @param obj The entry object
482 * @param entry The text to be displayed
484 * @see elm_entry_markup_filter_append()
486 EAPI void elm_entry_entry_append(Evas_Object *obj, const char *entry);
489 * Gets whether the entry is empty.
491 * Empty means no text at all. If there are any markup tags, like an item
492 * tag for which no provider finds anything, and no text is displayed, this
493 * function still returns EINA_FALSE.
495 * @param obj The entry object
496 * @return EINA_TRUE if the entry is empty, EINA_FALSE otherwise.
498 EAPI Eina_Bool elm_entry_is_empty(const Evas_Object *obj);
501 * Gets any selected text within the entry.
503 * If there's any selected text in the entry, this function returns it as
504 * a string in markup format. NULL is returned if no selection exists or
505 * if an error occurred.
507 * The returned value points to an internal string and should not be freed
508 * or modified in any way. If the @p entry object is deleted or its
509 * contents are changed, the returned pointer should be considered invalid.
511 * @param obj The entry object
512 * @return The selected text within the entry or NULL on failure
514 EAPI const char *elm_entry_selection_get(const Evas_Object *obj);
517 * Returns the actual textblock object of the entry.
519 * This function exposes the internal textblock object that actually
520 * contains and draws the text. This should be used for low-level
521 * manipulations that are otherwise not possible.
523 * Changing the textblock directly from here will not notify edje/elm to
524 * recalculate the textblock size automatically, so any modifications
525 * done to the textblock returned by this function should be followed by
526 * a call to elm_entry_calc_force().
528 * The return value is marked as const as an additional warning.
529 * One should not use the returned object with any of the generic evas
530 * functions (geometry_get/resize/move and etc), but only with the textblock
531 * functions; The former will either not work at all, or break the correct
534 * IMPORTANT: Many functions may change (i.e delete and create a new one)
535 * the internal textblock object. Do NOT cache the returned object, and try
536 * not to mix calls on this object with regular elm_entry calls (which may
537 * change the internal textblock object). This applies to all cursors
538 * returned from textblock calls, and all the other derivative values.
540 * @param obj The entry object
541 * @return The textblock object.
543 EAPI Evas_Object * elm_entry_textblock_get(Evas_Object *obj);
546 * Forces calculation of the entry size and text layouting.
548 * This should be used after modifying the textblock object directly. See
549 * elm_entry_textblock_get() for more information.
551 * @param obj The entry object
553 * @see elm_entry_textblock_get()
555 EAPI void elm_entry_calc_force(Evas_Object *obj);
558 * Inserts the given text into the entry at the current cursor position.
560 * This inserts text at the cursor position as if it was typed
561 * by the user (note that this also allows markup which a user
562 * can't just "type" as it would be converted to escaped text, so this
563 * call can be used to insert things like emoticon items or bold push/pop
564 * tags, other font and color change tags etc.)
566 * If any selection exists, it will be replaced by the inserted text.
568 * The inserted text is subject to any filters set for the widget.
570 * @param obj The entry object
571 * @param entry The text to insert
573 * @see elm_entry_markup_filter_append()
575 EAPI void elm_entry_entry_insert(Evas_Object *obj, const char *entry);
578 * Set the line wrap type to use on multi-line entries.
580 * Sets the wrap type used by the entry to any of the specified in
581 * Elm_Wrap_Type. This tells how the text will be implicitly cut into a new
582 * line (without inserting a line break or paragraph separator) when it
583 * reaches the far edge of the widget.
585 * Note that this only makes sense for multi-line entries. A widget set
586 * to be single line will never wrap.
588 * @param obj The entry object
589 * @param wrap The wrap mode to use. See Elm_Wrap_Type for details on them
591 EAPI void elm_entry_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap);
594 * Gets the wrap mode the entry was set to use.
596 * @param obj The entry object
599 * @see also elm_entry_line_wrap_set()
601 EAPI Elm_Wrap_Type elm_entry_line_wrap_get(const Evas_Object *obj);
604 * Sets if the entry is to be editable or not.
606 * By default, entries are editable and when focused, any text input by the
607 * user will be inserted at the current cursor position. But calling this
608 * function with @p editable as EINA_FALSE will prevent the user from
609 * inputting text into the entry.
611 * The only way to change the text of a non-editable entry is to use
612 * elm_object_text_set(), elm_entry_entry_insert() and other related
615 * @param obj The entry object
616 * @param editable If EINA_TRUE, user input will be inserted in the entry,
617 * if not, the entry is read-only and no user input is allowed.
619 EAPI void elm_entry_editable_set(Evas_Object *obj, Eina_Bool editable);
622 * Gets whether the entry is editable or not.
624 * @param obj The entry object
625 * @return If true, the entry is editable by the user.
626 * If false, it is not editable by the user
628 * @see elm_entry_editable_set()
630 EAPI Eina_Bool elm_entry_editable_get(const Evas_Object *obj);
633 * This drops any existing text selection within the entry.
635 * @param obj The entry object
637 EAPI void elm_entry_select_none(Evas_Object *obj);
640 * This selects all text within the entry.
642 * @param obj The entry object
644 EAPI void elm_entry_select_all(Evas_Object *obj);
647 * This moves the cursor one place to the right within the entry.
649 * @param obj The entry object
650 * @return EINA_TRUE upon success, EINA_FALSE upon failure
652 EAPI Eina_Bool elm_entry_cursor_next(Evas_Object *obj);
655 * This moves the cursor one place to the left within the entry.
657 * @param obj The entry object
658 * @return EINA_TRUE upon success, EINA_FALSE upon failure
660 EAPI Eina_Bool elm_entry_cursor_prev(Evas_Object *obj);
663 * This moves the cursor one line up within the entry.
665 * @param obj The entry object
666 * @return EINA_TRUE upon success, EINA_FALSE upon failure
668 EAPI Eina_Bool elm_entry_cursor_up(Evas_Object *obj);
671 * This moves the cursor one line down within the entry.
673 * @param obj The entry object
674 * @return EINA_TRUE upon success, EINA_FALSE upon failure
676 EAPI Eina_Bool elm_entry_cursor_down(Evas_Object *obj);
679 * This moves the cursor to the beginning of the entry.
681 * @param obj The entry object
683 EAPI void elm_entry_cursor_begin_set(Evas_Object *obj);
686 * This moves the cursor to the end of the entry.
688 * @param obj The entry object
690 EAPI void elm_entry_cursor_end_set(Evas_Object *obj);
693 * This moves the cursor to the beginning of the current line.
695 * @param obj The entry object
697 EAPI void elm_entry_cursor_line_begin_set(Evas_Object *obj);
700 * This moves the cursor to the end of the current line.
702 * @param obj The entry object
704 EAPI void elm_entry_cursor_line_end_set(Evas_Object *obj);
707 * This begins a selection within the entry as though
708 * the user were holding down the mouse button to make a selection.
710 * @param obj The entry object
712 EAPI void elm_entry_cursor_selection_begin(Evas_Object *obj);
715 * This ends a selection within the entry as though
716 * the user had just released the mouse button while making a selection.
718 * @param obj The entry object
720 EAPI void elm_entry_cursor_selection_end(Evas_Object *obj);
723 * Gets whether a format node exists at the current cursor position.
725 * A format node is anything that defines how the text is rendered. It can
726 * be a visible format node, such as a line break or a paragraph separator,
727 * or an invisible one, such as bold begin or end tag.
728 * This function returns whether any format node exists at the current
731 * @param obj The entry object
732 * @return EINA_TRUE if the current cursor position contains a format node,
733 * EINA_FALSE otherwise.
735 * @see elm_entry_cursor_is_visible_format_get()
737 EAPI Eina_Bool elm_entry_cursor_is_format_get(const Evas_Object *obj);
740 * Gets if the current cursor position holds a visible format node.
742 * @param obj The entry object
743 * @return EINA_TRUE if the current cursor is a visible format, EINA_FALSE
744 * if it's an invisible one or no format exists.
746 * @see elm_entry_cursor_is_format_get()
748 EAPI Eina_Bool elm_entry_cursor_is_visible_format_get(const Evas_Object *obj);
751 * Gets the character pointed by the cursor at its current position.
753 * This function returns a string with the utf8 character stored at the
754 * current cursor position.
755 * Only the text is returned, any format that may exist will not be part
756 * of the return value. You must free the string when done with free().
758 * @param obj The entry object
759 * @return The text pointed by the cursors.
761 EAPI char *elm_entry_cursor_content_get(const Evas_Object *obj);
764 * This function returns the geometry of the cursor.
766 * It's useful if you want to draw something on the cursor (or where it is),
767 * or for example in the case of scrolled entry where you want to show the
770 * @param obj The entry object
771 * @param x returned geometry
772 * @param y returned geometry
773 * @param w returned geometry
774 * @param h returned geometry
775 * @return EINA_TRUE upon success, EINA_FALSE upon failure
777 EAPI Eina_Bool elm_entry_cursor_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h);
780 * Sets the cursor position in the entry to the given value
782 * The value in @p pos is the index of the character position within the
783 * contents of the string as returned by elm_entry_cursor_pos_get().
785 * @param obj The entry object
786 * @param pos The position of the cursor
788 EAPI void elm_entry_cursor_pos_set(Evas_Object *obj, int pos);
791 * Retrieves the current position of the cursor in the entry
793 * @param obj The entry object
794 * @return The cursor position
796 EAPI int elm_entry_cursor_pos_get(const Evas_Object *obj);
799 * This executes a "cut" action on the selected text in the entry.
801 * @param obj The entry object
803 EAPI void elm_entry_selection_cut(Evas_Object *obj);
806 * This executes a "copy" action on the selected text in the entry.
808 * @param obj The entry object
810 EAPI void elm_entry_selection_copy(Evas_Object *obj);
813 * This executes a "paste" action in the entry.
815 * @param obj The entry object
817 EAPI void elm_entry_selection_paste(Evas_Object *obj);
820 * This clears and frees the items in a entry's contextual (longpress)
823 * @param obj The entry object
825 * @see elm_entry_context_menu_item_add()
827 EAPI void elm_entry_context_menu_clear(Evas_Object *obj);
830 * This adds an item to the entry's contextual menu.
832 * A longpress on an entry will make the contextual menu show up, if this
833 * hasn't been disabled with elm_entry_context_menu_disabled_set().
834 * By default, this menu provides a few options like enabling selection mode,
835 * which is useful on embedded devices that need to be explicit about it,
836 * and when a selection exists it also shows the copy and cut actions.
838 * With this function, developers can add other options to this menu to
839 * perform any action they deem necessary.
841 * @param obj The entry object
842 * @param label The item's text label
843 * @param icon_file The item's icon file
844 * @param icon_type The item's icon type
845 * @param func The callback to execute when the item is clicked
846 * @param data The data to associate with the item for related functions
848 EAPI void elm_entry_context_menu_item_add(Evas_Object *obj, const char *label, const char *icon_file, Elm_Icon_Type icon_type, Evas_Smart_Cb func, const void *data);
851 * This disables the entry's contextual (longpress) menu.
853 * @param obj The entry object
854 * @param disabled If true, the menu is disabled
856 EAPI void elm_entry_context_menu_disabled_set(Evas_Object *obj, Eina_Bool disabled);
859 * This returns whether the entry's contextual (longpress) menu is
862 * @param obj The entry object
863 * @return If true, the menu is disabled
865 EAPI Eina_Bool elm_entry_context_menu_disabled_get(const Evas_Object *obj);
868 * This appends a custom item provider to the list for that entry
870 * This appends the given callback. The list is walked from beginning to end
871 * with each function called given the item href string in the text. If the
872 * function returns an object handle other than NULL (it should create an
873 * object to do this), then this object is used to replace that item. If
874 * not the next provider is called until one provides an item object, or the
875 * default provider in entry does.
877 * @param obj The entry object
878 * @param func The function called to provide the item object
879 * @param data The data passed to @p func
881 * @see @ref entry-items
883 EAPI void elm_entry_item_provider_append(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
886 * This prepends a custom item provider to the list for that entry
888 * This prepends the given callback. See elm_entry_item_provider_append() for
891 * @param obj The entry object
892 * @param func The function called to provide the item object
893 * @param data The data passed to @p func
895 EAPI void elm_entry_item_provider_prepend(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
898 * This removes a custom item provider to the list for that entry
900 * This removes the given callback. See elm_entry_item_provider_append() for
903 * @param obj The entry object
904 * @param func The function called to provide the item object
905 * @param data The data passed to @p func
907 EAPI void elm_entry_item_provider_remove(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
910 * Append a markup filter function for text inserted in the entry
912 * Append the given callback to the list. This functions will be called
913 * whenever any text is inserted into the entry, with the text to be inserted
914 * as a parameter. The type of given text is always markup.
915 * The callback function is free to alter the text in any way it wants, but
916 * it must remember to free the given pointer and update it.
917 * If the new text is to be discarded, the function can free it and set its
918 * text parameter to NULL. This will also prevent any following filters from
921 * @param obj The entry object
922 * @param func The function to use as text filter
923 * @param data User data to pass to @p func
925 EAPI void elm_entry_markup_filter_append(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
928 * Prepend a markup filter function for text inserted in the entry
930 * Prepend the given callback to the list. See elm_entry_markup_filter_append()
931 * for more information
933 * @param obj The entry object
934 * @param func The function to use as text filter
935 * @param data User data to pass to @p func
937 EAPI void elm_entry_markup_filter_prepend(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
940 * Remove a markup filter from the list
942 * Removes the given callback from the filter list. See
943 * elm_entry_markup_filter_append() for more information.
945 * @param obj The entry object
946 * @param func The filter function to remove
947 * @param data The user data passed when adding the function
949 EAPI void elm_entry_markup_filter_remove(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
952 * This converts a markup (HTML-like) string into UTF-8.
954 * The returned string is a malloc'ed buffer and it should be freed when
955 * not needed anymore.
957 * @param s The string (in markup) to be converted
958 * @return The converted string (in UTF-8). It should be freed.
960 EAPI char *elm_entry_markup_to_utf8(const char *s);
963 * This converts a UTF-8 string into markup (HTML-like).
965 * The returned string is a malloc'ed buffer and it should be freed when
966 * not needed anymore.
968 * @param s The string (in UTF-8) to be converted
969 * @return The converted string (in markup). It should be freed.
971 EAPI char *elm_entry_utf8_to_markup(const char *s);
974 * This sets the file (and implicitly loads it) for the text to display and
975 * then edit. All changes are written back to the file after a short delay if
976 * the entry object is set to autosave (which is the default).
978 * If the entry had any other file set previously, any changes made to it
979 * will be saved if the autosave feature is enabled, otherwise, the file
980 * will be silently discarded and any non-saved changes will be lost.
982 * @param obj The entry object
983 * @param file The path to the file to load and save
984 * @param format The file format
986 EAPI void elm_entry_file_set(Evas_Object *obj, const char *file, Elm_Text_Format format);
989 * Gets the file being edited by the entry.
991 * This function can be used to retrieve any file set on the entry for
992 * edition, along with the format used to load and save it.
994 * @param obj The entry object
995 * @param file The path to the file to load and save
996 * @param format The file format
998 EAPI void elm_entry_file_get(const Evas_Object *obj, const char **file, Elm_Text_Format *format);
1001 * This function writes any changes made to the file set with
1002 * elm_entry_file_set()
1004 * @param obj The entry object
1006 EAPI void elm_entry_file_save(Evas_Object *obj);
1009 * This sets the entry object to 'autosave' the loaded text file or not.
1011 * @param obj The entry object
1012 * @param autosave Autosave the loaded file or not
1014 * @see elm_entry_file_set()
1016 EAPI void elm_entry_autosave_set(Evas_Object *obj, Eina_Bool autosave);
1019 * This gets the entry object's 'autosave' status.
1021 * @param obj The entry object
1022 * @return Autosave the loaded file or not
1024 * @see elm_entry_file_set()
1026 EAPI Eina_Bool elm_entry_autosave_get(const Evas_Object *obj);
1029 * Control pasting of text and images for the widget.
1031 * Normally the entry allows both text and images to be pasted. By setting
1032 * textonly to be true, this prevents images from being pasted.
1034 * Note this only changes the behaviour of text.
1036 * @param obj The entry object
1037 * @param textonly paste mode - EINA_TRUE is text only, EINA_FALSE is
1040 EAPI void elm_entry_cnp_textonly_set(Evas_Object *obj, Eina_Bool textonly);
1043 * Getting elm_entry text paste/drop mode.
1045 * In textonly mode, only text may be pasted or dropped into the widget.
1047 * @param obj The entry object
1048 * @return If the widget only accepts text from pastes.
1050 EAPI Eina_Bool elm_entry_cnp_textonly_get(const Evas_Object *obj);
1053 * Enable or disable scrolling in entry
1055 * Normally the entry is not scrollable unless you enable it with this call.
1057 * @param obj The entry object
1058 * @param scroll EINA_TRUE if it is to be scrollable, EINA_FALSE otherwise
1060 EAPI void elm_entry_scrollable_set(Evas_Object *obj, Eina_Bool scroll);
1063 * Get the scrollable state of the entry
1065 * Normally the entry is not scrollable. This gets the scrollable state
1066 * of the entry. See elm_entry_scrollable_set() for more information.
1068 * @param obj The entry object
1069 * @return The scrollable state
1071 EAPI Eina_Bool elm_entry_scrollable_get(const Evas_Object *obj);
1074 * Sets the visibility of the left-side widget of the scrolled entry,
1075 * set by elm_entry_icon_set().
1077 * @param obj The scrolled entry object
1078 * @param setting EINA_TRUE if the object should be displayed,
1079 * EINA_FALSE if not.
1081 EAPI void elm_entry_icon_visible_set(Evas_Object *obj, Eina_Bool setting);
1084 * Sets the visibility of the end widget of the scrolled entry, set by
1085 * elm_object_part_content_set(ent, "end", content).
1087 * @param obj The scrolled entry object
1088 * @param setting EINA_TRUE if the object should be displayed,
1089 * EINA_FALSE if not.
1091 EAPI void elm_entry_end_visible_set(Evas_Object *obj, Eina_Bool setting);
1094 * This sets the scrolled entry's scrollbar policy (i.e. enabling/disabling
1097 * Setting an entry to single-line mode with elm_entry_single_line_set()
1098 * will automatically disable the display of scrollbars when the entry
1099 * moves inside its scroller.
1101 * @param obj The scrolled entry object
1102 * @param h The horizontal scrollbar policy to apply
1103 * @param v The vertical scrollbar policy to apply
1105 EAPI void elm_entry_scrollbar_policy_set(Evas_Object *obj, Elm_Scroller_Policy h, Elm_Scroller_Policy v);
1108 * This enables/disables bouncing within the entry.
1110 * This function sets whether the entry will bounce when scrolling reaches
1111 * the end of the contained entry.
1113 * @param obj The scrolled entry object
1114 * @param h_bounce The horizontal bounce state
1115 * @param v_bounce The vertical bounce state
1117 EAPI void elm_entry_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
1120 * Get the bounce mode
1122 * @param obj The Entry object
1123 * @param h_bounce Allow bounce horizontally
1124 * @param v_bounce Allow bounce vertically
1126 EAPI void elm_entry_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
1129 * Set the input panel layout of the entry
1131 * @param obj The entry object
1132 * @param layout layout type
1134 EAPI void elm_entry_input_panel_layout_set(Evas_Object *obj, Elm_Input_Panel_Layout layout);
1137 * Get the input panel layout of the entry
1139 * @param obj The entry object
1140 * @return layout type
1142 * @see elm_entry_input_panel_layout_set
1144 EAPI Elm_Input_Panel_Layout elm_entry_input_panel_layout_get(const Evas_Object *obj);
1147 * Set the autocapitalization type on the immodule.
1149 * @param obj The entry object
1150 * @param autocapital_type The type of autocapitalization
1152 EAPI void elm_entry_autocapital_type_set(Evas_Object *obj, Elm_Autocapital_Type autocapital_type);
1155 * Retrieve the autocapitalization type on the immodule.
1157 * @param obj The entry object
1158 * @return autocapitalization type
1160 EAPI Elm_Autocapital_Type elm_entry_autocapital_type_get(const Evas_Object *obj);
1163 * Sets the attribute to show the input panel automatically.
1165 * @param obj The entry object
1166 * @param enabled If true, the input panel is appeared when entry is clicked or has a focus
1168 EAPI void elm_entry_input_panel_enabled_set(Evas_Object *obj, Eina_Bool enabled);
1171 * Retrieve the attribute to show the input panel automatically.
1173 * @param obj The entry object
1174 * @return EINA_TRUE if input panel will be appeared when the entry is clicked or has a focus, EINA_FALSE otherwise
1176 EAPI Eina_Bool elm_entry_input_panel_enabled_get(const Evas_Object *obj);
1179 * Show the input panel (virtual keyboard) based on the input panel property of entry such as layout, autocapital types, and so on.
1181 * Note that input panel is shown or hidden automatically according to the focus state of entry widget.
1182 * This API can be used in the case of manually controlling by using elm_entry_input_panel_enabled_set(en, EINA_FALSE).
1184 * @param obj The entry object
1186 EAPI void elm_entry_input_panel_show(Evas_Object *obj);
1189 * Hide the input panel (virtual keyboard).
1191 * Note that input panel is shown or hidden automatically according to the focus state of entry widget.
1192 * This API can be used in the case of manually controlling by using elm_entry_input_panel_enabled_set(en, EINA_FALSE)
1194 * @param obj The entry object
1196 EAPI void elm_entry_input_panel_hide(Evas_Object *obj);
1199 * Set the language mode of the input panel.
1201 * This API can be used if you want to show the alphabet keyboard mode.
1203 * @param obj The entry object
1204 * @param lang language to be set to the input panel.
1206 EAPI void elm_entry_input_panel_language_set(Evas_Object *obj, Elm_Input_Panel_Lang lang);
1209 * Get the language mode of the input panel.
1211 * See @ref elm_entry_input_panel_language_set for more details.
1213 * @param obj The entry object
1214 * @return input panel language type
1216 EAPI Elm_Input_Panel_Lang elm_entry_input_panel_language_get(const Evas_Object *obj);
1219 * Set the input panel-specific data to deliver to the input panel.
1221 * This API is used by applications to deliver specific data to the input panel.
1222 * The data format MUST be negotiated by both application and the input panel.
1223 * The size and format of data are defined by the input panel.
1225 * @param obj The entry object
1226 * @param data The specific data to be set to the input panel.
1227 * @param len the length of data, in bytes, to send to the input panel
1229 EAPI void elm_entry_input_panel_imdata_set(Evas_Object *obj, const void *data, int len);
1232 * Get the specific data of the current input panel.
1234 * See @ref elm_entry_input_panel_imdata_set for more details.
1236 * @param obj The entry object
1237 * @param data The specific data to be got from the input panel
1238 * @param len The length of data
1240 EAPI void elm_entry_input_panel_imdata_get(const Evas_Object *obj, void *data, int *len);
1243 * Set the "return" key type. This type is used to set string or icon on the "return" key of the input panel.
1245 * An input panel displays the string or icon associated with this type
1247 * @param obj The entry object
1248 * @param return_key_type The type of "return" key on the input panel
1250 EAPI void elm_entry_input_panel_return_key_type_set(Evas_Object *obj, Elm_Input_Panel_Return_Key_Type return_key_type);
1253 * Get the "return" key type.
1255 * @see elm_entry_input_panel_return_key_type_set() for more details
1257 * @param obj The entry object
1258 * @return The type of "return" key on the input panel
1260 EAPI Elm_Input_Panel_Return_Key_Type elm_entry_input_panel_return_key_type_get(const Evas_Object *obj);
1263 * Set the return key on the input panel to be disabled.
1265 * @param obj The entry object
1266 * @param disabled The state to put in in: @c EINA_TRUE for
1267 * disabled, @c EINA_FALSE for enabled
1269 EAPI void elm_entry_input_panel_return_key_disabled_set(Evas_Object *obj, Eina_Bool disabled);
1272 * Get whether the return key on the input panel should be disabled or not.
1274 * @param obj The entry object
1275 * @return EINA_TRUE if it should be disabled
1277 EAPI Eina_Bool elm_entry_input_panel_return_key_disabled_get(const Evas_Object *obj);
1280 * Set whether the return key on the input panel is disabled automatically when entry has no text.
1282 * If @p enabled is EINA_TRUE, The return key on input panel is disabled when the entry has no text.
1283 * The return key on the input panel is automatically enabled when the entry has text.
1284 * The default value is EINA_FALSE.
1286 * @param obj The entry object
1287 * @param enabled If @p enabled is EINA_TRUE, the return key is automatically disabled when the entry has no text.
1289 EAPI void elm_entry_input_panel_return_key_autoenabled_set(Evas_Object *obj, Eina_Bool enabled);
1292 * Reset the input method context of the entry if needed.
1294 * This can be necessary in the case where modifying the buffer would confuse on-going input method behavior
1295 * @param obj The entry object
1297 EAPI void elm_entry_imf_context_reset(Evas_Object *obj);
1300 * Set whether the entry should allow to use the text prediction.
1302 * @param obj The entry object
1303 * @param prediction Whether the entry should allow to use the text prediction.
1305 EAPI void elm_entry_prediction_allow_set(Evas_Object *obj, Eina_Bool prediction);
1308 * Get whether the entry should allow to use the text prediction.
1310 * @param obj The entry object
1311 * @return EINA_TRUE if it allows to use the text prediction, otherwise EINA_FALSE.
1313 EAPI Eina_Bool elm_entry_prediction_allow_get(const Evas_Object *obj);
1315 /* pre-made filters for entries */
1318 * @typedef Elm_Entry_Filter_Limit_Size
1320 * Data for the elm_entry_filter_limit_size() entry filter.
1322 typedef struct _Elm_Entry_Filter_Limit_Size Elm_Entry_Filter_Limit_Size;
1325 * @struct _Elm_Entry_Filter_Limit_Size
1327 * Data for the elm_entry_filter_limit_size() entry filter.
1329 struct _Elm_Entry_Filter_Limit_Size
1331 int max_char_count; /**< The maximum number of characters allowed. */
1332 int max_byte_count; /**< The maximum number of bytes allowed*/
1336 * Filter inserted text based on user defined character and byte limits
1338 * Add this filter to an entry to limit the characters that it will accept
1339 * based the the contents of the provided #Elm_Entry_Filter_Limit_Size.
1340 * The function works on the UTF-8 representation of the string, converting
1341 * it from the set markup, thus not accounting for any format in it.
1343 * The user must create an #Elm_Entry_Filter_Limit_Size structure and pass
1344 * it as data when setting the filter. In it, it's possible to set limits
1345 * by character count or bytes (any of them is disabled if 0), and both can
1346 * be set at the same time. In that case, it first checks for characters,
1349 * The function will cut the inserted text in order to allow only the first
1350 * number of characters that are still allowed. The cut is made in
1351 * characters, even when limiting by bytes, in order to always contain
1352 * valid ones and avoid half unicode characters making it in.
1354 * This filter, like any others, does not apply when setting the entry text
1355 * directly with elm_object_text_set().
1357 EAPI void elm_entry_filter_limit_size(void *data, Evas_Object *entry, char **text);
1360 * @typedef Elm_Entry_Filter_Accept_Set
1362 * Data for the elm_entry_filter_accept_set() entry filter.
1364 typedef struct _Elm_Entry_Filter_Accept_Set Elm_Entry_Filter_Accept_Set;
1367 * @struct _Elm_Entry_Filter_Accept_Set
1369 * Data for the elm_entry_filter_accept_set() entry filter.
1371 struct _Elm_Entry_Filter_Accept_Set
1373 const char *accepted; /**< Set of characters accepted in the entry. */
1374 const char *rejected; /**< Set of characters rejected from the entry. */
1378 * Filter inserted text based on accepted or rejected sets of characters
1380 * Add this filter to an entry to restrict the set of accepted characters
1381 * based on the sets in the provided #Elm_Entry_Filter_Accept_Set.
1382 * This structure contains both accepted and rejected sets, but they are
1383 * mutually exclusive.
1385 * The @c accepted set takes preference, so if it is set, the filter will
1386 * only work based on the accepted characters, ignoring anything in the
1387 * @c rejected value. If @c accepted is @c NULL, then @c rejected is used.
1389 * In both cases, the function filters by matching utf8 characters to the
1390 * raw markup text, so it can be used to remove formatting tags.
1392 * This filter, like any others, does not apply when setting the entry text
1393 * directly with elm_object_text_set()
1395 EAPI void elm_entry_filter_accept_set(void *data, Evas_Object *entry, char **text);
1398 * Returns the input method context of the entry.
1400 * This function exposes the internal input method context.
1402 * IMPORTANT: Many functions may change (i.e delete and create a new one)
1403 * the internal input method context. Do NOT cache the returned object.
1405 * @param obj The entry object
1406 * @return The input method context (Ecore_IMF_Context *) in entry.
1408 EAPI void *elm_entry_imf_context_get(Evas_Object *obj);