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 context.

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 is 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 mentioned for each case of deprecation here. Eventually, the deprecated ones are discarded (next major release).

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

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):

"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 mapping :

"thumb,done" - elm_icon_thumb_set() has completed with success (
Since (EFL) :
1.7)
"thumb,error" - elm_icon_thumb_set() has failed (
Since (EFL) :
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 is added unintentionally, though, and is deprecated. Expect it to be dropped on future releases.

Functions
Evas_Object *	elm_icon_add (Evas_Object *parent)
	Adds a new icon object to the parent.
void	elm_icon_thumb_set (Evas_Object obj, const char file, const char *group)
	Sets the file that is used, but uses a generated thumbnail.
Eina_Bool	elm_icon_standard_set (Evas_Object obj, const char name)
	Sets the icon by icon standard names.
const char *	elm_icon_standard_get (const Evas_Object *obj)
	Gets the icon name set by icon standard names.
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)
	Gets the icon lookup order.

Enumeration Type Documentation

enum Elm_Icon_Lookup_Order

Enumeration that defines the lookup order used by elm_icon_standard_set(). Should look for icons in the theme, FDO paths, or both.

Enumerator:

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

Function Documentation

Evas_Object* elm_icon_add ( Evas_Object * parent )

Adds a new icon object to the parent.

Since :: 2.3.1

Parameters:

[in] parent The parent object

Returns:: The new object, otherwise NULL if it cannot be created

See also:: elm_image_file_set()

Elm_Icon_Lookup_Order elm_icon_order_lookup_get ( const Evas_Object * obj )

Gets the icon lookup order.

Since :: 2.3.1

Parameters:

[in] obj The icon object

Returns:: The icon lookup order

See also:: elm_icon_order_lookup_set(); Elm_Icon_Lookup_Order

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().

Since :: 2.3.1

Parameters:

[in]	obj	The icon object
[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)

See also:: elm_icon_order_lookup_get(); Elm_Icon_Lookup_Order

const char* elm_icon_standard_get ( const Evas_Object * obj )

Gets the icon name set by icon standard names.

Since :: 2.3.1

Remarks:: If the icon image is set using elm_image_file_set() instead of elm_icon_standard_set(), then this function returns NULL.

Parameters:

[in] obj The icon object

Returns:: The icon name

See also:: elm_icon_standard_set()

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

Sets the icon by icon standard names.

Since :: 2.3.1

Remarks:: For example, freedesktop.org defines the standard icon names such as "home", "network", etc. There can be different icon sets to match those icon keys. The name given as a parameter is one of these "keys", and is used to look in the freedesktop.org paths and elementary theme. One can change the lookup order with elm_icon_order_lookup_set().; If name is not found in any of the expected locations and it is the absolute path of an image file, this image is used.; The icon image set by this function can be changed by elm_image_file_set().

Parameters:

[in]	obj	The icon object
[in]	name	The icon name

Returns:: (EINA_TRUE = success, EINA_FALSE = error)

See also:: elm_icon_standard_get(); elm_image_file_set()

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

Sets the file that is used, but uses a generated thumbnail.

Since :: 2.3.1

Remarks:: This function is like elm_image_file_set(). When set, the file indicated has a thumbnail generated and cached on disk for future use or directly uses an existing cached thumbnail if it is valid.

Parameters:

[in]	obj	The icon object
[in]	file	The path to the file that is used as an icon image
[in]	group	The group that the icon belongs to

See also:: elm_image_file_set()

Functions

Enumeration Type Documentation

Function Documentation