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
This commit is contained in:
Rafael Antognolli 2011-07-18 18:14:34 +00:00
parent 084496a834
commit f80e0b884f
2 changed files with 334 additions and 166 deletions

View File

@ -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
/**
* @}
*/
/**

View File

@ -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)
{