wearable/src/lib/elm_toolbar.h

   1 /**
   2  * @defgroup Toolbar Toolbar
   3  * @ingroup Elementary
   4  *
   5  * @image html toolbar_inheritance_tree.png
   6  * @image latex toolbar_inheritance_tree.eps
   7  *
   8  * @image html img/widget/toolbar/preview-00.png
   9  * @image latex img/widget/toolbar/preview-00.eps width=\textwidth
  10  *
  11  * @image html img/toolbar.png
  12  * @image latex img/toolbar.eps width=\textwidth
  13  *
  14  * A toolbar is a widget that displays a list of items inside
  15  * a box. It can be scrollable, show a menu with items that don't fit
  16  * to toolbar size or even crop them.
  17  *
  18  * Only one item can be selected at a time.
  19  *
  20  * Items can have multiple states, or show menus when selected by the user.
  21  *
  22  * This widget implements the @b @ref elm-scrollable-interface
  23  * interface, so that all (non-deprecated) functions for the base
  24  * @ref Scroller widget also work for toolbars (@since 1.8)
  25  *
  26  * Smart callbacks one can listen to:
  27  * - @c "clicked" - when the user clicks on a toolbar item and becomes
  28  *                  selected.
  29  * - @c "longpressed" - when the toolbar is pressed for a certain
  30  *                      amount of time.
  31  * - @c "language,changed" - when the program language changes.
  32  *
  33  * Available styles for it:
  34  * - @c "default"
  35  * - @c "transparent" - no background or shadow, just show the content
  36  *
  37  * Default text parts of the toolbar items that you can use for are:
  38  * @li "default" - label of the toolbar item
  39  *
  40  * Supported elm_object_item common APIs.
  41  * @li @ref elm_object_item_disabled_set
  42  * @li @ref elm_object_item_disabled_get
  43  * @li @ref elm_object_item_part_text_set
  44  * @li @ref elm_object_item_part_text_get
  45  *
  46  * List of examples:
  47  * @li @ref toolbar_example_01
  48  * @li @ref toolbar_example_02
  49  * @li @ref toolbar_example_03
  50  */
  51
  52 /**
  53  * @addtogroup Toolbar
  54  * @{
  55  */
  56
  57 /**
  58  * @enum Elm_Toolbar_Shrink_Mode
  59  * @typedef Elm_Toolbar_Shrink_Mode
  60  *
  61  * Set toolbar's items display behavior, it can be scrollable,
  62  * show a menu with exceeding items, or simply hide them.
  63  *
  64  * @note Default value is #ELM_TOOLBAR_SHRINK_MENU. It reads value
  65  * from elm config.
  66  *
  67  * Values <b> don't </b> work as bitmask, only one can be chosen.
  68  *
  69  * @see elm_toolbar_shrink_mode_set()
  70  * @see elm_toolbar_shrink_mode_get()
  71  *
  72  * @ingroup Toolbar
  73  */
  74 typedef enum
  75 {
  76    ELM_TOOLBAR_SHRINK_NONE, /**< Set toolbar minimum size to fit all the items. */
  77    ELM_TOOLBAR_SHRINK_HIDE, /**< Hide exceeding items. */
  78    ELM_TOOLBAR_SHRINK_SCROLL, /**< Allow accessing exceeding items through a scroller. */
  79    ELM_TOOLBAR_SHRINK_MENU, /**< Inserts a button to pop up a menu with exceeding items. */
  80    ELM_TOOLBAR_SHRINK_EXPAND, /**< Expand all items according the size of the toolbar. */
  81    ELM_TOOLBAR_SHRINK_LAST /**< Indicates error if returned by elm_toolbar_shrink_mode_get() */
  82 } Elm_Toolbar_Shrink_Mode;
  83
  84 /**
  85  * Defines where to position the item in the toolbar.
  86  *
  87  * @ingroup Toolbar
  88  */
  89 typedef enum
  90 {
  91    ELM_TOOLBAR_ITEM_SCROLLTO_NONE = 0,   /**< no scrollto */
  92    ELM_TOOLBAR_ITEM_SCROLLTO_IN = (1 << 0),   /**< to the nearest viewport */
  93    ELM_TOOLBAR_ITEM_SCROLLTO_FIRST = (1 << 1),   /**< to the first of viewport */
  94    ELM_TOOLBAR_ITEM_SCROLLTO_MIDDLE = (1 << 2),   /**< to the middle of viewport */
  95    ELM_TOOLBAR_ITEM_SCROLLTO_LAST = (1 << 3)   /**< to the last of viewport */
  96 } Elm_Toolbar_Item_Scrollto_Type;
  97
  98 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(). */
  99
 100 /**
 101  * Add a new toolbar widget to the given parent Elementary
 102  * (container) object.
 103  *
 104  * @param parent The parent object.
 105  * @return a new toolbar widget handle or @c NULL, on errors.
 106  *
 107  * This function inserts a new toolbar widget on the canvas.
 108  *
 109  * @ingroup Toolbar
 110  */
 111 EAPI Evas_Object                 *elm_toolbar_add(Evas_Object *parent);
 112
 113 /**
 114  * Set the icon size, in pixels, to be used by toolbar items.
 115  *
 116  * @param obj The toolbar object
 117  * @param icon_size The icon size in pixels
 118  *
 119  * @note Default value is @c 32. It reads value from elm config.
 120  *
 121  * @see elm_toolbar_icon_size_get()
 122  *
 123  * @ingroup Toolbar
 124  */
 125 EAPI void                         elm_toolbar_icon_size_set(Evas_Object *obj, int icon_size);
 126
 127 /**
 128  * Get the icon size, in pixels, to be used by toolbar items.
 129  *
 130  * @param obj The toolbar object.
 131  * @return The icon size in pixels.
 132  *
 133  * @see elm_toolbar_icon_size_set() for details.
 134  *
 135  * @ingroup Toolbar
 136  */
 137 EAPI int                          elm_toolbar_icon_size_get(const Evas_Object *obj);
 138
 139 /**
 140  * Sets icon lookup order, for toolbar items' icons.
 141  *
 142  * @param obj The toolbar object.
 143  * @param order The icon lookup order.
 144  *
 145  * Icons added before calling this function will not be affected.
 146  * The default lookup order is #ELM_ICON_LOOKUP_THEME_FDO.
 147  *
 148  * @see elm_toolbar_icon_order_lookup_get()
 149  *
 150  * @ingroup Toolbar
 151  */
 152 EAPI void                         elm_toolbar_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order);
 153
 154 /**
 155  * Gets the icon lookup order.
 156  *
 157  * @param obj The toolbar object.
 158  * @return The icon lookup order.
 159  *
 160  * @see elm_toolbar_icon_order_lookup_set() for details.
 161  *
 162  * @ingroup Toolbar
 163  */
 164 EAPI Elm_Icon_Lookup_Order        elm_toolbar_icon_order_lookup_get(const Evas_Object *obj);
 165
 166 /**
 167  * Append item to the toolbar.
 168  *
 169  * @param obj The toolbar object.
 170  * @param icon A string with icon name or the absolute path of an image file.
 171  * @param label The label of the item.
 172  * @param func The function to call when the item is clicked.
 173  * @param data The data to associate with the item for related callbacks.
 174  * @return The created item or @c NULL upon failure.
 175  *
 176  * A new item will be created and appended to the toolbar, i.e., will
 177  * be set as @b last item.
 178  *
 179  * Items created with this method can be deleted with
 180  * elm_object_item_del().
 181  *
 182  * Associated @p data can be properly freed when item is deleted if a
 183  * callback function is set with elm_object_item_del_cb_set().
 184  *
 185  * If a function is passed as argument, it will be called every time this item
 186  * is selected, i.e., the user clicks over an unselected item.
 187  * If such function isn't needed, just passing
 188  * @c NULL as @p func is enough. The same should be done for @p data.
 189  *
 190  * Toolbar will load icon image from fdo or current theme.
 191  * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 192  * If an absolute path is provided it will load it direct from a file.
 193  *
 194  * @see elm_toolbar_item_icon_set()
 195  * @see elm_object_item_del()
 196  *
 197  * @ingroup Toolbar
 198  */
 199 EAPI Elm_Object_Item             *elm_toolbar_item_append(Evas_Object *obj, const char *icon, const char *label, Evas_Smart_Cb func, const void *data);
 200
 201 /**
 202  * Prepend item to the toolbar.
 203  *
 204  * @param obj The toolbar object.
 205  * @param icon A string with icon name or the absolute path of an image file.
 206  * @param label The label of the item.
 207  * @param func The function to call when the item is clicked.
 208  * @param data The data to associate with the item for related callbacks.
 209  * @return The created item or @c NULL upon failure.
 210  *
 211  * A new item will be created and prepended to the toolbar, i.e., will
 212  * be set as @b first item.
 213  *
 214  * Items created with this method can be deleted with
 215  * elm_object_item_del().
 216  *
 217  * Associated @p data can be properly freed when item is deleted if a
 218  * callback function is set with elm_object_item_del_cb_set().
 219  *
 220  * If a function is passed as argument, it will be called every time this item
 221  * is selected, i.e., the user clicks over an unselected item.
 222  * If such function isn't needed, just passing
 223  * @c NULL as @p func is enough. The same should be done for @p data.
 224  *
 225  * Toolbar will load icon image from fdo or current theme.
 226  * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 227  * If an absolute path is provided it will load it direct from a file.
 228  *
 229  * @see elm_toolbar_item_icon_set()
 230  * @see elm_object_item_del()
 231  *
 232  * @ingroup Toolbar
 233  */
 234 EAPI Elm_Object_Item             *elm_toolbar_item_prepend(Evas_Object *obj, const char *icon, const char *label, Evas_Smart_Cb func, const void *data);
 235
 236 /**
 237  * Insert a new item into the toolbar object before item @p before.
 238  *
 239  * @param obj The toolbar object.
 240  * @param before The toolbar item to insert before.
 241  * @param icon A string with icon name or the absolute path of an image file.
 242  * @param label The label of the item.
 243  * @param func The function to call when the item is clicked.
 244  * @param data The data to associate with the item for related callbacks.
 245  * @return The created item or @c NULL upon failure.
 246  *
 247  * A new item will be created and added to the toolbar. Its position in
 248  * this toolbar will be just before item @p before.
 249  *
 250  * Items created with this method can be deleted with
 251  * elm_object_item_del().
 252  *
 253  * Associated @p data can be properly freed when item is deleted if a
 254  * callback function is set with elm_object_item_del_cb_set().
 255  *
 256  * If a function is passed as argument, it will be called every time this item
 257  * is selected, i.e., the user clicks over an unselected item.
 258  * If such function isn't needed, just passing
 259  * @c NULL as @p func is enough. The same should be done for @p data.
 260  *
 261  * Toolbar will load icon image from fdo or current theme.
 262  * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 263  * If an absolute path is provided it will load it direct from a file.
 264  *
 265  * @see elm_toolbar_item_icon_set()
 266  * @see elm_object_item_del()
 267  *
 268  * @ingroup Toolbar
 269  */
 270 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);
 271
 272 /**
 273  * Insert a new item into the toolbar object after item @p after.
 274  *
 275  * @param obj The toolbar object.
 276  * @param after The toolbar item to insert after.
 277  * @param icon A string with icon name or the absolute path of an image file.
 278  * @param label The label of the item.
 279  * @param func The function to call when the item is clicked.
 280  * @param data The data to associate with the item for related callbacks.
 281  * @return The created item or @c NULL upon failure.
 282  *
 283  * A new item will be created and added to the toolbar. Its position in
 284  * this toolbar will be just after item @p after.
 285  *
 286  * Items created with this method can be deleted with
 287  * elm_object_item_del().
 288  *
 289  * Associated @p data can be properly freed when item is deleted if a
 290  * callback function is set with elm_object_item_del_cb_set().
 291  *
 292  * If a function is passed as argument, it will be called every time this item
 293  * is selected, i.e., the user clicks over an unselected item.
 294  * If such function isn't needed, just passing
 295  * @c NULL as @p func is enough. The same should be done for @p data.
 296  *
 297  * Toolbar will load icon image from fdo or current theme.
 298  * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 299  * If an absolute path is provided it will load it direct from a file.
 300  *
 301  * @see elm_toolbar_item_icon_set()
 302  * @see elm_object_item_del()
 303  *
 304  * @ingroup Toolbar
 305  */
 306 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);
 307
 308 /**
 309  * Get the first item in the given toolbar widget's list of
 310  * items.
 311  *
 312  * @param obj The toolbar object
 313  * @return The first item or @c NULL, if it has no items (and on
 314  * errors)
 315  *
 316  * @see elm_toolbar_item_append()
 317  * @see elm_toolbar_last_item_get()
 318  *
 319  * @ingroup Toolbar
 320  */
 321 EAPI Elm_Object_Item             *elm_toolbar_first_item_get(const Evas_Object *obj);
 322
 323 /**
 324  * Get the last item in the given toolbar widget's list of
 325  * items.
 326  *
 327  * @param obj The toolbar object
 328  * @return The last item or @c NULL, if it has no items (and on
 329  * errors)
 330  *
 331  * @see elm_toolbar_item_prepend()
 332  * @see elm_toolbar_first_item_get()
 333  *
 334  * @ingroup Toolbar
 335  */
 336 EAPI Elm_Object_Item             *elm_toolbar_last_item_get(const Evas_Object *obj);
 337
 338 /**
 339  * Get the item after @p item in toolbar.
 340  *
 341  * @param it The toolbar item.
 342  * @return The item after @p item, or @c NULL if none or on failure.
 343  *
 344  * @note If it is the last item, @c NULL will be returned.
 345  *
 346  * @see elm_toolbar_item_append()
 347  *
 348  * @ingroup Toolbar
 349  */
 350 EAPI Elm_Object_Item             *elm_toolbar_item_next_get(const Elm_Object_Item *it);
 351
 352 /**
 353  * Get the item before @p item in toolbar.
 354  *
 355  * @param it The toolbar item.
 356  * @return The item before @p item, or @c NULL if none or on failure.
 357  *
 358  * @note If it is the first item, @c NULL will be returned.
 359  *
 360  * @see elm_toolbar_item_prepend()
 361  *
 362  * @ingroup Toolbar
 363  */
 364 EAPI Elm_Object_Item             *elm_toolbar_item_prev_get(const Elm_Object_Item *it);
 365
 366 /**
 367  * Set the priority of a toolbar item.
 368  *
 369  * @param it The toolbar item.
 370  * @param priority The item priority. The default is zero.
 371  *
 372  * This is used only when the toolbar shrink mode is set
 373  * to #ELM_TOOLBAR_SHRINK_MENU or #ELM_TOOLBAR_SHRINK_HIDE.
 374  * When space is less than required, items with low priority
 375  * will be removed from the toolbar and added to a dynamically-created menu,
 376  * while items with higher priority will remain on the toolbar,
 377  * with the same order they were added.
 378  *
 379  * @see elm_toolbar_item_priority_get()
 380  *
 381  * @ingroup Toolbar
 382  */
 383 EAPI void                         elm_toolbar_item_priority_set(Elm_Object_Item *it, int priority);
 384
 385 /**
 386  * Get the priority of a toolbar item.
 387  *
 388  * @param it The toolbar item.
 389  * @return The @p item priority, or @c 0 on failure.
 390  *
 391  * @see elm_toolbar_item_priority_set() for details.
 392  *
 393  * @ingroup Toolbar
 394  */
 395 EAPI int                          elm_toolbar_item_priority_get(const Elm_Object_Item *it);
 396
 397 /**
 398  * Returns a pointer to a toolbar item by its label.
 399  *
 400  * @param obj The toolbar object.
 401  * @param label The label of the item to find.
 402  *
 403  * @return The pointer to the toolbar item matching @p label or @c NULL
 404  * on failure.
 405  *
 406  * @ingroup Toolbar
 407  */
 408 EAPI Elm_Object_Item             *elm_toolbar_item_find_by_label(const Evas_Object *obj, const char *label);
 409
 410 /**
 411  * Get whether the @p item is selected or not.
 412  *
 413  * @param it The toolbar item.
 414  * @return @c EINA_TRUE means item is selected. @c EINA_FALSE indicates
 415  * it's not. If @p obj is @c NULL, @c EINA_FALSE is returned.
 416  *
 417  * @see elm_toolbar_selected_item_set() for details.
 418  * @see elm_toolbar_item_selected_get()
 419  *
 420  * @ingroup Toolbar
 421  */
 422 EAPI Eina_Bool                    elm_toolbar_item_selected_get(const Elm_Object_Item *it);
 423
 424 /**
 425  * Set the selected state of an item.
 426  *
 427  * @param it The toolbar item
 428  * @param selected The selected state
 429  *
 430  * This sets the selected state of the given item @p it.
 431  * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
 432  *
 433  * If a new item is selected the previously selected will be unselected.
 434  * Previously selected item can be get with function
 435  * elm_toolbar_selected_item_get().
 436  *
 437  * Selected items will be highlighted.
 438  *
 439  * @see elm_toolbar_item_selected_get()
 440  * @see elm_toolbar_selected_item_get()
 441  *
 442  * @ingroup Toolbar
 443  */
 444 EAPI void                         elm_toolbar_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 445
 446 /**
 447  * Get the selected item.
 448  *
 449  * @param obj The toolbar object.
 450  * @return The selected toolbar item.
 451  *
 452  * The selected item can be unselected with function
 453  * elm_toolbar_item_selected_set().
 454  *
 455  * The selected item always will be highlighted on toolbar.
 456  *
 457  * @see elm_toolbar_selected_items_get()
 458  *
 459  * @ingroup Toolbar
 460  */
 461 EAPI Elm_Object_Item             *elm_toolbar_selected_item_get(const Evas_Object *obj);
 462
 463 /**
 464  * Get the more item.
 465  *
 466  * @param obj The toolbar object.
 467  * @return The toolbar more item.
 468  *
 469  * The more item can be changed with function
 470  * elm_object_item_text_set() and elm_object_item_content_set.
 471  *
 472  * @ingroup Toolbar
 473  */
 474 EAPI Elm_Object_Item             *elm_toolbar_more_item_get(const Evas_Object *obj);
 475
 476 /**
 477  * Set the icon associated with @p item.
 478  *
 479  * @param it The toolbar item.
 480  * @param icon A string with icon name or the absolute path of an image file.
 481  *
 482  * Toolbar will load icon image from fdo or current theme.
 483  * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 484  * If an absolute path is provided it will load it direct from a file.
 485  *
 486  * @see elm_toolbar_icon_order_lookup_set()
 487  * @see elm_toolbar_icon_order_lookup_get()
 488  *
 489  * @ingroup Toolbar
 490  */
 491 EAPI void                         elm_toolbar_item_icon_set(Elm_Object_Item *it, const char *icon);
 492
 493 /**
 494  * Get the string used to set the icon of @p item.
 495  *
 496  * @param it The toolbar item.
 497  * @return The string associated with the icon object.
 498  *
 499  * @see elm_toolbar_item_icon_set() for details.
 500  *
 501  * @ingroup Toolbar
 502  */
 503 EAPI const char                  *elm_toolbar_item_icon_get(const Elm_Object_Item *it);
 504
 505 /**
 506  * Get the object of @p item.
 507  *
 508  * @param it The toolbar item.
 509  * @return The object
 510  *
 511  * @ingroup Toolbar
 512  */
 513 EAPI Evas_Object                 *elm_toolbar_item_object_get(const Elm_Object_Item *it);
 514
 515 /**
 516  * Get the icon object of @p item.
 517  *
 518  * @param it The toolbar item.
 519  * @return The icon object
 520  *
 521  * @see elm_toolbar_item_icon_set(), elm_toolbar_item_icon_file_set(),
 522  * or elm_toolbar_item_icon_memfile_set() for details.
 523  *
 524  * @ingroup Toolbar
 525  */
 526 EAPI Evas_Object                 *elm_toolbar_item_icon_object_get(Elm_Object_Item *it);
 527
 528 /**
 529  * Set the icon associated with @p item to an image in a binary buffer.
 530  *
 531  * @param it The toolbar item.
 532  * @param img The binary data that will be used as an image
 533  * @param size The size of binary data @p img
 534  * @param format Optional format of @p img to pass to the image loader
 535  * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
 536  *
 537  * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
 538  *
 539  * @note The icon image set by this function can be changed by
 540  * elm_toolbar_item_icon_set().
 541  *
 542  * @ingroup Toolbar
 543  */
 544 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);
 545
 546 /**
 547  * Set the icon associated with @p item to an image in a binary buffer.
 548  *
 549  * @param it The toolbar item.
 550  * @param file The file that contains the image
 551  * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
 552  *
 553  * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
 554  *
 555  * @note The icon image set by this function can be changed by
 556  * elm_toolbar_item_icon_set().
 557  *
 558  * @ingroup Toolbar
 559  */
 560 EAPI Eina_Bool                    elm_toolbar_item_icon_file_set(Elm_Object_Item *it, const char *file, const char *key);
 561
 562 /**
 563  * Set or unset item as a separator.
 564  *
 565  * @param it The toolbar item.
 566  * @param separator @c EINA_TRUE to set item @p item as separator or
 567  * @c EINA_FALSE to unset, i.e., item will be used as a regular item.
 568  *
 569  * Items aren't set as separator by default.
 570  *
 571  * If set as separator it will display separator theme, so won't display
 572  * icons or label.
 573  *
 574  * @see elm_toolbar_item_separator_get()
 575  *
 576  * @ingroup Toolbar
 577  */
 578 EAPI void                         elm_toolbar_item_separator_set(Elm_Object_Item *it, Eina_Bool separator);
 579
 580 /**
 581  * Get a value whether item is a separator or not.
 582  *
 583  * @param it The toolbar item.
 584  * @return @c EINA_TRUE means item @p it is a separator. @c EINA_FALSE
 585  * indicates it's not. If @p it is @c NULL, @c EINA_FALSE is returned.
 586  *
 587  * @see elm_toolbar_item_separator_set() for details.
 588  *
 589  * @ingroup Toolbar
 590  */
 591 EAPI Eina_Bool                    elm_toolbar_item_separator_get(const Elm_Object_Item *it);
 592
 593 /**
 594  * Set the item displaying mode of a given toolbar widget @p obj.
 595  *
 596  * @param obj The toolbar object handle
 597  * @param shrink_mode Toolbar's items display behavior
 598  *
 599  * The toolbar won't scroll under #ELM_TOOLBAR_SHRINK_NONE mode, but
 600  * it will enforce a minimum size, so that all the items will fit
 601  * inside it. It won't scroll and won't show the items that don't fit
 602  * under #ELM_TOOLBAR_SHRINK_HIDE mode. Finally, it'll scroll under
 603  * #ELM_TOOLBAR_SHRINK_SCROLL mode, and it will create a button to
 604  * aggregate items which didn't fit with the #ELM_TOOLBAR_SHRINK_MENU
 605  * mode.
 606  *
 607  * @warning This function's behavior will clash with those of
 608  * elm_scroller_policy_set(), so use either one of them, but not both.
 609  *
 610  * @ingroup Toolbar
 611  */
 612 EAPI void                         elm_toolbar_shrink_mode_set(Evas_Object *obj, Elm_Toolbar_Shrink_Mode shrink_mode);
 613
 614 /**
 615  * Get the shrink mode of toolbar @p obj.
 616  *
 617  * @param obj The toolbar object.
 618  * @return Toolbar's items display behavior.
 619  *
 620  * @see elm_toolbar_shrink_mode_set() for details.
 621  *
 622  * @ingroup Toolbar
 623  */
 624 EAPI Elm_Toolbar_Shrink_Mode      elm_toolbar_shrink_mode_get(const Evas_Object *obj);
 625
 626 /**
 627  * Set the item's transverse expansion of a given toolbar widget @p obj.
 628  *
 629  * @param obj The toolbar object.
 630  * @param transverse_expanded The transverse expansion of the item.
 631  * (EINA_TRUE = on, EINA_FALSE = off, default = EINA_FALSE)
 632  *
 633  * This will expand the transverse length of the item according the transverse length of the toolbar.
 634  * The default is what the transverse length of the item is set according its min value.
 635  *
 636  * @ingroup Toolbar
 637  */
 638 EAPI void                         elm_toolbar_transverse_expanded_set(Evas_Object *obj, Eina_Bool transverse_expanded);
 639
 640 /**
 641  * Get the transverse expansion of toolbar @p obj.
 642  *
 643  * @param obj The toolbar object.
 644  * @return The transverse expansion of the item.
 645  * (EINA_TRUE = on, EINA_FALSE = off, default = EINA_FALSE)
 646  *
 647  * @see elm_toolbar_transverse_expand_set() for details.
 648  *
 649  * @ingroup Toolbar
 650  */
 651 EAPI Eina_Bool                    elm_toolbar_transverse_expanded_get(const Evas_Object *obj);
 652
 653 /**
 654  * Enable/disable homogeneous mode.
 655  *
 656  * @param obj The toolbar object
 657  * @param homogeneous Assume the items within the toolbar are of the
 658  * same size (EINA_TRUE = on, EINA_FALSE = off). Default is @c EINA_FALSE.
 659  *
 660  * This will enable the homogeneous mode where items are of the same size.
 661  * @see elm_toolbar_homogeneous_get()
 662  *
 663  * @ingroup Toolbar
 664  */
 665 EAPI void                         elm_toolbar_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous);
 666
 667 /**
 668  * Get whether the homogeneous mode is enabled.
 669  *
 670  * @param obj The toolbar object.
 671  * @return Assume the items within the toolbar are of the same height
 672  * and width (EINA_TRUE = on, EINA_FALSE = off).
 673  *
 674  * @see elm_toolbar_homogeneous_set()
 675  *
 676  * @ingroup Toolbar
 677  */
 678 EAPI Eina_Bool                    elm_toolbar_homogeneous_get(const Evas_Object *obj);
 679
 680 /**
 681  * Set the parent object of the toolbar items' menus.
 682  *
 683  * @param obj The toolbar object.
 684  * @param parent The parent of the menu objects.
 685  *
 686  * Each item can be set as item menu, with elm_toolbar_item_menu_set().
 687  *
 688  * For more details about setting the parent for toolbar menus, see
 689  * elm_menu_parent_set().
 690  *
 691  * @see elm_menu_parent_set() for details.
 692  * @see elm_toolbar_item_menu_set() for details.
 693  *
 694  * @ingroup Toolbar
 695  */
 696 EAPI void                         elm_toolbar_menu_parent_set(Evas_Object *obj, Evas_Object *parent);
 697
 698 /**
 699  * Get the parent object of the toolbar items' menus.
 700  *
 701  * @param obj The toolbar object.
 702  * @return The parent of the menu objects.
 703  *
 704  * @see elm_toolbar_menu_parent_set() for details.
 705  *
 706  * @ingroup Toolbar
 707  */
 708 EAPI Evas_Object                 *elm_toolbar_menu_parent_get(const Evas_Object *obj);
 709
 710 /**
 711  * Set the alignment of the items.
 712  *
 713  * @param obj The toolbar object.
 714  * @param align The new alignment, a float between <tt> 0.0 </tt>
 715  * and <tt> 1.0 </tt>.
 716  *
 717  * Alignment of toolbar items, from <tt> 0.0 </tt> to indicates to align
 718  * left, to <tt> 1.0 </tt>, to align to right. <tt> 0.5 </tt> centralize
 719  * items.
 720  *
 721  * Centered items by default.
 722  *
 723  * @see elm_toolbar_align_get()
 724  *
 725  * @ingroup Toolbar
 726  */
 727 EAPI void                         elm_toolbar_align_set(Evas_Object *obj, double align);
 728
 729 /**
 730  * Get the alignment of the items.
 731  *
 732  * @param obj The toolbar object.
 733  * @return toolbar items alignment, a float between <tt> 0.0 </tt> and
 734  * <tt> 1.0 </tt>.
 735  *
 736  * @see elm_toolbar_align_set() for details.
 737  *
 738  * @ingroup Toolbar
 739  */
 740 EAPI double                       elm_toolbar_align_get(const Evas_Object *obj);
 741
 742 /**
 743  * Set whether the toolbar item opens a menu.
 744  *
 745  * @param it The toolbar item.
 746  * @param menu If @c EINA_TRUE, @p item will opens a menu when selected.
 747  *
 748  * A toolbar item can be set to be a menu, using this function.
 749  *
 750  * Once it is set to be a menu, it can be manipulated through the
 751  * menu-like function elm_toolbar_menu_parent_set() and the other
 752  * elm_menu functions, using the Evas_Object @c menu returned by
 753  * elm_toolbar_item_menu_get().
 754  *
 755  * So, items to be displayed in this item's menu should be added with
 756  * elm_menu_item_add().
 757  *
 758  * The following code exemplifies the most basic usage:
 759  * @code
 760  * tb = elm_toolbar_add(win)
 761  * item = elm_toolbar_item_append(tb, "refresh", "Menu", NULL, NULL);
 762  * elm_toolbar_item_menu_set(item, EINA_TRUE);
 763  * elm_toolbar_menu_parent_set(tb, win);
 764  * menu = elm_toolbar_item_menu_get(item);
 765  * elm_menu_item_add(menu, NULL, "edit-cut", "Cut", NULL, NULL);
 766  * menu_item = elm_menu_item_add(menu, NULL, "edit-copy", "Copy", NULL,
 767  * NULL);
 768  * @endcode
 769  *
 770  * @see elm_toolbar_item_menu_get()
 771  *
 772  * @ingroup Toolbar
 773  */
 774 EAPI void                         elm_toolbar_item_menu_set(Elm_Object_Item *it, Eina_Bool menu);
 775
 776 /**
 777  * Get toolbar item's menu.
 778  *
 779  * @param it The toolbar item.
 780  * @return Item's menu object or @c NULL on failure.
 781  *
 782  * If @p item wasn't set as menu item with elm_toolbar_item_menu_set(),
 783  * this function will set it.
 784  *
 785  * @see elm_toolbar_item_menu_set() for details.
 786  *
 787  * @ingroup Toolbar
 788  */
 789 EAPI Evas_Object                 *elm_toolbar_item_menu_get(const Elm_Object_Item *it);
 790
 791 /**
 792  * Add a new state to @p item.
 793  *
 794  * @param it The toolbar item.
 795  * @param icon A string with icon name or the absolute path of an image file.
 796  * @param label The label of the new state.
 797  * @param func The function to call when the item is clicked when this
 798  * state is selected.
 799  * @param data The data to associate with the state.
 800  * @return The toolbar item state, or @c NULL upon failure.
 801  *
 802  * Toolbar will load icon image from fdo or current theme.
 803  * This behavior can be set by elm_toolbar_icon_order_lookup_set() function.
 804  * If an absolute path is provided it will load it direct from a file.
 805  *
 806  * States created with this function can be removed with
 807  * elm_toolbar_item_state_del().
 808  *
 809  * @see elm_toolbar_item_state_del()
 810  * @see elm_toolbar_item_state_sel()
 811  * @see elm_toolbar_item_state_get()
 812  *
 813  * @ingroup Toolbar
 814  */
 815 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);
 816
 817 /**
 818  * Delete a previously added state to @p item.
 819  *
 820  * @param it The toolbar item.
 821  * @param state The state to be deleted.
 822  * @return @c EINA_TRUE on success or @c EINA_FALSE on failure.
 823  *
 824  * @see elm_toolbar_item_state_add()
 825  */
 826 EAPI Eina_Bool                    elm_toolbar_item_state_del(Elm_Object_Item *it, Elm_Toolbar_Item_State *state);
 827
 828 /**
 829  * Set @p state as the current state of @p it.
 830  *
 831  * @param it The toolbar item.
 832  * @param state The state to use.
 833  * @return @c EINA_TRUE on success or @c EINA_FALSE on failure.
 834  *
 835  * If @p state is @c NULL, it won't select any state and the default item's
 836  * icon and label will be used. It's the same behaviour than
 837  * elm_toolbar_item_state_unset().
 838  *
 839  * @see elm_toolbar_item_state_unset()
 840  *
 841  * @ingroup Toolbar
 842  */
 843 EAPI Eina_Bool                    elm_toolbar_item_state_set(Elm_Object_Item *it, Elm_Toolbar_Item_State *state);
 844
 845 /**
 846  * Unset the state of @p it.
 847  *
 848  * @param it The toolbar item.
 849  *
 850  * The default icon and label from this item will be displayed.
 851  *
 852  * @see elm_toolbar_item_state_set() for more details.
 853  *
 854  * @ingroup Toolbar
 855  */
 856 EAPI void                         elm_toolbar_item_state_unset(Elm_Object_Item *it);
 857
 858 /**
 859  * Get the current state of @p it.
 860  *
 861  * @param it The toolbar item.
 862  * @return The selected state or @c NULL if none is selected or on failure.
 863  *
 864  * @see elm_toolbar_item_state_set() for details.
 865  * @see elm_toolbar_item_state_unset()
 866  * @see elm_toolbar_item_state_add()
 867  *
 868  * @ingroup Toolbar
 869  */
 870 EAPI Elm_Toolbar_Item_State      *elm_toolbar_item_state_get(const Elm_Object_Item *it);
 871
 872 /**
 873  * Get the state after selected state in toolbar's @p item.
 874  *
 875  * @param it The toolbar item to change state.
 876  * @return The state after current state, or @c NULL on failure.
 877  *
 878  * If last state is selected, this function will return first state.
 879  *
 880  * @see elm_toolbar_item_state_set()
 881  * @see elm_toolbar_item_state_add()
 882  *
 883  * @ingroup Toolbar
 884  */
 885 EAPI Elm_Toolbar_Item_State      *elm_toolbar_item_state_next(Elm_Object_Item *it);
 886
 887 /**
 888  * Get the state before selected state in toolbar's @p item.
 889  *
 890  * @param it The toolbar item to change state.
 891  * @return The state before current state, or @c NULL on failure.
 892  *
 893  * If first state is selected, this function will return last state.
 894  *
 895  * @see elm_toolbar_item_state_set()
 896  * @see elm_toolbar_item_state_add()
 897  *
 898  * @ingroup Toolbar
 899  */
 900 EAPI Elm_Toolbar_Item_State      *elm_toolbar_item_state_prev(Elm_Object_Item *it);
 901
 902 /**
 903  * Change a toolbar's orientation
 904  * @param obj The toolbar object
 905  * @param horizontal If @c EINA_TRUE, the toolbar is horizontal
 906  * By default, a toolbar will be horizontal. Use this function to create a vertical toolbar.
 907  * @ingroup Toolbar
 908  */
 909 EAPI void                         elm_toolbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 910
 911 /**
 912  * Get a toolbar's orientation
 913  * @param obj The toolbar object
 914  * @return If @c EINA_TRUE, the toolbar is horizontal
 915  * By default, a toolbar will be horizontal. Use this function to determine whether a toolbar is vertical.
 916  * @ingroup Toolbar
 917  */
 918 EAPI Eina_Bool                    elm_toolbar_horizontal_get(const Evas_Object *obj);
 919
 920 /**
 921  * Get the number of items in a toolbar
 922  * @param obj The toolbar object
 923  * @return The number of items in @p obj toolbar
 924  * @ingroup Toolbar
 925  */
 926 EAPI unsigned int                 elm_toolbar_items_count(const Evas_Object *obj);
 927
 928 /**
 929  * Set the standard priority of visible items in a toolbar
 930  * @param obj The toolbar object
 931  * @param priority The standard_priority of visible items
 932  *
 933  * If the priority of the item is up to standard priority, it is shown in basic panel.
 934  * The other items are located in more menu or panel. The more menu or panel can be shown when the more item is clicked.
 935  *
 936  * @see elm_toolbar_standard_priority_get()
 937  *
 938  * @since 1.7
 939  * @ingroup Toolbar
 940  */
 941 EAPI void                         elm_toolbar_standard_priority_set(Evas_Object *obj, int priority);
 942
 943 /**
 944  * Get the standard_priority of visible items in a toolbar
 945  * @param obj The toolbar object
 946  * @return The standard priority of items in @p obj toolbar
 947  *
 948  * @see elm_toolbar_standard_priority_set()
 949  *
 950  * @since 1.7
 951  * @ingroup Toolbar
 952  */
 953 EAPI int                          elm_toolbar_standard_priority_get(const Evas_Object *obj);
 954
 955 /**
 956  * Set the toolbar select mode.
 957  *
 958  * @param obj The toolbar object
 959  * @param mode The select mode
 960  *
 961  * elm_toolbar_select_mode_set() changes item select mode in the toolbar widget.
 962  * - ELM_OBJECT_SELECT_MODE_DEFAULT : Items will only call their selection func and
 963  *      callback when first becoming selected. Any further clicks will
 964  *      do nothing, unless you set always select mode.
 965  * - ELM_OBJECT_SELECT_MODE_ALWAYS :  This means that, even if selected,
 966  *      every click will make the selected callbacks be called.
 967  * - ELM_OBJECT_SELECT_MODE_NONE : This will turn off the ability to select items
 968  *      entirely and they will neither appear selected nor call selected
 969  *      callback functions.
 970  *
 971  * @see elm_toolbar_select_mode_get()
 972  *
 973  * @ingroup Toolbar
 974  */
 975 EAPI void
 976 elm_toolbar_select_mode_set(Evas_Object *obj, Elm_Object_Select_Mode mode);
 977
 978 /**
 979  * Get the toolbar select mode.
 980  *
 981  * @param obj The toolbar object
 982  * @return The select mode
 983  * (If getting mode is failed, it returns ELM_OBJECT_SELECT_MODE_MAX)
 984  *
 985  * @see elm_toolbar_select_mode_set()
 986  *
 987  * @ingroup Toolbar
 988  */
 989 EAPI Elm_Object_Select_Mode
 990 elm_toolbar_select_mode_get(const Evas_Object *obj);
 991
 992 /**
 993  * Set reorder mode
 994  *
 995  * @param obj The toolbar object
 996  * @param reorder_mode The reorder mode
 997  * (EINA_TRUE = on, EINA_FALSE = off)
 998  *
 999  * @ingroup Toolbar
1000  */
1001 EAPI void                          elm_toolbar_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode);
1002
1003 /**
1004  * Get the reorder mode
1005  *
1006  * @param obj The toolbar object
1007  * @return The reorder mode
1008  * (EINA_TRUE = on, EINA_FALSE = off)
1009  *
1010  * @ingroup Toolbar
1011  */
1012 EAPI Eina_Bool                     elm_toolbar_reorder_mode_get(const Evas_Object *obj);
1013
1014 /**
1015  * Show a specific item, when the toolbar can be scrolled.
1016  *
1017  * @param it the toolbar item
1018  *
1019  * see elm_toolbar_item_bring_in()
1020  *
1021  * since 1.8
1022  * @ingroup Toolbar
1023  */
1024 EAPI void                          elm_toolbar_item_show(Elm_Object_Item *it, Elm_Toolbar_Item_Scrollto_Type type);
1025
1026 /**
1027  * Show a specific item with scroll animation, when the toolbar can be scrolled.
1028  *
1029  * @param it the toolbar item
1030  *
1031  * see elm_toolbar_item_show()
1032  *
1033  * since 1.8
1034  * @ingroup Toolbar
1035  */
1036 EAPI void                          elm_toolbar_item_bring_in(Elm_Object_Item *it, Elm_Toolbar_Item_Scrollto_Type type);
1037
1038 /**
1039  * @}
1040  */