5 * @image html icon_inheritance_tree.png
6 * @image latex icon_inheritance_tree.eps
8 * @image html img/widget/icon/preview-00.png
9 * @image latex img/widget/icon/preview-00.eps
11 * An icon object is used to display standard icon images ("delete",
12 * "edit", "arrows", etc.) or images coming from a custom file (PNG,
13 * JPG, EDJE, etc.), on icon contexts.
15 * The icon image requested can be in the Elementary theme in use, or
16 * in the @c freedesktop.org theme paths. It's possible to set the
17 * order of preference from where an image will be fetched.
19 * This widget inherits from the @ref Image one, so that all the
20 * functions acting on it also work for icon objects.
22 * You should be using an icon, instead of an image, whenever one of
23 * the following apply:
24 * - you need a @b thumbnail version of an original image
25 * - you need freedesktop.org provided icon images
26 * - you need theme provided icon images (Edje groups)
28 * Various calls on the icon's API are marked as @b deprecated, as
29 * they just wrap the image counterpart functions. Use the ones we
30 * point you to, for each case of deprecation here, instead --
31 * eventually the deprecated ones will be discarded (next major
34 * Default images provided by Elementary's default theme are described
37 * These are names for icons that were first intended to be used in
38 * toolbars, but can be used in many other places too:
45 * @li @c "arrow_right"
54 * These are names for icons that were designed to be used in menus
55 * (but again, you can use them anywhere else):
59 * @li @c "menu/arrow_up"
60 * @li @c "menu/arrow_down"
61 * @li @c "menu/arrow_left"
62 * @li @c "menu/arrow_right"
65 * @li @c "menu/delete"
67 * @li @c "menu/refresh"
68 * @li @c "menu/folder"
71 * And these are names for some media player specific icons:
72 * @li @c "media_player/forward"
73 * @li @c "media_player/info"
74 * @li @c "media_player/next"
75 * @li @c "media_player/pause"
76 * @li @c "media_player/play"
77 * @li @c "media_player/prev"
78 * @li @c "media_player/rewind"
79 * @li @c "media_player/stop"
81 * This widget emits the following signals, besides the ones sent from
83 * - @c "thumb,done" - elm_icon_thumb_set() has completed with success
85 * - @c "thumb,error" - elm_icon_thumb_set() has failed (@since 1.7)
87 * Elementary icon objects support the following API calls:
88 * @li elm_object_signal_emit()
89 * @li elm_object_signal_callback_add()
90 * @li elm_object_signal_callback_del()
91 * for emmiting and listening to signals on the object, when the
92 * internal image comes from an Edje object. This behavior was added
93 * unintentionally, though, and is @b deprecated. Expect it to be
94 * dropped on future releases.
96 * An example of usage for this API follows:
97 * @li @ref tutorial_icon
113 * @enum Elm_Icon_Lookup_Order
114 * @typedef Elm_Icon_Lookup_Order
116 * Lookup order used by elm_icon_standard_set(). Should look for icons in the
117 * theme, FDO paths, or both?
123 ELM_ICON_LOOKUP_FDO_THEME, /**< icon look up order: freedesktop, theme */
124 ELM_ICON_LOOKUP_THEME_FDO, /**< icon look up order: theme, freedesktop */
125 ELM_ICON_LOOKUP_FDO, /**< icon look up order: freedesktop */
126 ELM_ICON_LOOKUP_THEME /**< icon look up order: theme */
127 } Elm_Icon_Lookup_Order;
130 * Add a new icon object to the parent.
132 * @param parent The parent object
133 * @return The new object or NULL if it cannot be created
135 * @see elm_image_file_set()
139 EAPI Evas_Object *elm_icon_add(Evas_Object *parent);
142 * Set the file that will be used as icon.
144 * @param obj The icon object
145 * @param file The path to file that will be used as icon image
146 * @param group The group that the icon belongs to an edje file
148 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
150 * @note The icon image set by this function can be changed by
151 * elm_icon_standard_set().
153 * @see elm_icon_file_get()
155 * @deprecated Use elm_image_file_set() instead.
159 EINA_DEPRECATED EAPI Eina_Bool elm_icon_file_set(Evas_Object *obj, const char *file, const char *group);
162 * Set a location in memory to be used as an icon
164 * @param obj The icon object
165 * @param img The binary data that will be used as an image
166 * @param size The size of binary data @p img
167 * @param format Optional format of @p img to pass to the image loader
168 * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
170 * The @p format string should be something like "png", "jpg", "tga",
171 * "tiff", "bmp" etc. if it is provided (NULL if not). This improves
172 * the loader performance as it tries the "correct" loader first before
173 * trying a range of other possible loaders until one succeeds.
175 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
177 * @note The icon image set by this function can be changed by
178 * elm_icon_standard_set().
180 * @deprecated Use elm_image_memfile_set() instead.
184 EINA_DEPRECATED EAPI Eina_Bool elm_icon_memfile_set(Evas_Object *obj, const void *img, size_t size, const char *format, const char *key);
187 * Get the file that will be used as icon.
189 * @param obj The icon object
190 * @param file The path to file that will be used as the icon image
191 * @param group The group that the icon belongs to, in edje file
193 * @see elm_image_file_set()
195 * @deprecated Use elm_image_file_get() instead.
199 EINA_DEPRECATED EAPI void elm_icon_file_get(const Evas_Object *obj, const char **file, const char **group);
202 * Set the file that will be used, but use a generated thumbnail.
204 * @param obj The icon object
205 * @param file The path to file that will be used as icon image
206 * @param group The group that the icon belongs to an edje file
208 * This functions like elm_image_file_set() but requires the Ethumb library
209 * support to be enabled successfully with elm_need_ethumb(). When set
210 * the file indicated has a thumbnail generated and cached on disk for
211 * future use or will directly use an existing cached thumbnail if it
214 * @see elm_image_file_set()
218 EAPI void elm_icon_thumb_set(Evas_Object *obj, const char *file, const char *group);
221 * Set the icon by icon standards names.
223 * @param obj The icon object
224 * @param name The icon name
226 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
228 * For example, freedesktop.org defines standard icon names such as "home",
229 * "network", etc. There can be different icon sets to match those icon
230 * keys. The @p name given as parameter is one of these "keys", and will be
231 * used to look in the freedesktop.org paths and elementary theme. One can
232 * change the lookup order with elm_icon_order_lookup_set().
234 * If name is not found in any of the expected locations and it is the
235 * absolute path of an image file, this image will be used.
237 * @note The icon image set by this function can be changed by
238 * elm_image_file_set().
240 * @see elm_icon_standard_get()
241 * @see elm_image_file_set()
245 EAPI Eina_Bool elm_icon_standard_set(Evas_Object *obj, const char *name);
248 * Get the icon name set by icon standard names.
250 * @param obj The icon object
251 * @return The icon name
253 * If the icon image was set using elm_image_file_set() instead of
254 * elm_icon_standard_set(), then this function will return @c NULL.
256 * @see elm_icon_standard_set()
260 EAPI const char *elm_icon_standard_get(const Evas_Object *obj);
263 * Set the smooth scaling for an icon object.
265 * @param obj The icon object
266 * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
267 * otherwise. Default is @c EINA_TRUE.
269 * Set the scaling algorithm to be used when scaling the icon image. Smooth
270 * scaling provides a better resulting image, but is slower.
272 * The smooth scaling should be disabled when making animations that change
273 * the icon size, since they will be faster. Animations that don't require
274 * resizing of the icon can keep the smooth scaling enabled (even if the icon
275 * is already scaled, since the scaled icon image will be cached).
277 * @see elm_icon_smooth_get()
279 * @deprecated Use elm_image_smooth_set() instead.
283 EINA_DEPRECATED EAPI void elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth);
286 * Get whether smooth scaling is enabled for an icon object.
288 * @param obj The icon object
289 * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
291 * @see elm_icon_smooth_set()
293 * @deprecated Use elm_image_smooth_get() instead.
297 EINA_DEPRECATED EAPI Eina_Bool elm_icon_smooth_get(const Evas_Object *obj);
300 * Disable scaling of this object.
302 * @param obj The icon object.
303 * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
304 * otherwise. Default is @c EINA_FALSE.
306 * This function disables scaling of the icon object through the function
307 * elm_object_scale_set(). However, this does not affect the object
308 * size/resize in any way. For that effect, take a look at
309 * elm_icon_resizable_set().
311 * @see elm_icon_no_scale_get()
312 * @see elm_icon_resizable_set()
313 * @see elm_object_scale_set()
315 * @deprecated Use elm_image_no_scale_set() instead.
319 EINA_DEPRECATED EAPI void elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale);
322 * Get whether scaling is disabled on the object.
324 * @param obj The icon object
325 * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
327 * @see elm_icon_no_scale_set()
329 * @deprecated Use elm_image_no_scale_get() instead.
333 EINA_DEPRECATED EAPI Eina_Bool elm_icon_no_scale_get(const Evas_Object *obj);
336 * Set if the object is (up/down) resizable.
338 * @param obj The icon object
339 * @param size_up A bool to set if the object is resizable up. Default is
341 * @param size_down A bool to set if the object is resizable down. Default
344 * This function limits the icon object resize ability. If @p size_up is set to
345 * @c EINA_FALSE, the object can't have its height or width resized to a value
346 * higher than the original icon size. Same is valid for @p size_down.
348 * @see elm_icon_resizable_get()
350 * @deprecated Use elm_image_resizable_set() instead.
354 EINA_DEPRECATED EAPI void elm_icon_resizable_set(Evas_Object *obj, Eina_Bool size_up, Eina_Bool size_down);
357 * Get if the object is (up/down) resizable.
359 * @param obj The icon object
360 * @param size_up A bool to set if the object is resizable up
361 * @param size_down A bool to set if the object is resizable down
363 * @see elm_icon_resizable_set()
365 * @deprecated Use elm_image_resizable_get() instead.
369 EINA_DEPRECATED EAPI void elm_icon_resizable_get(const Evas_Object *obj, Eina_Bool *size_up, Eina_Bool *size_down);
372 * Get the object's image size
374 * @param obj The icon object
375 * @param w A pointer to store the width in
376 * @param h A pointer to store the height in
378 * @deprecated Use elm_image_object_size_get() instead.
382 EINA_DEPRECATED EAPI void elm_icon_size_get(const Evas_Object *obj, int *w, int *h);
385 * Set if the icon fill the entire object area.
387 * @param obj The icon object
388 * @param fill_outside @c EINA_TRUE if the object is filled outside,
389 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
391 * When the icon object is resized to a different aspect ratio from the
392 * original icon image, the icon image will still keep its aspect. This flag
393 * tells how the image should fill the object's area. They are: keep the
394 * entire icon inside the limits of height and width of the object (@p
395 * fill_outside is @c EINA_FALSE) or let the extra width or height go outside
396 * of the object, and the icon will fill the entire object (@p fill_outside
399 * @note Unlike @ref Image, there's no option in icon to set the aspect ratio
400 * retain property to false. Thus, the icon image will always keep its
401 * original aspect ratio.
403 * @see elm_icon_fill_outside_get()
405 * @deprecated Use elm_image_fill_outside_set() instead.
409 EINA_DEPRECATED EAPI void elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside);
412 * Get if the object is filled outside.
414 * @param obj The icon object
415 * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE
418 * @see elm_icon_fill_outside_set()
420 * @deprecated Use elm_image_fill_outside_get() instead.
424 EINA_DEPRECATED EAPI Eina_Bool elm_icon_fill_outside_get(const Evas_Object *obj);
427 * Set the prescale size for the icon.
429 * @param obj The icon object
430 * @param size The prescale size. This value is used for both width and
433 * This function sets a new size for pixmap representation of the given
434 * icon. It allows the icon to be loaded already in the specified size,
435 * reducing the memory usage and load time when loading a big icon with load
436 * size set to a smaller size.
438 * It's equivalent to the elm_bg_load_size_set() function for bg.
440 * @note this is just a hint, the real size of the pixmap may differ
441 * depending on the type of icon being loaded, being bigger than requested.
443 * @see elm_icon_prescale_get()
444 * @see elm_bg_load_size_set()
446 * @deprecated Use elm_image_prescale_set() instead.
450 EINA_DEPRECATED EAPI void elm_icon_prescale_set(Evas_Object *obj, int size);
453 * Get the prescale size for the icon.
455 * @param obj The icon object
456 * @return The prescale size
458 * @see elm_icon_prescale_set()
460 * @deprecated Use elm_image_prescale_get() instead.
464 EINA_DEPRECATED EAPI int elm_icon_prescale_get(const Evas_Object *obj);
467 * Gets the image object of the icon. DO NOT MODIFY THIS.
469 * @param obj The icon object
470 * @return The internal icon object
472 * @deprecated Use elm_image_object_get() instead.
476 EINA_DEPRECATED EAPI Evas_Object *elm_icon_object_get(Evas_Object *obj);
479 * Sets the icon lookup order used by elm_icon_standard_set().
481 * @param obj The icon object
482 * @param order The icon lookup order (can be one of
483 * ELM_ICON_LOOKUP_FDO_THEME, ELM_ICON_LOOKUP_THEME_FDO, ELM_ICON_LOOKUP_FDO
484 * or ELM_ICON_LOOKUP_THEME)
486 * @see elm_icon_order_lookup_get()
487 * @see Elm_Icon_Lookup_Order
491 EAPI void elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order);
494 * Gets the icon lookup order.
496 * @param obj The icon object
497 * @return The icon lookup order
499 * @see elm_icon_order_lookup_set()
500 * @see Elm_Icon_Lookup_Order
504 EAPI Elm_Icon_Lookup_Order elm_icon_order_lookup_get(const Evas_Object *obj);
507 * Enable or disable preloading of the icon
509 * @param obj The icon object
510 * @param disabled If EINA_TRUE, preloading will be disabled
513 * @deprecated Use elm_image_preload_disabled_set() instead.
516 EINA_DEPRECATED EAPI void elm_icon_preload_disabled_set(Evas_Object *obj, Eina_Bool disabled);
519 * Get if the icon supports animation or not.
521 * @param obj The icon object
522 * @return @c EINA_TRUE if the icon supports animation,
523 * @c EINA_FALSE otherwise.
525 * Return if this elm icon's image can be animated. Currently Evas only
526 * supports gif animation. If the return value is EINA_FALSE, other
527 * elm_icon_animated_xxx APIs won't work.
530 * @deprecated Use elm_image_animated_available_get() instead.
533 EINA_DEPRECATED EAPI Eina_Bool elm_icon_animated_available_get(const Evas_Object *obj);
536 * Set animation mode of the icon.
538 * @param obj The icon object
539 * @param animated @c EINA_TRUE if the object do animation job,
540 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
542 * Since the default animation mode is set to EINA_FALSE,
543 * the icon is shown without animation. Files like animated GIF files
544 * can animate, and this is supported if you enable animated support
546 * Set it to EINA_TRUE when the icon needs to be animated.
549 * @deprecated Use elm_image_animated_set() instead.
552 EINA_DEPRECATED EAPI void elm_icon_animated_set(Evas_Object *obj, Eina_Bool animated);
555 * Get animation mode of the icon.
557 * @param obj The icon object
558 * @return The animation mode of the icon object
559 * @see elm_icon_animated_set
562 * @deprecated Use elm_image_animated_get() instead.
565 EINA_DEPRECATED EAPI Eina_Bool elm_icon_animated_get(const Evas_Object *obj);
568 * Set animation play mode of the icon.
570 * @param obj The icon object
571 * @param play @c EINA_TRUE the object play animation images,
572 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
574 * To play elm icon's animation, set play to EINA_TRUE.
575 * For example, you make gif player using this set/get API and click event.
576 * This literally lets you control current play or paused state. To have
577 * this work with animated GIF files for example, you first, before
578 * setting the file have to use elm_icon_animated_set() to enable animation
579 * at all on the icon.
581 * 1. Click event occurs
582 * 2. Check play flag using elm_icon_animated_play_get
583 * 3. If elm icon was playing, set play to EINA_FALSE.
584 * Then animation will be stopped and vice versa
587 * @deprecated Use elm_image_animated_play_set() instead.
590 EINA_DEPRECATED EAPI void elm_icon_animated_play_set(Evas_Object *obj, Eina_Bool play);
593 * Get animation play mode of the icon.
595 * @param obj The icon object
596 * @return The play mode of the icon object
598 * @see elm_icon_animated_play_get
601 * @deprecated Use elm_image_animated_play_get() instead.
604 EINA_DEPRECATED EAPI Eina_Bool elm_icon_animated_play_get(const Evas_Object *obj);
607 * Set whether the original aspect ratio of the icon should be kept on resize.
609 * @param obj The icon object.
610 * @param fixed @c EINA_TRUE if the icon should retain the aspect,
611 * @c EINA_FALSE otherwise.
613 * The original aspect ratio (width / height) of the icon is usually
614 * distorted to match the object's size. Enabling this option will retain
615 * this original aspect, and the way that the icon is fit into the object's
616 * area depends on the option set by elm_icon_fill_outside_set().
618 * @see elm_icon_aspect_fixed_get()
619 * @see elm_icon_fill_outside_set()
623 * @deprecated Use elm_image_aspect_fixed_set() instead.
626 EINA_DEPRECATED EAPI void elm_icon_aspect_fixed_set(Evas_Object *obj, Eina_Bool fixed);
629 * Get if the object retains the original aspect ratio.
631 * @param obj The icon object.
632 * @return @c EINA_TRUE if the object keeps the original aspect, @c EINA_FALSE
635 * @deprecated Use elm_image_aspect_fixed_get() instead.
639 EINA_DEPRECATED EAPI Eina_Bool elm_icon_aspect_fixed_get(const Evas_Object *obj);