src/lib/elm_toolbar.h

   1    /**
   2     * @defgroup Toolbar Toolbar
   3     * @ingroup Elementary
   4     *
   5     * @image html img/widget/toolbar/preview-00.png
   6     * @image latex img/widget/toolbar/preview-00.eps width=\textwidth
   7     *
   8     * @image html img/toolbar.png
   9     * @image latex img/toolbar.eps width=\textwidth
  10     *
  11     * A toolbar is a widget that displays a list of items inside
  12     * a box. It can be scrollable, show a menu with items that don't fit
  13     * to toolbar size or even crop them.
  14     *
  15     * Only one item can be selected at a time.
  16     *
  17     * Items can have multiple states, or show menus when selected by the user.
  18     *
  19     * Smart callbacks one can listen to:
  20     * - "clicked" - when the user clicks on a toolbar item and becomes selected.
  21     * - "language,changed" - when the program language changes
  22     *
  23     * Available styles for it:
  24     * - @c "default"
  25     * - @c "transparent" - no background or shadow, just show the content
  26     *
  27     * Default text parts of the toolbar items that you can use for are:
  28     * @li "default" - label of the toolbar item
  29     *
  30     * Supported elm_object_item common APIs.
  31     * @li elm_object_item_disabled_set
  32     * @li elm_object_item_text_set
  33     * @li elm_object_item_part_text_set
  34     * @li elm_object_item_text_get
  35     * @li elm_object_item_part_text_get
  36     *
  37     * List of examples:
  38     * @li @ref toolbar_example_01
  39     * @li @ref toolbar_example_02
  40     * @li @ref toolbar_example_03
  41     */
  42
  43    /**
  44     * @addtogroup Toolbar
  45     * @{
  46     */
  47
  48    /**
  49     * @enum _Elm_Toolbar_Shrink_Mode
  50     * @typedef Elm_Toolbar_Shrink_Mode
  51     *
  52     * Set toolbar's items display behavior, it can be scrollabel,
  53     * show a menu with exceeding items, or simply hide them.
  54     *
  55     * @note Default value is #ELM_TOOLBAR_SHRINK_MENU. It reads value
  56     * from elm config.
  57     *
  58     * Values <b> don't </b> work as bitmask, only one can be choosen.
  59     *
  60     * @see elm_toolbar_mode_shrink_set()
  61     * @see elm_toolbar_mode_shrink_get()
  62     *
  63     * @ingroup Toolbar
  64     */
  65    typedef enum _Elm_Toolbar_Shrink_Mode
  66      {
  67         ELM_TOOLBAR_SHRINK_NONE,   /**< Set toolbar minimun size to fit all the items. */
  68         ELM_TOOLBAR_SHRINK_HIDE,   /**< Hide exceeding items. */
  69         ELM_TOOLBAR_SHRINK_SCROLL, /**< Allow accessing exceeding items through a scroller. */
  70         ELM_TOOLBAR_SHRINK_MENU,   /**< Inserts a button to pop up a menu with exceeding items. */
  71         ELM_TOOLBAR_SHRINK_LAST    /**< Indicates error if returned by elm_toolbar_shrink_mode_get() */
  72      } Elm_Toolbar_Shrink_Mode;
  73
  74    typedef struct _Elm_Toolbar_Item_State Elm_Toolbar_Item_State; /**< State of a Elm_Toolbar_Item. Can be created with elm_toolbar_item_state_add() and removed with elm_toolbar_item_state_del(). */
  75
  76    /**
  77     * Add a new toolbar widget to the given parent Elementary
  78     * (container) object.
  79     *
  80     * @param parent The parent object.
  81     * @return a new toolbar widget handle or @c NULL, on errors.
  82     *
  83     * This function inserts a new toolbar widget on the canvas.
  84     *
  85     * @ingroup Toolbar
  86     */
  87    EAPI Evas_Object            *elm_toolbar_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  88
  89    /**
  90     * Set the icon size, in pixels, to be used by toolbar items.
  91     *
  92     * @param obj The toolbar object
  93     * @param icon_size The icon size in pixels
  94     *
  95     * @note Default value is @c 32. It reads value from elm config.
  96     *
  97     * @see elm_toolbar_icon_size_get()
  98     *
  99     * @ingroup Toolbar
 100     */
 101    EAPI void                    elm_toolbar_icon_size_set(Evas_Object *obj, int icon_size) EINA_ARG_NONNULL(1);
 102
 103    /**
 104     * Get the icon size, in pixels, to be used by toolbar items.
 105     *
 106     * @param obj The toolbar object.
 107     * @return The icon size in pixels.
 108     *
 109     * @see elm_toolbar_icon_size_set() for details.
 110     *
 111     * @ingroup Toolbar
 112     */
 113    EAPI int                     elm_toolbar_icon_size_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 114
 115    /**
 116     * Sets icon lookup order, for toolbar items' icons.
 117     *
 118     * @param obj The toolbar object.
 119     * @param order The icon lookup order.
 120     *
 121     * Icons added before calling this function will not be affected.
 122     * The default lookup order is #ELM_ICON_LOOKUP_THEME_FDO.
 123     *
 124     * @see elm_toolbar_icon_order_lookup_get()
 125     *
 126     * @ingroup Toolbar
 127     */
 128    EAPI void                    elm_toolbar_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order) EINA_ARG_NONNULL(1);
 129
 130    /**
 131     * Gets the icon lookup order.
 132     *
 133     * @param obj The toolbar object.
 134     * @return The icon lookup order.
 135     *
 136     * @see elm_toolbar_icon_order_lookup_set() for details.
 137     *
 138     * @ingroup Toolbar
 139     */
 140    EAPI Elm_Icon_Lookup_Order   elm_toolbar_icon_order_lookup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 141
 142    /**
 143     * Set whether the toolbar should always have an item selected.
 144     *
 145     * @param obj The toolbar object.
 146     * @param wrap @c EINA_TRUE to enable always-select mode or @c EINA_FALSE to
 147     * disable it.
 148     *
 149     * This will cause the toolbar to always have an item selected, and clicking
 150     * the selected item will not cause a selected event to be emitted. Enabling this mode
 151     * will immediately select the first toolbar item.
 152     *
 153     * Always-selected is disabled by default.
 154     *
 155     * @see elm_toolbar_always_select_mode_get().
 156     *
 157     * @ingroup Toolbar
 158     */
 159    EAPI void                    elm_toolbar_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select) EINA_ARG_NONNULL(1);
 160
 161    /**
 162     * Get whether the toolbar should always have an item selected.
 163     *
 164     * @param obj The toolbar object.
 165     * @return @c EINA_TRUE means an item will always be selected, @c EINA_FALSE indicates
 166     * that it is possible to have no items selected. If @p obj is @c NULL, @c EINA_FALSE is returned.
 167     *
 168     * @see elm_toolbar_always_select_mode_set() for details.
 169     *
 170     * @ingroup Toolbar
 171     */
 172    EAPI Eina_Bool               elm_toolbar_always_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 173
 174    /**
 175     * Set whether the toolbar items' should be selected by the user or not.
 176     *
 177     * @param obj The toolbar object.
 178     * @param wrap @c EINA_TRUE to disable selection or @c EINA_FALSE to
 179     * enable it.
 180     *
 181     * This will turn off the ability to select items entirely and they will
 182     * neither appear selected nor emit selected signals. The clicked
 183     * callback function will still be called.
 184     *
 185     * Selection is enabled by default.
 186     *
 187     * @see elm_toolbar_no_select_mode_get().
 188     *
 189     * @ingroup Toolbar
 190     */
 191    EAPI void                    elm_toolbar_no_select_mode_set(Evas_Object *obj, Eina_Bool no_select) EINA_ARG_NONNULL(1);
 192
 193    /**
 194     * Set whether the toolbar items' should be selected by the user or not.
 195     *
 196     * @param obj The toolbar object.
 197     * @return @c EINA_TRUE means items can be selected. @c EINA_FALSE indicates
 198     * they can't. If @p obj is @c NULL, @c EINA_FALSE is returned.
 199     *
 200     * @see elm_toolbar_no_select_mode_set() for details.
 201     *
 202     * @ingroup Toolbar
 203     */
 204    EAPI Eina_Bool               elm_toolbar_no_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 205
 206    /**
 207     * Append item to the toolbar.
 208     *
 209     * @param obj The toolbar object.
 210     * @param icon A string with icon name or the absolute path of an image file.
 211     * @param label The label of the item.
 212     * @param func The function to call when the item is clicked.
 213     * @param data The data to associate with the item for related callbacks.
 214     * @return The created item or @c NULL upon failure.
 215     *
 216     * A new item will be created and appended to the toolbar, i.e., will
 217     * be set as @b last item.
 218     *
 219     * Items created with this method can be deleted with
 220     * elm_toolbar_item_del().
 221     *
 222     * Associated @p data can be properly freed when item is deleted if a
 223     * callback function is set with elm_toolbar_item_del_cb_set().
 224     *
 225     * If a function is passed as argument, it will be called everytime this item
 226     * is selected, i.e., the user clicks over an unselected item.
 227     * If such function isn't needed, just passing
 228     * @c NULL as @p func is enough. The same should be done for @p data.
 229     *
 230     * Toolbar will load icon image from fdo or current theme.
 231     * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 232     * If an absolute path is provided it will load it direct from a file.
 233     *
 234     * @see elm_toolbar_item_icon_set()
 235     * @see elm_toolbar_item_del()
 236     * @see elm_toolbar_item_del_cb_set()
 237     *
 238     * @ingroup Toolbar
 239     */
 240    EAPI Elm_Object_Item       *elm_toolbar_item_append(Evas_Object *obj, const char *icon, const char *label, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 241
 242    /**
 243     * Prepend item to the toolbar.
 244     *
 245     * @param obj The toolbar object.
 246     * @param icon A string with icon name or the absolute path of an image file.
 247     * @param label The label of the item.
 248     * @param func The function to call when the item is clicked.
 249     * @param data The data to associate with the item for related callbacks.
 250     * @return The created item or @c NULL upon failure.
 251     *
 252     * A new item will be created and prepended to the toolbar, i.e., will
 253     * be set as @b first item.
 254     *
 255     * Items created with this method can be deleted with
 256     * elm_toolbar_item_del().
 257     *
 258     * Associated @p data can be properly freed when item is deleted if a
 259     * callback function is set with elm_toolbar_item_del_cb_set().
 260     *
 261     * If a function is passed as argument, it will be called everytime this item
 262     * is selected, i.e., the user clicks over an unselected item.
 263     * If such function isn't needed, just passing
 264     * @c NULL as @p func is enough. The same should be done for @p data.
 265     *
 266     * Toolbar will load icon image from fdo or current theme.
 267     * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 268     * If an absolute path is provided it will load it direct from a file.
 269     *
 270     * @see elm_toolbar_item_icon_set()
 271     * @see elm_toolbar_item_del()
 272     * @see elm_toolbar_item_del_cb_set()
 273     *
 274     * @ingroup Toolbar
 275     */
 276    EAPI Elm_Object_Item       *elm_toolbar_item_prepend(Evas_Object *obj, const char *icon, const char *label, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 277
 278    /**
 279     * Insert a new item into the toolbar object before item @p before.
 280     *
 281     * @param obj The toolbar object.
 282     * @param before The toolbar item to insert before.
 283     * @param icon A string with icon name or the absolute path of an image file.
 284     * @param label The label of the item.
 285     * @param func The function to call when the item is clicked.
 286     * @param data The data to associate with the item for related callbacks.
 287     * @return The created item or @c NULL upon failure.
 288     *
 289     * A new item will be created and added to the toolbar. Its position in
 290     * this toolbar will be just before item @p before.
 291     *
 292     * Items created with this method can be deleted with
 293     * elm_toolbar_item_del().
 294     *
 295     * Associated @p data can be properly freed when item is deleted if a
 296     * callback function is set with elm_toolbar_item_del_cb_set().
 297     *
 298     * If a function is passed as argument, it will be called everytime this item
 299     * is selected, i.e., the user clicks over an unselected item.
 300     * If such function isn't needed, just passing
 301     * @c NULL as @p func is enough. The same should be done for @p data.
 302     *
 303     * Toolbar will load icon image from fdo or current theme.
 304     * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 305     * If an absolute path is provided it will load it direct from a file.
 306     *
 307     * @see elm_toolbar_item_icon_set()
 308     * @see elm_toolbar_item_del()
 309     * @see elm_toolbar_item_del_cb_set()
 310     *
 311     * @ingroup Toolbar
 312     */
 313    EAPI Elm_Object_Item       *elm_toolbar_item_insert_before(Evas_Object *obj, Elm_Object_Item *before, const char *icon, const char *label, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 314
 315    /**
 316     * Insert a new item into the toolbar object after item @p after.
 317     *
 318     * @param obj The toolbar object.
 319     * @param after The toolbar item to insert after.
 320     * @param icon A string with icon name or the absolute path of an image file.
 321     * @param label The label of the item.
 322     * @param func The function to call when the item is clicked.
 323     * @param data The data to associate with the item for related callbacks.
 324     * @return The created item or @c NULL upon failure.
 325     *
 326     * A new item will be created and added to the toolbar. Its position in
 327     * this toolbar will be just after item @p after.
 328     *
 329     * Items created with this method can be deleted with
 330     * elm_toolbar_item_del().
 331     *
 332     * Associated @p data can be properly freed when item is deleted if a
 333     * callback function is set with elm_toolbar_item_del_cb_set().
 334     *
 335     * If a function is passed as argument, it will be called everytime this item
 336     * is selected, i.e., the user clicks over an unselected item.
 337     * If such function isn't needed, just passing
 338     * @c NULL as @p func is enough. The same should be done for @p data.
 339     *
 340     * Toolbar will load icon image from fdo or current theme.
 341     * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 342     * If an absolute path is provided it will load it direct from a file.
 343     *
 344     * @see elm_toolbar_item_icon_set()
 345     * @see elm_toolbar_item_del()
 346     * @see elm_toolbar_item_del_cb_set()
 347     *
 348     * @ingroup Toolbar
 349     */
 350    EAPI Elm_Object_Item       *elm_toolbar_item_insert_after(Evas_Object *obj, Elm_Object_Item *after, const char *icon, const char *label, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 351
 352    /**
 353     * Get the first item in the given toolbar widget's list of
 354     * items.
 355     *
 356     * @param obj The toolbar object
 357     * @return The first item or @c NULL, if it has no items (and on
 358     * errors)
 359     *
 360     * @see elm_toolbar_item_append()
 361     * @see elm_toolbar_last_item_get()
 362     *
 363     * @ingroup Toolbar
 364     */
 365    EAPI Elm_Object_Item       *elm_toolbar_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 366
 367    /**
 368     * Get the last item in the given toolbar widget's list of
 369     * items.
 370     *
 371     * @param obj The toolbar object
 372     * @return The last item or @c NULL, if it has no items (and on
 373     * errors)
 374     *
 375     * @see elm_toolbar_item_prepend()
 376     * @see elm_toolbar_first_item_get()
 377     *
 378     * @ingroup Toolbar
 379     */
 380    EAPI Elm_Object_Item       *elm_toolbar_last_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 381
 382    /**
 383     * Get the item after @p item in toolbar.
 384     *
 385     * @param it The toolbar item.
 386     * @return The item after @p item, or @c NULL if none or on failure.
 387     *
 388     * @note If it is the last item, @c NULL will be returned.
 389     *
 390     * @see elm_toolbar_item_append()
 391     *
 392     * @ingroup Toolbar
 393     */
 394    EAPI Elm_Object_Item       *elm_toolbar_item_next_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 395
 396    /**
 397     * Get the item before @p item in toolbar.
 398     *
 399     * @param item The toolbar item.
 400     * @return The item before @p item, or @c NULL if none or on failure.
 401     *
 402     * @note If it is the first item, @c NULL will be returned.
 403     *
 404     * @see elm_toolbar_item_prepend()
 405     *
 406     * @ingroup Toolbar
 407     */
 408    EAPI Elm_Object_Item       *elm_toolbar_item_prev_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 409
 410    /**
 411     * Get the toolbar object from an item.
 412     *
 413     * @param it The item.
 414     * @return The toolbar object.
 415     *
 416     * This returns the toolbar object itself that an item belongs to.
 417     *
 418          * @deprecated use elm_object_item_object_get() instead.
 419     * @ingroup Toolbar
 420     */
 421    EINA_DEPRECATED EAPI Evas_Object            *elm_toolbar_item_toolbar_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 422
 423    /**
 424     * Set the priority of a toolbar item.
 425     *
 426     * @param it The toolbar item.
 427     * @param priority The item priority. The default is zero.
 428     *
 429     * This is used only when the toolbar shrink mode is set to
 430     * #ELM_TOOLBAR_SHRINK_MENU or #ELM_TOOLBAR_SHRINK_HIDE.
 431     * When space is less than required, items with low priority
 432     * will be removed from the toolbar and added to a dynamically-created menu,
 433     * while items with higher priority will remain on the toolbar,
 434     * with the same order they were added.
 435     *
 436     * @see elm_toolbar_item_priority_get()
 437     *
 438     * @ingroup Toolbar
 439     */
 440    EAPI void                    elm_toolbar_item_priority_set(Elm_Object_Item *it, int priority) EINA_ARG_NONNULL(1);
 441
 442    /**
 443     * Get the priority of a toolbar item.
 444     *
 445     * @param it The toolbar item.
 446     * @return The @p item priority, or @c 0 on failure.
 447     *
 448     * @see elm_toolbar_item_priority_set() for details.
 449     *
 450     * @ingroup Toolbar
 451     */
 452    EAPI int                     elm_toolbar_item_priority_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 453
 454    /**
 455     * Get the label of item.
 456     *
 457     * @param it The item of toolbar.
 458     * @return The label of item.
 459     *
 460     * The return value is a pointer to the label associated to @p item when
 461     * it was created, with function elm_toolbar_item_append() or similar,
 462     * or later,
 463     * with function elm_toolbar_item_label_set. If no label
 464     * was passed as argument, it will return @c NULL.
 465     *
 466     * @see elm_toolbar_item_label_set() for more details.
 467     * @see elm_toolbar_item_append()
 468     *
 469          * @deprecated use elm_object_item_text_get() instead.
 470     * @ingroup Toolbar
 471     */
 472    EINA_DEPRECATED EAPI const char             *elm_toolbar_item_label_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 473
 474    /**
 475     * Set the label of item.
 476     *
 477     * @param it The item of toolbar.
 478     * @param text The label of item.
 479     *
 480     * The label to be displayed by the item.
 481     * Label will be placed at icons bottom (if set).
 482     *
 483     * If a label was passed as argument on item creation, with function
 484     * elm_toolbar_item_append() or similar, it will be already
 485     * displayed by the item.
 486     *
 487     * @see elm_toolbar_item_label_get()
 488     * @see elm_toolbar_item_append()
 489     *
 490          * @deprecated use elm_object_item_text_set() instead
 491     * @ingroup Toolbar
 492     */
 493    EINA_DEPRECATED EAPI void                    elm_toolbar_item_label_set(Elm_Object_Item *it, const char *label) EINA_ARG_NONNULL(1);
 494
 495    /**
 496     * Return the data associated with a given toolbar widget item.
 497     *
 498     * @param it The toolbar widget item handle.
 499     * @return The data associated with @p item.
 500     *
 501     * @see elm_toolbar_item_data_set()
 502     *
 503     * @deprecated use elm_object_item_data_get() instead.
 504     * @ingroup Toolbar
 505     */
 506    EINA_DEPRECATED EAPI void                   *elm_toolbar_item_data_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 507
 508    /**
 509     * Set the data associated with a given toolbar widget item.
 510     *
 511     * @param it The toolbar widget item handle
 512     * @param data The new data pointer to set to @p item.
 513     *
 514     * This sets new item data on @p item.
 515     *
 516     * @warning The old data pointer won't be touched by this function, so
 517     * the user had better to free that old data himself/herself.
 518     *
 519     * @deprecated use elm_object_item_data_set() instead.
 520     * @ingroup Toolbar
 521     */
 522    EINA_DEPRECATED EAPI void                    elm_toolbar_item_data_set(Elm_Object_Item *it, const void *data) EINA_ARG_NONNULL(1);
 523
 524    /**
 525     * Returns a pointer to a toolbar item by its label.
 526     *
 527     * @param obj The toolbar object.
 528     * @param label The label of the item to find.
 529     *
 530     * @return The pointer to the toolbar item matching @p label or @c NULL
 531     * on failure.
 532     *
 533     * @ingroup Toolbar
 534     */
 535    EAPI Elm_Object_Item       *elm_toolbar_item_find_by_label(const Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
 536
 537    /*
 538     * Get whether the @p item is selected or not.
 539     *
 540     * @param it The toolbar item.
 541     * @return @c EINA_TRUE means item is selected. @c EINA_FALSE indicates
 542     * it's not. If @p obj is @c NULL, @c EINA_FALSE is returned.
 543     *
 544     * @see elm_toolbar_selected_item_set() for details.
 545     * @see elm_toolbar_item_selected_get()
 546     *
 547     * @ingroup Toolbar
 548     */
 549    EAPI Eina_Bool               elm_toolbar_item_selected_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 550
 551    /**
 552     * Set the selected state of an item.
 553     *
 554     * @param it The toolbar item
 555     * @param selected The selected state
 556     *
 557     * This sets the selected state of the given item @p it.
 558     * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
 559     *
 560     * If a new item is selected the previosly selected will be unselected.
 561     * Previoulsy selected item can be get with function
 562     * elm_toolbar_selected_item_get().
 563     *
 564     * Selected items will be highlighted.
 565     *
 566     * @see elm_toolbar_item_selected_get()
 567     * @see elm_toolbar_selected_item_get()
 568     *
 569     * @ingroup Toolbar
 570     */
 571    EAPI void                    elm_toolbar_item_selected_set(Elm_Object_Item *it, Eina_Bool selected) EINA_ARG_NONNULL(1);
 572
 573    /**
 574     * Get the selected item.
 575     *
 576     * @param obj The toolbar object.
 577     * @return The selected toolbar item.
 578     *
 579     * The selected item can be unselected with function
 580     * elm_toolbar_item_selected_set().
 581     *
 582     * The selected item always will be highlighted on toolbar.
 583     *
 584     * @see elm_toolbar_selected_items_get()
 585     *
 586     * @ingroup Toolbar
 587     */
 588    EAPI Elm_Object_Item       *elm_toolbar_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 589
 590    /**
 591     * Set the icon associated with @p item.
 592     *
 593     * @param obj The parent of this item.
 594     * @param it The toolbar item.
 595     * @param icon A string with icon name or the absolute path of an image file.
 596     *
 597     * Toolbar will load icon image from fdo or current theme.
 598     * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 599     * If an absolute path is provided it will load it direct from a file.
 600     *
 601     * @see elm_toolbar_icon_order_lookup_set()
 602     * @see elm_toolbar_icon_order_lookup_get()
 603     *
 604     * @ingroup Toolbar
 605     */
 606    EAPI void                    elm_toolbar_item_icon_set(Elm_Object_Item *it, const char *icon) EINA_ARG_NONNULL(1);
 607
 608    /**
 609     * Get the string used to set the icon of @p item.
 610     *
 611     * @param it The toolbar item.
 612     * @return The string associated with the icon object.
 613     *
 614     * @see elm_toolbar_item_icon_set() for details.
 615     *
 616     * @ingroup Toolbar
 617     */
 618    EAPI const char             *elm_toolbar_item_icon_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 619
 620    /**
 621     * Get the object of @p item.
 622     *
 623     * @param it The toolbar item.
 624     * @return The object
 625     *
 626     * @ingroup Toolbar
 627     */
 628    EAPI Evas_Object            *elm_toolbar_item_object_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 629
 630    /**
 631     * Get the icon object of @p item.
 632     *
 633     * @param it The toolbar item.
 634     * @return The icon object
 635     *
 636     * @see elm_toolbar_item_icon_set(), elm_toolbar_item_icon_file_set(),
 637     * or elm_toolbar_item_icon_memfile_set() for details.
 638     *
 639     * @ingroup Toolbar
 640     */
 641    EAPI Evas_Object            *elm_toolbar_item_icon_object_get(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 642
 643    /**
 644     * Set the icon associated with @p item to an image in a binary buffer.
 645     *
 646     * @param it The toolbar item.
 647     * @param img The binary data that will be used as an image
 648     * @param size The size of binary data @p img
 649     * @param format Optional format of @p img to pass to the image loader
 650     * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
 651     *
 652     * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
 653     *
 654     * @note The icon image set by this function can be changed by
 655     * elm_toolbar_item_icon_set().
 656     *
 657     * @ingroup Toolbar
 658     */
 659    EAPI Eina_Bool elm_toolbar_item_icon_memfile_set(Elm_Object_Item *it, const void *img, size_t size, const char *format, const char *key) EINA_ARG_NONNULL(1);
 660
 661    /**
 662     * Set the icon associated with @p item to an image in a binary buffer.
 663     *
 664     * @param it The toolbar item.
 665     * @param file The file that contains the image
 666     * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
 667     *
 668     * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
 669     *
 670     * @note The icon image set by this function can be changed by
 671     * elm_toolbar_item_icon_set().
 672     *
 673     * @ingroup Toolbar
 674     */
 675    EAPI Eina_Bool elm_toolbar_item_icon_file_set(Elm_Object_Item *it, const char *file, const char *key) EINA_ARG_NONNULL(1);
 676
 677    /**
 678     * Delete them item from the toolbar.
 679     *
 680     * @param it The item of toolbar to be deleted.
 681     *
 682     * @see elm_toolbar_item_append()
 683     * @see elm_toolbar_item_del_cb_set()
 684     *
 685     * @ingroup Toolbar
 686     */
 687    EAPI void                    elm_toolbar_item_del(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 688
 689    /**
 690     * Set the function called when a toolbar item is freed.
 691     *
 692     * @param it The item to set the callback on.
 693     * @param func The function called.
 694     *
 695     * If there is a @p func, then it will be called prior item's memory release.
 696     * That will be called with the following arguments:
 697     * @li item's data;
 698     * @li item's Evas object;
 699     * @li item itself;
 700     *
 701     * This way, a data associated to a toolbar item could be properly freed.
 702     *
 703     * @ingroup Toolbar
 704     */
 705    EAPI void                    elm_toolbar_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
 706
 707    /**
 708     * Get a value whether toolbar item is disabled or not.
 709     *
 710     * @param it The item.
 711     * @return The disabled state.
 712     *
 713     * @see elm_toolbar_item_disabled_set() for more details.
 714     *
 715     * @deprecated use elm_object_item_disabled_get() instead.
 716     * @ingroup Toolbar
 717     */
 718    EINA_DEPRECATED EAPI Eina_Bool               elm_toolbar_item_disabled_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 719
 720    /**
 721     * Sets the disabled/enabled state of a toolbar item.
 722     *
 723     * @param it The item.
 724     * @param disabled The disabled state.
 725     *
 726     * A disabled item cannot be selected or unselected. It will also
 727     * change its appearance (generally greyed out). This sets the
 728     * disabled state (@c EINA_TRUE for disabled, @c EINA_FALSE for
 729     * enabled).
 730     *
 731     * @deprecated use elm_object_item_disabled_set() instead.
 732     * @ingroup Toolbar
 733     */
 734    EINA_DEPRECATED EAPI void                    elm_toolbar_item_disabled_set(Elm_Object_Item *it, Eina_Bool disabled) EINA_ARG_NONNULL(1);
 735
 736    /**
 737     * Set or unset item as a separator.
 738     *
 739     * @param it The toolbar item.
 740     * @param setting @c EINA_TRUE to set item @p item as separator or
 741     * @c EINA_FALSE to unset, i.e., item will be used as a regular item.
 742     *
 743     * Items aren't set as separator by default.
 744     *
 745     * If set as separator it will display separator theme, so won't display
 746     * icons or label.
 747     *
 748     * @see elm_toolbar_item_separator_get()
 749     *
 750     * @ingroup Toolbar
 751     */
 752    EAPI void                    elm_toolbar_item_separator_set(Elm_Object_Item *it, Eina_Bool separator) EINA_ARG_NONNULL(1);
 753
 754    /**
 755     * Get a value whether item is a separator or not.
 756     *
 757     * @param it The toolbar item.
 758     * @return @c EINA_TRUE means item @p it is a separator. @c EINA_FALSE
 759     * indicates it's not. If @p it is @c NULL, @c EINA_FALSE is returned.
 760     *
 761     * @see elm_toolbar_item_separator_set() for details.
 762     *
 763     * @ingroup Toolbar
 764     */
 765    EAPI Eina_Bool               elm_toolbar_item_separator_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 766
 767    /**
 768     * Set the shrink state of toolbar @p obj.
 769     *
 770     * @param obj The toolbar object.
 771     * @param shrink_mode Toolbar's items display behavior.
 772     *
 773     * The toolbar won't scroll if #ELM_TOOLBAR_SHRINK_NONE,
 774     * but will enforce a minimun size so all the items will fit, won't scroll
 775     * and won't show the items that don't fit if #ELM_TOOLBAR_SHRINK_HIDE,
 776     * will scroll if #ELM_TOOLBAR_SHRINK_SCROLL, and will create a button to
 777     * pop up excess elements with #ELM_TOOLBAR_SHRINK_MENU.
 778     *
 779     * @ingroup Toolbar
 780     */
 781    EAPI void                    elm_toolbar_mode_shrink_set(Evas_Object *obj, Elm_Toolbar_Shrink_Mode shrink_mode) EINA_ARG_NONNULL(1);
 782
 783    /**
 784     * Get the shrink mode of toolbar @p obj.
 785     *
 786     * @param obj The toolbar object.
 787     * @return Toolbar's items display behavior.
 788     *
 789     * @see elm_toolbar_mode_shrink_set() for details.
 790     *
 791     * @ingroup Toolbar
 792     */
 793    EAPI Elm_Toolbar_Shrink_Mode elm_toolbar_mode_shrink_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 794
 795    /**
 796     * Enable/disable homogeneous mode.
 797     *
 798     * @param obj The toolbar object
 799     * @param homogeneous Assume the items within the toolbar are of the
 800     * same size (EINA_TRUE = on, EINA_FALSE = off). Default is @c EINA_FALSE.
 801     *
 802     * This will enable the homogeneous mode where items are of the same size.
 803     * @see elm_toolbar_homogeneous_get()
 804     *
 805     * @ingroup Toolbar
 806     */
 807    EAPI void                    elm_toolbar_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1);
 808
 809    /**
 810     * Get whether the homogeneous mode is enabled.
 811     *
 812     * @param obj The toolbar object.
 813     * @return Assume the items within the toolbar are of the same height
 814     * and width (EINA_TRUE = on, EINA_FALSE = off).
 815     *
 816     * @see elm_toolbar_homogeneous_set()
 817     *
 818     * @ingroup Toolbar
 819     */
 820    EAPI Eina_Bool               elm_toolbar_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 821
 822    /**
 823     * Set the parent object of the toolbar items' menus.
 824     *
 825     * @param obj The toolbar object.
 826     * @param parent The parent of the menu objects.
 827     *
 828     * Each item can be set as item menu, with elm_toolbar_item_menu_set().
 829     *
 830     * For more details about setting the parent for toolbar menus, see
 831     * elm_menu_parent_set().
 832     *
 833     * @see elm_menu_parent_set() for details.
 834     * @see elm_toolbar_item_menu_set() for details.
 835     *
 836     * @ingroup Toolbar
 837     */
 838    EAPI void                    elm_toolbar_menu_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
 839
 840    /**
 841     * Get the parent object of the toolbar items' menus.
 842     *
 843     * @param obj The toolbar object.
 844     * @return The parent of the menu objects.
 845     *
 846     * @see elm_toolbar_menu_parent_set() for details.
 847     *
 848     * @ingroup Toolbar
 849     */
 850    EAPI Evas_Object            *elm_toolbar_menu_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 851
 852    /**
 853     * Set the alignment of the items.
 854     *
 855     * @param obj The toolbar object.
 856     * @param align The new alignment, a float between <tt> 0.0 </tt>
 857     * and <tt> 1.0 </tt>.
 858     *
 859     * Alignment of toolbar items, from <tt> 0.0 </tt> to indicates to align
 860     * left, to <tt> 1.0 </tt>, to align to right. <tt> 0.5 </tt> centralize
 861     * items.
 862     *
 863     * Centered items by default.
 864     *
 865     * @see elm_toolbar_align_get()
 866     *
 867     * @ingroup Toolbar
 868     */
 869    EAPI void                    elm_toolbar_align_set(Evas_Object *obj, double align) EINA_ARG_NONNULL(1);
 870
 871    /**
 872     * Get the alignment of the items.
 873     *
 874     * @param obj The toolbar object.
 875     * @return toolbar items alignment, a float between <tt> 0.0 </tt> and
 876     * <tt> 1.0 </tt>.
 877     *
 878     * @see elm_toolbar_align_set() for details.
 879     *
 880     * @ingroup Toolbar
 881     */
 882    EAPI double                  elm_toolbar_align_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 883
 884    /**
 885     * Set whether the toolbar item opens a menu.
 886     *
 887     * @param it The toolbar item.
 888     * @param menu If @c EINA_TRUE, @p item will opens a menu when selected.
 889     *
 890     * A toolbar item can be set to be a menu, using this function.
 891     *
 892     * Once it is set to be a menu, it can be manipulated through the
 893     * menu-like function elm_toolbar_menu_parent_set() and the other
 894     * elm_menu functions, using the Evas_Object @c menu returned by
 895     * elm_toolbar_item_menu_get().
 896     *
 897     * So, items to be displayed in this item's menu should be added with
 898     * elm_menu_item_add().
 899     *
 900     * The following code exemplifies the most basic usage:
 901     * @code
 902     * tb = elm_toolbar_add(win)
 903     * item = elm_toolbar_item_append(tb, "refresh", "Menu", NULL, NULL);
 904     * elm_toolbar_item_menu_set(item, EINA_TRUE);
 905     * elm_toolbar_menu_parent_set(tb, win);
 906     * menu = elm_toolbar_item_menu_get(item);
 907     * elm_menu_item_add(menu, NULL, "edit-cut", "Cut", NULL, NULL);
 908     * menu_item = elm_menu_item_add(menu, NULL, "edit-copy", "Copy", NULL,
 909     * NULL);
 910     * @endcode
 911     *
 912     * @see elm_toolbar_item_menu_get()
 913     *
 914     * @ingroup Toolbar
 915     */
 916    EAPI void                    elm_toolbar_item_menu_set(Elm_Object_Item *it, Eina_Bool menu) EINA_ARG_NONNULL(1);
 917
 918    /**
 919     * Get toolbar item's menu.
 920     *
 921     * @param it The toolbar item.
 922     * @return Item's menu object or @c NULL on failure.
 923     *
 924     * If @p item wasn't set as menu item with elm_toolbar_item_menu_set(),
 925     * this function will set it.
 926     *
 927     * @see elm_toolbar_item_menu_set() for details.
 928     *
 929     * @ingroup Toolbar
 930     */
 931    EAPI Evas_Object            *elm_toolbar_item_menu_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 932
 933    /**
 934     * Add a new state to @p item.
 935     *
 936     * @param it The toolbar item.
 937     * @param icon A string with icon name or the absolute path of an image file.
 938     * @param label The label of the new state.
 939     * @param func The function to call when the item is clicked when this
 940     * state is selected.
 941     * @param data The data to associate with the state.
 942     * @return The toolbar item state, or @c NULL upon failure.
 943     *
 944     * Toolbar will load icon image from fdo or current theme.
 945     * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 946     * If an absolute path is provided it will load it direct from a file.
 947     *
 948     * States created with this function can be removed with
 949     * elm_toolbar_item_state_del().
 950     *
 951     * @see elm_toolbar_item_state_del()
 952     * @see elm_toolbar_item_state_sel()
 953     * @see elm_toolbar_item_state_get()
 954     *
 955     * @ingroup Toolbar
 956     */
 957    EAPI Elm_Toolbar_Item_State *elm_toolbar_item_state_add(Elm_Object_Item *it, const char *icon, const char *label, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 958
 959    /**
 960     * Delete a previoulsy added state to @p item.
 961     *
 962     * @param it The toolbar item.
 963     * @param state The state to be deleted.
 964     * @return @c EINA_TRUE on success or @c EINA_FALSE on failure.
 965     *
 966     * @see elm_toolbar_item_state_add()
 967     */
 968    EAPI Eina_Bool               elm_toolbar_item_state_del(Elm_Object_Item *it, Elm_Toolbar_Item_State *state) EINA_ARG_NONNULL(1);
 969
 970    /**
 971     * Set @p state as the current state of @p it.
 972     *
 973     * @param it The toolbar item.
 974     * @param state The state to use.
 975     * @return @c EINA_TRUE on success or @c EINA_FALSE on failure.
 976     *
 977     * If @p state is @c NULL, it won't select any state and the default item's
 978     * icon and label will be used. It's the same behaviour than
 979     * elm_toolbar_item_state_unser().
 980     *
 981     * @see elm_toolbar_item_state_unset()
 982     *
 983     * @ingroup Toolbar
 984     */
 985    EAPI Eina_Bool               elm_toolbar_item_state_set(Elm_Object_Item *it, Elm_Toolbar_Item_State *state) EINA_ARG_NONNULL(1);
 986
 987    /**
 988     * Unset the state of @p it.
 989     *
 990     * @param it The toolbar item.
 991     *
 992     * The default icon and label from this item will be displayed.
 993     *
 994     * @see elm_toolbar_item_state_set() for more details.
 995     *
 996     * @ingroup Toolbar
 997     */
 998    EAPI void                    elm_toolbar_item_state_unset(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 999
1000    /**
1001     * Get the current state of @p it.
1002     *
1003     * @param it The toolbar item.
1004     * @return The selected state or @c NULL if none is selected or on failure.
1005     *
1006     * @see elm_toolbar_item_state_set() for details.
1007     * @see elm_toolbar_item_state_unset()
1008     * @see elm_toolbar_item_state_add()
1009     *
1010     * @ingroup Toolbar
1011     */
1012    EAPI Elm_Toolbar_Item_State *elm_toolbar_item_state_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1013
1014    /**
1015     * Get the state after selected state in toolbar's @p item.
1016     *
1017     * @param it The toolbar item to change state.
1018     * @return The state after current state, or @c NULL on failure.
1019     *
1020     * If last state is selected, this function will return first state.
1021     *
1022     * @see elm_toolbar_item_state_set()
1023     * @see elm_toolbar_item_state_add()
1024     *
1025     * @ingroup Toolbar
1026     */
1027    EAPI Elm_Toolbar_Item_State *elm_toolbar_item_state_next(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1028
1029    /**
1030     * Get the state before selected state in toolbar's @p item.
1031     *
1032     * @param it The toolbar item to change state.
1033     * @return The state before current state, or @c NULL on failure.
1034     *
1035     * If first state is selected, this function will return last state.
1036     *
1037     * @see elm_toolbar_item_state_set()
1038     * @see elm_toolbar_item_state_add()
1039     *
1040     * @ingroup Toolbar
1041     */
1042    EAPI Elm_Toolbar_Item_State *elm_toolbar_item_state_prev(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1043
1044    /**
1045     * Set the text to be shown in a given toolbar item's tooltips.
1046     *
1047     * @param it toolbar item.
1048     * @param text The text to set in the content.
1049     *
1050     * Setup the text as tooltip to object. The item can have only one tooltip,
1051     * so any previous tooltip data - set with this function or
1052     * elm_toolbar_item_tooltip_content_cb_set() - is removed.
1053     *
1054     * @see elm_object_tooltip_text_set() for more details.
1055     *
1056     * @ingroup Toolbar
1057     */
1058    EAPI void             elm_toolbar_item_tooltip_text_set(Elm_Object_Item *it, const char *text) EINA_ARG_NONNULL(1);
1059
1060    /**
1061     * Set the content to be shown in the tooltip item.
1062     *
1063     * Setup the tooltip to item. The item can have only one tooltip,
1064     * so any previous tooltip data is removed. @p func(with @p data) will
1065     * be called every time that need show the tooltip and it should
1066     * return a valid Evas_Object. This object is then managed fully by
1067     * tooltip system and is deleted when the tooltip is gone.
1068     *
1069     * @param it the toolbar item being attached a tooltip.
1070     * @param func the function used to create the tooltip contents.
1071     * @param data what to provide to @a func as callback data/context.
1072     * @param del_cb called when data is not needed anymore, either when
1073     *        another callback replaces @a func, the tooltip is unset with
1074     *        elm_toolbar_item_tooltip_unset() or the owner @a item
1075     *        dies. This callback receives as the first parameter the
1076     *        given @a data, and @c event_info is the item.
1077     *
1078     * @see elm_object_tooltip_content_cb_set() for more details.
1079     *
1080     * @ingroup Toolbar
1081     */
1082    EAPI void             elm_toolbar_item_tooltip_content_cb_set(Elm_Object_Item *it, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb) EINA_ARG_NONNULL(1);
1083
1084    /**
1085     * Unset tooltip from item.
1086     *
1087     * @param it toolbar item to remove previously set tooltip.
1088     *
1089     * Remove tooltip from item. The callback provided as del_cb to
1090     * elm_toolbar_item_tooltip_content_cb_set() will be called to notify
1091     * it is not used anymore.
1092     *
1093     * @see elm_object_tooltip_unset() for more details.
1094     * @see elm_toolbar_item_tooltip_content_cb_set()
1095     *
1096     * @ingroup Toolbar
1097     */
1098    EAPI void             elm_toolbar_item_tooltip_unset(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1099
1100    /**
1101     * Sets a different style for this item tooltip.
1102     *
1103     * @note before you set a style you should define a tooltip with
1104     *       elm_toolbar_item_tooltip_content_cb_set() or
1105     *       elm_toolbar_item_tooltip_text_set()
1106     *
1107     * @param it toolbar item with tooltip already set.
1108     * @param style the theme style to use (default, transparent, ...)
1109     *
1110     * @see elm_object_tooltip_style_set() for more details.
1111     *
1112     * @ingroup Toolbar
1113     */
1114    EAPI void             elm_toolbar_item_tooltip_style_set(Elm_Object_Item *it, const char *style) EINA_ARG_NONNULL(1);
1115
1116    /**
1117     * Get the style for this item tooltip.
1118     *
1119     * @param it toolbar item with tooltip already set.
1120     * @return style the theme style in use, defaults to "default". If the
1121     *         object does not have a tooltip set, then NULL is returned.
1122     *
1123     * @see elm_object_tooltip_style_get() for more details.
1124     * @see elm_toolbar_item_tooltip_style_set()
1125     *
1126     * @ingroup Toolbar
1127     */
1128    EAPI const char      *elm_toolbar_item_tooltip_style_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1129
1130    /**
1131     * Set the type of mouse pointer/cursor decoration to be shown,
1132     * when the mouse pointer is over the given toolbar widget item
1133     *
1134     * @param it toolbar item to customize cursor on
1135     * @param cursor the cursor type's name
1136     *
1137     * This function works analogously as elm_object_cursor_set(), but
1138     * here the cursor's changing area is restricted to the item's
1139     * area, and not the whole widget's. Note that that item cursors
1140     * have precedence over widget cursors, so that a mouse over an
1141     * item with custom cursor set will always show @b that cursor.
1142     *
1143     * If this function is called twice for an object, a previously set
1144     * cursor will be unset on the second call.
1145     *
1146     * @see elm_object_cursor_set()
1147     * @see elm_toolbar_item_cursor_get()
1148     * @see elm_toolbar_item_cursor_unset()
1149     *
1150     * @ingroup Toolbar
1151     */
1152    EAPI void             elm_toolbar_item_cursor_set(Elm_Object_Item *it, const char *cursor) EINA_ARG_NONNULL(1);
1153
1154    /*
1155     * Get the type of mouse pointer/cursor decoration set to be shown,
1156     * when the mouse pointer is over the given toolbar widget item
1157     *
1158     * @param it toolbar item with custom cursor set
1159     * @return the cursor type's name or @c NULL, if no custom cursors
1160     * were set to @p item (and on errors)
1161     *
1162     * @see elm_object_cursor_get()
1163     * @see elm_toolbar_item_cursor_set()
1164     * @see elm_toolbar_item_cursor_unset()
1165     *
1166     * @ingroup Toolbar
1167     */
1168    EAPI const char      *elm_toolbar_item_cursor_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1169
1170    /**
1171     * Unset any custom mouse pointer/cursor decoration set to be
1172     * shown, when the mouse pointer is over the given toolbar widget
1173     * item, thus making it show the @b default cursor again.
1174     *
1175     * @param it a toolbar item
1176     *
1177     * Use this call to undo any custom settings on this item's cursor
1178     * decoration, bringing it back to defaults (no custom style set).
1179     *
1180     * @see elm_object_cursor_unset()
1181     * @see elm_toolbar_item_cursor_set()
1182     *
1183     * @ingroup Toolbar
1184     */
1185    EAPI void             elm_toolbar_item_cursor_unset(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1186
1187    /**
1188     * Set a different @b style for a given custom cursor set for a
1189     * toolbar item.
1190     *
1191     * @param it toolbar item with custom cursor set
1192     * @param style the <b>theme style</b> to use (e.g. @c "default",
1193     * @c "transparent", etc)
1194     *
1195     * This function only makes sense when one is using custom mouse
1196     * cursor decorations <b>defined in a theme file</b>, which can have,
1197     * given a cursor name/type, <b>alternate styles</b> on it. It
1198     * works analogously as elm_object_cursor_style_set(), but here
1199     * applyed only to toolbar item objects.
1200     *
1201     * @warning Before you set a cursor style you should have definen a
1202     *       custom cursor previously on the item, with
1203     *       elm_toolbar_item_cursor_set()
1204     *
1205     * @see elm_toolbar_item_cursor_engine_only_set()
1206     * @see elm_toolbar_item_cursor_style_get()
1207     *
1208     * @ingroup Toolbar
1209     */
1210    EAPI void             elm_toolbar_item_cursor_style_set(Elm_Object_Item *it, const char *style) EINA_ARG_NONNULL(1);
1211
1212    /**
1213     * Get the current @b style set for a given toolbar item's custom
1214     * cursor
1215     *
1216     * @param it toolbar item with custom cursor set.
1217     * @return style the cursor style in use. If the object does not
1218     *         have a cursor set, then @c NULL is returned.
1219     *
1220     * @see elm_toolbar_item_cursor_style_set() for more details
1221     *
1222     * @ingroup Toolbar
1223     */
1224    EAPI const char      *elm_toolbar_item_cursor_style_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1225
1226    /**
1227     * Set if the (custom)cursor for a given toolbar item should be
1228     * searched in its theme, also, or should only rely on the
1229     * rendering engine.
1230     *
1231     * @param it item with custom (custom) cursor already set on
1232     * @param engine_only Use @c EINA_TRUE to have cursors looked for
1233     * only on those provided by the rendering engine, @c EINA_FALSE to
1234     * have them searched on the widget's theme, as well.
1235     *
1236     * @note This call is of use only if you've set a custom cursor
1237     * for toolbar items, with elm_toolbar_item_cursor_set().
1238     *
1239     * @note By default, cursors will only be looked for between those
1240     * provided by the rendering engine.
1241     *
1242     * @ingroup Toolbar
1243     */
1244    EAPI void             elm_toolbar_item_cursor_engine_only_set(Elm_Object_Item *it, Eina_Bool engine_only) EINA_ARG_NONNULL(1);
1245
1246    /**
1247     * Get if the (custom) cursor for a given toolbar item is being
1248     * searched in its theme, also, or is only relying on the rendering
1249     * engine.
1250     *
1251     * @param it a toolbar item
1252     * @return @c EINA_TRUE, if cursors are being looked for only on
1253     * those provided by the rendering engine, @c EINA_FALSE if they
1254     * are being searched on the widget's theme, as well.
1255     *
1256     * @see elm_toolbar_item_cursor_engine_only_set(), for more details
1257     *
1258     * @ingroup Toolbar
1259     */
1260    EAPI Eina_Bool        elm_toolbar_item_cursor_engine_only_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1261
1262    /**
1263     * Change a toolbar's orientation
1264     * @param obj The toolbar object
1265     * @param vertical If @c EINA_TRUE, the toolbar is vertical
1266     * By default, a toolbar will be horizontal. Use this function to create a vertical toolbar.
1267     * @ingroup Toolbar
1268     * @deprecated use elm_toolbar_horizontal_set() instead.
1269     */
1270    EINA_DEPRECATED EAPI void             elm_toolbar_orientation_set(Evas_Object *obj, Eina_Bool vertical) EINA_ARG_NONNULL(1);
1271
1272    /**
1273     * Change a toolbar's orientation
1274     * @param obj The toolbar object
1275     * @param horizontal If @c EINA_TRUE, the toolbar is horizontal
1276     * By default, a toolbar will be horizontal. Use this function to create a vertical toolbar.
1277     * @ingroup Toolbar
1278     */
1279    EAPI void             elm_toolbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
1280
1281    /**
1282     * Get a toolbar's orientation
1283     * @param obj The toolbar object
1284     * @return If @c EINA_TRUE, the toolbar is vertical
1285     * By default, a toolbar will be horizontal. Use this function to determine whether a toolbar is vertical.
1286     * @ingroup Toolbar
1287     * @deprecated use elm_toolbar_horizontal_get() instead.
1288     */
1289    EINA_DEPRECATED EAPI Eina_Bool        elm_toolbar_orientation_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1290
1291    /**
1292     * Get a toolbar's orientation
1293     * @param obj The toolbar object
1294     * @return If @c EINA_TRUE, the toolbar is horizontal
1295     * By default, a toolbar will be horizontal. Use this function to determine whether a toolbar is vertical.
1296     * @ingroup Toolbar
1297     */
1298    EAPI Eina_Bool elm_toolbar_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1299
1300    /**
1301     * Get the number of items in a toolbar
1302     * @param obj The toolbar object
1303     * @return The number of items in @p obj toolbar
1304     * @ingroup Toolbar
1305     */
1306    EAPI unsigned int elm_toolbar_items_count(const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_PURE;
1307    /**
1308     * @}
1309     */
1310