Tizen Native API  6.5

icon_inheritance_tree.png

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:

Elementary icon objects support the following API calls:

An example of usage for this API follows:

Functions

const char * elm_config_icon_theme_get (void)
void elm_config_icon_theme_set (const char *theme)
EINA_DEPRECATED Eina_Bool elm_icon_file_set (Evas_Object *obj, const char *file, const char *group)
EINA_DEPRECATED Eina_Bool elm_icon_memfile_set (Evas_Object *obj, const void *img, size_t size, const char *format, const char *key)
EINA_DEPRECATED void elm_icon_file_get (const Evas_Object *obj, const char **file, const char **group)
EINA_DEPRECATED void elm_icon_smooth_set (Evas_Object *obj, Eina_Bool smooth)
EINA_DEPRECATED Eina_Bool elm_icon_smooth_get (const Evas_Object *obj)
EINA_DEPRECATED void elm_icon_no_scale_set (Evas_Object *obj, Eina_Bool no_scale)
EINA_DEPRECATED Eina_Bool elm_icon_no_scale_get (const Evas_Object *obj)
EINA_DEPRECATED void elm_icon_resizable_set (Evas_Object *obj, Eina_Bool size_up, Eina_Bool size_down)
EINA_DEPRECATED void elm_icon_resizable_get (const Evas_Object *obj, Eina_Bool *size_up, Eina_Bool *size_down)
EINA_DEPRECATED void elm_icon_size_get (const Evas_Object *obj, int *w, int *h)
EINA_DEPRECATED void elm_icon_fill_outside_set (Evas_Object *obj, Eina_Bool fill_outside)
EINA_DEPRECATED Eina_Bool elm_icon_fill_outside_get (const Evas_Object *obj)
EINA_DEPRECATED void elm_icon_prescale_set (Evas_Object *obj, int size)
EINA_DEPRECATED int elm_icon_prescale_get (const Evas_Object *obj)
EINA_DEPRECATED Evas_Objectelm_icon_object_get (Evas_Object *obj)
EINA_DEPRECATED void elm_icon_preload_disabled_set (Evas_Object *obj, Eina_Bool disabled)
EINA_DEPRECATED Eina_Bool elm_icon_animated_available_get (const Evas_Object *obj)
EINA_DEPRECATED void elm_icon_animated_set (Evas_Object *obj, Eina_Bool animated)
EINA_DEPRECATED Eina_Bool elm_icon_animated_get (const Evas_Object *obj)
EINA_DEPRECATED void elm_icon_animated_play_set (Evas_Object *obj, Eina_Bool play)
EINA_DEPRECATED Eina_Bool elm_icon_animated_play_get (const Evas_Object *obj)
EINA_DEPRECATED void elm_icon_aspect_fixed_set (Evas_Object *obj, Eina_Bool fixed)
EINA_DEPRECATED Eina_Bool elm_icon_aspect_fixed_get (const Evas_Object *obj)
Evas_Objectelm_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

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.

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

const char* elm_config_icon_theme_get ( void  )

Get the icon theme the user has set.

This gets the global icon theme currently set or the default value #ELM_CONFIG_ICON_THEME_ELEMENTARY.

Returns:
the icon theme to use
Since (EFL) :
1.18
void elm_config_icon_theme_set ( const char *  theme)

Set the icon theme for all elementary apps.

This method will set the icon theme for all elm_icon_standard_set calls. Valid parameters are the name of an installed freedesktop.org icon theme or #ELM_CONFIG_ICON_THEME_ELEMENTARY for the built in theme.

Parameters:
themethe name of a freedesktop.org icon theme or #ELM_CONFIG_ICON_THEME_ELEMENTARY
Since (EFL) :
1.18

Get if the icon supports animation or not.

Parameters:
objThe icon object
Returns:
EINA_TRUE if the icon supports animation, EINA_FALSE otherwise.

Return if this elm icon's image can be animated. Currently Evas only supports gif animation. If the return value is EINA_FALSE, other elm_icon_animated_xxx APIs won't work.

Deprecated:
Use elm_image_animated_available_get() instead.

Get animation mode of the icon.

Parameters:
objThe icon object
Returns:
The animation mode of the icon object
See also:
elm_icon_animated_set
Deprecated:
Use elm_image_animated_get() instead.

Get animation play mode of the icon.

Parameters:
objThe icon object
Returns:
The play mode of the icon object
See also:
elm_icon_animated_play_get
Deprecated:
Use elm_image_animated_play_get() instead.

Set animation play mode of the icon.

Parameters:
objThe icon object
playEINA_TRUE the object play animation images, EINA_FALSE otherwise. Default is EINA_FALSE.

To play elm icon's animation, set play to EINA_TRUE. For example, you make gif player using this set/get API and click event. This literally lets you control current play or paused state. To have this work with animated GIF files for example, you first, before setting the file have to use elm_icon_animated_set() to enable animation at all on the icon.

