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