2 * @defgroup Multibuttonentry Multibuttonentry
5 * @image html multibuttonentry_inheritance_tree.png
6 * @image latex multibuttonentry_inheritance_tree.eps
8 * A multi-button entry is a widget letting an user enter text and
9 * each chunk of text managed as a set of buttons. Each text button is
10 * inserted by pressing the "return" key. If there is no space in the
11 * current row, a new button is added to the next row. When a text
12 * button is pressed, it will become focused. Backspace removes the
13 * focus. When the multi-button entry loses focus, items longer than
14 * one line are shrunk to one line.
16 * The typical use case of multi-button entry is composing
17 * emails/messages to a group of addresses, each of which is an item
18 * that can be clicked for further actions.
20 * This widget inherits from the @ref Layout one, so that all the
21 * functions acting on it also work for multi-button entry objects
24 * This widget emits the following signals, besides the ones sent from
26 * - @c "item,selected" - this is called when an item is selected by
27 * api, user interaction, and etc. this is also called when a
28 * user press back space while cursor is on the first field of
30 * - @c "item,added" - when a new multi-button entry item is added.
31 * - @c "item,deleted" - when a multi-button entry item is deleted.
32 * - @c "item,clicked" - this is called when an item is clicked by user
33 * interaction. Both "item,selected" and "item,clicked" are needed.
34 * - @c "clicked" - when multi-button entry is clicked.
35 * - @c "focused" - when multi-button entry is focused.
36 * - @c "unfocused" - when multi-button entry is unfocused.
37 * - @c "expanded" - when multi-button entry is expanded.
38 * - @c "contracted" - when multi-button entry is contracted.
39 * - @c "expand,state,changed" - when shrink mode state of
40 * multi-button entry is changed.
41 * - @c "longpressed" - when multi-button entry is pressed for a long time.
43 * Default text parts of the multi-button entry widget that you can use are:
44 * @li "default" - A label of the multi-button entry
46 * Default text parts of multi-button entry @b items that you can use are:
47 * @li "default" - A label of the multi-button entry item
49 * Supported elm_object_item common APIs.
50 * @li @ref elm_object_item_part_text_set
51 * @li @ref elm_object_item_part_text_get
55 * @addtogroup Multibuttonentry
60 * @brief Callback to be invoked when an item is added to the multibuttonentry.
62 * @param obj The parent object
63 * @param item_label The label corresponding to the added item.
64 * @param item_data data specific to this item.
65 * @param data data specific to the multibuttonentry.
68 * EINA_FALSE otherwise.
70 * @ingroup Multibuttonentry
72 typedef Eina_Bool (*Elm_Multibuttonentry_Item_Filter_Cb)(Evas_Object *obj, const char *item_label, const void *item_data, const void *data);
75 * @brief Add a new multibuttonentry to the parent
77 * @param parent The parent object
78 * @return The new object or NULL if it cannot be created
81 * @ingroup Multibuttonentry
83 EAPI Evas_Object *elm_multibuttonentry_add(Evas_Object *parent);
87 * Get the entry of the multibuttonentry object
89 * @param obj The multibuttonentry object
90 * @return The entry object, or NULL if none
92 * @ingroup Multibuttonentry
94 EAPI Evas_Object *elm_multibuttonentry_entry_get(const Evas_Object *obj);
97 * Get the value of expanded state.
98 * In expanded state, the complete entry will be displayed.
99 * Otherwise, only single line of the entry will be displayed.
101 * @param obj The multibuttonentry object
102 * @return EINA_TRUE if the widget is in expanded state. EINA_FALSE if not.
104 * @ingroup Multibuttonentry
106 EAPI Eina_Bool elm_multibuttonentry_expanded_get(const Evas_Object *obj);
109 * Set/Unset the multibuttonentry to expanded state.
110 * In expanded state, the complete entry will be displayed.
111 * Otherwise, only single line of the entry will be displayed.
113 * @param obj The multibuttonentry object
114 * @param expanded the value of expanded state.
115 * Set this to EINA_TRUE for expanded state.
116 * Set this to EINA_FALSE for single line state.
118 * @ingroup Multibuttonentry
120 EAPI void elm_multibuttonentry_expanded_set(Evas_Object *obj, Eina_Bool expanded);
123 * Prepend a new item to the multibuttonentry
125 * @param obj The multibuttonentry object
126 * @param label The label of new item
127 * @param func The callback function to be invoked when this item is pressed.
128 * @param data The pointer to the data to be attached
129 * @return A handle to the item added or NULL if not possible
131 * @see Use elm_object_item_del() to delete the item.
133 * @ingroup Multibuttonentry
135 EAPI Elm_Object_Item *elm_multibuttonentry_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, const void *data);
138 * Append a new item to the multibuttonentry
140 * @param obj The multibuttonentry object
141 * @param label The label of new item
142 * @param func The callback function to be invoked when this item is pressed.
143 * @param data The pointer to the data to be attached
144 * @return A handle to the item added or NULL if not possible
146 * @see Use elm_object_item_del() to delete the item.
148 * @ingroup Multibuttonentry
150 EAPI Elm_Object_Item *elm_multibuttonentry_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, const void *data);
153 * Add a new item to the multibuttonentry before the indicated object
156 * @param obj The multibuttonentry object
157 * @param before The item before which to add it
158 * @param label The label of new item
159 * @param func The callback function to be invoked when this item is pressed.
160 * @param data The pointer to the data to be attached
161 * @return A handle to the item added or NULL if not possible
163 * @see Use elm_object_item_del() to delete the item.
165 * @ingroup Multibuttonentry
167 EAPI Elm_Object_Item *elm_multibuttonentry_item_insert_before(Evas_Object *obj, Elm_Object_Item *before, const char *label, Evas_Smart_Cb func, const void *data);
170 * Add a new item to the multibuttonentry after the indicated object
172 * @param obj The multibuttonentry object
173 * @param after The item after which to add it
174 * @param label The label of new item
175 * @param func The callback function to be invoked when this item is pressed.
176 * @param data The pointer to the data to be attached
177 * @return A handle to the item added or NULL if not possible
179 * @see Use elm_object_item_del() to delete the item.
181 * @ingroup Multibuttonentry
183 EAPI Elm_Object_Item *elm_multibuttonentry_item_insert_after(Evas_Object *obj, Elm_Object_Item *after, const char *label, Evas_Smart_Cb func, const void *data);
186 * Get a list of items in the multibuttonentry
188 * @param obj The multibuttonentry object
189 * @return The list of items, or NULL if none
191 * @ingroup Multibuttonentry
193 EAPI const Eina_List *elm_multibuttonentry_items_get(const Evas_Object *obj);
196 * Gets the base object of the item.
198 * @param it The multibuttonentry item
199 * @return The base object associated with @p item
201 * Base object is the @c Evas_Object that represents that item.
205 EAPI Evas_Object *elm_multibuttonentry_item_object_get(const Elm_Object_Item *it);
208 * Get the first item in the multibuttonentry
210 * @param obj The multibuttonentry object
211 * @return The first item, or NULL if none
213 * @ingroup Multibuttonentry
215 EAPI Elm_Object_Item *elm_multibuttonentry_first_item_get(const Evas_Object *obj);
218 * Get the last item in the multibuttonentry
220 * @param obj The multibuttonentry object
221 * @return The last item, or NULL if none
223 * @ingroup Multibuttonentry
225 EAPI Elm_Object_Item *elm_multibuttonentry_last_item_get(const Evas_Object *obj);
228 * Get the selected item in the multibuttonentry
230 * @param obj The multibuttonentry object
231 * @return The selected item, or NULL if none
233 * @ingroup Multibuttonentry
235 EAPI Elm_Object_Item *elm_multibuttonentry_selected_item_get(const Evas_Object *obj);
238 * Set the selected state of an item
241 * @param selected if it's EINA_TRUE, select the item otherwise, unselect the item
243 * @ingroup Multibuttonentry
245 EAPI void elm_multibuttonentry_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
249 * Get the selected state of an item
252 * @return EINA_TRUE if the item is selected, EINA_FALSE otherwise.
254 * @ingroup Multibuttonentry
256 EAPI Eina_Bool elm_multibuttonentry_item_selected_get(const Elm_Object_Item *it);
259 * Remove all items in the multibuttonentry.
261 * @param obj The multibuttonentry object
263 * @ingroup Multibuttonentry
265 EAPI void elm_multibuttonentry_clear(Evas_Object *obj);
268 * Get the previous item in the multibuttonentry
271 * @return The item before the item @p it
273 * @ingroup Multibuttonentry
275 EAPI Elm_Object_Item *elm_multibuttonentry_item_prev_get(const Elm_Object_Item *it);
278 * Get the next item in the multibuttonentry
281 * @return The item after the item @p it
283 * @ingroup Multibuttonentry
285 EAPI Elm_Object_Item *elm_multibuttonentry_item_next_get(const Elm_Object_Item *it);
288 * Append an item filter function for text inserted in the Multibuttonentry
290 * Append the given callback to the list. This functions will be called
291 * whenever any text is inserted into the Multibuttonentry, with the text to be inserted
292 * as a parameter. The callback function is free to alter the text in any way
293 * it wants, but it must remember to free the given pointer and update it.
294 * If the new text is to be discarded, the function can free it and set it text
295 * parameter to NULL. This will also prevent any following filters from being
298 * @param obj The multibuttonentry object
299 * @param func The function to use as item filter
300 * @param data User data to pass to @p func
302 * @ingroup Multibuttonentry
304 EAPI void elm_multibuttonentry_item_filter_append(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
307 * Prepend a filter function for text inserted in the Multibuttonentry
309 * Prepend the given callback to the list. See elm_multibuttonentry_item_filter_append()
310 * for more information
312 * @param obj The multibuttonentry object
313 * @param func The function to use as text filter
314 * @param data User data to pass to @p func
316 * @ingroup Multibuttonentry
318 EAPI void elm_multibuttonentry_item_filter_prepend(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
321 * Remove a filter from the list
323 * Removes the given callback from the filter list. See elm_multibuttonentry_item_filter_append()
324 * for more information.
326 * @param obj The multibuttonentry object
327 * @param func The filter function to remove
328 * @param data The user data passed when adding the function
330 * @ingroup Multibuttonentry
332 EAPI void elm_multibuttonentry_item_filter_remove(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
335 * Sets if the multibuttonentry is to be editable or not.
337 * @param obj The multibuttonentry object
338 * @param editable If EINA_TRUE, user can add/delete item in multibuttonentry, if not, the multibuttonentry is non-editable.
340 * @ingroup Multibuttonentry
344 EAPI void elm_multibuttonentry_editable_set(Evas_Object *obj, Eina_Bool editable);
347 * Gets whether the multibuttonentry is editable or not.
349 * @param obj The multibuttonentry object
350 * @return EINA_TRUE if the multibuttonentry is editable by the user. EINA_FALSE if not.
352 * @ingroup Multibuttonentry
356 EAPI Eina_Bool elm_multibuttonentry_editable_get(const Evas_Object *obj);