An icon object is used to display standard icon images ("delete", "edit", "arrows", etc.) or images coming from a custom file (PNG, JPG, EDJE, etc.), on icon contexts.

The icon image requested can be in the Elementary theme in use, or in the freedesktop.org theme paths. It's possible to set the order of preference from where an image will be fetched.

This widget inherits from the mapping one, so that all the functions acting on it also work for icon objects.

You should be using an icon, instead of an image, whenever one of the following apply:

you need a thumbnail version of an original image
you need freedesktop.org provided icon images
you need theme provided icon images (Edje groups)

Various calls on the icon's API are marked as deprecated, as they just wrap the image counterpart functions. Use the ones we point you to, for each case of deprecation here, instead -- eventually the deprecated ones will be discarded (next major release).

Default images provided by Elementary's default theme are described below.

These are names that follow (more or less) the Freedesktop icon naming specification. Use of these names are preferred, at least if you want to give your user the ability to use other themes. All these icons can be seen in the elementary_test application, the test is called "Icon Standard".

"folder" (since 1.13)
"user-home" (since 1.13)
"user-trash" (since 1.13)

"view-close" (since 1.13)
"view-refresh" (since 1.13)

"window-close" (since 1.13)

"document-close" (since 1.13)
"document-edit" (since 1.13)

"dialog-info" (since 1.13)
"dialog-close" (since 1.13)

"go-home" (sine 1.18)
"go-up" (since 1.18)
"go-down" (since 1.18)
"go-previous" (since 1.18)
"go-next" (since 1.18)

"edit-delete" (since 1.13)
"edit-find" (since 1.13)

"application-chat" (since 1.13)
"application-clock" (since 1.13)

"media-seek-forward" (since 1.13)
"media-seek-backward" (since 1.13)
"media-skip-forward" (since 1.13)
"media-skip-backward" (since 1.13)
"media-playback-pause" (since 1.13)
"media-playback-start" (since 1.13)
"media-playback-stop" (since 1.13)
"media-eject" (since 1.13)

"audio-volume" (since 1.13)
"audio-volume-muted" (since 1.13)

There is also a selection of old names that were used before standard names were being encouraged. These should be considered deprecated and one of the names above used instead.

"arrow_up" (since 1.13)
"arrow_down" (since 1.13)
"arrow_left" (since 1.13)
"arrow_right" (since 1.13)
"search" (since 1.13)

These are names for icons that were first intended to be used in toolbars, but can be used in many other places too:

"home"
"close"
"apps"
"arrow_up"
"arrow_down"
"arrow_left"
"arrow_right"
"chat"
"clock"
"delete"
"edit"
"refresh"
"folder"
"file"

These are names for icons that were designed to be used in menus (but again, you can use them anywhere else):

"menu/home"
"menu/close"
"menu/apps"
"menu/arrow_up"
"menu/arrow_down"
"menu/arrow_left"
"menu/arrow_right"
"menu/chat"
"menu/clock"
"menu/delete"
"menu/edit"
"menu/refresh"
"menu/folder"
"menu/file"

And these are names for some media player specific icons:

"media_player/forward"
"media_player/info"
"media_player/next"
"media_player/pause"
"media_player/play"
"media_player/prev"
"media_player/rewind"
"media_player/stop"

This widget emits the following signals, besides the ones sent from Image:

"thumb,done" - elm_icon_thumb_set() has completed with success (since 1.7)
"thumb,error" - elm_icon_thumb_set() has failed (since 1.7)

Elementary icon objects support the following API calls:

elm_object_signal_emit()
elm_object_signal_callback_add()
elm_object_signal_callback_del() for emitting and listening to signals on the object, when the internal image comes from an Edje object. This behavior was added unintentionally, though, and is deprecated. Expect it to be dropped on future releases.

An example of usage for this API follows:

Icon example

Functions
Evas_Object *	elm_icon_add (Evas_Object *parent)
void	elm_icon_thumb_set (Evas_Object obj, const char file, const char *group)
	Set the file that will be used, but use a generated thumbnail.
void	elm_icon_order_lookup_set (Evas_Object *obj, Elm_Icon_Lookup_Order order)
	Sets the icon lookup order used by elm_icon_standard_set().
