Tizen Native API  5.5

toolbar_inheritance_tree.png
preview-00.png
toolbar.png

A toolbar is a widget that displays a list of items inside a box. It can be scrollable, show a menu with items that don't fit to toolbar size or even crop them.

Only one item can be selected at a time.

Items can have multiple states, or show menus when selected by the user.

This widget implements the elm-scrollable-interface interface, so that all (non-deprecated) functions for the base Scroller widget also work for toolbars (since 1.8)

Smart callbacks one can listen for:

  • "clicked" - when the user clicks on a toolbar item and becomes selected.
  • "longpressed" - when the toolbar is pressed for a certain amount of time.
  • "language,changed" - when the program language changes.
  • "focused" - When the toolbar has received focus. (since 1.8)
  • "unfocused" - When the toolbar has lost focus. (since 1.8)
  • "item,focused" - When the toolbar item has received focus. (since 1.10)
  • "item,unfocused" - When the toolbar item has lost focus. (since 1.10)
  • "selected" - when an item is selected. event_info is a selected item. (since 1.11)
  • "unselected" - when an item is unselected. event_info is a unselected item. (since 1.11)

Available styles for it:

  • "default"
  • "transparent" - no background or shadow, just show the content

Default text parts of the toolbar items that you can use for are:

  • "default" - A label of the toolbar item

Supported elm_object_item common APIs.

List of examples:

Functions

void elm_toolbar_item_state_unset (Elm_Object_Item *it)
EOAPI Elm_Widget_Item * elm_obj_toolbar_selected_item_get (const Eo *obj)
 Get the selected item in the widget.
EOAPI Elm_Widget_Item * elm_obj_toolbar_first_item_get (const Eo *obj)
 Get the first item in the widget.
EOAPI Elm_Widget_Item * elm_obj_toolbar_last_item_get (const Eo *obj)
 Get the last item in the widget.
EOAPI Eina_Iteratorelm_obj_toolbar_items_get (const Eo *obj)
 Returns a list of the widget item.
EOAPI void elm_obj_toolbar_homogeneous_set (Eo *obj, Eina_Bool homogeneous)
 Control homogeneous mode.
EOAPI Eina_Bool elm_obj_toolbar_homogeneous_get (const Eo *obj)
 Control homogeneous mode.
EOAPI void elm_obj_toolbar_align_set (Eo *obj, double align)
 Control the alignment of the items.
EOAPI double elm_obj_toolbar_align_get (const Eo *obj)
 Control the alignment of the items.
EOAPI void elm_obj_toolbar_select_mode_set (Eo *obj, Elm_Object_Select_Mode mode)
 Control the toolbar select mode.
EOAPI Elm_Object_Select_Mode elm_obj_toolbar_select_mode_get (const Eo *obj)
 Control the toolbar select mode.
EOAPI void elm_obj_toolbar_icon_size_set (Eo *obj, int icon_size)
 Control the icon size, in pixels, to be used by toolbar items.
EOAPI int elm_obj_toolbar_icon_size_get (const Eo *obj)
 Control the icon size, in pixels, to be used by toolbar items.
EOAPI void elm_obj_toolbar_shrink_mode_set (Eo *obj, Elm_Toolbar_Shrink_Mode shrink_mode)
 Control the item displaying mode of a given toolbar widget obj.
EOAPI Elm_Toolbar_Shrink_Mode elm_obj_toolbar_shrink_mode_get (const Eo *obj)
 Control the item displaying mode of a given toolbar widget obj.
EOAPI void elm_obj_toolbar_menu_parent_set (Eo *obj, Efl_Canvas_Object *parent)
 Control the parent object of the toolbar items' menus.
EOAPI Efl_Canvas_Objectelm_obj_toolbar_menu_parent_get (const Eo *obj)
 Control the parent object of the toolbar items' menus.
EOAPI void elm_obj_toolbar_standard_priority_set (Eo *obj, int priority)
 Set the standard priority of visible items in a toolbar.
EOAPI int elm_obj_toolbar_standard_priority_get (const Eo *obj)
 Set the standard priority of visible items in a toolbar.