1. Click event occurs 2. Check play flag using elm_icon_animated_play_get 3. If elm icon was playing, set play to EINA_FALSE. Then animation will be stopped and vice versa

Deprecated:
Use elm_image_animated_play_set() instead.

Set animation mode of the icon.

Parameters:
objThe icon object
animatedEINA_TRUE if the object do animation job, EINA_FALSE otherwise. Default is EINA_FALSE.

Since the default animation mode is set to EINA_FALSE, the icon is shown without animation. Files like animated GIF files can animate, and this is supported if you enable animated support on the icon. Set it to EINA_TRUE when the icon needs to be animated.

Deprecated:
Use elm_image_animated_set() instead.

Get if the object retains the original aspect ratio.

Parameters:
objThe icon object.
Returns:
EINA_TRUE if the object keeps the original aspect, EINA_FALSE otherwise.
Deprecated:
Use elm_image_aspect_fixed_get() instead.

Set whether the original aspect ratio of the icon should be kept on resize.

Parameters:
objThe icon object.
fixedEINA_TRUE if the icon should retain the aspect, EINA_FALSE otherwise.

The original aspect ratio (width / height) of the icon is usually distorted to match the object's size. Enabling this option will retain this original aspect, and the way that the icon is fit into the object's area depends on the option set by elm_icon_fill_outside_set().

See also:
elm_icon_aspect_fixed_get()
elm_icon_fill_outside_set()
Deprecated:
Use elm_image_aspect_fixed_set() instead.
EINA_DEPRECATED void elm_icon_file_get ( const Evas_Object obj,
const char **  file,
const char **  group 
)

Get the file that will be used as icon.

Parameters:
objThe icon object
fileThe path to file that will be used as the icon image
groupThe group that the icon belongs to, in edje file
See also:
elm_image_file_set()
Deprecated:
Use elm_image_file_get() instead.
EINA_DEPRECATED Eina_Bool elm_icon_file_set ( Evas_Object obj,
const char *  file,
const char *  group 
)

Set the file that will be used as icon.

Parameters:
objThe icon object
fileThe path to file that will be used as icon image
groupThe group that the icon belongs to an edje file
Returns:
(EINA_TRUE = success, EINA_FALSE = error)
Note:
The icon image set by this function can be changed by elm_icon_standard_set().
See also:
elm_icon_file_get()
Deprecated:
Use elm_image_file_set() instead.

Get if the object is filled outside.

Parameters:
objThe icon object
Returns:
EINA_TRUE if the object is filled outside, EINA_FALSE otherwise.
See also:
elm_icon_fill_outside_set()
Deprecated:
Use elm_image_fill_outside_get() instead.
EINA_DEPRECATED void elm_icon_fill_outside_set ( Evas_Object obj,
Eina_Bool  fill_outside 
)

Set if the icon fill the entire object area.

Parameters:
objThe icon object
fill_outsideEINA_TRUE if the object is filled outside, EINA_FALSE otherwise. Default is EINA_FALSE.

When the icon object is resized to a different aspect ratio from the original icon image, the icon image will still keep its aspect. This flag tells how the image should fill the object's area. They are: keep the entire icon inside the limits of height and width of the object (fill_outside is EINA_FALSE) or let the extra width or height go outside of the object, and the icon will fill the entire object (fill_outside is EINA_TRUE).

Note:
Unlike mapping, there's no option in icon to set the aspect ratio retain property to false. Thus, the icon image will always keep its original aspect ratio.
See also:
elm_icon_fill_outside_get()
Deprecated:
Use elm_image_fill_outside_set() instead.
EINA_DEPRECATED Eina_Bool elm_icon_memfile_set ( Evas_Object obj,
const void *  img,
size_t  size,
const char *  format,
const char *  key 
)

Set a location in memory to be used as an icon

Parameters:
objThe icon object
imgThe binary data that will be used as an image
sizeThe size of binary data img
formatOptional format of img to pass to the image loader
keyOptional key of img to pass to the image loader (eg. if img is an edje file)

The format string should be something like "png", "jpg", "tga", "tiff", "bmp" etc. if it is provided (NULL if not). This improves the loader performance as it tries the "correct" loader first before trying a range of other possible loaders until one succeeds.

Returns:
(EINA_TRUE = success, EINA_FALSE = error)
Note:
The icon image set by this function can be changed by elm_icon_standard_set().
Deprecated:
Use elm_image_memfile_set() instead.

Get whether scaling is disabled on the object.

Parameters:
objThe icon object
Returns:
EINA_TRUE if scaling is disabled, EINA_FALSE otherwise
See also:
elm_icon_no_scale_set()
Deprecated:
Use elm_image_no_scale_get() instead.

Disable scaling of this object.

