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  *
  42  * Default text parts of the multi-button entry widget that you can use are:
  43  * @li "default" - A label of the multi-button entry
  44  *
  45  * Default text parts of multi-button entry @b items that you can use are:
  46  * @li "default" - A label of the multi-button entry item
  47  *
  48  * Supported elm_object_item common APIs.
  49  * @li @ref elm_object_item_part_text_set
  50  * @li @ref elm_object_item_part_text_get
  51  */
  52
  53 /**
  54  * @addtogroup Multibuttonentry
  55  * @{
  56  */
  57
  58 /**
  59  * @brief Callback to be invoked when an item is added to the multibuttonentry.
  60  *
  61  * @param obj The parent object
  62  * @param item_label The label corresponding to the added item.
  63  * @param item_data data specific to this item.
  64  * @param data data specific to the multibuttonentry.
  65  *
  66  * @return EINA_TRUE
  67  *         EINA_FALSE otherwise.
  68  *
  69  * @ingroup Multibuttonentry
  70  */
  71 typedef Eina_Bool                   (*Elm_Multibuttonentry_Item_Filter_Cb)(Evas_Object *obj, const char *item_label, const void *item_data, const void *data);
  72
  73 /**
  74  * @brief Add a new multibuttonentry to the parent
  75  *
  76  * @param parent The parent object
  77  * @return The new object or NULL if it cannot be created
  78  *
  79  *
  80  * @ingroup Multibuttonentry
  81  */
  82 EAPI Evas_Object               *elm_multibuttonentry_add(Evas_Object *parent);
  83
  84
  85 /**
  86  * Get the entry of the multibuttonentry object
  87  *
  88  * @param obj The multibuttonentry object
  89  * @return The entry object, or NULL if none
  90  *
  91  * @ingroup Multibuttonentry
  92  */
  93 EAPI Evas_Object               *elm_multibuttonentry_entry_get(const Evas_Object *obj);
  94
  95 /**
  96  * Get the value of expanded state.
  97  * In expanded state, the complete entry will be displayed.
  98  * Otherwise, only single line of the entry will be displayed.
  99  *
 100  * @param obj The multibuttonentry object
 101  * @return EINA_TRUE if the widget is in expanded state. EINA_FALSE if not.
 102  *
 103  * @ingroup Multibuttonentry
 104  */
 105 EAPI Eina_Bool                  elm_multibuttonentry_expanded_get(const Evas_Object *obj);
 106
 107 /**
 108  * Set/Unset the multibuttonentry to expanded state.
 109  * In expanded state, the complete entry will be displayed.
 110  * Otherwise, only single line of the entry will be displayed.
 111  *
 112  * @param obj The multibuttonentry object
 113  * @param expanded the value of expanded state.
 114  *        Set this to EINA_TRUE for expanded state.
 115  *        Set this to EINA_FALSE for single line state.
 116  *
 117  * @ingroup Multibuttonentry
 118  */
 119 EAPI void                       elm_multibuttonentry_expanded_set(Evas_Object *obj, Eina_Bool expanded);
 120
 121 /**
 122  * Prepend a new item to the multibuttonentry
 123  *
 124  * @param obj The multibuttonentry object
 125  * @param label The label of new item
 126  * @param func The callback function to be invoked when this item is pressed.
 127  * @param data The pointer to the data to be attached
 128  * @return A handle to the item added or NULL if not possible
 129  *
 130  * @see Use elm_object_item_del() to delete the item.
 131  *
 132  * @ingroup Multibuttonentry
 133  */
 134 EAPI Elm_Object_Item *elm_multibuttonentry_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, const void *data);
 135
 136 /**
 137  * Append a new item to the multibuttonentry
 138  *
 139  * @param obj The multibuttonentry object
 140  * @param label The label of new item
 141  * @param func The callback function to be invoked when this item is pressed.
 142  * @param data The pointer to the data to be attached
 143  * @return A handle to the item added or NULL if not possible
 144  *
 145  * @see Use elm_object_item_del() to delete the item.
 146  *
 147  * @ingroup Multibuttonentry
 148  */
 149 EAPI Elm_Object_Item *elm_multibuttonentry_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, const void *data);
 150
 151 /**
 152  * Add a new item to the multibuttonentry before the indicated object
 153  *
 154  * reference.
 155  * @param obj The multibuttonentry object
 156  * @param before The item before which to add it
 157  * @param label The label of new item
 158  * @param func The callback function to be invoked when this item is pressed.
 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  * @see Use elm_object_item_del() to delete the item.
 163  *
 164  * @ingroup Multibuttonentry
 165  */
 166 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);
 167
 168 /**
 169  * Add a new item to the multibuttonentry after the indicated object
 170  *
 171  * @param obj The multibuttonentry object
 172  * @param after The item after which to add it
 173  * @param label The label of new item
 174  * @param func The callback function to be invoked when this item is pressed.
 175  * @param data The pointer to the data to be attached
 176  * @return A handle to the item added or NULL if not possible
 177  *
 178  * @see Use elm_object_item_del() to delete the item.
 179  *
 180  * @ingroup Multibuttonentry
 181  */
 182 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);
 183
 184 /**
 185  * Get a list of items in the multibuttonentry
 186  *
 187  * @param obj The multibuttonentry object
 188  * @return The list of items, or NULL if none
 189  *
 190  * @ingroup Multibuttonentry
 191  */
 192 EAPI const Eina_List           *elm_multibuttonentry_items_get(const Evas_Object *obj);
 193
 194 /**
 195  * Get the first item in the multibuttonentry
 196  *
 197  * @param obj The multibuttonentry object
 198  * @return The first item, or NULL if none
 199  *
 200  * @ingroup Multibuttonentry
 201  */
 202 EAPI Elm_Object_Item *elm_multibuttonentry_first_item_get(const Evas_Object *obj);
 203
 204 /**
 205  * Get the last item in the multibuttonentry
 206  *
 207  * @param obj The multibuttonentry object
 208  * @return The last item, or NULL if none
 209  *
 210  * @ingroup Multibuttonentry
 211  */
 212 EAPI Elm_Object_Item *elm_multibuttonentry_last_item_get(const Evas_Object *obj);
 213
 214 /**
 215  * Get the selected item in the multibuttonentry
 216  *
 217  * @param obj The multibuttonentry object
 218  * @return The selected item, or NULL if none
 219  *
 220  * @ingroup Multibuttonentry
 221  */
 222 EAPI Elm_Object_Item *elm_multibuttonentry_selected_item_get(const Evas_Object *obj);
 223
 224 /**
 225  * Set the selected state of an item
 226  *
 227  * @param it The item
 228  * @param selected if it's EINA_TRUE, select the item otherwise, unselect the item
 229  *
 230  * @ingroup Multibuttonentry
 231  */
 232 EAPI void                       elm_multibuttonentry_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 233
 234
 235 /**
 236  * Get the selected state of an item
 237  *
 238  * @param it The item
 239  * @return EINA_TRUE if the item is selected, EINA_FALSE otherwise.
 240  *
 241  * @ingroup Multibuttonentry
 242  */
 243 EAPI Eina_Bool elm_multibuttonentry_item_selected_get(const Elm_Object_Item *it);
 244
 245 /**
 246  * Remove all items in the multibuttonentry.
 247  *
 248  * @param obj The multibuttonentry object
 249  *
 250  * @ingroup Multibuttonentry
 251  */
 252 EAPI void                       elm_multibuttonentry_clear(Evas_Object *obj);
 253
 254 /**
 255  * Get the previous item in the multibuttonentry
 256  *
 257  * @param it The item
 258  * @return The item before the item @p it
 259  *
 260  * @ingroup Multibuttonentry
 261  */
 262 EAPI Elm_Object_Item *elm_multibuttonentry_item_prev_get(const Elm_Object_Item *it);
 263
 264 /**
 265  * Get the next item in the multibuttonentry
 266  *
 267  * @param it The item
 268  * @return The item after the item @p it
 269  *
 270  * @ingroup Multibuttonentry
 271  */
 272 EAPI Elm_Object_Item *elm_multibuttonentry_item_next_get(const Elm_Object_Item *it);
 273
 274 /**
 275  * Append an item filter function for text inserted in the Multibuttonentry
 276  *
 277  * Append the given callback to the list. This functions will be called
 278  * whenever any text is inserted into the Multibuttonentry, with the text to be inserted
 279  * as a parameter. The callback function is free to alter the text in any way
 280  * it wants, but it must remember to free the given pointer and update it.
 281  * If the new text is to be discarded, the function can free it and set it text
 282  * parameter to NULL. This will also prevent any following filters from being
 283  * called.
 284  *
 285  * @param obj The multibuttonentry object
 286  * @param func The function to use as item filter
 287  * @param data User data to pass to @p func
 288  *
 289  * @ingroup Multibuttonentry
 290  */
 291 EAPI void                       elm_multibuttonentry_item_filter_append(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
 292
 293 /**
 294  * Prepend a filter function for text inserted in the Multibuttonentry
 295  *
 296  * Prepend the given callback to the list. See elm_multibuttonentry_item_filter_append()
 297  * for more information
 298  *
 299  * @param obj The multibuttonentry object
 300  * @param func The function to use as text filter
 301  * @param data User data to pass to @p func
 302  *
 303  * @ingroup Multibuttonentry
 304  */
 305 EAPI void                       elm_multibuttonentry_item_filter_prepend(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
 306
 307 /**
 308  * Remove a filter from the list
 309  *
 310  * Removes the given callback from the filter list. See elm_multibuttonentry_item_filter_append()
 311  * for more information.
 312  *
 313  * @param obj The multibuttonentry object
 314  * @param func The filter function to remove
 315  * @param data The user data passed when adding the function
 316  *
 317  * @ingroup Multibuttonentry
 318  */
 319 EAPI void                       elm_multibuttonentry_item_filter_remove(Evas_Object *obj, Elm_Multibuttonentry_Item_Filter_Cb func, const void *data);
 320
 321 /**
 322  * Sets if the multibuttonentry is to be editable or not.
 323  *
 324  * @param obj The multibuttonentry object
 325  * @param editable If EINA_TRUE, user can add/delete item in multibuttonentry, if not, the multibuttonentry is non-editable.
 326  *
 327  * @ingroup Multibuttonentry
 328  *
 329  * @since 1.7
 330  */
 331 EAPI void elm_multibuttonentry_editable_set(Evas_Object *obj, Eina_Bool editable);
 332
 333 /**
 334  * Gets whether the multibuttonentry is editable or not.
 335  *
 336  * @param obj The multibuttonentry object
 337  * @return EINA_TRUE if the multibuttonentry is editable by the user. EINA_FALSE if not.
 338  *
 339  * @ingroup Multibuttonentry
 340  *
 341  * @since 1.7
 342  */
 343 EAPI Eina_Bool elm_multibuttonentry_editable_get(const Evas_Object *obj);
 344
 345 /**
 346  * @}
 347  */