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