3 ELM_TEXT_FORMAT_PLAIN_UTF8,
4 ELM_TEXT_FORMAT_MARKUP_UTF8
12 ELM_WRAP_NONE = 0, /**< No wrap - value is zero */
13 ELM_WRAP_CHAR, /**< Char wrap - wrap between characters */
14 ELM_WRAP_WORD, /**< Word wrap - wrap in allowed wrapping points (as defined in the unicode standard) */
15 ELM_WRAP_MIXED, /**< Mixed wrap - Word wrap, and if that fails, char wrap. */
17 } Elm_Wrap_Type; /**< Type of word or character wrapping to use */
21 ELM_INPUT_PANEL_LAYOUT_NORMAL, /**< Default layout */
22 ELM_INPUT_PANEL_LAYOUT_NUMBER, /**< Number layout */
23 ELM_INPUT_PANEL_LAYOUT_EMAIL, /**< Email layout */
24 ELM_INPUT_PANEL_LAYOUT_URL, /**< URL layout */
25 ELM_INPUT_PANEL_LAYOUT_PHONENUMBER, /**< Phone Number layout */
26 ELM_INPUT_PANEL_LAYOUT_IP, /**< IP layout */
27 ELM_INPUT_PANEL_LAYOUT_MONTH, /**< Month layout */
28 ELM_INPUT_PANEL_LAYOUT_NUMBERONLY, /**< Number Only layout */
29 ELM_INPUT_PANEL_LAYOUT_INVALID // XXX: remove this so we can expand
30 } Elm_Input_Panel_Layout; /**< Type of input panel (virtual keyboard) to use */
34 ELM_AUTOCAPITAL_TYPE_NONE, /**< No auto-capitalization when typing */
35 ELM_AUTOCAPITAL_TYPE_WORD, /**< Autocapitalize each word typed */
36 ELM_AUTOCAPITAL_TYPE_SENTENCE, /**< Autocapitalize the start of each sentence */
37 ELM_AUTOCAPITAL_TYPE_ALLCHARACTER, /**< Autocapitalize all letters */
38 } Elm_Autocapital_Type; /**< Choose method of auto-capitalization */
41 * @defgroup Entry Entry
43 * @image html img/widget/entry/preview-00.png
44 * @image latex img/widget/entry/preview-00.eps width=\textwidth
45 * @image html img/widget/entry/preview-01.png
46 * @image latex img/widget/entry/preview-01.eps width=\textwidth
47 * @image html img/widget/entry/preview-02.png
48 * @image latex img/widget/entry/preview-02.eps width=\textwidth
49 * @image html img/widget/entry/preview-03.png
50 * @image latex img/widget/entry/preview-03.eps width=\textwidth
52 * An entry is a convenience widget which shows a box that the user can
53 * enter text into. Entries by default don't scroll, so they grow to
54 * accomodate the entire text, resizing the parent window as needed. This
55 * can be changed with the elm_entry_scrollable_set() function.
57 * They can also be single line or multi line (the default) and when set
58 * to multi line mode they support text wrapping in any of the modes
59 * indicated by Elm_Wrap_Type.
61 * Other features include password mode, filtering of inserted text with
62 * elm_entry_text_filter_append() and related functions, inline "items" and
63 * formatted markup text.
65 * @section entry-markup Formatted text
67 * The markup tags supported by the Entry are defined by the theme, but
68 * even when writing new themes or extensions it's a good idea to stick to
69 * a sane default, to maintain coherency and avoid application breakages.
70 * Currently defined by the default theme are the following tags:
71 * @li \<br\>: Inserts a line break.
72 * @li \<ps\>: Inserts a paragraph separator. This is preferred over line
74 * @li \<tab\>: Inserts a tab.
75 * @li \<em\>...\</em\>: Emphasis. Sets the @em oblique style for the
77 * @li \<b\>...\</b\>: Sets the @b bold style for the enclosed text.
78 * @li \<link\>...\</link\>: Underlines the enclosed text.
79 * @li \<hilight\>...\</hilight\>: Hilights the enclosed text.
81 * @section entry-special Special markups
83 * Besides those used to format text, entries support two special markup
84 * tags used to insert clickable portions of text or items inlined within
87 * @subsection entry-anchors Anchors
89 * Anchors are similar to HTML anchors. Text can be surrounded by \<a\> and
90 * \</a\> tags and an event will be generated when this text is clicked,
94 * This text is outside <a href=anc-01>but this one is an anchor</a>
97 * The @c href attribute in the opening tag gives the name that will be
98 * used to identify the anchor and it can be any valid utf8 string.
100 * When an anchor is clicked, an @c "anchor,clicked" signal is emitted with
101 * an #Elm_Entry_Anchor_Info in the @c event_info parameter for the
102 * callback function. The same applies for "anchor,in" (mouse in), "anchor,out"
103 * (mouse out), "anchor,down" (mouse down), and "anchor,up" (mouse up) events on
106 * @subsection entry-items Items
108 * Inlined in the text, any other @c Evas_Object can be inserted by using
109 * \<item\> tags this way:
112 * <item size=16x16 vsize=full href=emoticon/haha></item>
115 * Just like with anchors, the @c href identifies each item, but these need,
116 * in addition, to indicate their size, which is done using any one of
117 * @c size, @c absize or @c relsize attributes. These attributes take their
118 * value in the WxH format, where W is the width and H the height of the
121 * @li absize: Absolute pixel size for the item. Whatever value is set will
122 * be the item's size regardless of any scale value the object may have
123 * been set to. The final line height will be adjusted to fit larger items.
124 * @li size: Similar to @c absize, but it's adjusted to the scale value set
126 * @li relsize: Size is adjusted for the item to fit within the current
129 * Besides their size, items are specificed a @c vsize value that affects
130 * how their final size and position are calculated. The possible values
132 * @li ascent: Item will be placed within the line's baseline and its
133 * ascent. That is, the height between the line where all characters are
134 * positioned and the highest point in the line. For @c size and @c absize
135 * items, the descent value will be added to the total line height to make
136 * them fit. @c relsize items will be adjusted to fit within this space.
137 * @li full: Items will be placed between the descent and ascent, or the
138 * lowest point in the line and its highest.
140 * The next image shows different configurations of items and how
141 * the previously mentioned options affect their sizes. In all cases,
142 * the green line indicates the ascent, blue for the baseline and red for
145 * @image html entry_item.png
146 * @image latex entry_item.eps width=\textwidth
148 * And another one to show how size differs from absize. In the first one,
149 * the scale value is set to 1.0, while the second one is using one of 2.0.
151 * @image html entry_item_scale.png
152 * @image latex entry_item_scale.eps width=\textwidth
154 * After the size for an item is calculated, the entry will request an
155 * object to place in its space. For this, the functions set with
156 * elm_entry_item_provider_append() and related functions will be called
157 * in order until one of them returns a @c non-NULL value. If no providers
158 * are available, or all of them return @c NULL, then the entry falls back
159 * to one of the internal defaults, provided the name matches with one of
162 * All of the following are currently supported:
165 * - emoticon/angry-shout
166 * - emoticon/crazy-laugh
167 * - emoticon/evil-laugh
169 * - emoticon/goggle-smile
171 * - emoticon/grumpy-smile
173 * - emoticon/guilty-smile
175 * - emoticon/half-smile
176 * - emoticon/happy-panting
178 * - emoticon/indifferent
180 * - emoticon/knowing-grin
182 * - emoticon/little-bit-sorry
183 * - emoticon/love-lots
185 * - emoticon/minimal-smile
186 * - emoticon/not-happy
187 * - emoticon/not-impressed
189 * - emoticon/opensmile
192 * - emoticon/squint-laugh
193 * - emoticon/surprised
194 * - emoticon/suspicious
195 * - emoticon/tongue-dangling
196 * - emoticon/tongue-poke
199 * - emoticon/very-sorry
205 * Alternatively, an item may reference an image by its path, using
206 * the URI form @c file:///path/to/an/image.png and the entry will then
207 * use that image for the item.
209 * @section entry-files Loading and saving files
211 * Entries have convinience functions to load text from a file and save
212 * changes back to it after a short delay. The automatic saving is enabled
213 * by default, but can be disabled with elm_entry_autosave_set() and files
214 * can be loaded directly as plain text or have any markup in them
215 * recognized. See elm_entry_file_set() for more details.
217 * @section entry-signals Emitted signals
219 * This widget emits the following signals:
221 * @li "changed": The text within the entry was changed.
222 * @li "changed,user": The text within the entry was changed because of user interaction.
223 * @li "activated": The enter key was pressed on a single line entry.
224 * @li "press": A mouse button has been pressed on the entry.
225 * @li "longpressed": A mouse button has been pressed and held for a couple
227 * @li "clicked": The entry has been clicked (mouse press and release).
228 * @li "clicked,double": The entry has been double clicked.
229 * @li "clicked,triple": The entry has been triple clicked.
230 * @li "focused": The entry has received focus.
231 * @li "unfocused": The entry has lost focus.
232 * @li "selection,paste": A paste of the clipboard contents was requested.
233 * @li "selection,copy": A copy of the selected text into the clipboard was
235 * @li "selection,cut": A cut of the selected text into the clipboard was
237 * @li "selection,start": A selection has begun and no previous selection
239 * @li "selection,changed": The current selection has changed.
240 * @li "selection,cleared": The current selection has been cleared.
241 * @li "cursor,changed": The cursor has changed position.
242 * @li "anchor,clicked": An anchor has been clicked. The event_info
243 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
244 * @li "anchor,in": Mouse cursor has moved into an anchor. The event_info
245 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
246 * @li "anchor,out": Mouse cursor has moved out of an anchor. The event_info
247 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
248 * @li "anchor,up": Mouse button has been unpressed on an anchor. The event_info
249 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
250 * @li "anchor,down": Mouse button has been pressed on an anchor. The event_info
251 * parameter for the callback will be an #Elm_Entry_Anchor_Info.
252 * @li "preedit,changed": The preedit string has changed.
253 * @li "language,changed": Program language changed.
255 * @section entry-examples
257 * An overview of the Entry API can be seen in @ref entry_example_01
263 * @typedef Elm_Entry_Anchor_Info
265 * The info sent in the callback for the "anchor,clicked" signals emitted
268 typedef struct _Elm_Entry_Anchor_Info Elm_Entry_Anchor_Info;
271 * @struct _Elm_Entry_Anchor_Info
273 * The info sent in the callback for the "anchor,clicked" signals emitted
276 struct _Elm_Entry_Anchor_Info
278 const char *name; /**< The name of the anchor, as stated in its href */
279 int button; /**< The mouse button used to click on it */
280 Evas_Coord x, /**< Anchor geometry, relative to canvas */
281 y, /**< Anchor geometry, relative to canvas */
282 w, /**< Anchor geometry, relative to canvas */
283 h; /**< Anchor geometry, relative to canvas */
287 * @typedef Elm_Entry_Filter_Cb
288 * This callback type is used by entry filters to modify text.
289 * @param data The data specified as the last param when adding the filter
290 * @param entry The entry object
291 * @param text A pointer to the location of the text being filtered. This data can be modified,
292 * but any additional allocations must be managed by the user.
293 * @see elm_entry_text_filter_append
294 * @see elm_entry_text_filter_prepend
296 typedef void (*Elm_Entry_Filter_Cb)(void *data, Evas_Object *entry, char **text);
299 * @typedef Elm_Entry_Change_Info
300 * This corresponds to Edje_Entry_Change_Info. Includes information about
301 * a change in the entry.
303 typedef Edje_Entry_Change_Info Elm_Entry_Change_Info;
306 * This adds an entry to @p parent object.
308 * By default, entries are:
312 * @li autosave is enabled
314 * @param parent The parent object
315 * @return The new object or NULL if it cannot be created
317 EAPI Evas_Object *elm_entry_add(Evas_Object *parent);
320 * Sets the entry to single line mode.
322 * In single line mode, entries don't ever wrap when the text reaches the
323 * edge, and instead they keep growing horizontally. Pressing the @c Enter
324 * key will generate an @c "activate" event instead of adding a new line.
326 * When @p single_line is @c EINA_FALSE, line wrapping takes effect again
327 * and pressing enter will break the text into a different line
328 * without generating any events.
330 * @param obj The entry object
331 * @param single_line If true, the text in the entry
332 * will be on a single line.
334 EAPI void elm_entry_single_line_set(Evas_Object *obj, Eina_Bool single_line);
337 * Gets whether the entry is set to be single line.
339 * @param obj The entry object
340 * @return single_line If true, the text in the entry is set to display
343 * @see elm_entry_single_line_set()
345 EAPI Eina_Bool elm_entry_single_line_get(const Evas_Object *obj);
348 * Sets the entry to password mode.
350 * In password mode, entries are implicitly single line and the display of
351 * any text in them is replaced with asterisks (*).
353 * @param obj The entry object
354 * @param password If true, password mode is enabled.
356 EAPI void elm_entry_password_set(Evas_Object *obj, Eina_Bool password);
359 * Gets whether the entry is set to password mode.
361 * @param obj The entry object
362 * @return If true, the entry is set to display all characters
365 * @see elm_entry_password_set()
367 EAPI Eina_Bool elm_entry_password_get(const Evas_Object *obj);
370 * Appends @p entry to the text of the entry.
372 * Adds the text in @p entry to the end of any text already present in the
375 * The appended text is subject to any filters set for the widget.
377 * @param obj The entry object
378 * @param entry The text to be displayed
380 * @see elm_entry_text_filter_append()
382 EAPI void elm_entry_entry_append(Evas_Object *obj, const char *entry);
385 * Gets whether the entry is empty.
387 * Empty means no text at all. If there are any markup tags, like an item
388 * tag for which no provider finds anything, and no text is displayed, this
389 * function still returns EINA_FALSE.
391 * @param obj The entry object
392 * @return EINA_TRUE if the entry is empty, EINA_FALSE otherwise.
394 EAPI Eina_Bool elm_entry_is_empty(const Evas_Object *obj);
397 * Gets any selected text within the entry.
399 * If there's any selected text in the entry, this function returns it as
400 * a string in markup format. NULL is returned if no selection exists or
401 * if an error occurred.
403 * The returned value points to an internal string and should not be freed
404 * or modified in any way. If the @p entry object is deleted or its
405 * contents are changed, the returned pointer should be considered invalid.
407 * @param obj The entry object
408 * @return The selected text within the entry or NULL on failure
410 EAPI const char *elm_entry_selection_get(const Evas_Object *obj);
413 * Returns the actual textblock object of the entry.
415 * This function exposes the internal textblock object that actually
416 * contains and draws the text. This should be used for low-level
417 * manipulations that are otherwise not possible.
419 * Changing the textblock directly from here will not notify edje/elm to
420 * recalculate the textblock size automatically, so any modifications
421 * done to the textblock returned by this function should be followed by
422 * a call to elm_entry_calc_force().
424 * The return value is marked as const as an additional warning.
425 * One should not use the returned object with any of the generic evas
426 * functions (geometry_get/resize/move and etc), but only with the textblock
427 * functions; The former will either not work at all, or break the correct
430 * IMPORTANT: Many functions may change (i.e delete and create a new one)
431 * the internal textblock object. Do NOT cache the returned object, and try
432 * not to mix calls on this object with regular elm_entry calls (which may
433 * change the internal textblock object). This applies to all cursors
434 * returned from textblock calls, and all the other derivative values.
436 * @param obj The entry object
437 * @return The textblock object.
439 EAPI const Evas_Object *elm_entry_textblock_get(const Evas_Object *obj);
442 * Forces calculation of the entry size and text layouting.
444 * This should be used after modifying the textblock object directly. See
445 * elm_entry_textblock_get() for more information.
447 * @param obj The entry object
449 * @see elm_entry_textblock_get()
451 EAPI void elm_entry_calc_force(const Evas_Object *obj);
454 * Inserts the given text into the entry at the current cursor position.
456 * This inserts text at the cursor position as if it was typed
457 * by the user (note that this also allows markup which a user
458 * can't just "type" as it would be converted to escaped text, so this
459 * call can be used to insert things like emoticon items or bold push/pop
460 * tags, other font and color change tags etc.)
462 * If any selection exists, it will be replaced by the inserted text.
464 * The inserted text is subject to any filters set for the widget.
466 * @param obj The entry object
467 * @param entry The text to insert
469 * @see elm_entry_text_filter_append()
471 EAPI void elm_entry_entry_insert(Evas_Object *obj, const char *entry);
474 * Set the line wrap type to use on multi-line entries.
476 * Sets the wrap type used by the entry to any of the specified in
477 * Elm_Wrap_Type. This tells how the text will be implicitly cut into a new
478 * line (without inserting a line break or paragraph separator) when it
479 * reaches the far edge of the widget.
481 * Note that this only makes sense for multi-line entries. A widget set
482 * to be single line will never wrap.
484 * @param obj The entry object
485 * @param wrap The wrap mode to use. See Elm_Wrap_Type for details on them
487 EAPI void elm_entry_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap);
490 * Gets the wrap mode the entry was set to use.
492 * @param obj The entry object
495 * @see also elm_entry_line_wrap_set()
497 EAPI Elm_Wrap_Type elm_entry_line_wrap_get(const Evas_Object *obj);
500 * Sets if the entry is to be editable or not.
502 * By default, entries are editable and when focused, any text input by the
503 * user will be inserted at the current cursor position. But calling this
504 * function with @p editable as EINA_FALSE will prevent the user from
505 * inputting text into the entry.
507 * The only way to change the text of a non-editable entry is to use
508 * elm_object_text_set(), elm_entry_entry_insert() and other related
511 * @param obj The entry object
512 * @param editable If EINA_TRUE, user input will be inserted in the entry,
513 * if not, the entry is read-only and no user input is allowed.
515 EAPI void elm_entry_editable_set(Evas_Object *obj, Eina_Bool editable);
518 * Gets whether the entry is editable or not.
520 * @param obj The entry object
521 * @return If true, the entry is editable by the user.
522 * If false, it is not editable by the user
524 * @see elm_entry_editable_set()
526 EAPI Eina_Bool elm_entry_editable_get(const Evas_Object *obj);
529 * This drops any existing text selection within the entry.
531 * @param obj The entry object
533 EAPI void elm_entry_select_none(Evas_Object *obj);
536 * This selects all text within the entry.
538 * @param obj The entry object
540 EAPI void elm_entry_select_all(Evas_Object *obj);
543 * This moves the cursor one place to the right within the entry.
545 * @param obj The entry object
546 * @return EINA_TRUE upon success, EINA_FALSE upon failure
548 EAPI Eina_Bool elm_entry_cursor_next(Evas_Object *obj);
551 * This moves the cursor one place to the left within the entry.
553 * @param obj The entry object
554 * @return EINA_TRUE upon success, EINA_FALSE upon failure
556 EAPI Eina_Bool elm_entry_cursor_prev(Evas_Object *obj);
559 * This moves the cursor one line up within the entry.
561 * @param obj The entry object
562 * @return EINA_TRUE upon success, EINA_FALSE upon failure
564 EAPI Eina_Bool elm_entry_cursor_up(Evas_Object *obj);
567 * This moves the cursor one line down within the entry.
569 * @param obj The entry object
570 * @return EINA_TRUE upon success, EINA_FALSE upon failure
572 EAPI Eina_Bool elm_entry_cursor_down(Evas_Object *obj);
575 * This moves the cursor to the beginning of the entry.
577 * @param obj The entry object
579 EAPI void elm_entry_cursor_begin_set(Evas_Object *obj);
582 * This moves the cursor to the end of the entry.
584 * @param obj The entry object
586 EAPI void elm_entry_cursor_end_set(Evas_Object *obj);
589 * This moves the cursor to the beginning of the current line.
591 * @param obj The entry object
593 EAPI void elm_entry_cursor_line_begin_set(Evas_Object *obj);
596 * This moves the cursor to the end of the current line.
598 * @param obj The entry object
600 EAPI void elm_entry_cursor_line_end_set(Evas_Object *obj);
603 * This begins a selection within the entry as though
604 * the user were holding down the mouse button to make a selection.
606 * @param obj The entry object
608 EAPI void elm_entry_cursor_selection_begin(Evas_Object *obj);
611 * This ends a selection within the entry as though
612 * the user had just released the mouse button while making a selection.
614 * @param obj The entry object
616 EAPI void elm_entry_cursor_selection_end(Evas_Object *obj);
619 * Gets whether a format node exists at the current cursor position.
621 * A format node is anything that defines how the text is rendered. It can
622 * be a visible format node, such as a line break or a paragraph separator,
623 * or an invisible one, such as bold begin or end tag.
624 * This function returns whether any format node exists at the current
627 * @param obj The entry object
628 * @return EINA_TRUE if the current cursor position contains a format node,
629 * EINA_FALSE otherwise.
631 * @see elm_entry_cursor_is_visible_format_get()
633 EAPI Eina_Bool elm_entry_cursor_is_format_get(const Evas_Object *obj);
636 * Gets if the current cursor position holds a visible format node.
638 * @param obj The entry object
639 * @return EINA_TRUE if the current cursor is a visible format, EINA_FALSE
640 * if it's an invisible one or no format exists.
642 * @see elm_entry_cursor_is_format_get()
644 EAPI Eina_Bool elm_entry_cursor_is_visible_format_get(const Evas_Object *obj);
647 * Gets the character pointed by the cursor at its current position.
649 * This function returns a string with the utf8 character stored at the
650 * current cursor position.
651 * Only the text is returned, any format that may exist will not be part
652 * of the return value.
654 * @param obj The entry object
655 * @return The text pointed by the cursors.
657 EAPI const char *elm_entry_cursor_content_get(const Evas_Object *obj);
660 * This function returns the geometry of the cursor.
662 * It's useful if you want to draw something on the cursor (or where it is),
663 * or for example in the case of scrolled entry where you want to show the
666 * @param obj The entry object
667 * @param x returned geometry
668 * @param y returned geometry
669 * @param w returned geometry
670 * @param h returned geometry
671 * @return EINA_TRUE upon success, EINA_FALSE upon failure
673 EAPI Eina_Bool elm_entry_cursor_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h);
676 * Sets the cursor position in the entry to the given value
678 * The value in @p pos is the index of the character position within the
679 * contents of the string as returned by elm_entry_cursor_pos_get().
681 * @param obj The entry object
682 * @param pos The position of the cursor
684 EAPI void elm_entry_cursor_pos_set(Evas_Object *obj, int pos);
687 * Retrieves the current position of the cursor in the entry
689 * @param obj The entry object
690 * @return The cursor position
692 EAPI int elm_entry_cursor_pos_get(const Evas_Object *obj);
695 * This executes a "cut" action on the selected text in the entry.
697 * @param obj The entry object
699 EAPI void elm_entry_selection_cut(Evas_Object *obj);
702 * This executes a "copy" action on the selected text in the entry.
704 * @param obj The entry object
706 EAPI void elm_entry_selection_copy(Evas_Object *obj);
709 * This executes a "paste" action in the entry.
711 * @param obj The entry object
713 EAPI void elm_entry_selection_paste(Evas_Object *obj);
716 * This clears and frees the items in a entry's contextual (longpress)
719 * @param obj The entry object
721 * @see elm_entry_context_menu_item_add()
723 EAPI void elm_entry_context_menu_clear(Evas_Object *obj);
726 * This adds an item to the entry's contextual menu.
728 * A longpress on an entry will make the contextual menu show up, if this
729 * hasn't been disabled with elm_entry_context_menu_disabled_set().
730 * By default, this menu provides a few options like enabling selection mode,
731 * which is useful on embedded devices that need to be explicit about it,
732 * and when a selection exists it also shows the copy and cut actions.
734 * With this function, developers can add other options to this menu to
735 * perform any action they deem necessary.
737 * @param obj The entry object
738 * @param label The item's text label
739 * @param icon_file The item's icon file
740 * @param icon_type The item's icon type
741 * @param func The callback to execute when the item is clicked
742 * @param data The data to associate with the item for related functions
744 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);
747 * This disables the entry's contextual (longpress) menu.
749 * @param obj The entry object
750 * @param disabled If true, the menu is disabled
752 EAPI void elm_entry_context_menu_disabled_set(Evas_Object *obj, Eina_Bool disabled);
755 * This returns whether the entry's contextual (longpress) menu is
758 * @param obj The entry object
759 * @return If true, the menu is disabled
761 EAPI Eina_Bool elm_entry_context_menu_disabled_get(const Evas_Object *obj);
764 * This appends a custom item provider to the list for that entry
766 * This appends the given callback. The list is walked from beginning to end
767 * with each function called given the item href string in the text. If the
768 * function returns an object handle other than NULL (it should create an
769 * object to do this), then this object is used to replace that item. If
770 * not the next provider is called until one provides an item object, or the
771 * default provider in entry does.
773 * @param obj The entry object
774 * @param func The function called to provide the item object
775 * @param data The data passed to @p func
777 * @see @ref entry-items
779 EAPI void elm_entry_item_provider_append(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
782 * This prepends a custom item provider to the list for that entry
784 * This prepends the given callback. See elm_entry_item_provider_append() for
787 * @param obj The entry object
788 * @param func The function called to provide the item object
789 * @param data The data passed to @p func
791 EAPI void elm_entry_item_provider_prepend(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
794 * This removes a custom item provider to the list for that entry
796 * This removes the given callback. See elm_entry_item_provider_append() for
799 * @param obj The entry object
800 * @param func The function called to provide the item object
801 * @param data The data passed to @p func
803 EAPI void elm_entry_item_provider_remove(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
806 * Append a filter function for text inserted in the entry
808 * Append the given callback to the list. This functions will be called
809 * whenever any text is inserted into the entry, with the text to be inserted
810 * as a parameter. The callback function is free to alter the text in any way
811 * it wants, but it must remember to free the given pointer and update it.
812 * If the new text is to be discarded, the function can free it and set its
813 * text parameter to NULL. This will also prevent any following filters from
816 * @param obj The entry object
817 * @param func The function to use as text filter
818 * @param data User data to pass to @p func
820 EAPI void elm_entry_text_filter_append(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
823 * Prepend a filter function for text insdrted in the entry
825 * Prepend the given callback to the list. See elm_entry_text_filter_append()
826 * for more information
828 * @param obj The entry object
829 * @param func The function to use as text filter
830 * @param data User data to pass to @p func
832 EAPI void elm_entry_text_filter_prepend(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
835 * Remove a filter from the list
837 * Removes the given callback from the filter list. See
838 * elm_entry_text_filter_append() for more information.
840 * @param obj The entry object
841 * @param func The filter function to remove
842 * @param data The user data passed when adding the function
844 EAPI void elm_entry_text_filter_remove(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
847 * This converts a markup (HTML-like) string into UTF-8.
849 * The returned string is a malloc'ed buffer and it should be freed when
850 * not needed anymore.
852 * @param s The string (in markup) to be converted
853 * @return The converted string (in UTF-8). It should be freed.
855 EAPI char *elm_entry_markup_to_utf8(const char *s)
856 EINA_MALLOC EINA_WARN_UNUSED_RESULT;
859 * This converts a UTF-8 string into markup (HTML-like).
861 * The returned string is a malloc'ed buffer and it should be freed when
862 * not needed anymore.
864 * @param s The string (in UTF-8) to be converted
865 * @return The converted string (in markup). It should be freed.
867 EAPI char *elm_entry_utf8_to_markup(const char *s)
868 EINA_MALLOC EINA_WARN_UNUSED_RESULT;
871 * This sets the file (and implicitly loads it) for the text to display and
872 * then edit. All changes are written back to the file after a short delay if
873 * the entry object is set to autosave (which is the default).
875 * If the entry had any other file set previously, any changes made to it
876 * will be saved if the autosave feature is enabled, otherwise, the file
877 * will be silently discarded and any non-saved changes will be lost.
879 * @param obj The entry object
880 * @param file The path to the file to load and save
881 * @param format The file format
883 EAPI void elm_entry_file_set(Evas_Object *obj, const char *file, Elm_Text_Format format);
886 * Gets the file being edited by the entry.
888 * This function can be used to retrieve any file set on the entry for
889 * edition, along with the format used to load and save it.
891 * @param obj The entry object
892 * @param file The path to the file to load and save
893 * @param format The file format
895 EAPI void elm_entry_file_get(const Evas_Object *obj, const char **file, Elm_Text_Format *format);
898 * This function writes any changes made to the file set with
899 * elm_entry_file_set()
901 * @param obj The entry object
903 EAPI void elm_entry_file_save(Evas_Object *obj);
906 * This sets the entry object to 'autosave' the loaded text file or not.
908 * @param obj The entry object
909 * @param autosave Autosave the loaded file or not
911 * @see elm_entry_file_set()
913 EAPI void elm_entry_autosave_set(Evas_Object *obj, Eina_Bool autosave);
916 * This gets the entry object's 'autosave' status.
918 * @param obj The entry object
919 * @return Autosave the loaded file or not
921 * @see elm_entry_file_set()
923 EAPI Eina_Bool elm_entry_autosave_get(const Evas_Object *obj);
926 * Control pasting of text and images for the widget.
928 * Normally the entry allows both text and images to be pasted. By setting
929 * textonly to be true, this prevents images from being pasted.
931 * Note this only changes the behaviour of text.
933 * @param obj The entry object
934 * @param textonly paste mode - EINA_TRUE is text only, EINA_FALSE is
937 EAPI void elm_entry_cnp_textonly_set(Evas_Object *obj, Eina_Bool textonly);
940 * Getting elm_entry text paste/drop mode.
942 * In textonly mode, only text may be pasted or dropped into the widget.
944 * @param obj The entry object
945 * @return If the widget only accepts text from pastes.
947 EAPI Eina_Bool elm_entry_cnp_textonly_get(const Evas_Object *obj);
950 * Enable or disable scrolling in entry
952 * Normally the entry is not scrollable unless you enable it with this call.
954 * @param obj The entry object
955 * @param scroll EINA_TRUE if it is to be scrollable, EINA_FALSE otherwise
957 EAPI void elm_entry_scrollable_set(Evas_Object *obj, Eina_Bool scroll);
960 * Get the scrollable state of the entry
962 * Normally the entry is not scrollable. This gets the scrollable state
963 * of the entry. See elm_entry_scrollable_set() for more information.
965 * @param obj The entry object
966 * @return The scrollable state
968 EAPI Eina_Bool elm_entry_scrollable_get(const Evas_Object *obj);
971 * This sets a widget to be displayed to the left of a scrolled entry.
973 * @param obj The scrolled entry object
974 * @param icon The widget to display on the left side of the scrolled
977 * @note A previously set widget will be destroyed.
978 * @note If the object being set does not have minimum size hints set,
979 * it won't get properly displayed.
981 * @see elm_entry_end_set()
983 EAPI void elm_entry_icon_set(Evas_Object *obj, Evas_Object *icon);
986 * Gets the leftmost widget of the scrolled entry. This object is
987 * owned by the scrolled entry and should not be modified.
989 * @param obj The scrolled entry object
990 * @return the left widget inside the scroller
992 EAPI Evas_Object *elm_entry_icon_get(const Evas_Object *obj);
995 * Unset the leftmost widget of the scrolled entry, unparenting and
998 * @param obj The scrolled entry object
999 * @return the previously set icon sub-object of this entry, on
1002 * @see elm_entry_icon_set()
1004 EAPI Evas_Object *elm_entry_icon_unset(Evas_Object *obj);
1007 * Sets the visibility of the left-side widget of the scrolled entry,
1008 * set by elm_entry_icon_set().
1010 * @param obj The scrolled entry object
1011 * @param setting EINA_TRUE if the object should be displayed,
1012 * EINA_FALSE if not.
1014 EAPI void elm_entry_icon_visible_set(Evas_Object *obj, Eina_Bool setting);
1017 * This sets a widget to be displayed to the end of a scrolled entry.
1019 * @param obj The scrolled entry object
1020 * @param end The widget to display on the right side of the scrolled
1023 * @note A previously set widget will be destroyed.
1024 * @note If the object being set does not have minimum size hints set,
1025 * it won't get properly displayed.
1027 * @see elm_entry_icon_set
1029 EAPI void elm_entry_end_set(Evas_Object *obj, Evas_Object *end);
1032 * Gets the endmost widget of the scrolled entry. This object is owned
1033 * by the scrolled entry and should not be modified.
1035 * @param obj The scrolled entry object
1036 * @return the right widget inside the scroller
1038 EAPI Evas_Object *elm_entry_end_get(const Evas_Object *obj);
1041 * Unset the endmost widget of the scrolled entry, unparenting and
1044 * @param obj The scrolled entry object
1045 * @return the previously set icon sub-object of this entry, on
1048 * @see elm_entry_icon_set()
1050 EAPI Evas_Object *elm_entry_end_unset(Evas_Object *obj);
1053 * Sets the visibility of the end widget of the scrolled entry, set by
1054 * elm_entry_end_set().
1056 * @param obj The scrolled entry object
1057 * @param setting EINA_TRUE if the object should be displayed,
1058 * EINA_FALSE if not.
1060 EAPI void elm_entry_end_visible_set(Evas_Object *obj, Eina_Bool setting);
1063 * This sets the scrolled entry's scrollbar policy (ie. enabling/disabling
1066 * Setting an entry to single-line mode with elm_entry_single_line_set()
1067 * will automatically disable the display of scrollbars when the entry
1068 * moves inside its scroller.
1070 * @param obj The scrolled entry object
1071 * @param h The horizontal scrollbar policy to apply
1072 * @param v The vertical scrollbar policy to apply
1074 EAPI void elm_entry_scrollbar_policy_set(Evas_Object *obj, Elm_Scroller_Policy h, Elm_Scroller_Policy v);
1077 * This enables/disables bouncing within the entry.
1079 * This function sets whether the entry will bounce when scrolling reaches
1080 * the end of the contained entry.
1082 * @param obj The scrolled entry object
1083 * @param h_bounce The horizontal bounce state
1084 * @param v_bounce The vertical bounce state
1086 EAPI void elm_entry_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
1089 * Get the bounce mode
1091 * @param obj The Entry object
1092 * @param h_bounce Allow bounce horizontally
1093 * @param v_bounce Allow bounce vertically
1095 EAPI void elm_entry_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
1097 /* pre-made filters for entries */
1099 * @typedef Elm_Entry_Filter_Limit_Size
1101 * Data for the elm_entry_filter_limit_size() entry filter.
1103 typedef struct _Elm_Entry_Filter_Limit_Size Elm_Entry_Filter_Limit_Size;
1106 * @struct _Elm_Entry_Filter_Limit_Size
1108 * Data for the elm_entry_filter_limit_size() entry filter.
1110 struct _Elm_Entry_Filter_Limit_Size
1112 int max_char_count; /**< The maximum number of characters allowed. */
1113 int max_byte_count; /**< The maximum number of bytes allowed*/
1117 * Filter inserted text based on user defined character and byte limits
1119 * Add this filter to an entry to limit the characters that it will accept
1120 * based the the contents of the provided #Elm_Entry_Filter_Limit_Size.
1121 * The funtion works on the UTF-8 representation of the string, converting
1122 * it from the set markup, thus not accounting for any format in it.
1124 * The user must create an #Elm_Entry_Filter_Limit_Size structure and pass
1125 * it as data when setting the filter. In it, it's possible to set limits
1126 * by character count or bytes (any of them is disabled if 0), and both can
1127 * be set at the same time. In that case, it first checks for characters,
1130 * The function will cut the inserted text in order to allow only the first
1131 * number of characters that are still allowed. The cut is made in
1132 * characters, even when limiting by bytes, in order to always contain
1133 * valid ones and avoid half unicode characters making it in.
1135 * This filter, like any others, does not apply when setting the entry text
1136 * directly with elm_object_text_set().
1138 EAPI void elm_entry_filter_limit_size(void *data, Evas_Object *entry, char **text);
1141 * @typedef Elm_Entry_Filter_Accept_Set
1143 * Data for the elm_entry_filter_accept_set() entry filter.
1145 typedef struct _Elm_Entry_Filter_Accept_Set Elm_Entry_Filter_Accept_Set;
1148 * @struct _Elm_Entry_Filter_Accept_Set
1150 * Data for the elm_entry_filter_accept_set() entry filter.
1152 struct _Elm_Entry_Filter_Accept_Set
1154 const char *accepted; /**< Set of characters accepted in the entry. */
1155 const char *rejected; /**< Set of characters rejected from the entry. */
1159 * Filter inserted text based on accepted or rejected sets of characters
1161 * Add this filter to an entry to restrict the set of accepted characters
1162 * based on the sets in the provided #Elm_Entry_Filter_Accept_Set.
1163 * This structure contains both accepted and rejected sets, but they are
1164 * mutually exclusive.
1166 * The @c accepted set takes preference, so if it is set, the filter will
1167 * only work based on the accepted characters, ignoring anything in the
1168 * @c rejected value. If @c accepted is @c NULL, then @c rejected is used.
1170 * In both cases, the function filters by matching utf8 characters to the
1171 * raw markup text, so it can be used to remove formatting tags.
1173 * This filter, like any others, does not apply when setting the entry text
1174 * directly with elm_object_text_set()
1176 EAPI void elm_entry_filter_accept_set(void *data, Evas_Object *entry, char **text);
1178 * Set the input panel layout of the entry
1180 * @param obj The entry object
1181 * @param layout layout type
1183 EAPI void elm_entry_input_panel_layout_set(Evas_Object *obj, Elm_Input_Panel_Layout layout);
1186 * Get the input panel layout of the entry
1188 * @param obj The entry object
1189 * @return layout type
1191 * @see elm_entry_input_panel_layout_set
1193 EAPI Elm_Input_Panel_Layout elm_entry_input_panel_layout_get(Evas_Object *obj);
1196 * Set the autocapitalization type on the immodule.
1198 * @param obj The entry object
1199 * @param autocapital_type The type of autocapitalization
1201 EAPI void elm_entry_autocapital_type_set(Evas_Object *obj, Elm_Autocapital_Type autocapital_type);
1204 * Retrieve the autocapitalization type on the immodule.
1206 * @param obj The entry object
1207 * @return autocapitalization type
1209 EAPI Elm_Autocapital_Type elm_entry_autocapital_type_get(Evas_Object *obj);
1212 * Sets the attribute to show the input panel automatically.
1214 * @param obj The entry object
1215 * @param enabled If true, the input panel is appeared when entry is clicked or has a focus
1217 EAPI void elm_entry_input_panel_enabled_set(Evas_Object *obj, Eina_Bool enabled);
1220 * Retrieve the attribute to show the input panel automatically.
1222 * @param obj The entry object
1223 * @return EINA_TRUE if input panel will be appeared when the entry is clicked or has a focus, EINA_FALSE otherwise
1225 EAPI Eina_Bool elm_entry_input_panel_enabled_get(Evas_Object *obj);