src/lib/elc_multibuttonentry.h

   1 /**
   2  * @defgroup Multibuttonentry Multibuttonentry
   3  *
   4  * A Multibuttonentry is a widget to allow a user enter text and manage it as a number
   5  * of buttons. Each text button is inserted by pressing the "return" key.
   6  * If there is no space in the current row, a new button is added to the next row.
   7  * When a text button is pressed, it will become focused.
   8  * Backspace removes the focus.
   9  * When the Multibuttonentry loses focus items longer than one line are shrunk
  10  * to one line.
  11  *
  12  * Typical use case of multibuttonentry is, composing emails/messages to a group
  13  * of addresses, each of which is an item that can be clicked for further actions.
  14  *
  15  * Smart callbacks one can register:
  16  * - @c "item,selected" - this is called when an item is selected by api, user
  17  *       interaction, and etc. this is also called when a user press back space
  18  *       while cursor is on the first field of entry.
  19  * - @c "item,added" - when a new multibuttonentry item is added.
  20  * - @c "item,deleted" - when a multibuttonentry item is deleted.
  21  * - @c "item,clicked" - this is called when an item is clicked by user
  22  *       interaction. Both "item,selected" and "item,clicked" are needed.
  23  * - @c "clicked" - when multibuttonentry is clicked.
  24  * - @c "focused" - when multibuttonentry is focused.
  25  * - @c "unfocused" - when multibuttonentry is unfocused.
  26  * - @c "expanded" - when multibuttonentry is expanded.
  27  * - @c "contracted" - when multibuttonentry is contracted.
  28  * - @c "expand,state,changed" - when shrink mode state of multibuttonentry is changed.
  29  *
  30  * Default text parts of the multibuttonentry widget that you can use for are:
  31  * @li "default" - A label of the multibuttonentry
  32  *
  33  * Default text parts of the multibuttonentry items that you can use for are:
  34  * @li "default" - A label of the multibuttonentry item
  35  *
  36  * Supported elm_object common APIs.
  37  * @li elm_object_signal_emit
  38  * @li elm_object_part_text_set
  39  * @li elm_object_part_text_get
  40  *
  41  * Supported elm_object_item common APIs.
  42  * @li elm_object_item_part_text_set
  43  * @li elm_object_item_part_text_get
  44  *
  45  */
  46
  47 /**
  48  * @addtogroup Multibuttonentry
  49  * @{
  50  */
  51
  52 /**
  53  * @brief Callback to be invoked when an item is added to the multibuttonentry.
  54  *
  55  * @param obj The parent object
  56  * @param item_label The label corresponding to the added item.
  57  * @param item_data data specific to this item.
  58  * @param data data specific to the multibuttonentry.
  59  *
  60  * @return EINA_TRUE
  61  *         EINA_FALSE otherwise.
  62  *
  63  * @ingroup Multibuttonentry
  64  */
  65 typedef Eina_Bool                   (*Elm_Multibuttonentry_Item_Filter_Cb)(Evas_Object *obj, const char *item_label, void *item_data, void *data);
  66
  67 /**
  68  * @brief Add a new multibuttonentry to the parent
  69  *
  70  * @param parent The parent object
  71  * @return The new object or NULL if it cannot be created
  72  *
  73  *
  74  * @ingroup Multibuttonentry
  75  */
  76 EAPI Evas_Object               *elm_multibuttonentry_add(Evas_Object *parent);
  77
  78
  79 /**
  80  * Get the entry of the multibuttonentry object
  81  *
  82  * @param obj The multibuttonentry object
  83  * @return The entry object, or NULL if none
  84  *
  85  * @ingroup Multibuttonentry
  86  */
  87 EAPI Evas_Object               *elm_multibuttonentry_entry_get(const Evas_Object *obj);
  88
  89 /**
  90  * Get the value of expanded state.
  91  * In expanded state, the complete entry will be displayed.
  92  * Otherwise, only single line of the entry will be displayed.
  93  *
  94  * @param obj The multibuttonentry object
  95  * @return EINA_TRUE if the widget is in expanded state. EINA_FALSE if not.
  96  *
  97  * @ingroup Multibuttonentry
  98  */
  99 EAPI Eina_Bool                  elm_multibuttonentry_expanded_get(const Evas_Object *obj);
 100
 101 /**
 102  * Set/Unset the multibuttonentry to expanded state.
 103  * In expanded state, the complete entry will be displayed.
 104  * Otherwise, only single line of the entry will be displayed.
 105  *
 106  * @param obj The multibuttonentry object
 107  * @param expanded the value of expanded state.
 108  *        Set this to EINA_TRUE for expanded state.
 109  *        Set this to EINA_FALSE for single line state.
 110  *
 111  * @ingroup Multibuttonentry
 112  */
 113 EAPI void                       elm_multibuttonentry_expanded_set(Evas_Object *obj, Eina_Bool expanded);
 114
 115 /**
 116  * Prepend a new item to the multibuttonentry
 117  *
 118  * @param obj The multibuttonentry object
 119  * @param label The label of new item
 120  * @param func The callback function to be invoked when this item is pressed.
 121  * @param data The pointer to the data to be attached
 122  * @return A handle to the item added or NULL if not possible
 123  *
 124  * @see Use elm_object_item_del() to delete the item.
 125  *
 126  * @ingroup Multibuttonentry
 127  */
 128 EAPI Elm_Object_Item *elm_multibuttonentry_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
 129
 130 /**
 131  * Append a new item to the multibuttonentry
 132  *
 133  * @param obj The multibuttonentry object
 134  * @param label The label of new item
 135  * @param func The callback function to be invoked when this item is pressed.
 136  * @param data The pointer to the data to be attached
 137  * @return A handle to the item added or NULL if not possible
 138  *
 139  * @see Use elm_object_item_del() to delete the item.
 140  *
 141  * @ingroup Multibuttonentry
 142  */
 143 EAPI Elm_Object_Item *elm_multibuttonentry_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
 144
 145 /**
 146  * Add a new item to the multibuttonentry before the indicated object
 147  *
 148  * reference.
 149  * @param obj The multibuttonentry object
 150  * @param before The item before which to add it
 151  * @param label The label of new item
 152  * @param func The callback function to be invoked when this item is pressed.
 153  * @param data The pointer to the data to be attached
 154  * @return A handle to the item added or NULL if not possible
 155  *
 156  * @see Use elm_object_item_del() to delete the item.
 157  *
 158  * @ingroup Multibuttonentry
 159  */
 160 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);
 161
 162 /**
 163  * Add a new item to the multibuttonentry after the indicated object
 164  *
 165  * @param obj The multibuttonentry object
 166  * @param after The item after which to add it
 167  * @param label The label of new item
 168  * @param func The callback function to be invoked when this item is pressed.
 169  * @param data The pointer to the data to be attached
 170  * @return A handle to the item added or NULL if not possible
 171  *
 172  * @see Use elm_object_item_del() to delete the item.
 173  *
 174  * @ingroup Multibuttonentry
 175  */
 176 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);
 177
 178 /**
 179  * Get a list of items in the multibuttonentry
 180  *
 181  * @param obj The multibuttonentry object
 182  * @return The list of items, or NULL if none
 183  *
 184  * @ingroup Multibuttonentry
 185  */
 186 EAPI const Eina_List           *elm_multibuttonentry_items_get(const Evas_Object *obj);
 187
 188 /**
 189  * Get the first item in the multibuttonentry
 190  *
 191  * @param obj The multibuttonentry object
 192  * @return The first item, or NULL if none
 193  *
 194  * @ingroup Multibuttonentry
 195  */
 196 EAPI Elm_Object_Item *elm_multibuttonentry_first_item_get(const Evas_Object *obj);
 197
 198 /**
 199  * Get the last item in the multibuttonentry
 200  *
 201  * @param obj The multibuttonentry object
 202  * @return The last item, or NULL if none
 203  *
 204  * @ingroup Multibuttonentry
 205  */
 206 EAPI Elm_Object_Item *elm_multibuttonentry_last_item_get(const Evas_Object *obj);
 207
 208 /**
 209  * Get the selected item in the multibuttonentry
 210  *
 211  * @param obj The multibuttonentry object
 212  * @return The selected item, or NULL if none
 213  *
 214  * @ingroup Multibuttonentry
 215  */
 216 EAPI Elm_Object_Item *elm_multibuttonentry_selected_item_get(const Evas_Object *obj);
 217
 218 /**
 219  * Set the selected state of an item
 220  *
 221  * @param it The item
 222  * @param selected if it's EINA_TRUE, select the item otherwise, unselect the item
 223  *
 224  * @ingroup Multibuttonentry
 225  */
 226 EAPI void                       elm_multibuttonentry_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 227
 228
 229 /**
 230  * Get the selected state of an item
 231  *
 232  * @param it The item
 233  * @return EINA_TRUE if the item is selected, EINA_FALSE otherwise.
 234  *
 235  * @ingroup Multibuttonentry
 236  */
 237 EAPI Eina_Bool elm_multibuttonentry_item_selected_get(const Elm_Object_Item *it);
 238
 239 /**
 240  * Remove all items in the multibuttonentry.
 241  *
 242  * @param obj The multibuttonentry object
 243  *
 244  * @ingroup Multibuttonentry
 245  */
 246 EAPI void                       elm_multibuttonentry_clear(Evas_Object *obj);
 247
 248 /**
 249  * Get the previous item in the multibuttonentry
 250  *
 251  * @param it The item
 252  * @return The item before the item @p it
 253  *
 254  * @ingroup Multibuttonentry
 255  */
 256 EAPI Elm_Object_Item *elm_multibuttonentry_item_prev_get(const Elm_Object_Item *it);
 257
 258 /**
 259  * Get the next item in the multibuttonentry
 260  *
 261  * @param it The item
 262  * @return The item after the item @p it
 263  *
 264  * @ingroup Multibuttonentry
 265  */
 266 EAPI Elm_Object_Item *elm_multibuttonentry_item_next_get(const Elm_Object_Item *it);
 267
 268 /**
 269  * Append an item filter function for text inserted in the Multibuttonentry
 270  *
 271  * Append the given callback to the list. This functions will be called
 272  * whenever any text is inserted into the Multibuttonentry, with the text to be inserted
 273  * as a parameter. The callback function is free to alter the text in any way
 274  * it wants, but it must remember to free the given pointer and update it.
 275  * If the new text is to be discarded, the function can free it and set it text
 276  * parameter to NULL. This will also prevent any following filters from being
 277  * called.
 278  *
 279  * @param obj The multibuttonentry object
 280  * @param func The function to use as item filter
 281  * @param data User data to pass to @p func
 282  *
 283  * @ingroup Multibuttonentry
 284  */
 285 EAPI void                       elm_multibuttonentry_item_filter_append(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 286
 287 /**
 288  * Prepend a filter function for text inserted in the Multibuttonentry
 289  *
 290  * Prepend the given callback to the list. See elm_multibuttonentry_item_filter_append()
 291  * for more information
 292  *
 293  * @param obj The multibuttonentry object
 294  * @param func The function to use as text filter
 295  * @param data User data to pass to @p func
 296  *
 297  * @ingroup Multibuttonentry
 298  */
 299 EAPI void                       elm_multibuttonentry_item_filter_prepend(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 300
 301 /**
 302  * Remove a filter from the list
 303  *
 304  * Removes the given callback from the filter list. See elm_multibuttonentry_item_filter_append()
 305  * for more information.
 306  *
 307  * @param obj The multibuttonentry object
 308  * @param func The filter function to remove
 309  * @param data The user data passed when adding the function
 310  *
 311  * @ingroup Multibuttonentry
 312  */
 313 EAPI void                       elm_multibuttonentry_item_filter_remove(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 314
 315 /**
 316  * @}
 317  */