EOAPI Elm_Widget_Item * elm_obj_toolbar_more_item_get (const Eo *obj)
 Get the more item which is auto-generated by toolbar.
EOAPI Elm_Widget_Item * elm_obj_toolbar_item_insert_before (Eo *obj, Elm_Widget_Item *before, const char *icon, const char *label, Evas_Smart_Cb func, const void *data)
 Insert a new item into the toolbar object before item before.
EOAPI Elm_Widget_Item * elm_obj_toolbar_item_insert_after (Eo *obj, Elm_Widget_Item *after, const char *icon, const char *label, Evas_Smart_Cb func, const void *data)
 Insert a new item into the toolbar object after item after.
EOAPI Elm_Widget_Item * elm_obj_toolbar_item_append (Eo *obj, const char *icon, const char *label, Evas_Smart_Cb func, const void *data)
 Append item to the toolbar.
EOAPI unsigned int elm_obj_toolbar_items_count (const Eo *obj)
 Get the number of items in a toolbar.
EOAPI Elm_Widget_Item * elm_obj_toolbar_item_prepend (Eo *obj, const char *icon, const char *label, Evas_Smart_Cb func, const void *data)
 Prepend item to the toolbar.
EOAPI Elm_Widget_Item * elm_obj_toolbar_item_find_by_label (const Eo *obj, const char *label)
 Returns a pointer to a toolbar item by its label.
Evas_Objectelm_toolbar_add (Evas_Object *parent)
void elm_toolbar_reorder_mode_set (Evas_Object *obj, Eina_Bool reorder_mode)
Eina_Bool elm_toolbar_reorder_mode_get (const Evas_Object *obj)
void elm_toolbar_transverse_expanded_set (Evas_Object *obj, Eina_Bool transverse_expanded)
Eina_Bool elm_toolbar_transverse_expanded_get (const Evas_Object *obj)
void elm_toolbar_icon_order_lookup_set (Evas_Object *obj, Elm_Icon_Lookup_Order order)
Elm_Icon_Lookup_Order elm_toolbar_icon_order_lookup_get (const Evas_Object *obj)
void elm_toolbar_horizontal_set (Evas_Object *obj, Eina_Bool horizontal)
 Change a toolbar's orientation.
Eina_Bool elm_toolbar_horizontal_get (const Evas_Object *obj)
 Get toolbar's current orientation.

Defines

#define ELM_TOOLBAR_CLASS   elm_toolbar_class_get()
#define ELM_TOOLBAR_EVENT_ITEM_FOCUSED   (&(_ELM_TOOLBAR_EVENT_ITEM_FOCUSED))
#define ELM_TOOLBAR_EVENT_ITEM_UNFOCUSED   (&(_ELM_TOOLBAR_EVENT_ITEM_UNFOCUSED))

Define Documentation

#define ELM_TOOLBAR_CLASS   elm_toolbar_class_get()

Elementary toolbar class

#define ELM_TOOLBAR_EVENT_ITEM_FOCUSED   (&(_ELM_TOOLBAR_EVENT_ITEM_FOCUSED))

Called when toolbar item got focus

Returns:
Efl_Object *
#define ELM_TOOLBAR_EVENT_ITEM_UNFOCUSED   (&(_ELM_TOOLBAR_EVENT_ITEM_UNFOCUSED))

Called when toolbar item lost focus

Returns:
Efl_Object *

Function Documentation

EOAPI double elm_obj_toolbar_align_get ( const Eo *  obj)

Control the alignment of the items.

Alignment of toolbar items, from 0.0 to indicates to align left, to 1.0, to align to right. 0.5 centralize items.

Centered items by default.

Parameters:
[in]objThe object.
Returns:
The new alignment, a float between 0.0 and 1.0.
EOAPI void elm_obj_toolbar_align_set ( Eo *  obj,
double  align 
)

Control the alignment of the items.

Alignment of toolbar items, from 0.0 to indicates to align left, to 1.0, to align to right. 0.5 centralize items.

Centered items by default.