Parameters:
objThe icon object.
no_scaleEINA_TRUE if the object is not scalable, EINA_FALSE otherwise. Default is EINA_FALSE.

This function disables scaling of the icon object through the function elm_object_scale_set(). However, this does not affect the object size/resize in any way. For that effect, take a look at elm_icon_resizable_set().

See also:
elm_icon_no_scale_get()
elm_icon_resizable_set()
elm_object_scale_set()
Deprecated:
Use elm_image_no_scale_set() instead.

Get the image object of the icon. DO NOT MODIFY THIS.

Parameters:
objThe icon object
Returns:
The internal icon object
Deprecated:
Use elm_image_object_get() instead.

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

Sets the icon lookup order used by elm_icon_standard_set().

See also elm_icon_order_lookup_get, Elm_Icon_Lookup_Order.

Parameters:
[in]orderThe 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

Enable or disable preloading of the icon

Parameters:
objThe icon object
disabledIf EINA_TRUE, preloading will be disabled
Deprecated:
Use elm_image_preload_disabled_set() instead.

Get the prescale size for the icon.

Parameters:
objThe icon object
Returns:
The prescale size
See also:
elm_icon_prescale_set()
Deprecated:
Use elm_image_prescale_get() instead.
EINA_DEPRECATED void elm_icon_prescale_set ( Evas_Object obj,
int  size 
)

Set the prescale size for the icon.

Parameters:
objThe icon object
sizeThe prescale size. This value is used for both width and height.

This function sets a new size for pixmap representation of the given icon. It allows the icon to be loaded already in the specified size, reducing the memory usage and load time when loading a big icon with load size set to a smaller size.

It's equivalent to the elm_bg_load_size_set() function for bg.

Note:
this is just a hint, the real size of the pixmap may differ depending on the type of icon being loaded, being bigger than requested.
See also:
elm_icon_prescale_get()
elm_bg_load_size_set()
Deprecated:
Use elm_image_prescale_set() instead.
EINA_DEPRECATED void elm_icon_resizable_get ( const Evas_Object obj,
Eina_Bool size_up,
Eina_Bool size_down 
)

Get if the object is (up/down) resizable.

Parameters:
objThe icon object
size_upA bool to set if the object is resizable up
size_downA bool to set if the object is resizable down
See also:
elm_icon_resizable_set()
Deprecated:
Use elm_image_resizable_get() instead.
EINA_DEPRECATED void elm_icon_resizable_set ( Evas_Object obj,
Eina_Bool  size_up,
Eina_Bool  size_down 
)

Set if the object is (up/down) resizable.

Parameters:
objThe icon object
size_upA bool to set if the object is resizable up. Default is EINA_TRUE.
size_downA bool to set if the object is resizable down. Default is EINA_TRUE.

This function limits the icon object resize ability. If size_up is set to EINA_FALSE, the object can't have its height or width resized to a value higher than the original icon size. Same is valid for size_down.

See also:
elm_icon_resizable_get()
Deprecated:
Use elm_image_resizable_set() instead.
EINA_DEPRECATED void elm_icon_size_get ( const Evas_Object obj,
int *  w,
int *  h 
)

Get the object's image size

Parameters:
objThe icon object
wA pointer to store the width in
hA pointer to store the height in
Deprecated:
Use elm_image_object_size_get() instead.

Get whether smooth scaling is enabled for an icon object.

Parameters:
objThe icon object
Returns:
EINA_TRUE if smooth scaling is enabled, EINA_FALSE otherwise.
See also:
elm_icon_smooth_set()
Deprecated:
Use elm_image_smooth_get() instead.

Set the smooth scaling for an icon object.

Parameters:
objThe icon object
smoothEINA_TRUE if smooth scaling should be used, EINA_FALSE otherwise. Default is EINA_TRUE.

Set the scaling algorithm to be used when scaling the icon image. Smooth scaling provides a better resulting image, but is slower.

The smooth scaling should be disabled when making animations that change the icon size, since they will be faster. Animations that don't require resizing of the icon can keep the smooth scaling enabled (even if the icon is already scaled, since the scaled icon image will be cached).

See also:
elm_icon_smooth_get()
Deprecated:
Use elm_image_smooth_set() instead.
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.

See also elm_icon_standard_get.

Parameters:
[in]nameThe icon name
Returns:
true on success, false on error
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, mapbuf_example.c, radio_example_01.c, segment_control_example.c, slider_example.c, and web_example_02.c.
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.

This functions like elm_image_file_set() but requires the Ethumb library support to be enabled successfully with elm_need_ethumb. When set the file indicated has a thumbnail generated and cached on disk for future use or will directly use an existing cached thumbnail if it is valid.

Parameters:
[in]fileThe path to file that will be used as icon image
[in]groupThe group that the icon belongs to an edje file
Since :
2.3