From f80e0b884f47e50be3754242526e17cfc7007c40 Mon Sep 17 00:00:00 2001 From: Rafael Antognolli Date: Mon, 18 Jul 2011 18:14:34 +0000 Subject: [PATCH] elementary/icon - Improving documentation. Moved doxygen comments from .c to .h and added more description to them. Also increased the group detailed description. SVN revision: 61484 --- legacy/elementary/src/lib/Elementary.h.in | 338 +++++++++++++++++++++- legacy/elementary/src/lib/elm_icon.c | 162 ----------- 2 files changed, 334 insertions(+), 166 deletions(-) diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index 30fac94e39..d05912f62c 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -1827,7 +1827,86 @@ extern "C" { /* smart callbacks called: */ - /* icon */ + /** + * @defgroup Icon Icon + * + * An object that provides standard icon images (delete, edit, arrows, etc.) + * or a custom file (PNG, JPG, EDJE, etc.) used for an icon. + * + * The icon image requested can be in the elementary theme, or in the + * freedesktop.org paths. It's possible to set the order of preference from + * where the image will be used. + * + * This API is very similar to @ref Image, but with ready to use images. + * + * Default images provided by the theme are described below. + * + * The first list contains icons that were first intended to be used in + * toolbars, but can be used in many other places too: + * @li home + * @li close + * @li apps + * @li arrow_up + * @li arrow_down + * @li arrow_left + * @li arrow_right + * @li chat + * @li clock + * @li delete + * @li edit + * @li refresh + * @li folder + * @li file + * + * Now some icons that were designed to be used in menus (but again, you can + * use them anywhere else): + * @li menu/home + * @li menu/close + * @li menu/apps + * @li menu/arrow_up + * @li menu/arrow_down + * @li menu/arrow_left + * @li menu/arrow_right + * @li menu/chat + * @li menu/clock + * @li menu/delete + * @li menu/edit + * @li menu/refresh + * @li menu/folder + * @li menu/file + * + * And here we have some media player specific icons: + * @li media_player/forward + * @li media_player/info + * @li media_player/next + * @li media_player/pause + * @li media_player/play + * @li media_player/prev + * @li media_player/rewind + * @li media_player/stop + * + * Signals that you can add callbacks for are: + * + * "clicked" - This is called when a user has clicked the icon + * + * An example of usage for this API follows: + * @li @ref tutorial_icon + */ + + /** + * @addtogroup Icon + * @{ + */ + + /** + * @enum _Elm_Icon_Lookup_Order + * @typedef Elm_Icon_Lookup_Order + * + * Lookup order used by elm_icon_standard_set(). Should look for icons in the + * theme, FDO paths, or both? + * + * @ingroup Icon + */ typedef enum _Elm_Icon_Lookup_Order { ELM_ICON_LOOKUP_FDO_THEME, /**< icon look up order: freedesktop, theme */ @@ -1836,26 +1915,277 @@ 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 in 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); + /** + * 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 icon 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 effect 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 the smooth effect 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) resizeable. + * + * @param obj The icon object + * @param scale_up A bool to set if the object is resizeable up. Default is + * @c EINA_TRUE. + * @param scale_down A bool to set if the object is resizeable 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) resizeable. + * + * @param obj The icon object + * @param scale_up A bool to set if the object is resizeable up + * @param scale_down A bool to set if the object is resizeable 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); + /** + * 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); - /* smart callbacks called: - * "clicked" - the user clicked the icon + + /** + * @} */ /** diff --git a/legacy/elementary/src/lib/elm_icon.c b/legacy/elementary/src/lib/elm_icon.c index abb302876e..62ffb615e8 100644 --- a/legacy/elementary/src/lib/elm_icon.c +++ b/legacy/elementary/src/lib/elm_icon.c @@ -6,19 +6,6 @@ static const char *icon_theme = NULL; #endif -/** - * @defgroup Icon Icon - * - * A standard icon that may be provided by the theme (delete, edit, - * arrows etc.) or a custom file (PNG, JPG, EDJE etc.) used for an - * icon. The Icon may scale or not and of course... support alpha - * channels. - * - * Signals that you can add callbacks for are: - * - * "clicked" - This is called when a user has clicked the icon - */ - typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -443,14 +430,6 @@ _mouse_up(void *data, Evas *e __UNUSED__, Evas_Object *obj __UNUSED__, void *eve evas_object_smart_callback_call(data, SIG_CLICKED, event_info); } -/** - * Add a new icon to the parent - * - * @param parent The parent object - * @return The new object or NULL if it cannot be created - * - * @ingroup Icon - */ EAPI Evas_Object * elm_icon_add(Evas_Object *parent) { @@ -492,17 +471,6 @@ elm_icon_add(Evas_Object *parent) return obj; } -/** - * 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 - * @param group The group that the icon belongs in edje file - * - * @return (1 = success, 0 = error) - * - * @ingroup Icon - */ EAPI Eina_Bool elm_icon_file_set(Evas_Object *obj, const char *file, const char *group) { @@ -523,15 +491,6 @@ elm_icon_file_set(Evas_Object *obj, const char *file, const char *group) return ret; } -/** - * 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 icon - * @param group The group that the icon belongs in edje file - * - * @ingroup Icon - */ EAPI void elm_icon_file_get(const Evas_Object *obj, const char **file, const char **group) { @@ -717,18 +676,6 @@ _elm_icon_standard_resize(void *data, eina_stringshare_del(refup); } -/** - * Set the theme, as standard, for an icon. - * If theme was not found and it is the absolute path of an image file, this - * image will be used. - * - * @param obj The icon object - * @param name The theme name - * - * @return (1 = success, 0 = error) - * - * @ingroup Icon - */ EAPI Eina_Bool elm_icon_standard_set(Evas_Object *obj, const char *name) { @@ -751,14 +698,6 @@ elm_icon_standard_set(Evas_Object *obj, const char *name) return ret; } -/** - * Get the theme, as standard, for an icon - * - * @param obj The icon object - * @return The theme name - * - * @ingroup Icon - */ EAPI const char * elm_icon_standard_get(const Evas_Object *obj) { @@ -768,14 +707,6 @@ elm_icon_standard_get(const Evas_Object *obj) return wd->stdicon; } -/** - * Sets icon lookup order, used by elm_icon_standard_set(). - * - * @param obj The icon object - * @param order The icon lookup order - * - * @ingroup Icon - */ EAPI void elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order) { @@ -784,14 +715,6 @@ elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order) if (wd) wd->lookup_order = order; } -/** - * Gets the icon lookup order. - * - * @param obj The icon object - * @return The icon lookup order - * - * @ingroup Icon - */ EAPI Elm_Icon_Lookup_Order elm_icon_order_lookup_get(const Evas_Object *obj) { @@ -801,15 +724,6 @@ elm_icon_order_lookup_get(const Evas_Object *obj) return wd->lookup_order; } -/** - * Set the smooth effect for an icon - * - * @param obj The icon object - * @param smooth A bool to set (or no) smooth effect - * (1 = smooth, 0 = not smooth) - * - * @ingroup Icon - */ EAPI void elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth) { @@ -821,14 +735,6 @@ elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth) _sizing_eval(obj); } -/** - * Get the smooth effect for an icon - * - * @param obj The icon object - * @return If setted smooth effect - * - * @ingroup Icon - */ EAPI Eina_Bool elm_icon_smooth_get(const Evas_Object *obj) { @@ -839,15 +745,6 @@ elm_icon_smooth_get(const Evas_Object *obj) return wd->smooth; } -/** - * Set if the object is scalable - * - * @param obj The icon object - * @param no_scale A bool to set scale (or no) - * (1 = no_scale, 0 = scale) - * - * @ingroup Icon - */ EAPI void elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) { @@ -859,14 +756,6 @@ elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) _sizing_eval(obj); } -/** - * Get if the object isn't scalable - * - * @param obj The icon object - * @return If isn't scalable - * - * @ingroup Icon - */ EAPI Eina_Bool elm_icon_no_scale_get(const Evas_Object *obj) { @@ -876,15 +765,6 @@ elm_icon_no_scale_get(const Evas_Object *obj) return wd->no_scale; } -/** - * Set if the object is (up/down) scalable - * - * @param obj The icon object - * @param scale_up A bool to set if the object is scalable up - * @param scale_down A bool to set if the object is scalable down - * - * @ingroup Icon - */ EAPI void elm_icon_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) { @@ -897,15 +777,6 @@ elm_icon_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) _sizing_eval(obj); } -/** - * Get if the object is (up/down) scalable - * - * @param obj The icon object - * @param scale_up A bool to set if the object is scalable up - * @param scale_down A bool to set if the object is scalable down - * - * @ingroup Icon - */ EAPI void elm_icon_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) { @@ -916,15 +787,6 @@ elm_icon_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale if (scale_down) *scale_down = wd->scale_down; } -/** - * Set if the object is filled outside - * - * @param obj The icon object - * @param fill_outside A bool to set if the object is filled outside - * (1 = filled, 0 = no filled) - * - * @ingroup Icon - */ EAPI void elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) { @@ -936,14 +798,6 @@ elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) _sizing_eval(obj); } -/** - * Get if the object is filled outside - * - * @param obj The icon object - * @return If the object is filled outside - * - * @ingroup Icon - */ EAPI Eina_Bool elm_icon_fill_outside_get(const Evas_Object *obj) { @@ -954,14 +808,6 @@ elm_icon_fill_outside_get(const Evas_Object *obj) return wd->fill_outside; } -/** - * Set the prescale size for the icon - * - * @param obj The icon object - * @param size The prescale size - * - * @ingroup Icon - */ EAPI void elm_icon_prescale_set(Evas_Object *obj, int size) { @@ -972,14 +818,6 @@ elm_icon_prescale_set(Evas_Object *obj, int size) _els_smart_icon_scale_size_set(wd->img, size); } -/** - * Get the prescale size for the icon - * - * @param obj The icon object - * @return The prescale size - * - * @ingroup Icon - */ EAPI int elm_icon_prescale_get(const Evas_Object *obj) {