Parameters:
[in]objThe object.
[in]alignThe new alignment, a float between 0.0 and 1.0.
EOAPI Elm_Widget_Item* elm_obj_toolbar_first_item_get ( const Eo *  obj)

Get the first item in the widget.

Parameters:
[in]objThe object.
Returns:
The first item or null.
EOAPI Eina_Bool elm_obj_toolbar_homogeneous_get ( const Eo *  obj)

Control homogeneous mode.

This will enable the homogeneous mode where items are of the same size.

Parameters:
[in]objThe object.
Returns:
Assume the items within the toolbar are of the same size (true = on, false = off). Default is false.
EOAPI void elm_obj_toolbar_homogeneous_set ( Eo *  obj,
Eina_Bool  homogeneous 
)

Control homogeneous mode.

This will enable the homogeneous mode where items are of the same size.

Parameters:
[in]objThe object.
[in]homogeneousAssume the items within the toolbar are of the same size (true = on, false = off). Default is false.
EOAPI int elm_obj_toolbar_icon_size_get ( const Eo *  obj)

Control the icon size, in pixels, to be used by toolbar items.

Note:
Default value is $32. It reads value from elm config.
Parameters:
[in]objThe object.
Returns:
The icon size in pixels
EOAPI void elm_obj_toolbar_icon_size_set ( Eo *  obj,
int  icon_size 
)

Control the icon size, in pixels, to be used by toolbar items.

Note:
Default value is $32. It reads value from elm config.
Parameters:
[in]objThe object.
[in]icon_sizeThe icon size in pixels
EOAPI Elm_Widget_Item* elm_obj_toolbar_item_append ( Eo *  obj,
const char *  icon,
const char *  label,
Evas_Smart_Cb  func,
const void *  data 
)

Append item to the toolbar.

A new item will be created and appended to the toolbar, i.e., will be set as last item.

Items created with this method can be deleted with elm_object_item_del().

Associated data can be properly freed when item is deleted if a callback function is set with elm_object_item_del_cb_set().

If a function is passed as argument, it will be called every time this item is selected, i.e., the user clicks over an unselected item. If such function isn't needed, just passing NULL as func is enough. The same should be done for data.

Toolbar will load icon image from fdo or current theme. This behavior can be set by elm_toolbar_icon_order_lookup_set() function. If an absolute path is provided it will load it direct from a file.

Note:
This function does not accept relative icon path.

See: elm_toolbar_item_icon_set()

Parameters:
[in]objThe object.
[in]iconA string with icon name or the absolute path of an image file.
[in]labelThe label of the item.
[in]funcThe function to call when the item is clicked.
[in]dataThe data to associate with the item for related callbacks.
Returns:
The created item or NULL upon failure.
EOAPI Elm_Widget_Item* elm_obj_toolbar_item_find_by_label ( const Eo *  obj,
const char *  label 
)

Returns a pointer to a toolbar item by its label.

Parameters:
[in]objThe object.
[in]labelThe label of the item to find.
Returns:
The pointer to the toolbar item matching label or NULL on failure.
EOAPI Elm_Widget_Item* elm_obj_toolbar_item_insert_after ( Eo *  obj,
Elm_Widget_Item *  after,
const char *  icon,
const char *  label,
Evas_Smart_Cb  func,
const void *  data 
)

Insert a new item into the toolbar object after item after.

A new item will be created and added to the toolbar. Its position in this toolbar will be just after item after.

Items created with this method can be deleted with elm_object_item_del().

Associated data can be properly freed when item is deleted if a callback function is set with elm_object_item_del_cb_set().

If a function is passed as argument, it will be called every time this item is selected, i.e., the user clicks over an unselected item. If such function isn't needed, just passing NULL as func is enough. The same should be done for data.

Toolbar will load icon image from fdo or current theme. This behavior can be set by elm_toolbar_icon_order_lookup_set() function. If an absolute path is provided it will load it direct from a file.

Note:
This function does not accept relative icon path.

See: elm_toolbar_item_icon_set()

