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