4 * @image html img/widget/icon/preview-00.png
5 * @image latex img/widget/icon/preview-00.eps
7 * An object that provides standard icon images (delete, edit, arrows, etc.)
8 * or a custom file (PNG, JPG, EDJE, etc.) used for an icon.
10 * The icon image requested can be in the elementary theme, or in the
11 * freedesktop.org paths. It's possible to set the order of preference from
12 * where the image will be used.
14 * This API is very similar to @ref Image, but with ready to use images.
16 * Default images provided by the theme are described below.
18 * The first list contains icons that were first intended to be used in
19 * toolbars, but can be used in many other places too:
35 * Now some icons that were designed to be used in menus (but again, you can
36 * use them anywhere else):
43 * @li menu/arrow_right
52 * And here we have some media player specific icons:
53 * @li media_player/forward
54 * @li media_player/info
55 * @li media_player/next
56 * @li media_player/pause
57 * @li media_player/play
58 * @li media_player/prev
59 * @li media_player/rewind
60 * @li media_player/stop
62 * Signals that you can add callbacks for are:
64 * "clicked" - This is called when a user has clicked the icon
66 * An example of usage for this API follows:
67 * @li @ref tutorial_icon
75 typedef enum _Elm_Icon_Type
83 * @enum _Elm_Icon_Lookup_Order
84 * @typedef Elm_Icon_Lookup_Order
86 * Lookup order used by elm_icon_standard_set(). Should look for icons in the
87 * theme, FDO paths, or both?
91 typedef enum _Elm_Icon_Lookup_Order
93 ELM_ICON_LOOKUP_FDO_THEME, /**< icon look up order: freedesktop, theme */
94 ELM_ICON_LOOKUP_THEME_FDO, /**< icon look up order: theme, freedesktop */
95 ELM_ICON_LOOKUP_FDO, /**< icon look up order: freedesktop */
96 ELM_ICON_LOOKUP_THEME /**< icon look up order: theme */
97 } Elm_Icon_Lookup_Order;
100 * Add a new icon object to the parent.
102 * @param parent The parent object
103 * @return The new object or NULL if it cannot be created
105 * @see elm_icon_file_set()
109 EAPI Evas_Object *elm_icon_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
112 * Set the file that will be used as icon.
114 * @param obj The icon object
115 * @param file The path to file that will be used as icon image
116 * @param group The group that the icon belongs to an edje file
118 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
120 * @note The icon image set by this function can be changed by
121 * elm_icon_standard_set().
123 * @see elm_icon_file_get()
127 EAPI Eina_Bool elm_icon_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
130 * Set a location in memory to be used as an icon
132 * @param obj The icon object
133 * @param img The binary data that will be used as an image
134 * @param size The size of binary data @p img
135 * @param format Optional format of @p img to pass to the image loader
136 * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
138 * The @p format string should be something like "png", "jpg", "tga",
139 * "tiff", "bmp" etc. if it is provided (NULL if not). This improves
140 * the loader performance as it tries the "correct" loader first before
141 * trying a range of other possible loaders until one succeeds.
143 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
145 * @note The icon image set by this function can be changed by
146 * elm_icon_standard_set().
150 EAPI Eina_Bool elm_icon_memfile_set(Evas_Object *obj, const void *img, size_t size, const char *format, const char *key) EINA_ARG_NONNULL(1, 2);
153 * Get the file that will be used as icon.
155 * @param obj The icon object
156 * @param file The path to file that will be used as the icon image
157 * @param group The group that the icon belongs to, in edje file
159 * @see elm_icon_file_set()
163 EAPI void elm_icon_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
166 * Set the file that will be used, but use a generated thumbnail.
168 * @param obj The icon object
169 * @param file The path to file that will be used as icon image
170 * @param group The group that the icon belongs to an edje file
172 * This functions like elm_icon_file_set() but requires the Ethumb library
173 * support to be enabled successfully with elm_need_ethumb(). When set
174 * the file indicated has a thumbnail generated and cached on disk for
175 * future use or will directly use an existing cached thumbnail if it
178 * @see elm_icon_file_set()
182 EAPI void elm_icon_thumb_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
185 * Set the icon by icon standards names.
187 * @param obj The icon object
188 * @param name The icon name
190 * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
192 * For example, freedesktop.org defines standard icon names such as "home",
193 * "network", etc. There can be different icon sets to match those icon
194 * keys. The @p name given as parameter is one of these "keys", and will be
195 * used to look in the freedesktop.org paths and elementary theme. One can
196 * change the lookup order with elm_icon_order_lookup_set().
198 * If name is not found in any of the expected locations and it is the
199 * absolute path of an image file, this image will be used.
201 * @note The icon image set by this function can be changed by
202 * elm_icon_file_set().
204 * @see elm_icon_standard_get()
205 * @see elm_icon_file_set()
209 EAPI Eina_Bool elm_icon_standard_set(Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
212 * Get the icon name set by icon standard names.
214 * @param obj The icon object
215 * @return The icon name
217 * If the icon image was set using elm_icon_file_set() instead of
218 * elm_icon_standard_set(), then this function will return @c NULL.
220 * @see elm_icon_standard_set()
224 EAPI const char *elm_icon_standard_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
227 * Set the smooth scaling for an icon object.
229 * @param obj The icon object
230 * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
231 * otherwise. Default is @c EINA_TRUE.
233 * Set the scaling algorithm to be used when scaling the icon image. Smooth
234 * scaling provides a better resulting image, but is slower.
236 * The smooth scaling should be disabled when making animations that change
237 * the icon size, since they will be faster. Animations that don't require
238 * resizing of the icon can keep the smooth scaling enabled (even if the icon
239 * is already scaled, since the scaled icon image will be cached).
241 * @see elm_icon_smooth_get()
245 EAPI void elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1);
248 * Get whether smooth scaling is enabled for an icon object.
250 * @param obj The icon object
251 * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
253 * @see elm_icon_smooth_set()
257 EAPI Eina_Bool elm_icon_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
260 * Disable scaling of this object.
262 * @param obj The icon object.
263 * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
264 * otherwise. Default is @c EINA_FALSE.
266 * This function disables scaling of the icon object through the function
267 * elm_object_scale_set(). However, this does not affect the object
268 * size/resize in any way. For that effect, take a look at
269 * elm_icon_scale_set().
271 * @see elm_icon_no_scale_get()
272 * @see elm_icon_scale_set()
273 * @see elm_object_scale_set()
277 EAPI void elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) EINA_ARG_NONNULL(1);
280 * Get whether scaling is disabled on the object.
282 * @param obj The icon object
283 * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
285 * @see elm_icon_no_scale_set()
289 EAPI Eina_Bool elm_icon_no_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
292 * Set if the object is (up/down) resizable.
294 * @param obj The icon object
295 * @param scale_up A bool to set if the object is resizable up. Default is
297 * @param scale_down A bool to set if the object is resizable down. Default
300 * This function limits the icon object resize ability. If @p scale_up is set to
301 * @c EINA_FALSE, the object can't have its height or width resized to a value
302 * higher than the original icon size. Same is valid for @p scale_down.
304 * @see elm_icon_scale_get()
308 EAPI void elm_icon_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) EINA_ARG_NONNULL(1);
311 * Get if the object is (up/down) resizable.
313 * @param obj The icon object
314 * @param scale_up A bool to set if the object is resizable up
315 * @param scale_down A bool to set if the object is resizable down
317 * @see elm_icon_scale_set()
321 EAPI void elm_icon_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) EINA_ARG_NONNULL(1);
324 * Get the object's image size
326 * @param obj The icon object
327 * @param w A pointer to store the width in
328 * @param h A pointer to store the height in
332 EAPI void elm_icon_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
335 * Set if the icon fill the entire object area.
337 * @param obj The icon object
338 * @param fill_outside @c EINA_TRUE if the object is filled outside,
339 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
341 * When the icon object is resized to a different aspect ratio from the
342 * original icon image, the icon image will still keep its aspect. This flag
343 * tells how the image should fill the object's area. They are: keep the
344 * entire icon inside the limits of height and width of the object (@p
345 * fill_outside is @c EINA_FALSE) or let the extra width or height go outside
346 * of the object, and the icon will fill the entire object (@p fill_outside
349 * @note Unlike @ref Image, there's no option in icon to set the aspect ratio
350 * retain property to false. Thus, the icon image will always keep its
351 * original aspect ratio.
353 * @see elm_icon_fill_outside_get()
354 * @see elm_image_fill_outside_set()
358 EAPI void elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) EINA_ARG_NONNULL(1);
361 * Get if the object is filled outside.
363 * @param obj The icon object
364 * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
366 * @see elm_icon_fill_outside_set()
370 EAPI Eina_Bool elm_icon_fill_outside_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
373 * Set the prescale size for the icon.
375 * @param obj The icon object
376 * @param size The prescale size. This value is used for both width and
379 * This function sets a new size for pixmap representation of the given
380 * icon. It allows the icon to be loaded already in the specified size,
381 * reducing the memory usage and load time when loading a big icon with load
382 * size set to a smaller size.
384 * It's equivalent to the elm_bg_load_size_set() function for bg.
386 * @note this is just a hint, the real size of the pixmap may differ
387 * depending on the type of icon being loaded, being bigger than requested.
389 * @see elm_icon_prescale_get()
390 * @see elm_bg_load_size_set()
394 EAPI void elm_icon_prescale_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
397 * Get the prescale size for the icon.
399 * @param obj The icon object
400 * @return The prescale size
402 * @see elm_icon_prescale_set()
406 EAPI int elm_icon_prescale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
409 * Gets the image object of the icon. DO NOT MODIFY THIS.
411 * @param obj The icon object
412 * @return The internal icon object
416 EAPI Evas_Object *elm_icon_object_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
419 * Sets the icon lookup order used by elm_icon_standard_set().
421 * @param obj The icon object
422 * @param order The icon lookup order (can be one of
423 * ELM_ICON_LOOKUP_FDO_THEME, ELM_ICON_LOOKUP_THEME_FDO, ELM_ICON_LOOKUP_FDO
424 * or ELM_ICON_LOOKUP_THEME)
426 * @see elm_icon_order_lookup_get()
427 * @see Elm_Icon_Lookup_Order
431 EAPI void elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order) EINA_ARG_NONNULL(1);
434 * Gets the icon lookup order.
436 * @param obj The icon object
437 * @return The icon lookup order
439 * @see elm_icon_order_lookup_set()
440 * @see Elm_Icon_Lookup_Order
444 EAPI Elm_Icon_Lookup_Order elm_icon_order_lookup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
447 * Enable or disable preloading of the icon
449 * @param obj The icon object
450 * @param disable If EINA_TRUE, preloading will be disabled
453 EAPI void elm_icon_preload_set(Evas_Object *obj, Eina_Bool disable) EINA_ARG_NONNULL(1);
456 * Get if the icon supports animation or not.
458 * @param obj The icon object
459 * @return @c EINA_TRUE if the icon supports animation,
460 * @c EINA_FALSE otherwise.
462 * Return if this elm icon's image can be animated. Currently Evas only
463 * supports gif animation. If the return value is EINA_FALSE, other
464 * elm_icon_animated_XXX APIs won't work.
467 EAPI Eina_Bool elm_icon_animated_available_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
470 * Set animation mode of the icon.
472 * @param obj The icon object
473 * @param anim @c EINA_TRUE if the object do animation job,
474 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
476 * Since the default animation mode is set to EINA_FALSE,
477 * the icon is shown without animation. Files like animated GIF files
478 * can animate, and this is supported if you enable animated support
480 * Set it to EINA_TRUE when the icon needs to be animated.
483 EAPI void elm_icon_animated_set(Evas_Object *obj, Eina_Bool animated) EINA_ARG_NONNULL(1);
486 * Get animation mode of the icon.
488 * @param obj The icon object
489 * @return The animation mode of the icon object
490 * @see elm_icon_animated_set
493 EAPI Eina_Bool elm_icon_animated_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
496 * Set animation play mode of the icon.
498 * @param obj The icon object
499 * @param play @c EINA_TRUE the object play animation images,
500 * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
502 * To play elm icon's animation, set play to EINA_TURE.
503 * For example, you make gif player using this set/get API and click event.
504 * This literally lets you control current play or paused state. To have
505 * this work with animated GIF files for example, you first, before
506 * setting the file have to use elm_icon_animated_set() to enable animation
507 * at all on the icon.
509 * 1. Click event occurs
510 * 2. Check play flag using elm_icon_animaged_play_get
511 * 3. If elm icon was playing, set play to EINA_FALSE.
512 * Then animation will be stopped and vice versa
515 EAPI void elm_icon_animated_play_set(Evas_Object *obj, Eina_Bool play) EINA_ARG_NONNULL(1);
518 * Get animation play mode of the icon.
520 * @param obj The icon object
521 * @return The play mode of the icon object
523 * @see elm_icon_animated_play_get
526 EAPI Eina_Bool elm_icon_animated_play_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);