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