2 * @defgroup Multibuttonentry Multibuttonentry
5 * A Multibuttonentry is a widget to allow a user enter text and manage it as a number
6 * of buttons. Each text button is inserted by pressing the "return" key.
7 * If there is no space in the current row, a new button is added to the next row.
8 * When a text button is pressed, it will become focused.
9 * Backspace removes the focus.
10 * When the Multibuttonentry loses focus items longer than one line are shrunk
13 * Typical use case of multibuttonentry is, composing emails/messages to a group
14 * of addresses, each of which is an item that can be clicked for further actions.
16 * Smart callbacks one can register:
17 * - @c "item,selected" - this is called when an item is selected by api, user
18 * interaction, and etc. this is also called when a user press back space
19 * while cursor is on the first field of entry.
20 * - @c "item,added" - when a new multibuttonentry item is added.
21 * - @c "item,deleted" - when a multibuttonentry item is deleted.
22 * - @c "item,clicked" - this is called when an item is clicked by user
23 * interaction. Both "item,selected" and "item,clicked" are needed.
24 * - @c "clicked" - when multibuttonentry is clicked.
25 * - @c "focused" - when multibuttonentry is focused.
26 * - @c "unfocused" - when multibuttonentry is unfocused.
27 * - @c "expanded" - when multibuttonentry is expanded.
28 * - @c "contracted" - when multibuttonentry is contracted.
29 * - @c "expand,state,changed" - when shrink mode state of multibuttonentry is changed.
31 * Default text parts of the multibuttonentry widget that you can use for are:
32 * @li "default" - A label of the multibuttonentry
34 * Default text parts of the multibuttonentry items that you can use for are:
35 * @li "default" - A label of the multibuttonentry item
37 * Supported elm_object common APIs.
38 * @li @ref elm_object_signal_emit
39 * @li @ref elm_object_part_text_set
40 * @li @ref elm_object_part_text_get
42 * Supported elm_object_item common APIs.
43 * @li @ref elm_object_item_part_text_set
44 * @li @ref elm_object_item_part_text_get
49 * @addtogroup Multibuttonentry
54 * @brief Callback to be invoked when an item is added to the multibuttonentry.
56 * @param obj The parent object
57 * @param item_label The label corresponding to the added item.
58 * @param item_data data specific to this item.
59 * @param data data specific to the multibuttonentry.
62 * EINA_FALSE otherwise.
64 * @ingroup Multibuttonentry
66 typedef Eina_Bool (*Elm_Multibuttonentry_Item_Filter_Cb)(Evas_Object *obj, const char *item_label, void *item_data, void *data);
69 * @brief Add a new multibuttonentry to the parent
71 * @param parent The parent object
72 * @return The new object or NULL if it cannot be created
75 * @ingroup Multibuttonentry
77 EAPI Evas_Object *elm_multibuttonentry_add(Evas_Object *parent);
81 * Get the entry of the multibuttonentry object
83 * @param obj The multibuttonentry object
84 * @return The entry object, or NULL if none
86 * @ingroup Multibuttonentry
88 EAPI Evas_Object *elm_multibuttonentry_entry_get(const Evas_Object *obj);
91 * Get the value of expanded state.
92 * In expanded state, the complete entry will be displayed.
93 * Otherwise, only single line of the entry will be displayed.
95 * @param obj The multibuttonentry object
96 * @return EINA_TRUE if the widget is in expanded state. EINA_FALSE if not.
98 * @ingroup Multibuttonentry
100 EAPI Eina_Bool elm_multibuttonentry_expanded_get(const Evas_Object *obj);
103 * Set/Unset the multibuttonentry to expanded state.
104 * In expanded state, the complete entry will be displayed.
105 * Otherwise, only single line of the entry will be displayed.
107 * @param obj The multibuttonentry object
108 * @param expanded the value of expanded state.
109 * Set this to EINA_TRUE for expanded state.
110 * Set this to EINA_FALSE for single line state.
112 * @ingroup Multibuttonentry
114 EAPI void elm_multibuttonentry_expanded_set(Evas_Object *obj, Eina_Bool expanded);
117 * Prepend a new item to the multibuttonentry
119 * @param obj The multibuttonentry object
120 * @param label The label of new item
121 * @param func The callback function to be invoked when this item is pressed.
122 * @param data The pointer to the data to be attached
123 * @return A handle to the item added or NULL if not possible
125 * @see Use elm_object_item_del() to delete the item.
127 * @ingroup Multibuttonentry
129 EAPI Elm_Object_Item *elm_multibuttonentry_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
132 * Append a new item to the multibuttonentry
134 * @param obj The multibuttonentry object
135 * @param label The label of new item
136 * @param func The callback function to be invoked when this item is pressed.
137 * @param data The pointer to the data to be attached
138 * @return A handle to the item added or NULL if not possible
140 * @see Use elm_object_item_del() to delete the item.
142 * @ingroup Multibuttonentry
144 EAPI Elm_Object_Item *elm_multibuttonentry_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
147 * Add a new item to the multibuttonentry before the indicated object
150 * @param obj The multibuttonentry object
151 * @param before The item before which to add it
152 * @param label The label of new item
153 * @param func The callback function to be invoked when this item is pressed.
154 * @param data The pointer to the data to be attached
155 * @return A handle to the item added or NULL if not possible
157 * @see Use elm_object_item_del() to delete the item.
159 * @ingroup Multibuttonentry
161 EAPI Elm_Object_Item *elm_multibuttonentry_item_insert_before(Evas_Object *obj, Elm_Object_Item *before, const char *label, Evas_Smart_Cb func, void *data);
164 * Add a new item to the multibuttonentry after the indicated object
166 * @param obj The multibuttonentry object
167 * @param after The item after which to add it
168 * @param label The label of new item
169 * @param func The callback function to be invoked when this item is pressed.
170 * @param data The pointer to the data to be attached
171 * @return A handle to the item added or NULL if not possible
173 * @see Use elm_object_item_del() to delete the item.
175 * @ingroup Multibuttonentry
177 EAPI Elm_Object_Item *elm_multibuttonentry_item_insert_after(Evas_Object *obj, Elm_Object_Item *after, const char *label, Evas_Smart_Cb func, void *data);
180 * Get a list of items in the multibuttonentry
182 * @param obj The multibuttonentry object
183 * @return The list of items, or NULL if none
185 * @ingroup Multibuttonentry
187 EAPI const Eina_List *elm_multibuttonentry_items_get(const Evas_Object *obj);
190 * Get the first item in the multibuttonentry
192 * @param obj The multibuttonentry object
193 * @return The first item, or NULL if none
195 * @ingroup Multibuttonentry
197 EAPI Elm_Object_Item *elm_multibuttonentry_first_item_get(const Evas_Object *obj);
200 * Get the last item in the multibuttonentry
202 * @param obj The multibuttonentry object
203 * @return The last item, or NULL if none
205 * @ingroup Multibuttonentry
207 EAPI Elm_Object_Item *elm_multibuttonentry_last_item_get(const Evas_Object *obj);
210 * Get the selected item in the multibuttonentry
212 * @param obj The multibuttonentry object
213 * @return The selected item, or NULL if none
215 * @ingroup Multibuttonentry
217 EAPI Elm_Object_Item *elm_multibuttonentry_selected_item_get(const Evas_Object *obj);
220 * Set the selected state of an item
223 * @param selected if it's EINA_TRUE, select the item otherwise, unselect the item
225 * @ingroup Multibuttonentry
227 EAPI void elm_multibuttonentry_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
231 * Get the selected state of an item
234 * @return EINA_TRUE if the item is selected, EINA_FALSE otherwise.
236 * @ingroup Multibuttonentry
238 EAPI Eina_Bool elm_multibuttonentry_item_selected_get(const Elm_Object_Item *it);
241 * Remove all items in the multibuttonentry.
243 * @param obj The multibuttonentry object
245 * @ingroup Multibuttonentry
247 EAPI void elm_multibuttonentry_clear(Evas_Object *obj);
250 * Get the previous item in the multibuttonentry
253 * @return The item before the item @p it
255 * @ingroup Multibuttonentry
257 EAPI Elm_Object_Item *elm_multibuttonentry_item_prev_get(const Elm_Object_Item *it);
260 * Get the next item in the multibuttonentry
263 * @return The item after the item @p it
265 * @ingroup Multibuttonentry
267 EAPI Elm_Object_Item *elm_multibuttonentry_item_next_get(const Elm_Object_Item *it);
270 * Append an item filter function for text inserted in the Multibuttonentry
272 * Append the given callback to the list. This functions will be called
273 * whenever any text is inserted into the Multibuttonentry, with the text to be inserted
274 * as a parameter. The callback function is free to alter the text in any way
275 * it wants, but it must remember to free the given pointer and update it.
276 * If the new text is to be discarded, the function can free it and set it text
277 * parameter to NULL. This will also prevent any following filters from being
280 * @param obj The multibuttonentry object
281 * @param func The function to use as item filter
282 * @param data User data to pass to @p func
284 * @ingroup Multibuttonentry
286 EAPI void elm_multibuttonentry_item_filter_append(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
289 * Prepend a filter function for text inserted in the Multibuttonentry
291 * Prepend the given callback to the list. See elm_multibuttonentry_item_filter_append()
292 * for more information
294 * @param obj The multibuttonentry object
295 * @param func The function to use as text filter
296 * @param data User data to pass to @p func
298 * @ingroup Multibuttonentry
300 EAPI void elm_multibuttonentry_item_filter_prepend(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
303 * Remove a filter from the list
305 * Removes the given callback from the filter list. See elm_multibuttonentry_item_filter_append()
306 * for more information.
308 * @param obj The multibuttonentry object
309 * @param func The filter function to remove
310 * @param data The user data passed when adding the function
312 * @ingroup Multibuttonentry
314 EAPI void elm_multibuttonentry_item_filter_remove(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
317 * Sets if the multibuttonentry is to be editable or not.
319 * @param obj The multibuttonentry object
320 * @param editable If EINA_TRUE, user can add/delete item in multibuttonentry, if not, the multibuttonentry is non-editable.
322 * @ingroup Multibuttonentry
326 EAPI void elm_multibuttonentry_editable_set(Evas_Object *obj, Eina_Bool editable);
329 * Gets whether the multibuttonentry is editable or not.
331 * @param obj The multibuttonentry object
332 * @return EINA_TRUE if the multibuttonentry is editable by the user. EINA_FALSE if not.
334 * @ingroup Multibuttonentry
338 EAPI Eina_Bool elm_multibuttonentry_editable_get(const Evas_Object *obj);