Parameters:
[in]objThe object.
[in]afterThe toolbar item to insert after.
[in]iconA string with icon name or the absolute path of an image file.
[in]labelThe label of the item.
[in]funcThe function to call when the item is clicked.
[in]dataThe data to associate with the item for related callbacks.
Returns:
The created item or NULL upon failure.
EOAPI Elm_Widget_Item* elm_obj_toolbar_item_insert_before ( Eo *  obj,
Elm_Widget_Item *  before,
const char *  icon,
const char *  label,
Evas_Smart_Cb  func,
const void *  data 
)

Insert a new item into the toolbar object before item before.

A new item will be created and added to the toolbar. Its position in this toolbar will be just before item before.

Items created with this method can be deleted with elm_object_item_del().

Associated data can be properly freed when item is deleted if a callback function is set with elm_object_item_del_cb_set().

If a function is passed as argument, it will be called every time this item is selected, i.e., the user clicks over an unselected item. If such function isn't needed, just passing NULL as func is enough. The same should be done for data.

Toolbar will load icon image from fdo or current theme. This behavior can be set by elm_toolbar_icon_order_lookup_set() function. If an absolute path is provided it will load it direct from a file.

Note:
This function does not accept relative icon path.

See: elm_toolbar_item_icon_set()

Parameters:
[in]objThe object.
[in]beforeThe toolbar item to insert before.
[in]iconA string with icon name or the absolute path of an image file.
[in]labelThe label of the item.
[in]funcThe function to call when the item is clicked.
[in]dataThe data to associate with the item for related callbacks.
Returns:
The created item or NULL upon failure.
EOAPI Elm_Widget_Item* elm_obj_toolbar_item_prepend ( Eo *  obj,
const char *  icon,
const char *  label,
Evas_Smart_Cb  func,
const void *  data 
)

Prepend item to the toolbar.

A new item will be created and prepended to the toolbar, i.e., will be set as first item.

Items created with this method can be deleted with elm_object_item_del().

Associated data can be properly freed when item is deleted if a callback function is set with elm_object_item_del_cb_set().

If a function is passed as argument, it will be called every time this item is selected, i.e., the user clicks over an unselected item. If such function isn't needed, just passing NULL as func is enough. The same should be done for data.

Toolbar will load icon image from fdo or current theme. This behavior can be set by elm_toolbar_icon_order_lookup_set() function. If an absolute path is provided it will load it direct from a file.

Note:
This function does not accept relative icon path.

See: elm_toolbar_item_icon_set()

Parameters:
[in]objThe object.
[in]iconA string with icon name or the absolute path of an image file.
[in]labelThe label of the item.
[in]funcThe function to call when the item is clicked.
[in]dataThe data to associate with the item for related callbacks.
Returns:
The created item or NULL upon failure.
EOAPI unsigned int elm_obj_toolbar_items_count ( const Eo *  obj)

Get the number of items in a toolbar.

Parameters:
[in]objThe object.
Returns:
The number of items in obj toolbar
EOAPI Eina_Iterator* elm_obj_toolbar_items_get ( const Eo *  obj)

Returns a list of the widget item.

Parameters:
[in]objThe object.
Returns:
iterator to widget items
EOAPI Elm_Widget_Item* elm_obj_toolbar_last_item_get ( const Eo *  obj)

Get the last item in the widget.

Parameters:
[in]objThe object.
Returns:
The last item or null.

Control the parent object of the toolbar items' menus.

Each item can be set as item menu, with elm_toolbar_item_menu_set().

For more details about setting the parent for toolbar menus, see elm_menu_parent_set().

See: elm_menu_parent_set() for details. See: elm_toolbar_item_menu_set() for details.

Parameters:
[in]objThe object.
Returns:
The parent of the menu objects.
EOAPI void elm_obj_toolbar_menu_parent_set ( Eo *  obj,
Efl_Canvas_Object parent 
)

Control the parent object of the toolbar items' menus.

Each item can be set as item menu, with elm_toolbar_item_menu_set().

For more details about setting the parent for toolbar menus, see elm_menu_parent_set().

See: elm_menu_parent_set() for details. See: elm_toolbar_item_menu_set() for details.

