src/lib/elc_multibuttonentry.h

   1 /**
   2  * @defgroup Multibuttonentry Multibuttonentry
   3  * @ingroup Elementary
   4  *
   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
  11  * to one line.
  12  *
  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.
  15  *
  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.
  30  *
  31  * Default text parts of the multibuttonentry widget that you can use for are:
  32  * @li "default" - A label of the multibuttonentry
  33  *
  34  * Default text parts of the multibuttonentry items that you can use for are:
  35  * @li "default" - A label of the multibuttonentry item
  36  *
  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
  41  *
  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
  45  *
  46  */
  47
  48 /**
  49  * @addtogroup Multibuttonentry
  50  * @{
  51  */
  52
  53 /**
  54  * @brief Callback to be invoked when an item is added to the multibuttonentry.
  55  *
  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.
  60  *
  61  * @return EINA_TRUE
  62  *         EINA_FALSE otherwise.
  63  *
  64  * @ingroup Multibuttonentry
  65  */
  66 typedef Eina_Bool                   (*Elm_Multibuttonentry_Item_Filter_Cb)(Evas_Object *obj, const char *item_label, void *item_data, void *data);
  67
  68 /**
  69  * @brief Add a new multibuttonentry to the parent
  70  *
  71  * @param parent The parent object
  72  * @return The new object or NULL if it cannot be created
  73  *
  74  *
  75  * @ingroup Multibuttonentry
  76  */
  77 EAPI Evas_Object               *elm_multibuttonentry_add(Evas_Object *parent);
  78
  79
  80 /**
  81  * Get the entry of the multibuttonentry object
  82  *
  83  * @param obj The multibuttonentry object
  84  * @return The entry object, or NULL if none
  85  *
  86  * @ingroup Multibuttonentry
  87  */
  88 EAPI Evas_Object               *elm_multibuttonentry_entry_get(const Evas_Object *obj);
  89
  90 /**
  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.
  94  *
  95  * @param obj The multibuttonentry object
  96  * @return EINA_TRUE if the widget is in expanded state. EINA_FALSE if not.
  97  *
  98  * @ingroup Multibuttonentry
  99  */
 100 EAPI Eina_Bool                  elm_multibuttonentry_expanded_get(const Evas_Object *obj);
 101
 102 /**
 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.
 106  *
 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.
 111  *
 112  * @ingroup Multibuttonentry
 113  */
 114 EAPI void                       elm_multibuttonentry_expanded_set(Evas_Object *obj, Eina_Bool expanded);
 115
 116 /**
 117  * Prepend a new item to the multibuttonentry
 118  *
 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
 124  *
 125  * @see Use elm_object_item_del() to delete the item.
 126  *
 127  * @ingroup Multibuttonentry
 128  */
 129 EAPI Elm_Object_Item *elm_multibuttonentry_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
 130
 131 /**
 132  * Append a new item to the multibuttonentry
 133  *
 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
 139  *
 140  * @see Use elm_object_item_del() to delete the item.
 141  *
 142  * @ingroup Multibuttonentry
 143  */
 144 EAPI Elm_Object_Item *elm_multibuttonentry_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
 145
 146 /**
 147  * Add a new item to the multibuttonentry before the indicated object
 148  *
 149  * reference.
 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
 156  *
 157  * @see Use elm_object_item_del() to delete the item.
 158  *
 159  * @ingroup Multibuttonentry
 160  */
 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);
 162
 163 /**
 164  * Add a new item to the multibuttonentry after the indicated object
 165  *
 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
 172  *
 173  * @see Use elm_object_item_del() to delete the item.
 174  *
 175  * @ingroup Multibuttonentry
 176  */
 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);
 178
 179 /**
 180  * Get a list of items in the multibuttonentry
 181  *
 182  * @param obj The multibuttonentry object
 183  * @return The list of items, or NULL if none
 184  *
 185  * @ingroup Multibuttonentry
 186  */
 187 EAPI const Eina_List           *elm_multibuttonentry_items_get(const Evas_Object *obj);
 188
 189 /**
 190  * Get the first item in the multibuttonentry
 191  *
 192  * @param obj The multibuttonentry object
 193  * @return The first item, or NULL if none
 194  *
 195  * @ingroup Multibuttonentry
 196  */
 197 EAPI Elm_Object_Item *elm_multibuttonentry_first_item_get(const Evas_Object *obj);
 198
 199 /**
 200  * Get the last item in the multibuttonentry
 201  *
 202  * @param obj The multibuttonentry object
 203  * @return The last item, or NULL if none
 204  *
 205  * @ingroup Multibuttonentry
 206  */
 207 EAPI Elm_Object_Item *elm_multibuttonentry_last_item_get(const Evas_Object *obj);
 208
 209 /**
 210  * Get the selected item in the multibuttonentry
 211  *
 212  * @param obj The multibuttonentry object
 213  * @return The selected item, or NULL if none
 214  *
 215  * @ingroup Multibuttonentry
 216  */
 217 EAPI Elm_Object_Item *elm_multibuttonentry_selected_item_get(const Evas_Object *obj);
 218
 219 /**
 220  * Set the selected state of an item
 221  *
 222  * @param it The item
 223  * @param selected if it's EINA_TRUE, select the item otherwise, unselect the item
 224  *
 225  * @ingroup Multibuttonentry
 226  */
 227 EAPI void                       elm_multibuttonentry_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 228
 229
 230 /**
 231  * Get the selected state of an item
 232  *
 233  * @param it The item
 234  * @return EINA_TRUE if the item is selected, EINA_FALSE otherwise.
 235  *
 236  * @ingroup Multibuttonentry
 237  */
 238 EAPI Eina_Bool elm_multibuttonentry_item_selected_get(const Elm_Object_Item *it);
 239
 240 /**
 241  * Remove all items in the multibuttonentry.
 242  *
 243  * @param obj The multibuttonentry object
 244  *
 245  * @ingroup Multibuttonentry
 246  */
 247 EAPI void                       elm_multibuttonentry_clear(Evas_Object *obj);
 248
 249 /**
 250  * Get the previous item in the multibuttonentry
 251  *
 252  * @param it The item
 253  * @return The item before the item @p it
 254  *
 255  * @ingroup Multibuttonentry
 256  */
 257 EAPI Elm_Object_Item *elm_multibuttonentry_item_prev_get(const Elm_Object_Item *it);
 258
 259 /**
 260  * Get the next item in the multibuttonentry
 261  *
 262  * @param it The item
 263  * @return The item after the item @p it
 264  *
 265  * @ingroup Multibuttonentry
 266  */
 267 EAPI Elm_Object_Item *elm_multibuttonentry_item_next_get(const Elm_Object_Item *it);
 268
 269 /**
 270  * Append an item filter function for text inserted in the Multibuttonentry
 271  *
 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
 278  * called.
 279  *
 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
 283  *
 284  * @ingroup Multibuttonentry
 285  */
 286 EAPI void                       elm_multibuttonentry_item_filter_append(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 287
 288 /**
 289  * Prepend a filter function for text inserted in the Multibuttonentry
 290  *
 291  * Prepend the given callback to the list. See elm_multibuttonentry_item_filter_append()
 292  * for more information
 293  *
 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
 297  *
 298  * @ingroup Multibuttonentry
 299  */
 300 EAPI void                       elm_multibuttonentry_item_filter_prepend(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 301
 302 /**
 303  * Remove a filter from the list
 304  *
 305  * Removes the given callback from the filter list. See elm_multibuttonentry_item_filter_append()
 306  * for more information.
 307  *
 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
 311  *
 312  * @ingroup Multibuttonentry
 313  */
 314 EAPI void                       elm_multibuttonentry_item_filter_remove(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 315
 316 /**
 317  * Sets if the multibuttonentry is to be editable or not.
 318  *
 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.
 321  *
 322  * @ingroup Multibuttonentry
 323  *
 324  * @since 1.1
 325  */
 326 EAPI void elm_multibuttonentry_editable_set(Evas_Object *obj, Eina_Bool editable);
 327
 328 /**
 329  * Gets whether the multibuttonentry is editable or not.
 330  *
 331  * @param obj The multibuttonentry object
 332  * @return EINA_TRUE if the multibuttonentry is editable by the user. EINA_FALSE if not.
 333  *
 334  * @ingroup Multibuttonentry
 335  *
 336  * @since 1.1
 337  */
 338 EAPI Eina_Bool elm_multibuttonentry_editable_get(const Evas_Object *obj);
 339
 340 /**
 341  * @}
 342  */