5 * @image html img/widget/icon/preview-00.png
6 * @image latex img/widget/icon/preview-00.eps
8 * An object that provides standard icon images (delete, edit, arrows, etc.)
9 * or a custom file (PNG, JPG, EDJE, etc.) used for an icon.
11 * The icon image requested can be in the elementary theme, or in the
12 * freedesktop.org paths. It's possible to set the order of preference from
13 * where the image will be used.
15 * This API is very similar to @ref Image, but with ready to use images.
17 * Default images provided by the theme are described below.
19 * The first list contains icons that were first intended to be used in
20 * toolbars, but can be used in many other places too:
36 * Now some icons that were designed to be used in menus (but again, you can
37 * use them anywhere else):
44 * @li menu/arrow_right
53 * And here we have some media player specific icons:
54 * @li media_player/forward
55 * @li media_player/info
56 * @li media_player/next
57 * @li media_player/pause
58 * @li media_player/play
59 * @li media_player/prev
60 * @li media_player/rewind
61 * @li media_player/stop
63 * Signals that you can add callbacks for are:
65 * "clicked" - This is called when a user has clicked the icon
67 * Supported elm_object common APIs.
68 * @li @ref elm_object_signal_emit
69 * @li @ref elm_object_signal_callback_add
70 * @li @ref elm_object_signal_callback_del
72 * An example of usage for this API follows:
73 * @li @ref tutorial_icon
89 * @enum _Elm_Icon_Lookup_Order
90 * @typedef Elm_Icon_Lookup_Order
92 * Lookup order used by elm_icon_standard_set(). Should look for icons in the
93 * theme, FDO paths, or both?
99 ELM_ICON_LOOKUP_FDO_THEME, /**< icon look up order: freedesktop, theme */
100 ELM_ICON_LOOKUP_THEME_FDO, /**< icon look up order: theme, freedesktop */
101 ELM_ICON_LOOKUP_FDO, /**< icon look up order: freedesktop */
102 ELM_ICON_LOOKUP_THEME /**< icon look up order: theme */
103 } Elm_Icon_Lookup_Order;
106 * Add a new icon object to the parent.
108 * @param parent The parent object
109 * @return The new object or NULL if it cannot be created
111 * @see elm_icon_file_set()
115 EAPI Evas_Object *elm_icon_add(Evas_Object *parent);
118 * Set the file that will be used as icon.
120 * @param obj The icon object
121 * @param file The path to file that will be used as icon image
122 * @param group The group that the icon belongs to an edje file
124 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
126 * @note The icon image set by this function can be changed by
127 * elm_icon_standard_set().
129 * @see elm_icon_file_get()
133 EAPI Eina_Bool elm_icon_file_set(Evas_Object *obj, const char *file, const char *group);
136 * Set a location in memory to be used as an icon
138 * @param obj The icon object
139 * @param img The binary data that will be used as an image
140 * @param size The size of binary data @p img
141 * @param format Optional format of @p img to pass to the image loader
142 * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
144 * The @p format string should be something like "png", "jpg", "tga",
145 * "tiff", "bmp" etc. if it is provided (NULL if not). This improves
146 * the loader performance as it tries the "correct" loader first before
147 * trying a range of other possible loaders until one succeeds.
149 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
151 * @note The icon image set by this function can be changed by
152 * elm_icon_standard_set().
156 EAPI Eina_Bool elm_icon_memfile_set(Evas_Object *obj, const void *img, size_t size, const char *format, const char *key);
159 * Get the file that will be used as icon.
161 * @param obj The icon object
162 * @param file The path to file that will be used as the icon image
163 * @param group The group that the icon belongs to, in edje file
165 * @see elm_icon_file_set()
169 EAPI void elm_icon_file_get(const Evas_Object *obj, const char **file, const char **group);
172 * Set the file that will be used, but use a generated thumbnail.
174 * @param obj The icon object
175 * @param file The path to file that will be used as icon image
176 * @param group The group that the icon belongs to an edje file
178 * This functions like elm_icon_file_set() but requires the Ethumb library
179 * support to be enabled successfully with elm_need_ethumb(). When set
180 * the file indicated has a thumbnail generated and cached on disk for
181 * future use or will directly use an existing cached thumbnail if it
184 * @see elm_icon_file_set()
188 EAPI void elm_icon_thumb_set(Evas_Object *obj, const char *file, const char *group);
191 * Set the icon by icon standards names.
193 * @param obj The icon object
194 * @param name The icon name
196 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
198 * For example, freedesktop.org defines standard icon names such as "home",
199 * "network", etc. There can be different icon sets to match those icon
200 * keys. The @p name given as parameter is one of these "keys", and will be
201 * used to look in the freedesktop.org paths and elementary theme. One can
202 * change the lookup order with elm_icon_order_lookup_set().
204 * If name is not found in any of the expected locations and it is the
205 * absolute path of an image file, this image will be used.
207 * @note The icon image set by this function can be changed by
208 * elm_icon_file_set().
210 * @see elm_icon_standard_get()
211 * @see elm_icon_file_set()
215 EAPI Eina_Bool elm_icon_standard_set(Evas_Object *obj, const char *name);
218 * Get the icon name set by icon standard names.
220 * @param obj The icon object
221 * @return The icon name
223 * If the icon image was set using elm_icon_file_set() instead of
224 * elm_icon_standard_set(), then this function will return @c NULL.
226 * @see elm_icon_standard_set()
230 EAPI const char *elm_icon_standard_get(const Evas_Object *obj);
233 * Set the smooth scaling for an icon object.
235 * @param obj The icon object
236 * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
237 * otherwise. Default is @c EINA_TRUE.
239 * Set the scaling algorithm to be used when scaling the icon image. Smooth
240 * scaling provides a better resulting image, but is slower.
242 * The smooth scaling should be disabled when making animations that change
243 * the icon size, since they will be faster. Animations that don't require
244 * resizing of the icon can keep the smooth scaling enabled (even if the icon
245 * is already scaled, since the scaled icon image will be cached).
247 * @see elm_icon_smooth_get()
251 EAPI void elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth);
254 * Get whether smooth scaling is enabled for an icon object.
256 * @param obj The icon object
257 * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
259 * @see elm_icon_smooth_set()
263 EAPI Eina_Bool elm_icon_smooth_get(const Evas_Object *obj);
266 * Disable scaling of this object.
268 * @param obj The icon object.
269 * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
270 * otherwise. Default is @c EINA_FALSE.
272 * This function disables scaling of the icon object through the function
273 * elm_object_scale_set(). However, this does not affect the object
274 * size/resize in any way. For that effect, take a look at
275 * elm_icon_resizable_set().
277 * @see elm_icon_no_scale_get()
278 * @see elm_icon_resizable_set()
279 * @see elm_object_scale_set()
283 EAPI void elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale);
286 * Get whether scaling is disabled on the object.
288 * @param obj The icon object
289 * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
291 * @see elm_icon_no_scale_set()
295 EAPI Eina_Bool elm_icon_no_scale_get(const Evas_Object *obj);
298 * Set if the object is (up/down) resizable.
300 * @param obj The icon object
301 * @param size_up A bool to set if the object is resizable up. Default is
303 * @param size_down A bool to set if the object is resizable down. Default
306 * This function limits the icon object resize ability. If @p size_up is set to
307 * @c EINA_FALSE, the object can't have its height or width resized to a value
308 * higher than the original icon size. Same is valid for @p size_down.
310 * @see elm_icon_resizable_get()
314 EAPI void elm_icon_resizable_set(Evas_Object *obj, Eina_Bool size_up, Eina_Bool size_down);
317 * Get if the object is (up/down) resizable.
319 * @param obj The icon object
320 * @param size_up A bool to set if the object is resizable up
321 * @param size_down A bool to set if the object is resizable down
323 * @see elm_icon_resizable_set()
327 EAPI void elm_icon_resizable_get(const Evas_Object *obj, Eina_Bool *size_up, Eina_Bool *size_down);
330 * Get the object's image size
332 * @param obj The icon object
333 * @param w A pointer to store the width in
334 * @param h A pointer to store the height in
338 EAPI void elm_icon_size_get(const Evas_Object *obj, int *w, int *h);
341 * Set if the icon fill the entire object area.
343 * @param obj The icon object
344 * @param fill_outside @c EINA_TRUE if the object is filled outside,
345 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
347 * When the icon object is resized to a different aspect ratio from the
348 * original icon image, the icon image will still keep its aspect. This flag
349 * tells how the image should fill the object's area. They are: keep the
350 * entire icon inside the limits of height and width of the object (@p
351 * fill_outside is @c EINA_FALSE) or let the extra width or height go outside
352 * of the object, and the icon will fill the entire object (@p fill_outside
355 * @note Unlike @ref Image, there's no option in icon to set the aspect ratio
356 * retain property to false. Thus, the icon image will always keep its
357 * original aspect ratio.
359 * @see elm_icon_fill_outside_get()
360 * @see elm_image_fill_outside_set()
364 EAPI void elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside);
367 * Get if the object is filled outside.
369 * @param obj The icon object
370 * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
372 * @see elm_icon_fill_outside_set()
376 EAPI Eina_Bool elm_icon_fill_outside_get(const Evas_Object *obj);
379 * Set the prescale size for the icon.
381 * @param obj The icon object
382 * @param size The prescale size. This value is used for both width and
385 * This function sets a new size for pixmap representation of the given
386 * icon. It allows the icon to be loaded already in the specified size,
387 * reducing the memory usage and load time when loading a big icon with load
388 * size set to a smaller size.
390 * It's equivalent to the elm_bg_load_size_set() function for bg.
392 * @note this is just a hint, the real size of the pixmap may differ
393 * depending on the type of icon being loaded, being bigger than requested.
395 * @see elm_icon_prescale_get()
396 * @see elm_bg_load_size_set()
400 EAPI void elm_icon_prescale_set(Evas_Object *obj, int size);
403 * Get the prescale size for the icon.
405 * @param obj The icon object
406 * @return The prescale size
408 * @see elm_icon_prescale_set()
412 EAPI int elm_icon_prescale_get(const Evas_Object *obj);
415 * Gets the image object of the icon. DO NOT MODIFY THIS.
417 * @param obj The icon object
418 * @return The internal icon object
422 EAPI Evas_Object *elm_icon_object_get(Evas_Object *obj);
425 * Sets the icon lookup order used by elm_icon_standard_set().
427 * @param obj The icon object
428 * @param order The icon lookup order (can be one of
429 * ELM_ICON_LOOKUP_FDO_THEME, ELM_ICON_LOOKUP_THEME_FDO, ELM_ICON_LOOKUP_FDO
430 * or ELM_ICON_LOOKUP_THEME)
432 * @see elm_icon_order_lookup_get()
433 * @see Elm_Icon_Lookup_Order
437 EAPI void elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order);
440 * Gets the icon lookup order.
442 * @param obj The icon object
443 * @return The icon lookup order
445 * @see elm_icon_order_lookup_set()
446 * @see Elm_Icon_Lookup_Order
450 EAPI Elm_Icon_Lookup_Order elm_icon_order_lookup_get(const Evas_Object *obj);
453 * Enable or disable preloading of the icon
455 * @param obj The icon object
456 * @param disabled If EINA_TRUE, preloading will be disabled
459 EAPI void elm_icon_preload_disabled_set(Evas_Object *obj, Eina_Bool disabled);
462 * Get if the icon supports animation or not.
464 * @param obj The icon object
465 * @return @c EINA_TRUE if the icon supports animation,
466 * @c EINA_FALSE otherwise.
468 * Return if this elm icon's image can be animated. Currently Evas only
469 * supports gif animation. If the return value is EINA_FALSE, other
470 * elm_icon_animated_xxx APIs won't work.
473 EAPI Eina_Bool elm_icon_animated_available_get(const Evas_Object *obj);
476 * Set animation mode of the icon.
478 * @param obj The icon object
479 * @param animated @c EINA_TRUE if the object do animation job,
480 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
482 * Since the default animation mode is set to EINA_FALSE,
483 * the icon is shown without animation. Files like animated GIF files
484 * can animate, and this is supported if you enable animated support
486 * Set it to EINA_TRUE when the icon needs to be animated.
489 EAPI void elm_icon_animated_set(Evas_Object *obj, Eina_Bool animated);
492 * Get animation mode of the icon.
494 * @param obj The icon object
495 * @return The animation mode of the icon object
496 * @see elm_icon_animated_set
499 EAPI Eina_Bool elm_icon_animated_get(const Evas_Object *obj);
502 * Set animation play mode of the icon.
504 * @param obj The icon object
505 * @param play @c EINA_TRUE the object play animation images,
506 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
508 * To play elm icon's animation, set play to EINA_TRUE.
509 * For example, you make gif player using this set/get API and click event.
510 * This literally lets you control current play or paused state. To have
511 * this work with animated GIF files for example, you first, before
512 * setting the file have to use elm_icon_animated_set() to enable animation
513 * at all on the icon.
515 * 1. Click event occurs
516 * 2. Check play flag using elm_icon_animated_play_get
517 * 3. If elm icon was playing, set play to EINA_FALSE.
518 * Then animation will be stopped and vice versa
521 EAPI void elm_icon_animated_play_set(Evas_Object *obj, Eina_Bool play);
524 * Get animation play mode of the icon.
526 * @param obj The icon object
527 * @return The play mode of the icon object
529 * @see elm_icon_animated_play_get
532 EAPI Eina_Bool elm_icon_animated_play_get(const Evas_Object *obj);
535 * Set whether the original aspect ratio of the icon should be kept on resize.
537 * @param obj The icon object.
538 * @param fixed @c EINA_TRUE if the icon should retain the aspect,
539 * @c EINA_FALSE otherwise.
541 * The original aspect ratio (width / height) of the icon is usually
542 * distorted to match the object's size. Enabling this option will retain
543 * this original aspect, and the way that the icon is fit into the object's
544 * area depends on the option set by elm_icon_fill_outside_set().
546 * @see elm_icon_aspect_fixed_get()
547 * @see elm_icon_fill_outside_set()
551 EAPI void elm_icon_aspect_fixed_set(Evas_Object *obj, Eina_Bool fixed);
554 * Get if the object retains the original aspect ratio.
556 * @param obj The icon object.
557 * @return @c EINA_TRUE if the object keeps the original aspect, @c EINA_FALSE
562 EAPI Eina_Bool elm_icon_aspect_fixed_get(const Evas_Object *obj);