From: Mike McCormack Date: Fri, 4 Nov 2011 01:51:16 +0000 (+0900) Subject: [Elementary.h] Merge documentation for icons X-Git-Tag: REBUILDD-ARMEL-67367~100 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3a8482a3b78c7082cbfd8928b65117857906547c;p=framework%2Fuifw%2Felementary.git [Elementary.h] Merge documentation for icons --- diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in index 267ba73..f4d9623 100644 --- a/src/lib/Elementary.h.in +++ b/src/lib/Elementary.h.in @@ -4631,30 +4631,370 @@ extern "C" { ELM_ICON_LOOKUP_THEME /**< icon look up order: theme */ } Elm_Icon_Lookup_Order; + /** + * Add a new icon object to the parent. + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + * + * @see elm_icon_file_set() + * + * @ingroup Icon + */ EAPI Evas_Object *elm_icon_add(Evas_Object *parent) EINA_ARG_NONNULL(1); + /** + * Set the file that will be used as icon. + * + * @param obj The icon object + * @param file The path to file that will be used as icon image + * @param group The group that the icon belongs to an edje file + * + * @return (@c EINA_TRUE = success, @c EINA_FALSE = error) + * + * @note The icon image set by this function can be changed by + * elm_icon_standard_set(). + * + * @see elm_icon_file_get() + * + * @ingroup Icon + */ EAPI Eina_Bool elm_icon_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2); - EAPI void elm_icon_thumb_set(const Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2); + /** + * Set a location in memory to be used as an icon + * + * @param obj The icon object + * @param img The binary data that will be used as an image + * @param size The size of binary data @p img + * @param format Optional format of @p img to pass to the image loader + * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file) + * + * @return (@c EINA_TRUE = success, @c EINA_FALSE = error) + * + * @note The icon image set by this function can be changed by + * elm_icon_standard_set(). + * + * @ingroup Icon + */ + 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); + /** + * Get the file that will be used as icon. + * + * @param obj The icon object + * @param file The path to file that will be used as the icon image + * @param group The group that the icon belongs to, in edje file + * + * @see elm_icon_file_set() + * + * @ingroup Icon + */ EAPI void elm_icon_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1); + EAPI void elm_icon_thumb_set(const Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2); + /** + * Set the icon by icon standards names. + * + * @param obj The icon object + * @param name The icon name + * + * @return (@c EINA_TRUE = success, @c EINA_FALSE = error) + * + * For example, freedesktop.org defines standard icon names such as "home", + * "network", etc. There can be different icon sets to match those icon + * keys. The @p name given as parameter is one of these "keys", and will be + * 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 will be used. + * + * @note The icon image set by this function can be changed by + * elm_icon_file_set(). + * + * @see elm_icon_standard_get() + * @see elm_icon_file_set() + * + * @ingroup Icon + */ EAPI Eina_Bool elm_icon_standard_set(Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1); + /** + * Get the icon name set by icon standard names. + * + * @param obj The icon object + * @return The icon name + * + * If the icon image was set using elm_icon_file_set() instead of + * elm_icon_standard_set(), then this function will return @c NULL. + * + * @see elm_icon_standard_set() + * + * @ingroup Icon + */ EAPI const char *elm_icon_standard_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set the smooth scaling for an icon object. + * + * @param obj The icon object + * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE + * otherwise. Default is @c 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 elm_icon_smooth_get() + * + * @ingroup Icon + */ EAPI void elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1); + /** + * Get whether smooth scaling is enabled for an icon object. + * + * @param obj The icon object + * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise. + * + * @see elm_icon_smooth_set() + * + * @ingroup Icon + */ EAPI Eina_Bool elm_icon_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Disable scaling of this object. + * + * @param obj The icon object. + * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE + * otherwise. Default is @c 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_scale_set(). + * + * @see elm_icon_no_scale_get() + * @see elm_icon_scale_set() + * @see elm_object_scale_set() + * + * @ingroup Icon + */ EAPI void elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) EINA_ARG_NONNULL(1); + /** + * Get whether scaling is disabled on the object. + * + * @param obj The icon object + * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise + * + * @see elm_icon_no_scale_set() + * + * @ingroup Icon + */ EAPI Eina_Bool elm_icon_no_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set if the object is (up/down) resizable. + * + * @param obj The icon object + * @param scale_up A bool to set if the object is resizable up. Default is + * @c EINA_TRUE. + * @param scale_down A bool to set if the object is resizable down. Default + * is @c EINA_TRUE. + * + * This function limits the icon object resize ability. If @p scale_up is set to + * @c 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 @p scale_down. + * + * @see elm_icon_scale_get() + * + * @ingroup Icon + */ EAPI void elm_icon_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) EINA_ARG_NONNULL(1); + /** + * Get if the object is (up/down) resizable. + * + * @param obj The icon object + * @param scale_up A bool to set if the object is resizable up + * @param scale_down A bool to set if the object is resizable down + * + * @see elm_icon_scale_set() + * + * @ingroup Icon + */ EAPI void elm_icon_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) EINA_ARG_NONNULL(1); + /** + * Get the object's image size + * + * @param obj The icon object + * @param w A pointer to store the width in + * @param h A pointer to store the height in + * + * @ingroup Icon + */ + EAPI void elm_icon_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1); + /** + * Set if the icon fill the entire object area. + * + * @param obj The icon object + * @param fill_outside @c EINA_TRUE if the object is filled outside, + * @c EINA_FALSE otherwise. Default is @c 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 (@p + * fill_outside is @c EINA_FALSE) or let the extra width or height go outside + * of the object, and the icon will fill the entire object (@p fill_outside + * is @c EINA_TRUE). + * + * @note Unlike @ref Image, 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 elm_icon_fill_outside_get() + * @see elm_image_fill_outside_set() + * + * @ingroup Icon + */ EAPI void elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) EINA_ARG_NONNULL(1); + /** + * Get if the object is filled outside. + * + * @param obj The icon object + * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise. + * + * @see elm_icon_fill_outside_set() + * + * @ingroup Icon + */ EAPI Eina_Bool elm_icon_fill_outside_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set the prescale size for the icon. + * + * @param obj The icon object + * @param size The 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 elm_icon_prescale_get() + * @see elm_bg_load_size_set() + * + * @ingroup Icon + */ EAPI void elm_icon_prescale_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1); + /** + * Get the prescale size for the icon. + * + * @param obj The icon object + * @return The prescale size + * + * @see elm_icon_prescale_set() + * + * @ingroup Icon + */ EAPI int elm_icon_prescale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Sets the icon lookup order used by elm_icon_standard_set(). + * + * @param obj The icon object + * @param 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 elm_icon_order_lookup_get() + * @see Elm_Icon_Lookup_Order + * + * @ingroup Icon + */ EAPI void elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order) EINA_ARG_NONNULL(1); + /** + * Gets the icon lookup order. + * + * @param obj The icon object + * @return The icon lookup order + * + * @see elm_icon_order_lookup_set() + * @see Elm_Icon_Lookup_Order + * + * @ingroup Icon + */ EAPI Elm_Icon_Lookup_Order elm_icon_order_lookup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Get if the icon supports animation or not. + * + * @param obj The icon object + * @return @c EINA_TRUE if the icon supports animation, + * @c 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. + * @ingroup Icon + */ EAPI Eina_Bool elm_icon_anim_available_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set animation mode of the icon. + * + * @param obj The icon object + * @param anim @c EINA_TRUE if the object do animation job, + * @c EINA_FALSE otherwise. Default is @c EINA_FALSE. + * + * Since the default animation mode is set to EINA_FALSE, + * the icon is shown without animation. + * This might be desirable when the application developer wants to show + * a snapshot of the animated icon. + * Set it to EINA_TRUE when the icon needs to be animated. + * @ingroup Icon + */ EAPI void elm_icon_anim_set(Evas_Object *obj, Eina_Bool anim) EINA_ARG_NONNULL(1); + /** + * Get animation mode of the icon. + * + * @param obj The icon object + * @return The animation mode of the icon object + * @see elm_icon_animated_set + * @ingroup Icon + */ EAPI Eina_Bool elm_icon_anim_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set animation play mode of the icon. + * + * @param obj The icon object + * @param play @c EINA_TRUE the object play animation images, + * @c EINA_FALSE otherwise. Default is @c EINA_FALSE. + * + * To play elm icon's animation, set play to EINA_TURE. + * For example, you make gif player using this set/get API and click event. + * + * 1. Click event occurs + * 2. Check play flag using elm_icon_animaged_play_get + * 3. If elm icon was playing, set play to EINA_FALSE. + * Then animation will be stopped and vice versa + * @ingroup Icon + */ EAPI void elm_icon_anim_play_set(Evas_Object *obj, Eina_Bool play) EINA_ARG_NONNULL(1); + /** + * Get animation play mode of the icon. + * + * @param obj The icon object + * @return The play mode of the icon object + * + * @see elm_icon_animated_play_get + * @ingroup Icon + */ EAPI Eina_Bool elm_icon_anim_play_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @} + */ + /* smart callbacks called: * "clicked" - the user clicked the icon */ @@ -6237,12 +6577,6 @@ extern "C" { int button; Evas_Coord x, y, w, h; }; - typedef enum _Elm_Icon_Type - { - ELM_ICON_NONE, - ELM_ICON_FILE, - ELM_ICON_STANDARD - } Elm_Icon_Type; typedef struct _Elm_Hoversel_Item Elm_Hoversel_Item; /**< Item of Elm_Hoversel. Sub-type of Elm_Widget_Item */