Parameters:
[in]objThe object.
[in]parentThe parent of the menu objects.
EOAPI Elm_Widget_Item* elm_obj_toolbar_more_item_get ( const Eo *  obj)

Get the more item which is auto-generated by toolbar.

Toolbar generates 'more' item when there is no more space to fit items in and toolbar is in #ELM_TOOLBAR_SHRINK_MENU or #ELM_TOOLBAR_SHRINK_EXPAND mode. The more item can be manipulated by elm_object_item_text_set() and elm_object_item_content_set.

Parameters:
[in]objThe object.
Returns:
The toolbar more item.

Control the toolbar select mode.

elm_toolbar_select_mode_set() changes item select mode in the toolbar widget. - ELM_OBJECT_SELECT_MODE_DEFAULT : Items will only call their selection func and callback when first becoming selected. Any further clicks will do nothing, unless you set always select mode. - ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected, every click will make the selected callbacks be called. - ELM_OBJECT_SELECT_MODE_NONE : This will turn off the ability to select items entirely and they will neither appear selected nor call selected callback functions.

Parameters:
[in]objThe object.
Returns:
The select mode If getting mode fails, it returns ELM_OBJECT_SELECT_MODE_MAX
EOAPI void elm_obj_toolbar_select_mode_set ( Eo *  obj,
Elm_Object_Select_Mode  mode 
)

Control the toolbar select mode.

elm_toolbar_select_mode_set() changes item select mode in the toolbar widget. - ELM_OBJECT_SELECT_MODE_DEFAULT : Items will only call their selection func and callback when first becoming selected. Any further clicks will do nothing, unless you set always select mode. - ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected, every click will make the selected callbacks be called. - ELM_OBJECT_SELECT_MODE_NONE : This will turn off the ability to select items entirely and they will neither appear selected nor call selected callback functions.

Parameters:
[in]objThe object.
[in]modeThe select mode If getting mode fails, it returns ELM_OBJECT_SELECT_MODE_MAX
EOAPI Elm_Widget_Item* elm_obj_toolbar_selected_item_get ( const Eo *  obj)

Get the selected item in the widget.

Parameters:
[in]objThe object.
Returns:
The selected item or null.
EOAPI Elm_Toolbar_Shrink_Mode elm_obj_toolbar_shrink_mode_get ( const Eo *  obj)

Control the item displaying mode of a given toolbar widget obj.

The toolbar won't scroll under #ELM_TOOLBAR_SHRINK_NONE mode, but it will enforce a minimum size, so that all the items will fit inside it. It won't scroll and won't show the items that don't fit under #ELM_TOOLBAR_SHRINK_HIDE mode. Finally, it'll scroll under #ELM_TOOLBAR_SHRINK_SCROLL mode, and it will create a button to aggregate items which didn't fit with the #ELM_TOOLBAR_SHRINK_MENU mode.

If shrink mode is changed, Toolbar will send one of the following signal to each item for informing the current shrink mode. "elm,state,shrink,default" "elm,state,shrink,hide" "elm,state,shrink,scroll" "elm,state,shrink,menu" "elm,state,shrink,expand"

Warning:
This function's behavior will clash with those of elm_scroller_policy_set(), so use either one of them, but not both.
Parameters:
[in]objThe object.
Returns:
Toolbar's items display behavior
EOAPI void elm_obj_toolbar_shrink_mode_set ( Eo *  obj,
Elm_Toolbar_Shrink_Mode  shrink_mode 
)

Control the item displaying mode of a given toolbar widget obj.

The toolbar won't scroll under #ELM_TOOLBAR_SHRINK_NONE mode, but it will enforce a minimum size, so that all the items will fit inside it. It won't scroll and won't show the items that don't fit under #ELM_TOOLBAR_SHRINK_HIDE mode. Finally, it'll scroll under #ELM_TOOLBAR_SHRINK_SCROLL mode, and it will create a button to aggregate items which didn't fit with the #ELM_TOOLBAR_SHRINK_MENU mode.

