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