src/lib/elc_multibuttonentry.h

   1 /**
   2  * @defgroup Multibuttonentry Multibuttonentry
   3  * @ingroup Elementary
   4  *
   5  * @image html multibuttonentry_inheritance_tree.png
   6  * @image latex multibuttonentry_inheritance_tree.eps
   7  *
   8  * A multi-button entry is a widget letting an user enter text and
   9  * each chunk of text managed as a set of buttons. Each text button is
  10  * inserted by pressing the "return" key. If there is no space in the
  11  * current row, a new button is added to the next row. When a text
  12  * button is pressed, it will become focused. Backspace removes the
  13  * focus. When the multi-button entry loses focus, items longer than
  14  * one line are shrunk to one line.
  15  *
  16  * The typical use case of multi-button entry is composing
  17  * emails/messages to a group of addresses, each of which is an item
  18  * that can be clicked for further actions.
  19  *
  20  * This widget inherits from the @ref Layout one, so that all the
  21  * functions acting on it also work for multi-button entry objects
  22  * (@since 1.8).
  23  *
  24  * This widget emits the following signals, besides the ones sent from
  25  * @ref Layout:
  26  * - @c "item,selected" - this is called when an item is selected by
  27  *       api, user interaction, and etc. this is also called when a
  28  *       user press back space while cursor is on the first field of
  29  *       entry.
  30  * - @c "item,added" - when a new multi-button entry item is added.
  31  * - @c "item,deleted" - when a multi-button entry item is deleted.
  32  * - @c "item,clicked" - this is called when an item is clicked by user
  33  *       interaction. Both "item,selected" and "item,clicked" are needed.
  34  * - @c "clicked" - when multi-button entry is clicked.
  35  * - @c "focused" - when multi-button entry is focused.
  36  * - @c "unfocused" - when multi-button entry is unfocused.
  37  * - @c "expanded" - when multi-button entry is expanded.
  38  * - @c "contracted" - when multi-button entry is contracted.
  39  * - @c "expand,state,changed" - when shrink mode state of
  40  *       multi-button entry is changed.
  41  * - @c "longpressed" - when multi-button entry is pressed for a long time.
  42  *
  43  * Default text parts of the multi-button entry widget that you can use are:
  44  * @li "default" - A label of the multi-button entry
  45  *
  46  * Default text parts of multi-button entry @b items that you can use are:
  47  * @li "default" - A label of the multi-button entry item
  48  *
  49  * Supported elm_object_item common APIs.
  50  * @li @ref elm_object_item_part_text_set
  51  * @li @ref elm_object_item_part_text_get
  52  */
  53
  54 /**
  55  * @addtogroup Multibuttonentry
  56  * @{
  57  */
  58
  59 /**
  60  * @brief Callback to be invoked when an item is added to the multibuttonentry.
  61  *
  62  * @param obj The parent object
  63  * @param item_label The label corresponding to the added item.
  64  * @param item_data data specific to this item.
  65  * @param data data specific to the multibuttonentry.
  66  *
  67  * @return EINA_TRUE
  68  *         EINA_FALSE otherwise.
  69  *
  70  * @ingroup Multibuttonentry
  71  */
  72 typedef Eina_Bool                   (*Elm_Multibuttonentry_Item_Filter_Cb)(Evas_Object *obj, const char *item_label, const void *item_data, const void *data);
  73
  74 /**
  75  * @brief Add a new multibuttonentry to the parent
  76  *
  77  * @param parent The parent object
  78  * @return The new object or NULL if it cannot be created
  79  *
  80  *
  81  * @ingroup Multibuttonentry
  82  */
  83 EAPI Evas_Object               *elm_multibuttonentry_add(Evas_Object *parent);
  84
  85
  86 /**
  87  * Get the entry of the multibuttonentry object
  88  *
  89  * @param obj The multibuttonentry object
  90  * @return The entry object, or NULL if none
  91  *
  92  * @ingroup Multibuttonentry
  93  */
  94 EAPI Evas_Object               *elm_multibuttonentry_entry_get(const Evas_Object *obj);
  95
  96 /**
  97  * Get the value of expanded state.
  98  * In expanded state, the complete entry will be displayed.
  99  * Otherwise, only single line of the entry will be displayed.
 100  *
 101  * @param obj The multibuttonentry object
 102  * @return EINA_TRUE if the widget is in expanded state. EINA_FALSE if not.
 103  *
 104  * @ingroup Multibuttonentry
 105  */
 106 EAPI Eina_Bool                  elm_multibuttonentry_expanded_get(const Evas_Object *obj);
 107
 108 /**
 109  * Set/Unset the multibuttonentry to expanded state.
 110  * In expanded state, the complete entry will be displayed.
 111  * Otherwise, only single line of the entry will be displayed.
 112  *
 113  * @param obj The multibuttonentry object
 114  * @param expanded the value of expanded state.
 115  *        Set this to EINA_TRUE for expanded state.
 116  *        Set this to EINA_FALSE for single line state.
 117  *
 118  * @ingroup Multibuttonentry
 119  */
 120 EAPI void                       elm_multibuttonentry_expanded_set(Evas_Object *obj, Eina_Bool expanded);
 121
 122 /**
 123  * Prepend a new item to the multibuttonentry
 124  *
 125  * @param obj The multibuttonentry object
 126  * @param label The label of new item
 127  * @param func The callback function to be invoked when this item is pressed.
 128  * @param data The pointer to the data to be attached
 129  * @return A handle to the item added or NULL if not possible
 130  *
 131  * @see Use elm_object_item_del() to delete the item.
 132  *
 133  * @ingroup Multibuttonentry
 134  */
 135 EAPI Elm_Object_Item *elm_multibuttonentry_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, const void *data);
 136
 137 /**
 138  * Append a new item to the multibuttonentry
 139  *
 140  * @param obj The multibuttonentry object
 141  * @param label The label of new item
 142  * @param func The callback function to be invoked when this item is pressed.
 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  * @see Use elm_object_item_del() to delete the item.
 147  *
 148  * @ingroup Multibuttonentry
 149  */
 150 EAPI Elm_Object_Item *elm_multibuttonentry_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, const 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 func The callback function to be invoked when this item is pressed.
 160  * @param data The pointer to the data to be attached
 161  * @return A handle to the item added or NULL if not possible
 162  *
 163  * @see Use elm_object_item_del() to delete the item.
 164  *
 165  * @ingroup Multibuttonentry
 166  */
 167 EAPI Elm_Object_Item *elm_multibuttonentry_item_insert_before(Evas_Object *obj, Elm_Object_Item *before, const char *label, Evas_Smart_Cb func, const void *data);
 168
 169 /**
 170  * Add a new item to the multibuttonentry after the indicated object
 171  *
 172  * @param obj The multibuttonentry object
 173  * @param after The item after which to add it
 174  * @param label The label of new item
 175  * @param func The callback function to be invoked when this item is pressed.
 176  * @param data The pointer to the data to be attached
 177  * @return A handle to the item added or NULL if not possible
 178  *
 179  * @see Use elm_object_item_del() to delete the item.
 180  *
 181  * @ingroup Multibuttonentry
 182  */
 183 EAPI Elm_Object_Item *elm_multibuttonentry_item_insert_after(Evas_Object *obj, Elm_Object_Item *after, const char *label, Evas_Smart_Cb func, const void *data);
 184
 185 /**
 186  * Get a list of items in the multibuttonentry
 187  *
 188  * @param obj The multibuttonentry object
 189  * @return The list of items, or NULL if none
 190  *
 191  * @ingroup Multibuttonentry
 192  */
 193 EAPI const Eina_List           *elm_multibuttonentry_items_get(const Evas_Object *obj);
 194
 195 /**
 196  * Gets the base object of the item.
 197  *
 198  * @param it The multibuttonentry item
 199  * @return The base object associated with @p item
 200  *
 201  * Base object is the @c Evas_Object that represents that item.
 202  *
 203  * @ingroup List
 204  */
 205 EAPI Evas_Object *elm_multibuttonentry_item_object_get(const Elm_Object_Item *it);
 206
 207 /**
 208  * Get the first item in the multibuttonentry
 209  *
 210  * @param obj The multibuttonentry object
 211  * @return The first item, or NULL if none
 212  *
 213  * @ingroup Multibuttonentry
 214  */
 215 EAPI Elm_Object_Item *elm_multibuttonentry_first_item_get(const Evas_Object *obj);
 216
 217 /**
 218  * Get the last item in the multibuttonentry
 219  *
 220  * @param obj The multibuttonentry object
 221  * @return The last item, or NULL if none
 222  *
 223  * @ingroup Multibuttonentry
 224  */
 225 EAPI Elm_Object_Item *elm_multibuttonentry_last_item_get(const Evas_Object *obj);
 226
 227 /**
 228  * Get the selected item in the multibuttonentry
 229  *
 230  * @param obj The multibuttonentry object
 231  * @return The selected item, or NULL if none
 232  *
 233  * @ingroup Multibuttonentry
 234  */
 235 EAPI Elm_Object_Item *elm_multibuttonentry_selected_item_get(const Evas_Object *obj);
 236
 237 /**
 238  * Set the selected state of an item
 239  *
 240  * @param it The item
 241  * @param selected if it's EINA_TRUE, select the item otherwise, unselect the item
 242  *
 243  * @ingroup Multibuttonentry
 244  */
 245 EAPI void                       elm_multibuttonentry_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 246
 247
 248 /**
 249  * Get the selected state of an item
 250  *
 251  * @param it The item
 252  * @return EINA_TRUE if the item is selected, EINA_FALSE otherwise.
 253  *
 254  * @ingroup Multibuttonentry
 255  */
 256 EAPI Eina_Bool elm_multibuttonentry_item_selected_get(const Elm_Object_Item *it);
 257
 258 /**
 259  * Remove all items in the multibuttonentry.
 260  *
 261  * @param obj The multibuttonentry object
 262  *
 263  * @ingroup Multibuttonentry
 264  */
 265 EAPI void                       elm_multibuttonentry_clear(Evas_Object *obj);
 266
 267 /**
 268  * Get the previous item in the multibuttonentry
 269  *
 270  * @param it The item
 271  * @return The item before the item @p it
 272  *
 273  * @ingroup Multibuttonentry
 274  */
 275 EAPI Elm_Object_Item *elm_multibuttonentry_item_prev_get(const Elm_Object_Item *it);
 276
 277 /**
 278  * Get the next item in the multibuttonentry
 279  *
 280  * @param it The item
 281  * @return The item after the item @p it
 282  *
 283  * @ingroup Multibuttonentry
 284  */
 285 EAPI Elm_Object_Item *elm_multibuttonentry_item_next_get(const Elm_Object_Item *it);
 286
 287 /**
 288  * Append an item filter function for text inserted in the Multibuttonentry
 289  *
 290  * Append the given callback to the list. This functions will be called
 291  * whenever any text is inserted into the Multibuttonentry, with the text to be inserted
 292  * as a parameter. The callback function is free to alter the text in any way
 293  * it wants, but it must remember to free the given pointer and update it.
 294  * If the new text is to be discarded, the function can free it and set it text
 295  * parameter to NULL. This will also prevent any following filters from being
 296  * called.
 297  *
 298  * @param obj The multibuttonentry object
 299  * @param func The function to use as item filter
 300  * @param data User data to pass to @p func
 301  *
 302  * @ingroup Multibuttonentry
 303  */
 304 EAPI void                       elm_multibuttonentry_item_filter_append(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
 305
 306 /**
 307  * Prepend a filter function for text inserted in the Multibuttonentry
 308  *
 309  * Prepend the given callback to the list. See elm_multibuttonentry_item_filter_append()
 310  * for more information
 311  *
 312  * @param obj The multibuttonentry object
 313  * @param func The function to use as text filter
 314  * @param data User data to pass to @p func
 315  *
 316  * @ingroup Multibuttonentry
 317  */
 318 EAPI void                       elm_multibuttonentry_item_filter_prepend(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
 319
 320 /**
 321  * Remove a filter from the list
 322  *
 323  * Removes the given callback from the filter list. See elm_multibuttonentry_item_filter_append()
 324  * for more information.
 325  *
 326  * @param obj The multibuttonentry object
 327  * @param func The filter function to remove
 328  * @param data The user data passed when adding the function
 329  *
 330  * @ingroup Multibuttonentry
 331  */
 332 EAPI void                       elm_multibuttonentry_item_filter_remove(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
 333
 334 /**
 335  * Sets if the multibuttonentry is to be editable or not.
 336  *
 337  * @param obj The multibuttonentry object
 338  * @param editable If EINA_TRUE, user can add/delete item in multibuttonentry, if not, the multibuttonentry is non-editable.
 339  *
 340  * @ingroup Multibuttonentry
 341  *
 342  * @since 1.7
 343  */
 344 EAPI void elm_multibuttonentry_editable_set(Evas_Object *obj, Eina_Bool editable);
 345
 346 /**
 347  * Gets whether the multibuttonentry is editable or not.
 348  *
 349  * @param obj The multibuttonentry object
 350  * @return EINA_TRUE if the multibuttonentry is editable by the user. EINA_FALSE if not.
 351  *
 352  * @ingroup Multibuttonentry
 353  *
 354  * @since 1.7
 355  */
 356 EAPI Eina_Bool elm_multibuttonentry_editable_get(const Evas_Object *obj);
 357
 358 /**
 359  * @}
 360  */