If shrink mode is changed, Toolbar will send one of the following signal to each item for informing the current shrink mode. "elm,state,shrink,default" "elm,state,shrink,hide" "elm,state,shrink,scroll" "elm,state,shrink,menu" "elm,state,shrink,expand"

Warning:
This function's behavior will clash with those of elm_scroller_policy_set(), so use either one of them, but not both.
Parameters:
[in]objThe object.
[in]shrink_modeToolbar's items display behavior
EOAPI int elm_obj_toolbar_standard_priority_get ( const Eo *  obj)

Set the standard priority of visible items in a toolbar.

If the priority of the item is up to standard priority, it is shown in basic panel. The other items are located in more menu or panel. The more menu or panel can be shown when the more item is clicked.

Parameters:
[in]objThe object.
Returns:
The standard_priority of visible items
Since (EFL) :
1.7
EOAPI void elm_obj_toolbar_standard_priority_set ( Eo *  obj,
int  priority 
)

Set the standard priority of visible items in a toolbar.

If the priority of the item is up to standard priority, it is shown in basic panel. The other items are located in more menu or panel. The more menu or panel can be shown when the more item is clicked.

Parameters:
[in]objThe object.
[in]priorityThe standard_priority of visible items
Since (EFL) :
1.7

Add a new toolbar widget to the given parent Elementary (container) object.

Parameters:
parentThe parent object.
Returns:
a new toolbar widget handle or NULL, on errors.

This function inserts a new toolbar widget on the canvas.

Since :
2.3
Examples:
toolbar_example_01.c, toolbar_example_02.c, toolbar_example_03.c, and web_example_02.c.

Get toolbar's current orientation.

Use this function to get orientation of toolbar.

Returns:
If true, the toolbar is horizontal.
Since :
2.3
void elm_toolbar_horizontal_set ( Evas_Object obj,
Eina_Bool  horizontal 
)

Change a toolbar's orientation.

By default, a toolbar will be horizontal. Use this function to create a vertical toolbar.

Parameters:
[in]horizontalIf true, the toolbar is horizontal.
Since :
2.3

Gets icon lookup order, for toolbar items' icons.

Icons added before calling this function will not be affected. The default lookup order is ELM_ICON_LOOKUP_THEME_FDO.

Returns:
The icon lookup order. (If getting the icon order loopup fails, it returns ELM_ICON_LOOKUP_THEME_FDO)
Since :
2.3

Sets icon lookup order, for toolbar items' icons.

Icons added before calling this function will not be affected. The default lookup order is ELM_ICON_LOOKUP_THEME_FDO.

Parameters:
[in]orderThe icon lookup order. (If getting the icon order loopup fails, it returns ELM_ICON_LOOKUP_THEME_FDO)
Since :
2.3

Unset the state of it.

Parameters:
itThe toolbar item.

The default icon and label from this item will be displayed.

See also:
elm_toolbar_item_state_set() for more details.
Since :
2.3

Get the reorder mode

Parameters:
objThe toolbar object
Returns:
The reorder mode (EINA_TRUE = on, EINA_FALSE = off)
Since :
2.3
void elm_toolbar_reorder_mode_set ( Evas_Object obj,
Eina_Bool  reorder_mode 
)

Set reorder mode

Parameters:
objThe toolbar object
reorder_modeThe reorder mode (EINA_TRUE = on, EINA_FALSE = off)
Since :
2.3

Get the transverse expansion of toolbar obj.

Parameters:
objThe toolbar object.
Returns:
The transverse expansion of the item. (EINA_TRUE = on, EINA_FALSE = off, default = EINA_FALSE)
See also:
elm_toolbar_transverse_expand_set() for details.
Since :
2.3
void elm_toolbar_transverse_expanded_set ( Evas_Object obj,
Eina_Bool  transverse_expanded 
)

Set the item's transverse expansion of a given toolbar widget obj.

Parameters:
objThe toolbar object.
transverse_expandedThe transverse expansion of the item. (EINA_TRUE = on, EINA_FALSE = off, default = EINA_FALSE)

This will expand the transverse length of the item according the transverse length of the toolbar. The default is what the transverse length of the item is set according its min value.

Since :
2.3