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  * @ingroup Multibuttonentry
 125  */
 126 EAPI Elm_Object_Item *elm_multibuttonentry_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
 127
 128 /**
 129  * Append a new item to the multibuttonentry
 130  *
 131  * @param obj The multibuttonentry object
 132  * @param label The label of new item
 133  * @param func The callback function to be invoked when this item is pressed.
 134  * @param data The pointer to the data to be attached
 135  * @return A handle to the item added or NULL if not possible
 136  *
 137  * @ingroup Multibuttonentry
 138  */
 139 EAPI Elm_Object_Item *elm_multibuttonentry_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
 140
 141 /**
 142  * Add a new item to the multibuttonentry before the indicated object
 143  *
 144  * reference.
 145  * @param obj The multibuttonentry object
 146  * @param before The item before which to add it
 147  * @param label The label of new item
 148  * @param func The callback function to be invoked when this item is pressed.
 149  * @param data The pointer to the data to be attached
 150  * @return A handle to the item added or NULL if not possible
 151  *
 152  * @ingroup Multibuttonentry
 153  */
 154 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);
 155
 156 /**
 157  * Add a new item to the multibuttonentry after the indicated object
 158  *
 159  * @param obj The multibuttonentry object
 160  * @param after The item after which to add it
 161  * @param label The label of new item
 162  * @param func The callback function to be invoked when this item is pressed.
 163  * @param data The pointer to the data to be attached
 164  * @return A handle to the item added or NULL if not possible
 165  *
 166  * @ingroup Multibuttonentry
 167  */
 168 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);
 169
 170 /**
 171  * Get a list of items in the multibuttonentry
 172  *
 173  * @param obj The multibuttonentry object
 174  * @return The list of items, or NULL if none
 175  *
 176  * @ingroup Multibuttonentry
 177  */
 178 EAPI const Eina_List           *elm_multibuttonentry_items_get(const Evas_Object *obj);
 179
 180 /**
 181  * Get the first item in the multibuttonentry
 182  *
 183  * @param obj The multibuttonentry object
 184  * @return The first item, or NULL if none
 185  *
 186  * @ingroup Multibuttonentry
 187  */
 188 EAPI Elm_Object_Item *elm_multibuttonentry_first_item_get(const Evas_Object *obj);
 189
 190 /**
 191  * Get the last item in the multibuttonentry
 192  *
 193  * @param obj The multibuttonentry object
 194  * @return The last item, or NULL if none
 195  *
 196  * @ingroup Multibuttonentry
 197  */
 198 EAPI Elm_Object_Item *elm_multibuttonentry_last_item_get(const Evas_Object *obj);
 199
 200 /**
 201  * Get the selected item in the multibuttonentry
 202  *
 203  * @param obj The multibuttonentry object
 204  * @return The selected item, or NULL if none
 205  *
 206  * @ingroup Multibuttonentry
 207  */
 208 EAPI Elm_Object_Item *elm_multibuttonentry_selected_item_get(const Evas_Object *obj);
 209
 210 /**
 211  * Set the selected state of an item
 212  *
 213  * @param it The item
 214  * @param selected if it's EINA_TRUE, select the item otherwise, unselect the item
 215  *
 216  * @ingroup Multibuttonentry
 217  */
 218 EAPI void                       elm_multibuttonentry_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 219
 220
 221 /**
 222  * Get the selected state of an item
 223  *
 224  * @param it The item
 225  * @return EINA_TRUE if the item is selected, EINA_FALSE otherwise.
 226  *
 227  * @ingroup Multibuttonentry
 228  */
 229 EAPI Eina_Bool elm_multibuttonentry_item_selected_get(const Elm_Object_Item *it);
 230
 231 /**
 232  * Remove all items in the multibuttonentry.
 233  *
 234  * @param obj The multibuttonentry object
 235  *
 236  * @ingroup Multibuttonentry
 237  */
 238 EAPI void                       elm_multibuttonentry_clear(Evas_Object *obj);
 239
 240 /**
 241  * Get the previous item in the multibuttonentry
 242  *
 243  * @param it The item
 244  * @return The item before the item @p it
 245  *
 246  * @ingroup Multibuttonentry
 247  */
 248 EAPI Elm_Object_Item *elm_multibuttonentry_item_prev_get(const Elm_Object_Item *it);
 249
 250 /**
 251  * Get the next item in the multibuttonentry
 252  *
 253  * @param it The item
 254  * @return The item after the item @p it
 255  *
 256  * @ingroup Multibuttonentry
 257  */
 258 EAPI Elm_Object_Item *elm_multibuttonentry_item_next_get(const Elm_Object_Item *it);
 259
 260 /**
 261  * Append an item filter function for text inserted in the Multibuttonentry
 262  *
 263  * Append the given callback to the list. This functions will be called
 264  * whenever any text is inserted into the Multibuttonentry, with the text to be inserted
 265  * as a parameter. The callback function is free to alter the text in any way
 266  * it wants, but it must remember to free the given pointer and update it.
 267  * If the new text is to be discarded, the function can free it and set it text
 268  * parameter to NULL. This will also prevent any following filters from being
 269  * called.
 270  *
 271  * @param obj The multibuttonentry object
 272  * @param func The function to use as item filter
 273  * @param data User data to pass to @p func
 274  *
 275  * @ingroup Multibuttonentry
 276  */
 277 EAPI void                       elm_multibuttonentry_item_filter_append(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 278
 279 /**
 280  * Prepend a filter function for text inserted in the Multibuttonentry
 281  *
 282  * Prepend the given callback to the list. See elm_multibuttonentry_item_filter_append()
 283  * for more information
 284  *
 285  * @param obj The multibuttonentry object
 286  * @param func The function to use as text filter
 287  * @param data User data to pass to @p func
 288  *
 289  * @ingroup Multibuttonentry
 290  */
 291 EAPI void                       elm_multibuttonentry_item_filter_prepend(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 292
 293 /**
 294  * Remove a filter from the list
 295  *
 296  * Removes the given callback from the filter list. See elm_multibuttonentry_item_filter_append()
 297  * for more information.
 298  *
 299  * @param obj The multibuttonentry object
 300  * @param func The filter function to remove
 301  * @param data The user data passed when adding the function
 302  *
 303  * @ingroup Multibuttonentry
 304  */
 305 EAPI void                       elm_multibuttonentry_item_filter_remove(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, void *data);
 306
 307 /**
 308  * @}
 309  */