dd8bab9b3cd5511c8cb8320c0ae071d16dfc07f3
[framework/uifw/elementary.git] / src / lib / elm_entry.h
1 typedef enum
2 {
3    ELM_TEXT_FORMAT_PLAIN_UTF8,
4    ELM_TEXT_FORMAT_MARKUP_UTF8
5 } Elm_Text_Format;
6
7 /**
8  * Line wrapping types.
9  */
10 typedef enum
11 {
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. */
16    ELM_WRAP_LAST
17 } Elm_Wrap_Type; /**< Type of word or character wrapping to use */
18
19 typedef enum
20 {
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, /**< Never use this */
30    ELM_INPUT_PANEL_LAYOUT_HEX, /**< Hexadecimal layout */
31    ELM_INPUT_PANEL_LAYOUT_TERMINAL, /**< Command-line terminal layout */
32    ELM_INPUT_PANEL_LAYOUT_PASSWORD /**< Like normal, but no auto-correct, no auto-capitalization etc. */
33 } Elm_Input_Panel_Layout; /**< Type of input panel (virtual keyboard) to use - this is a hint and may not provide exactly what is desired. */
34
35 typedef enum
36 {
37    ELM_INPUT_PANEL_LANG_AUTOMATIC,    /**< Automatic */
38    ELM_INPUT_PANEL_LANG_ALPHABET      /**< Alphabet */
39 } Elm_Input_Panel_Lang;
40
41 typedef enum
42 {
43    ELM_AUTOCAPITAL_TYPE_NONE, /**< No auto-capitalization when typing */
44    ELM_AUTOCAPITAL_TYPE_WORD, /**< Autocapitalize each word typed */
45    ELM_AUTOCAPITAL_TYPE_SENTENCE, /**< Autocapitalize the start of each sentence */
46    ELM_AUTOCAPITAL_TYPE_ALLCHARACTER, /**< Autocapitalize all letters */
47 } Elm_Autocapital_Type; /**< Choose method of auto-capitalization */
48
49 typedef enum
50 {
51    ELM_INPUT_PANEL_RETURN_KEY_TYPE_DEFAULT,
52    ELM_INPUT_PANEL_RETURN_KEY_TYPE_DONE,
53    ELM_INPUT_PANEL_RETURN_KEY_TYPE_GO,
54    ELM_INPUT_PANEL_RETURN_KEY_TYPE_JOIN,
55    ELM_INPUT_PANEL_RETURN_KEY_TYPE_LOGIN,
56    ELM_INPUT_PANEL_RETURN_KEY_TYPE_NEXT,
57    ELM_INPUT_PANEL_RETURN_KEY_TYPE_SEARCH,
58    ELM_INPUT_PANEL_RETURN_KEY_TYPE_SEND
59 } Elm_Input_Panel_Return_Key_Type;
60
61 /**
62  * @defgroup Entry Entry
63  *
64  * @image html img/widget/entry/preview-00.png
65  * @image latex img/widget/entry/preview-00.eps width=\textwidth
66  * @image html img/widget/entry/preview-01.png
67  * @image latex img/widget/entry/preview-01.eps width=\textwidth
68  * @image html img/widget/entry/preview-02.png
69  * @image latex img/widget/entry/preview-02.eps width=\textwidth
70  * @image html img/widget/entry/preview-03.png
71  * @image latex img/widget/entry/preview-03.eps width=\textwidth
72  *
73  * An entry is a convenience widget which shows a box that the user can
74  * enter text into. Entries by default don't scroll, so they grow to
75  * accommodate the entire text, resizing the parent window as needed. This
76  * can be changed with the elm_entry_scrollable_set() function.
77  *
78  * They can also be single line or multi line (the default) and when set
79  * to multi line mode they support text wrapping in any of the modes
80  * indicated by Elm_Wrap_Type.
81  *
82  * Other features include password mode, filtering of inserted text with
83  * elm_entry_markup_filter_append() and related functions, inline "items" and
84  * formatted markup text.
85  *
86  * @section entry-markup Formatted text
87  *
88  * The markup tags supported by the Entry are defined by the theme, but
89  * even when writing new themes or extensions it's a good idea to stick to
90  * a sane default, to maintain coherency and avoid application breakages.
91  * Currently defined by the default theme are the following tags:
92  * @li \<br\>: Inserts a line break.
93  * @li \<ps\>: Inserts a paragraph separator. This is preferred over line
94  * breaks.
95  * @li \<tab\>: Inserts a tab.
96  * @li \<em\>...\</em\>: Emphasis. Sets the @em oblique style for the
97  * enclosed text.
98  * @li \<b\>...\</b\>: Sets the @b bold style for the enclosed text.
99  * @li \<link\>...\</link\>: Underlines the enclosed text.
100  * @li \<hilight\>...\</hilight\>: Highlights the enclosed text.
101  *
102  * @section entry-special Special markups
103  *
104  * Besides those used to format text, entries support two special markup
105  * tags used to insert click-able portions of text or items inlined within
106  * the text.
107  *
108  * @subsection entry-anchors Anchors
109  *
110  * Anchors are similar to HTML anchors. Text can be surrounded by \<a\> and
111  * \</a\> tags and an event will be generated when this text is clicked,
112  * like this:
113  *
114  * @code
115  * This text is outside <a href=anc-01>but this one is an anchor</a>
116  * @endcode
117  *
118  * The @c href attribute in the opening tag gives the name that will be
119  * used to identify the anchor and it can be any valid utf8 string.
120  *
121  * When an anchor is clicked, an @c "anchor,clicked" signal is emitted with
122  * an #Elm_Entry_Anchor_Info in the @c event_info parameter for the
123  * callback function. The same applies for "anchor,in" (mouse in), "anchor,out"
124  * (mouse out), "anchor,down" (mouse down), and "anchor,up" (mouse up) events on
125  * an anchor.
126  *
127  * @subsection entry-items Items
128  *
129  * Inlined in the text, any other @c Evas_Object can be inserted by using
130  * \<item\> tags this way:
131  *
132  * @code
133  * <item size=16x16 vsize=full href=emoticon/haha></item>
134  * @endcode
135  *
136  * Just like with anchors, the @c href identifies each item, but these need,
137  * in addition, to indicate their size, which is done using any one of
138  * @c size, @c absize or @c relsize attributes. These attributes take their
139  * value in the WxH format, where W is the width and H the height of the
140  * item.
141  *
142  * @li absize: Absolute pixel size for the item. Whatever value is set will
143  * be the item's size regardless of any scale value the object may have
144  * been set to. The final line height will be adjusted to fit larger items.
145  * @li size: Similar to @c absize, but it's adjusted to the scale value set
146  * for the object.
147  * @li relsize: Size is adjusted for the item to fit within the current
148  * line height.
149  *
150  * Besides their size, items are specified a @c vsize value that affects
151  * how their final size and position are calculated. The possible values
152  * are:
153  * @li ascent: Item will be placed within the line's baseline and its
154  * ascent. That is, the height between the line where all characters are
155  * positioned and the highest point in the line. For @c size and @c absize
156  * items, the descent value will be added to the total line height to make
157  * them fit. @c relsize items will be adjusted to fit within this space.
158  * @li full: Items will be placed between the descent and ascent, or the
159  * lowest point in the line and its highest.
160  *
161  * The next image shows different configurations of items and how
162  * the previously mentioned options affect their sizes. In all cases,
163  * the green line indicates the ascent, blue for the baseline and red for
164  * the descent.
165  *
166  * @image html entry_item.png
167  * @image latex entry_item.eps width=\textwidth
168  *
169  * And another one to show how size differs from absize. In the first one,
170  * the scale value is set to 1.0, while the second one is using one of 2.0.
171  *
172  * @image html entry_item_scale.png
173  * @image latex entry_item_scale.eps width=\textwidth
174  *
175  * After the size for an item is calculated, the entry will request an
176  * object to place in its space. For this, the functions set with
177  * elm_entry_item_provider_append() and related functions will be called
178  * in order until one of them returns a @c non-NULL value. If no providers
179  * are available, or all of them return @c NULL, then the entry falls back
180  * to one of the internal defaults, provided the name matches with one of
181  * them.
182  *
183  * All of the following are currently supported:
184  *
185  * - emoticon/angry
186  * - emoticon/angry-shout
187  * - emoticon/crazy-laugh
188  * - emoticon/evil-laugh
189  * - emoticon/evil
190  * - emoticon/goggle-smile
191  * - emoticon/grumpy
192  * - emoticon/grumpy-smile
193  * - emoticon/guilty
194  * - emoticon/guilty-smile
195  * - emoticon/haha
196  * - emoticon/half-smile
197  * - emoticon/happy-panting
198  * - emoticon/happy
199  * - emoticon/indifferent
200  * - emoticon/kiss
201  * - emoticon/knowing-grin
202  * - emoticon/laugh
203  * - emoticon/little-bit-sorry
204  * - emoticon/love-lots
205  * - emoticon/love
206  * - emoticon/minimal-smile
207  * - emoticon/not-happy
208  * - emoticon/not-impressed
209  * - emoticon/omg
210  * - emoticon/opensmile
211  * - emoticon/smile
212  * - emoticon/sorry
213  * - emoticon/squint-laugh
214  * - emoticon/surprised
215  * - emoticon/suspicious
216  * - emoticon/tongue-dangling
217  * - emoticon/tongue-poke
218  * - emoticon/uh
219  * - emoticon/unhappy
220  * - emoticon/very-sorry
221  * - emoticon/what
222  * - emoticon/wink
223  * - emoticon/worried
224  * - emoticon/wtf
225  *
226  * Alternatively, an item may reference an image by its path, using
227  * the URI form @c file:///path/to/an/image.png and the entry will then
228  * use that image for the item.
229  *
230  * @section entry-files Loading and saving files
231  *
232  * Entries have convenience functions to load text from a file and save
233  * changes back to it after a short delay. The automatic saving is enabled
234  * by default, but can be disabled with elm_entry_autosave_set() and files
235  * can be loaded directly as plain text or have any markup in them
236  * recognized. See elm_entry_file_set() for more details.
237  *
238  * @section entry-signals Emitted signals
239  *
240  * This widget emits the following signals:
241  *
242  * @li "changed": The text within the entry was changed.
243  * @li "changed,user": The text within the entry was changed because of user interaction.
244  * @li "activated": The enter key was pressed on a single line entry.
245  * @li "press": A mouse button has been pressed on the entry.
246  * @li "longpressed": A mouse button has been pressed and held for a couple
247  * seconds.
248  * @li "clicked": The entry has been clicked (mouse press and release).
249  * @li "clicked,double": The entry has been double clicked.
250  * @li "clicked,triple": The entry has been triple clicked.
251  * @li "focused": The entry has received focus.
252  * @li "unfocused": The entry has lost focus.
253  * @li "selection,paste": A paste of the clipboard contents was requested.
254  * @li "selection,copy": A copy of the selected text into the clipboard was
255  * requested.
256  * @li "selection,cut": A cut of the selected text into the clipboard was
257  * requested.
258  * @li "selection,start": A selection has begun and no previous selection
259  * existed.
260  * @li "selection,changed": The current selection has changed.
261  * @li "selection,cleared": The current selection has been cleared.
262  * @li "cursor,changed": The cursor has changed position.
263  * @li "anchor,clicked": An anchor has been clicked. The event_info
264  * parameter for the callback will be an #Elm_Entry_Anchor_Info.
265  * @li "anchor,in": Mouse cursor has moved into an anchor. The event_info
266  * parameter for the callback will be an #Elm_Entry_Anchor_Info.
267  * @li "anchor,out": Mouse cursor has moved out of an anchor. The event_info
268  * parameter for the callback will be an #Elm_Entry_Anchor_Info.
269  * @li "anchor,up": Mouse button has been unpressed on an anchor. The event_info
270  * parameter for the callback will be an #Elm_Entry_Anchor_Info.
271  * @li "anchor,down": Mouse button has been pressed on an anchor. The event_info
272  * parameter for the callback will be an #Elm_Entry_Anchor_Info.
273  * @li "preedit,changed": The preedit string has changed.
274  * @li "language,changed": Program language changed.
275  *
276  * Default contents parts of the entry items that you can use for are:
277  * @li "icon" - An icon in the entry
278  * @li "end" - A content in the end of the entry
279  *
280  * Default text parts of the entry that you can use for are:
281  * @li "default" - text of the entry
282  *
283  * Supported elm_object common APIs.
284  * @li elm_object_signal_emit
285  * @li elm_object_part_text_set
286  * @li elm_object_part_text_get
287  * @li elm_object_part_content_set
288  * @li elm_object_part_content_get
289  * @li elm_object_part_content_unset
290  * @li elm_object_signal_callback_add
291  * @li elm_object_signal_callback_del
292  * @li elm_object_disabled_set
293  * @li elm_object_disabled_get
294  *
295  * @section entry-examples
296  *
297  * An overview of the Entry API can be seen in @ref entry_example_01
298  *
299  * @{
300  */
301
302 /**
303  * @typedef Elm_Entry_Anchor_Info
304  *
305  * The info sent in the callback for the "anchor,clicked" signals emitted
306  * by entries.
307  */
308 typedef struct _Elm_Entry_Anchor_Info Elm_Entry_Anchor_Info;
309
310 /**
311  * @struct _Elm_Entry_Anchor_Info
312  *
313  * The info sent in the callback for the "anchor,clicked" signals emitted
314  * by entries.
315  */
316 struct _Elm_Entry_Anchor_Info
317 {
318    const char *name; /**< The name of the anchor, as stated in its href */
319    int         button; /**< The mouse button used to click on it */
320    Evas_Coord  x, /**< Anchor geometry, relative to canvas */
321                y, /**< Anchor geometry, relative to canvas */
322                w, /**< Anchor geometry, relative to canvas */
323                h; /**< Anchor geometry, relative to canvas */
324 };
325
326 /**
327  * @typedef Elm_Entry_Filter_Cb
328  * This callback type is used by entry filters to modify text.
329  * @param data The data specified as the last param when adding the filter
330  * @param entry The entry object
331  * @param text A pointer to the location of the text being filtered. The type of text is always markup. This data can be modified,
332  * but any additional allocations must be managed by the user.
333  * @see elm_entry_markup_filter_append
334  * @see elm_entry_markup_filter_prepend
335  */
336 typedef void (*Elm_Entry_Filter_Cb)(void *data, Evas_Object *entry, char **text);
337
338 /**
339  * @typedef Elm_Entry_Change_Info
340  * This corresponds to Edje_Entry_Change_Info. Includes information about
341  * a change in the entry.
342  */
343 typedef Edje_Entry_Change_Info Elm_Entry_Change_Info;
344
345 /**
346  * This adds an entry to @p parent object.
347  *
348  * By default, entries are:
349  * @li not scrolled
350  * @li multi-line
351  * @li word wrapped
352  * @li autosave is enabled
353  *
354  * @param parent The parent object
355  * @return The new object or NULL if it cannot be created
356  */
357 EAPI Evas_Object       *elm_entry_add(Evas_Object *parent);
358
359 /**
360  * Sets the entry to single line mode.
361  *
362  * In single line mode, entries don't ever wrap when the text reaches the
363  * edge, and instead they keep growing horizontally. Pressing the @c Enter
364  * key will generate an @c "activate" event instead of adding a new line.
365  *
366  * When @p single_line is @c EINA_FALSE, line wrapping takes effect again
367  * and pressing enter will break the text into a different line
368  * without generating any events.
369  *
370  * @param obj The entry object
371  * @param single_line If true, the text in the entry
372  * will be on a single line.
373  */
374 EAPI void               elm_entry_single_line_set(Evas_Object *obj, Eina_Bool single_line);
375
376 /**
377  * Gets whether the entry is set to be single line.
378  *
379  * @param obj The entry object
380  * @return single_line If true, the text in the entry is set to display
381  * on a single line.
382  *
383  * @see elm_entry_single_line_set()
384  */
385 EAPI Eina_Bool          elm_entry_single_line_get(const Evas_Object *obj);
386
387 /**
388  * Sets the entry to password mode.
389  *
390  * In password mode, entries are implicitly single line and the display of
391  * any text in them is replaced with asterisks (*).
392  *
393  * @param obj The entry object
394  * @param password If true, password mode is enabled.
395  */
396 EAPI void               elm_entry_password_set(Evas_Object *obj, Eina_Bool password);
397
398 /**
399  * Gets whether the entry is set to password mode.
400  *
401  * @param obj The entry object
402  * @return If true, the entry is set to display all characters
403  * as asterisks (*).
404  *
405  * @see elm_entry_password_set()
406  */
407 EAPI Eina_Bool          elm_entry_password_get(const Evas_Object *obj);
408
409 /**
410  * This sets the text displayed within the entry to @p entry.
411  *
412  * @param obj The entry object
413  * @param entry The text to be displayed
414  *
415  * @note Using this function bypasses text filters
416  */
417 EAPI void               elm_entry_entry_set(Evas_Object *obj, const char *entry);
418
419 /**
420  * This returns the text currently shown in object @p entry.
421  * See also elm_entry_entry_set().
422  *
423  * @param obj The entry object
424  * @return The currently displayed text or NULL on failure
425  */
426 EAPI const char        *elm_entry_entry_get(const Evas_Object *obj);
427
428 /**
429  * Appends @p entry to the text of the entry.
430  *
431  * Adds the text in @p entry to the end of any text already present in the
432  * widget.
433  *
434  * The appended text is subject to any filters set for the widget.
435  *
436  * @param obj The entry object
437  * @param entry The text to be displayed
438  *
439  * @see elm_entry_markup_filter_append()
440  */
441 EAPI void               elm_entry_entry_append(Evas_Object *obj, const char *entry);
442
443 /**
444  * Gets whether the entry is empty.
445  *
446  * Empty means no text at all. If there are any markup tags, like an item
447  * tag for which no provider finds anything, and no text is displayed, this
448  * function still returns EINA_FALSE.
449  *
450  * @param obj The entry object
451  * @return EINA_TRUE if the entry is empty, EINA_FALSE otherwise.
452  */
453 EAPI Eina_Bool          elm_entry_is_empty(const Evas_Object *obj);
454
455 /**
456  * Gets any selected text within the entry.
457  *
458  * If there's any selected text in the entry, this function returns it as
459  * a string in markup format. NULL is returned if no selection exists or
460  * if an error occurred.
461  *
462  * The returned value points to an internal string and should not be freed
463  * or modified in any way. If the @p entry object is deleted or its
464  * contents are changed, the returned pointer should be considered invalid.
465  *
466  * @param obj The entry object
467  * @return The selected text within the entry or NULL on failure
468  */
469 EAPI const char        *elm_entry_selection_get(const Evas_Object *obj);
470
471 /**
472  * Returns the actual textblock object of the entry.
473  *
474  * This function exposes the internal textblock object that actually
475  * contains and draws the text. This should be used for low-level
476  * manipulations that are otherwise not possible.
477  *
478  * Changing the textblock directly from here will not notify edje/elm to
479  * recalculate the textblock size automatically, so any modifications
480  * done to the textblock returned by this function should be followed by
481  * a call to elm_entry_calc_force().
482  *
483  * The return value is marked as const as an additional warning.
484  * One should not use the returned object with any of the generic evas
485  * functions (geometry_get/resize/move and etc), but only with the textblock
486  * functions; The former will either not work at all, or break the correct
487  * functionality.
488  *
489  * IMPORTANT: Many functions may change (i.e delete and create a new one)
490  * the internal textblock object. Do NOT cache the returned object, and try
491  * not to mix calls on this object with regular elm_entry calls (which may
492  * change the internal textblock object). This applies to all cursors
493  * returned from textblock calls, and all the other derivative values.
494  *
495  * @param obj The entry object
496  * @return The textblock object.
497  */
498 EAPI Evas_Object *      elm_entry_textblock_get(Evas_Object *obj);
499
500 /**
501  * Forces calculation of the entry size and text layouting.
502  *
503  * This should be used after modifying the textblock object directly. See
504  * elm_entry_textblock_get() for more information.
505  *
506  * @param obj The entry object
507  *
508  * @see elm_entry_textblock_get()
509  */
510 EAPI void               elm_entry_calc_force(Evas_Object *obj);
511
512 /**
513  * Inserts the given text into the entry at the current cursor position.
514  *
515  * This inserts text at the cursor position as if it was typed
516  * by the user (note that this also allows markup which a user
517  * can't just "type" as it would be converted to escaped text, so this
518  * call can be used to insert things like emoticon items or bold push/pop
519  * tags, other font and color change tags etc.)
520  *
521  * If any selection exists, it will be replaced by the inserted text.
522  *
523  * The inserted text is subject to any filters set for the widget.
524  *
525  * @param obj The entry object
526  * @param entry The text to insert
527  *
528  * @see elm_entry_markup_filter_append()
529  */
530 EAPI void               elm_entry_entry_insert(Evas_Object *obj, const char *entry);
531
532 /**
533  * Set the line wrap type to use on multi-line entries.
534  *
535  * Sets the wrap type used by the entry to any of the specified in
536  * Elm_Wrap_Type. This tells how the text will be implicitly cut into a new
537  * line (without inserting a line break or paragraph separator) when it
538  * reaches the far edge of the widget.
539  *
540  * Note that this only makes sense for multi-line entries. A widget set
541  * to be single line will never wrap.
542  *
543  * @param obj The entry object
544  * @param wrap The wrap mode to use. See Elm_Wrap_Type for details on them
545  */
546 EAPI void               elm_entry_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap);
547
548 /**
549  * Gets the wrap mode the entry was set to use.
550  *
551  * @param obj The entry object
552  * @return Wrap type
553  *
554  * @see also elm_entry_line_wrap_set()
555  */
556 EAPI Elm_Wrap_Type      elm_entry_line_wrap_get(const Evas_Object *obj);
557
558 /**
559  * Sets if the entry is to be editable or not.
560  *
561  * By default, entries are editable and when focused, any text input by the
562  * user will be inserted at the current cursor position. But calling this
563  * function with @p editable as EINA_FALSE will prevent the user from
564  * inputting text into the entry.
565  *
566  * The only way to change the text of a non-editable entry is to use
567  * elm_object_text_set(), elm_entry_entry_insert() and other related
568  * functions.
569  *
570  * @param obj The entry object
571  * @param editable If EINA_TRUE, user input will be inserted in the entry,
572  * if not, the entry is read-only and no user input is allowed.
573  */
574 EAPI void               elm_entry_editable_set(Evas_Object *obj, Eina_Bool editable);
575
576 /**
577  * Gets whether the entry is editable or not.
578  *
579  * @param obj The entry object
580  * @return If true, the entry is editable by the user.
581  * If false, it is not editable by the user
582  *
583  * @see elm_entry_editable_set()
584  */
585 EAPI Eina_Bool          elm_entry_editable_get(const Evas_Object *obj);
586
587 /**
588  * This drops any existing text selection within the entry.
589  *
590  * @param obj The entry object
591  */
592 EAPI void               elm_entry_select_none(Evas_Object *obj);
593
594 /**
595  * This selects all text within the entry.
596  *
597  * @param obj The entry object
598  */
599 EAPI void               elm_entry_select_all(Evas_Object *obj);
600
601 /**
602  * This moves the cursor one place to the right within the entry.
603  *
604  * @param obj The entry object
605  * @return EINA_TRUE upon success, EINA_FALSE upon failure
606  */
607 EAPI Eina_Bool          elm_entry_cursor_next(Evas_Object *obj);
608
609 /**
610  * This moves the cursor one place to the left within the entry.
611  *
612  * @param obj The entry object
613  * @return EINA_TRUE upon success, EINA_FALSE upon failure
614  */
615 EAPI Eina_Bool          elm_entry_cursor_prev(Evas_Object *obj);
616
617 /**
618  * This moves the cursor one line up within the entry.
619  *
620  * @param obj The entry object
621  * @return EINA_TRUE upon success, EINA_FALSE upon failure
622  */
623 EAPI Eina_Bool          elm_entry_cursor_up(Evas_Object *obj);
624
625 /**
626  * This moves the cursor one line down within the entry.
627  *
628  * @param obj The entry object
629  * @return EINA_TRUE upon success, EINA_FALSE upon failure
630  */
631 EAPI Eina_Bool          elm_entry_cursor_down(Evas_Object *obj);
632
633 /**
634  * This moves the cursor to the beginning of the entry.
635  *
636  * @param obj The entry object
637  */
638 EAPI void               elm_entry_cursor_begin_set(Evas_Object *obj);
639
640 /**
641  * This moves the cursor to the end of the entry.
642  *
643  * @param obj The entry object
644  */
645 EAPI void               elm_entry_cursor_end_set(Evas_Object *obj);
646
647 /**
648  * This moves the cursor to the beginning of the current line.
649  *
650  * @param obj The entry object
651  */
652 EAPI void               elm_entry_cursor_line_begin_set(Evas_Object *obj);
653
654 /**
655  * This moves the cursor to the end of the current line.
656  *
657  * @param obj The entry object
658  */
659 EAPI void               elm_entry_cursor_line_end_set(Evas_Object *obj);
660
661 /**
662  * This begins a selection within the entry as though
663  * the user were holding down the mouse button to make a selection.
664  *
665  * @param obj The entry object
666  */
667 EAPI void               elm_entry_cursor_selection_begin(Evas_Object *obj);
668
669 /**
670  * This ends a selection within the entry as though
671  * the user had just released the mouse button while making a selection.
672  *
673  * @param obj The entry object
674  */
675 EAPI void               elm_entry_cursor_selection_end(Evas_Object *obj);
676
677 /**
678  * Gets whether a format node exists at the current cursor position.
679  *
680  * A format node is anything that defines how the text is rendered. It can
681  * be a visible format node, such as a line break or a paragraph separator,
682  * or an invisible one, such as bold begin or end tag.
683  * This function returns whether any format node exists at the current
684  * cursor position.
685  *
686  * @param obj The entry object
687  * @return EINA_TRUE if the current cursor position contains a format node,
688  * EINA_FALSE otherwise.
689  *
690  * @see elm_entry_cursor_is_visible_format_get()
691  */
692 EAPI Eina_Bool          elm_entry_cursor_is_format_get(const Evas_Object *obj);
693
694 /**
695  * Gets if the current cursor position holds a visible format node.
696  *
697  * @param obj The entry object
698  * @return EINA_TRUE if the current cursor is a visible format, EINA_FALSE
699  * if it's an invisible one or no format exists.
700  *
701  * @see elm_entry_cursor_is_format_get()
702  */
703 EAPI Eina_Bool          elm_entry_cursor_is_visible_format_get(const Evas_Object *obj);
704
705 /**
706  * Gets the character pointed by the cursor at its current position.
707  *
708  * This function returns a string with the utf8 character stored at the
709  * current cursor position.
710  * Only the text is returned, any format that may exist will not be part
711  * of the return value. You must free the string when done with free().
712  *
713  * @param obj The entry object
714  * @return The text pointed by the cursors.
715  */
716 EAPI char              *elm_entry_cursor_content_get(const Evas_Object *obj);
717
718 /**
719  * This function returns the geometry of the cursor.
720  *
721  * It's useful if you want to draw something on the cursor (or where it is),
722  * or for example in the case of scrolled entry where you want to show the
723  * cursor.
724  *
725  * @param obj The entry object
726  * @param x returned geometry
727  * @param y returned geometry
728  * @param w returned geometry
729  * @param h returned geometry
730  * @return EINA_TRUE upon success, EINA_FALSE upon failure
731  */
732 EAPI Eina_Bool          elm_entry_cursor_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h);
733
734 /**
735  * Sets the cursor position in the entry to the given value
736  *
737  * The value in @p pos is the index of the character position within the
738  * contents of the string as returned by elm_entry_cursor_pos_get().
739  *
740  * @param obj The entry object
741  * @param pos The position of the cursor
742  */
743 EAPI void               elm_entry_cursor_pos_set(Evas_Object *obj, int pos);
744
745 /**
746  * Retrieves the current position of the cursor in the entry
747  *
748  * @param obj The entry object
749  * @return The cursor position
750  */
751 EAPI int                elm_entry_cursor_pos_get(const Evas_Object *obj);
752
753 /**
754  * This executes a "cut" action on the selected text in the entry.
755  *
756  * @param obj The entry object
757  */
758 EAPI void               elm_entry_selection_cut(Evas_Object *obj);
759
760 /**
761  * This executes a "copy" action on the selected text in the entry.
762  *
763  * @param obj The entry object
764  */
765 EAPI void               elm_entry_selection_copy(Evas_Object *obj);
766
767 /**
768  * This executes a "paste" action in the entry.
769  *
770  * @param obj The entry object
771  */
772 EAPI void               elm_entry_selection_paste(Evas_Object *obj);
773
774 /**
775  * This clears and frees the items in a entry's contextual (longpress)
776  * menu.
777  *
778  * @param obj The entry object
779  *
780  * @see elm_entry_context_menu_item_add()
781  */
782 EAPI void               elm_entry_context_menu_clear(Evas_Object *obj);
783
784 /**
785  * This adds an item to the entry's contextual menu.
786  *
787  * A longpress on an entry will make the contextual menu show up, if this
788  * hasn't been disabled with elm_entry_context_menu_disabled_set().
789  * By default, this menu provides a few options like enabling selection mode,
790  * which is useful on embedded devices that need to be explicit about it,
791  * and when a selection exists it also shows the copy and cut actions.
792  *
793  * With this function, developers can add other options to this menu to
794  * perform any action they deem necessary.
795  *
796  * @param obj The entry object
797  * @param label The item's text label
798  * @param icon_file The item's icon file
799  * @param icon_type The item's icon type
800  * @param func The callback to execute when the item is clicked
801  * @param data The data to associate with the item for related functions
802  */
803 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);
804
805 /**
806  * This disables the entry's contextual (longpress) menu.
807  *
808  * @param obj The entry object
809  * @param disabled If true, the menu is disabled
810  */
811 EAPI void               elm_entry_context_menu_disabled_set(Evas_Object *obj, Eina_Bool disabled);
812
813 /**
814  * This returns whether the entry's contextual (longpress) menu is
815  * disabled.
816  *
817  * @param obj The entry object
818  * @return If true, the menu is disabled
819  */
820 EAPI Eina_Bool          elm_entry_context_menu_disabled_get(const Evas_Object *obj);
821
822 /**
823  * This appends a custom item provider to the list for that entry
824  *
825  * This appends the given callback. The list is walked from beginning to end
826  * with each function called given the item href string in the text. If the
827  * function returns an object handle other than NULL (it should create an
828  * object to do this), then this object is used to replace that item. If
829  * not the next provider is called until one provides an item object, or the
830  * default provider in entry does.
831  *
832  * @param obj The entry object
833  * @param func The function called to provide the item object
834  * @param data The data passed to @p func
835  *
836  * @see @ref entry-items
837  */
838 EAPI void               elm_entry_item_provider_append(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
839
840 /**
841  * This prepends a custom item provider to the list for that entry
842  *
843  * This prepends the given callback. See elm_entry_item_provider_append() for
844  * more information
845  *
846  * @param obj The entry object
847  * @param func The function called to provide the item object
848  * @param data The data passed to @p func
849  */
850 EAPI void               elm_entry_item_provider_prepend(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
851
852 /**
853  * This removes a custom item provider to the list for that entry
854  *
855  * This removes the given callback. See elm_entry_item_provider_append() for
856  * more information
857  *
858  * @param obj The entry object
859  * @param func The function called to provide the item object
860  * @param data The data passed to @p func
861  */
862 EAPI void               elm_entry_item_provider_remove(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * entry, const char *item), void *data);
863
864 /**
865  * Append a markup filter function for text inserted in the entry
866  *
867  * Append the given callback to the list. This functions will be called
868  * whenever any text is inserted into the entry, with the text to be inserted
869  * as a parameter. The type of given text is always markup.
870  * The callback function is free to alter the text in any way it wants, but 
871  * it must remember to free the given pointer and update it.
872  * If the new text is to be discarded, the function can free it and set its
873  * text parameter to NULL. This will also prevent any following filters from
874  * being called.
875  *
876  * @param obj The entry object
877  * @param func The function to use as text filter
878  * @param data User data to pass to @p func
879  */
880 EAPI void               elm_entry_markup_filter_append(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
881
882 /**
883  * Prepend a markup filter function for text inserted in the entry
884  *
885  * Prepend the given callback to the list. See elm_entry_markup_filter_append()
886  * for more information
887  *
888  * @param obj The entry object
889  * @param func The function to use as text filter
890  * @param data User data to pass to @p func
891  */
892 EAPI void               elm_entry_markup_filter_prepend(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
893
894 /**
895  * Remove a markup filter from the list
896  *
897  * Removes the given callback from the filter list. See
898  * elm_entry_markup_filter_append() for more information.
899  *
900  * @param obj The entry object
901  * @param func The filter function to remove
902  * @param data The user data passed when adding the function
903  */
904 EAPI void               elm_entry_markup_filter_remove(Evas_Object *obj, Elm_Entry_Filter_Cb func, void *data);
905
906 /**
907  * This converts a markup (HTML-like) string into UTF-8.
908  *
909  * The returned string is a malloc'ed buffer and it should be freed when
910  * not needed anymore.
911  *
912  * @param s The string (in markup) to be converted
913  * @return The converted string (in UTF-8). It should be freed.
914  */
915 EAPI char              *elm_entry_markup_to_utf8(const char *s);
916
917 /**
918  * This converts a UTF-8 string into markup (HTML-like).
919  *
920  * The returned string is a malloc'ed buffer and it should be freed when
921  * not needed anymore.
922  *
923  * @param s The string (in UTF-8) to be converted
924  * @return The converted string (in markup). It should be freed.
925  */
926 EAPI char              *elm_entry_utf8_to_markup(const char *s);
927
928 /**
929  * This sets the file (and implicitly loads it) for the text to display and
930  * then edit. All changes are written back to the file after a short delay if
931  * the entry object is set to autosave (which is the default).
932  *
933  * If the entry had any other file set previously, any changes made to it
934  * will be saved if the autosave feature is enabled, otherwise, the file
935  * will be silently discarded and any non-saved changes will be lost.
936  *
937  * @param obj The entry object
938  * @param file The path to the file to load and save
939  * @param format The file format
940  */
941 EAPI void               elm_entry_file_set(Evas_Object *obj, const char *file, Elm_Text_Format format);
942
943 /**
944  * Gets the file being edited by the entry.
945  *
946  * This function can be used to retrieve any file set on the entry for
947  * edition, along with the format used to load and save it.
948  *
949  * @param obj The entry object
950  * @param file The path to the file to load and save
951  * @param format The file format
952  */
953 EAPI void               elm_entry_file_get(const Evas_Object *obj, const char **file, Elm_Text_Format *format);
954
955 /**
956  * This function writes any changes made to the file set with
957  * elm_entry_file_set()
958  *
959  * @param obj The entry object
960  */
961 EAPI void               elm_entry_file_save(Evas_Object *obj);
962
963 /**
964  * This sets the entry object to 'autosave' the loaded text file or not.
965  *
966  * @param obj The entry object
967  * @param autosave Autosave the loaded file or not
968  *
969  * @see elm_entry_file_set()
970  */
971 EAPI void               elm_entry_autosave_set(Evas_Object *obj, Eina_Bool autosave);
972
973 /**
974  * This gets the entry object's 'autosave' status.
975  *
976  * @param obj The entry object
977  * @return Autosave the loaded file or not
978  *
979  * @see elm_entry_file_set()
980  */
981 EAPI Eina_Bool          elm_entry_autosave_get(const Evas_Object *obj);
982
983 /**
984  * Control pasting of text and images for the widget.
985  *
986  * Normally the entry allows both text and images to be pasted.  By setting
987  * textonly to be true, this prevents images from being pasted.
988  *
989  * Note this only changes the behaviour of text.
990  *
991  * @param obj The entry object
992  * @param textonly paste mode - EINA_TRUE is text only, EINA_FALSE is
993  * text+image+other.
994  */
995 EAPI void               elm_entry_cnp_textonly_set(Evas_Object *obj, Eina_Bool textonly);
996
997 /**
998  * Getting elm_entry text paste/drop mode.
999  *
1000  * In textonly mode, only text may be pasted or dropped into the widget.
1001  *
1002  * @param obj The entry object
1003  * @return If the widget only accepts text from pastes.
1004  */
1005 EAPI Eina_Bool          elm_entry_cnp_textonly_get(const Evas_Object *obj);
1006
1007 /**
1008  * Enable or disable scrolling in entry
1009  *
1010  * Normally the entry is not scrollable unless you enable it with this call.
1011  *
1012  * @param obj The entry object
1013  * @param scroll EINA_TRUE if it is to be scrollable, EINA_FALSE otherwise
1014  */
1015 EAPI void               elm_entry_scrollable_set(Evas_Object *obj, Eina_Bool scroll);
1016
1017 /**
1018  * Get the scrollable state of the entry
1019  *
1020  * Normally the entry is not scrollable. This gets the scrollable state
1021  * of the entry. See elm_entry_scrollable_set() for more information.
1022  *
1023  * @param obj The entry object
1024  * @return The scrollable state
1025  */
1026 EAPI Eina_Bool          elm_entry_scrollable_get(const Evas_Object *obj);
1027
1028 /**
1029  * Sets the visibility of the left-side widget of the scrolled entry,
1030  * set by elm_entry_icon_set().
1031  *
1032  * @param obj The scrolled entry object
1033  * @param setting EINA_TRUE if the object should be displayed,
1034  * EINA_FALSE if not.
1035  */
1036 EAPI void               elm_entry_icon_visible_set(Evas_Object *obj, Eina_Bool setting);
1037
1038 /**
1039  * Sets the visibility of the end widget of the scrolled entry, set by
1040  * elm_object_part_content_set(ent, "end", content).
1041  *
1042  * @param obj The scrolled entry object
1043  * @param setting EINA_TRUE if the object should be displayed,
1044  * EINA_FALSE if not.
1045  */
1046 EAPI void               elm_entry_end_visible_set(Evas_Object *obj, Eina_Bool setting);
1047
1048 /**
1049  * This sets the scrolled entry's scrollbar policy (i.e. enabling/disabling
1050  * them).
1051  *
1052  * Setting an entry to single-line mode with elm_entry_single_line_set()
1053  * will automatically disable the display of scrollbars when the entry
1054  * moves inside its scroller.
1055  *
1056  * @param obj The scrolled entry object
1057  * @param h The horizontal scrollbar policy to apply
1058  * @param v The vertical scrollbar policy to apply
1059  */
1060 EAPI void               elm_entry_scrollbar_policy_set(Evas_Object *obj, Elm_Scroller_Policy h, Elm_Scroller_Policy v);
1061
1062 /**
1063  * This enables/disables bouncing within the entry.
1064  *
1065  * This function sets whether the entry will bounce when scrolling reaches
1066  * the end of the contained entry.
1067  *
1068  * @param obj The scrolled entry object
1069  * @param h_bounce The horizontal bounce state
1070  * @param v_bounce The vertical bounce state
1071  */
1072 EAPI void               elm_entry_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
1073
1074 /**
1075  * Get the bounce mode
1076  *
1077  * @param obj The Entry object
1078  * @param h_bounce Allow bounce horizontally
1079  * @param v_bounce Allow bounce vertically
1080  */
1081 EAPI void               elm_entry_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
1082
1083 /**
1084  * Set the input panel layout of the entry
1085  *
1086  * @param obj The entry object
1087  * @param layout layout type
1088  */
1089 EAPI void                   elm_entry_input_panel_layout_set(Evas_Object *obj, Elm_Input_Panel_Layout layout);
1090
1091 /**
1092  * Get the input panel layout of the entry
1093  *
1094  * @param obj The entry object
1095  * @return layout type
1096  *
1097  * @see elm_entry_input_panel_layout_set
1098  */
1099 EAPI Elm_Input_Panel_Layout elm_entry_input_panel_layout_get(const Evas_Object *obj);
1100
1101 /**
1102  * Set the autocapitalization type on the immodule.
1103  *
1104  * @param obj The entry object
1105  * @param autocapital_type The type of autocapitalization
1106  */
1107 EAPI void                   elm_entry_autocapital_type_set(Evas_Object *obj, Elm_Autocapital_Type autocapital_type);
1108
1109 /**
1110  * Retrieve the autocapitalization type on the immodule.
1111  *
1112  * @param obj The entry object
1113  * @return autocapitalization type
1114  */
1115 EAPI Elm_Autocapital_Type   elm_entry_autocapital_type_get(const Evas_Object *obj);
1116
1117 /**
1118  * Sets the attribute to show the input panel automatically.
1119  *
1120  * @param obj The entry object
1121  * @param enabled If true, the input panel is appeared when entry is clicked or has a focus
1122  */
1123 EAPI void                   elm_entry_input_panel_enabled_set(Evas_Object *obj, Eina_Bool enabled);
1124
1125 /**
1126  * Retrieve the attribute to show the input panel automatically.
1127  *
1128  * @param obj The entry object
1129  * @return EINA_TRUE if input panel will be appeared when the entry is clicked or has a focus, EINA_FALSE otherwise
1130  */
1131 EAPI Eina_Bool              elm_entry_input_panel_enabled_get(const Evas_Object *obj);
1132
1133 /**
1134  * Show the input panel (virtual keyboard) based on the input panel property of entry such as layout, autocapital types, and so on.
1135  *
1136  * Note that input panel is shown or hidden automatically according to the focus state of entry widget.
1137  * This API can be used in the case of manually controlling by using elm_entry_input_panel_enabled_set(en, EINA_FALSE)
1138  *
1139  * @param obj The entry object
1140  */
1141 EAPI void                   elm_entry_input_panel_show(Evas_Object *obj);
1142
1143 /**
1144  * Hide the input panel (virtual keyboard).
1145  *
1146  * Note that input panel is shown or hidden automatically according to the focus state of entry widget.
1147  * This API can be used in the case of manually controlling by using elm_entry_input_panel_enabled_set(en, EINA_FALSE)
1148  *
1149  * @param obj The entry object
1150  */
1151 EAPI void                   elm_entry_input_panel_hide(Evas_Object *obj);
1152
1153 /**
1154  * Set the language mode of the input panel.
1155  *
1156  * This API can be used if you want to show the alphabet keyboard mode. 
1157  *
1158  * @param obj The entry object
1159  * @param lang language to be set to the input panel.
1160  */
1161 EAPI void                   elm_entry_input_panel_language_set(Evas_Object *obj, Elm_Input_Panel_Lang lang);
1162
1163 /**
1164  * Get the language mode of the input panel.
1165  *
1166  * See @ref elm_entry_input_panel_language_set for more details.
1167  *
1168  * @param obj The entry object
1169  * @return input panel language type
1170  */
1171 EAPI Elm_Input_Panel_Lang   elm_entry_input_panel_language_get(const Evas_Object *obj);
1172
1173 /**
1174  * Set the input panel-specific data to deliver to the input panel.
1175  *
1176  * This API is used by applications to deliver specific data to the input panel.
1177  * The data format MUST be negotiated by both application and the input panel.
1178  * The size and format of data are defined by the input panel.
1179  *
1180  * @param obj The entry object
1181  * @param data The specific data to be set to the input panel.
1182  * @param len the length of data, in bytes, to send to the input panel
1183  */
1184 EAPI void                   elm_entry_input_panel_imdata_set(Evas_Object *obj, const void *data, int len);
1185
1186 /**
1187  * Get the specific data of the current input panel.
1188  *
1189  * See @ref elm_entry_input_panel_imdata_set for more details. 
1190  *
1191  * @param obj The entry object
1192  * @param data The specific data to be got from the input panel
1193  * @param len The length of data
1194  */
1195 EAPI void                   elm_entry_input_panel_imdata_get(const Evas_Object *obj, void *data, int *len);
1196
1197 /**
1198  * Set the "return" key type. This type is used to set string or icon on the "return" key of the input panel.
1199  *
1200  * An input panel displays the string or icon associated with this type
1201  *
1202  * @param obj The entry object
1203  * @param return_key_type The type of "return" key on the input panel
1204  */
1205 EAPI void                   elm_text_input_panel_return_key_type_set(Evas_Object *obj, Elm_Input_Panel_Return_Key_Type return_key_type);
1206
1207 /**
1208  * Get the "return" key type.
1209  *
1210  * @see elm_entry_input_panel_return_key_type_set() for more details
1211  *
1212  * @param obj The entry object
1213  * @return The type of "return" key on the input panel
1214  */
1215 EAPI Elm_Input_Panel_Return_Key_Type elm_entry_input_panel_return_key_type_get(const Evas_Object *obj);
1216
1217 /**
1218  * Set the return key on the input panel to be disabled.
1219  *
1220  * @param obj The entry object
1221  * @param disabled The state to put in in: @c EINA_TRUE for
1222  *        disabled, @c EINA_FALSE for enabled 
1223  */
1224 EAPI void                   elm_entry_input_panel_return_key_disabled_set(Evas_Object *obj, Eina_Bool disabled);
1225
1226 /**
1227  * Get whether the return key on the input panel should be disabled or not.
1228  *
1229  * @param obj The entry object
1230  * @return EINA_TRUE if it should be disabled
1231  */
1232 EAPI Eina_Bool              elm_entry_input_panel_return_key_disabled_get(const Evas_Object *obj);
1233
1234 /**
1235  * Reset the input method context of the entry if needed. 
1236  *
1237  * This can be necessary in the case where modifying the buffer would confuse on-going input method behavior
1238  * @param obj The entry object
1239  */
1240 EAPI void                   elm_entry_imf_context_reset(Evas_Object *obj);
1241
1242 /**
1243  * Set whether the entry should allow to use the text prediction.
1244  *
1245  * @param obj The entry object
1246  * @param prediction Whether the entry should allow to use the text prediction.
1247  */
1248 EAPI void                   elm_entry_prediction_allow_set(Evas_Object *obj, Eina_Bool prediction);
1249
1250 /**
1251  * Get whether the entry should allow to use the text prediction.
1252  *
1253  * @param obj The entry object
1254  * @return EINA_TRUE if it allows to use the text prediction, otherwise EINA_FALSE.
1255  */
1256 EAPI Eina_Bool              elm_entry_prediction_allow_get(const Evas_Object *obj);
1257
1258 /* pre-made filters for entries */
1259
1260 /**
1261  * @typedef Elm_Entry_Filter_Limit_Size
1262  *
1263  * Data for the elm_entry_filter_limit_size() entry filter.
1264  */
1265 typedef struct _Elm_Entry_Filter_Limit_Size Elm_Entry_Filter_Limit_Size;
1266
1267 /**
1268  * @struct _Elm_Entry_Filter_Limit_Size
1269  *
1270  * Data for the elm_entry_filter_limit_size() entry filter.
1271  */
1272 struct _Elm_Entry_Filter_Limit_Size
1273 {
1274    int max_char_count;      /**< The maximum number of characters allowed. */
1275    int max_byte_count;      /**< The maximum number of bytes allowed*/
1276 };
1277
1278 /**
1279  * Filter inserted text based on user defined character and byte limits
1280  *
1281  * Add this filter to an entry to limit the characters that it will accept
1282  * based the the contents of the provided #Elm_Entry_Filter_Limit_Size.
1283  * The function works on the UTF-8 representation of the string, converting
1284  * it from the set markup, thus not accounting for any format in it.
1285  *
1286  * The user must create an #Elm_Entry_Filter_Limit_Size structure and pass
1287  * it as data when setting the filter. In it, it's possible to set limits
1288  * by character count or bytes (any of them is disabled if 0), and both can
1289  * be set at the same time. In that case, it first checks for characters,
1290  * then bytes.
1291  *
1292  * The function will cut the inserted text in order to allow only the first
1293  * number of characters that are still allowed. The cut is made in
1294  * characters, even when limiting by bytes, in order to always contain
1295  * valid ones and avoid half unicode characters making it in.
1296  *
1297  * This filter, like any others, does not apply when setting the entry text
1298  * directly with elm_object_text_set().
1299  */
1300 EAPI void elm_entry_filter_limit_size(void *data, Evas_Object *entry, char **text);
1301
1302 /**
1303  * @typedef Elm_Entry_Filter_Accept_Set
1304  *
1305  * Data for the elm_entry_filter_accept_set() entry filter.
1306  */
1307 typedef struct _Elm_Entry_Filter_Accept_Set Elm_Entry_Filter_Accept_Set;
1308
1309 /**
1310  * @struct _Elm_Entry_Filter_Accept_Set
1311  *
1312  * Data for the elm_entry_filter_accept_set() entry filter.
1313  */
1314 struct _Elm_Entry_Filter_Accept_Set
1315 {
1316    const char *accepted;      /**< Set of characters accepted in the entry. */
1317    const char *rejected;      /**< Set of characters rejected from the entry. */
1318 };
1319
1320 /**
1321  * Filter inserted text based on accepted or rejected sets of characters
1322  *
1323  * Add this filter to an entry to restrict the set of accepted characters
1324  * based on the sets in the provided #Elm_Entry_Filter_Accept_Set.
1325  * This structure contains both accepted and rejected sets, but they are
1326  * mutually exclusive.
1327  *
1328  * The @c accepted set takes preference, so if it is set, the filter will
1329  * only work based on the accepted characters, ignoring anything in the
1330  * @c rejected value. If @c accepted is @c NULL, then @c rejected is used.
1331  *
1332  * In both cases, the function filters by matching utf8 characters to the
1333  * raw markup text, so it can be used to remove formatting tags.
1334  *
1335  * This filter, like any others, does not apply when setting the entry text
1336  * directly with elm_object_text_set()
1337  */
1338 EAPI void                   elm_entry_filter_accept_set(void *data, Evas_Object *entry, char **text);
1339
1340 /**
1341  * @}
1342  */