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