Elm_Icon_Lookup_Order	elm_icon_order_lookup_get (const Evas_Object *obj)
	Get the icon lookup order.
Eina_Bool	elm_icon_standard_set (Evas_Object obj, const char name)
	Set the icon by icon standards names.
const char *	elm_icon_standard_get (const Evas_Object *obj)
	Get the icon name set by icon standard names.

Enumeration Type Documentation

enum Elm_Icon_Lookup_Order

Lookup order used by elm_icon_standard_set(). Should look for icons in the theme, FDO paths, or both?

Deprecated:: Prefer using elm_config "icon_theme" instead.

Enumerator:

ELM_ICON_LOOKUP_THEME_FDO	Icon look up order: freedesktop, theme.
ELM_ICON_LOOKUP_FDO	Icon look up order: theme, freedesktop.
ELM_ICON_LOOKUP_THEME	Icon look up order: freedesktop. Icon look up order: theme.

enum Elm_Icon_Type

Elementary icon types

Enumerator:

ELM_ICON_NONE	Icon has no type set
ELM_ICON_FILE	Icon is of type file
ELM_ICON_STANDARD	Icon is of type standard

Function Documentation

Evas_Object* elm_icon_add ( Evas_Object * parent )

Add a new icon object to the parent.

Parameters:

parent The parent object

Returns:: The new object or NULL if it cannot be created

See also:: elm_image_file_set()

Since :: 2.3

Examples:: button_example_01.c, ctxpopup_example_01.c, diskselector_example_02.c, fileselector_button_example.c, fileselector_entry_example.c, genlist_example_01.c, genlist_example_02.c, genlist_example_03.c, genlist_example_04.c, genlist_example_05.c, icon_example_01.c, layout_example_01.c, layout_example_02.c, list_example_03.c, map_example_02.c, mapbuf_example.c, popup_example_02.c, popup_example_03.c, progressbar_example.c, radio_example_01.c, segment_control_example.c, slider_example.c, transit_example_03.c, transit_example_04.c, web_example_02.c, and win_example.c.

Elm_Icon_Lookup_Order elm_icon_order_lookup_get ( const Evas_Object * obj )

Get the icon lookup order.

Since :: 2.3 See also elm_icon_order_lookup_set, Elm_Icon_Lookup_Order.

Returns:: The icon lookup order (can be one of ELM_ICON_LOOKUP_FDO_THEME, ELM_ICON_LOOKUP_THEME_FDO, ELM_ICON_LOOKUP_FDO or ELM_ICON_LOOKUP_THEME)

Since :: 2.3

void elm_icon_order_lookup_set	(	Evas_Object *	obj,
		Elm_Icon_Lookup_Order	order
	)

Sets the icon lookup order used by elm_icon_standard_set().

Parameters:

[in] order The icon lookup order (can be one of ELM_ICON_LOOKUP_FDO_THEME, ELM_ICON_LOOKUP_THEME_FDO, ELM_ICON_LOOKUP_FDO or ELM_ICON_LOOKUP_THEME)

Since :: 2.3

const char* elm_icon_standard_get ( const Evas_Object * obj )

Get the icon name set by icon standard names.

If the icon image was set using elm_image_file_set() instead of elm_icon_standard_set, then this function will return null.

Returns:: The icon name

Since :: 2.3

Examples:: icon_example_01.c.

Eina_Bool elm_icon_standard_set	(	Evas_Object *	obj,
		const char *	name
	)

Set the icon by icon standards names.

Since :: 2.3 For example, freedesktop.org defines standard icon names such as "go-home", "network-wired", etc. There can be different icon sets to match those icon keys. The "name" given as parameter is one of these "keys", and will be used to look in the freedesktop.org paths and elementary theme.

If name is not found in any of the expected locations and it is the absolute path of an image file, this image will be used.

Note:: The icon image set by this function can be changed by Efl::File::file::set.; This function does not accept relative icon path.

void elm_icon_thumb_set	(	Evas_Object *	obj,
		const char *	file,
		const char *	group
	)

[in]	file	The path to file that will be used as icon image
[in]	group	The group that the icon belongs to an edje file

Functions

Enumeration Type Documentation

Function Documentation