From 77eb15359d96864a80a737e0dc28c184c7bf0919 Mon Sep 17 00:00:00 2001 From: glima Date: Tue, 6 Mar 2012 22:12:42 +0000 Subject: [PATCH] [Elm] Now applying some more ret. values on bg. Also bumping docs, as I had to fix them. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/elementary@68854 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/lib/elm_bg.c | 44 +++++++++------ src/lib/elm_bg.h | 166 ++++++++++++++++++++++++++++++++++++------------------- 2 files changed, 137 insertions(+), 73 deletions(-) diff --git a/src/lib/elm_bg.c b/src/lib/elm_bg.c index 6782f9e..4d507e0 100644 --- a/src/lib/elm_bg.c +++ b/src/lib/elm_bg.c @@ -201,10 +201,10 @@ elm_bg_add(Evas_Object *parent) return obj; } -EAPI void +EAPI Eina_Bool elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) { - ELM_CHECK_WIDTYPE(obj, widtype); + ELM_CHECK_WIDTYPE(obj, widtype) EINA_FALSE; Widget_Data *wd = elm_widget_data_get(obj); const char *p; @@ -219,7 +219,7 @@ elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) wd->file = NULL; eina_stringshare_del(wd->group); wd->group = NULL; - return; + return EINA_TRUE; } eina_stringshare_replace(&wd->file, file); eina_stringshare_replace(&wd->group, group); @@ -239,42 +239,48 @@ elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) edje_object_part_swallow(wd->base, "elm.swallow.background", wd->img); elm_widget_sub_object_add(obj, wd->img); _custom_resize(wd, NULL, NULL, NULL); + + return EINA_TRUE; } -EAPI void +EAPI Eina_Bool elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group) { - ELM_CHECK_WIDTYPE(obj, widtype); + ELM_CHECK_WIDTYPE(obj, widtype) EINA_FALSE; Widget_Data *wd = elm_widget_data_get(obj); if (file) *file = wd->file; if (group) *group = wd->group; + + return EINA_TRUE; } -EAPI void +EAPI Eina_Bool elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option) { - ELM_CHECK_WIDTYPE(obj, widtype); + ELM_CHECK_WIDTYPE(obj, widtype) EINA_FALSE; Widget_Data *wd; wd = elm_widget_data_get(obj); wd->option = option; _custom_resize(wd, NULL, NULL, NULL); + + return EINA_TRUE; } EAPI Elm_Bg_Option elm_bg_option_get(const Evas_Object *obj) { - ELM_CHECK_WIDTYPE(obj, widtype) 0; + ELM_CHECK_WIDTYPE(obj, widtype) ELM_BG_OPTION_LAST; Widget_Data *wd; wd = elm_widget_data_get(obj); return wd->option; } -EAPI void +EAPI Eina_Bool elm_bg_color_set(Evas_Object *obj, int r, int g, int b) { - ELM_CHECK_WIDTYPE(obj, widtype); + ELM_CHECK_WIDTYPE(obj, widtype) EINA_FALSE; Widget_Data *wd; wd = elm_widget_data_get(obj); @@ -286,29 +292,35 @@ elm_bg_color_set(Evas_Object *obj, int r, int g, int b) _custom_resize(wd, NULL, NULL, NULL); } evas_object_color_set(wd->rect, r, g, b, 255); + + return EINA_TRUE; } -EAPI void +EAPI Eina_Bool elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b) { - ELM_CHECK_WIDTYPE(obj, widtype); + ELM_CHECK_WIDTYPE(obj, widtype) EINA_FALSE; Widget_Data *wd; wd = elm_widget_data_get(obj); evas_object_color_get(wd->rect, r, g, b, NULL); + + return EINA_TRUE; } -EAPI void +EAPI Eina_Bool elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) { - ELM_CHECK_WIDTYPE(obj, widtype); + ELM_CHECK_WIDTYPE(obj, widtype) EINA_FALSE; Widget_Data *wd = elm_widget_data_get(obj); const char *p; - if (!wd) return; + if (!wd) return EINA_FALSE; wd->load_opts.w = w; wd->load_opts.h = h; - if (!wd->img) return; + if (!wd->img) return EINA_FALSE; if (!(((p = strrchr(wd->file, '.'))) && (!strcasecmp(p, ".edj")))) evas_object_image_load_size_set(wd->img, w, h); + + return EINA_TRUE; } diff --git a/src/lib/elm_bg.h b/src/lib/elm_bg.h index 0feff07..1af2aa3 100644 --- a/src/lib/elm_bg.h +++ b/src/lib/elm_bg.h @@ -4,12 +4,13 @@ * @image html img/widget/bg/preview-00.png * @image latex img/widget/bg/preview-00.eps * - * @brief Background object, used for setting a solid color, image or Edje - * group as background to a window or any container object. + * @brief Background object, used for setting a solid color, image or + * Edje group as a background to a window or any container object. * - * The bg object is used for setting a solid background to a window or - * packing into any container object. It works just like an image, but has - * some properties useful to a background, like setting it to tiled, + * The bg (background) widget is used for setting (solid) background + * decorations to a window (unless it has transparency enabled) or to + * any container object. It works just like an image, but has some + * properties useful to a background, like setting it to tiled, * centered, scaled or stretched. * * Default content parts of the bg widget that you can use for are: @@ -26,13 +27,20 @@ * @li @ref bg_03_example_page */ -/* bg */ +/** + * Identifiers on how a background widget is to display its image -- + * if it was tset to use an image file. + * + * @see elm_bg_option_set() + * @see elm_bg_option_get() + */ typedef enum { - ELM_BG_OPTION_CENTER, /**< center the background */ - ELM_BG_OPTION_SCALE, /**< scale the background retaining aspect ratio */ - ELM_BG_OPTION_STRETCH, /**< stretch the background to fill */ - ELM_BG_OPTION_TILE /**< tile background at its original size */ + ELM_BG_OPTION_CENTER, /**< center the background image */ + ELM_BG_OPTION_SCALE, /**< scale the background image, retaining aspect ratio */ + ELM_BG_OPTION_STRETCH, /**< stretch the background image to fill the widget's area */ + ELM_BG_OPTION_TILE, /**< tile background image at its original size */ + ELM_BG_OPTION_LAST /**< sentinel value, also used to indicate errors */ } Elm_Bg_Option; /** @@ -46,102 +54,146 @@ typedef enum EAPI Evas_Object *elm_bg_add(Evas_Object *parent); /** - * Set the file (image or edje) used for the background + * Set the file (image or edje collection) to give life for the + * background * - * @param obj The bg object + * @param obj The background object handle * @param file The file path * @param group Optional key (group in Edje) within the file + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise * - * This sets the image file used in the background object. The image (or edje) - * will be stretched (retaining aspect if its an image file) to completely fill - * the bg object. This may mean some parts are not visible. + * This sets the image file used in the background object. If the + * image comes from an Edje group, it will be stretched to completely + * fill the background object. If it comes from a traditional image file, it + * will by default be centered in this widget's are (thus retaining + * its aspect), what could lead to some parts being not visible. You + * may change the mode of exhibition for a real image file with + * elm_bg_option_set(). * - * @note Once the image of @p obj is set, a previously set one will be deleted, - * even if @p file is NULL. + * @note Once the image of @p obj is set, a previously set one will be + * deleted, even if @p file is NULL. + * + * @note This will only affect the contents of one of the background's + * swallow spots, namely @c "elm.swallow.background". If you want to + * achieve the @c Layout's file setting behavior, you'll have to call + * that method on this object. * * @ingroup Bg */ -EAPI void elm_bg_file_set(Evas_Object *obj, const char *file, const char *group); +EAPI Eina_Bool elm_bg_file_set(Evas_Object *obj, const char *file, const char *group); /** - * Get the file (image or edje) used for the background + * Get the file (image or edje collection) set on a given background + * widget * - * @param obj The bg object - * @param file The file path - * @param group Optional key (group in Edje) within the file + * @param obj The background object handle + * @param file Where to store the requested file's path + * @param group Where to store the optional key within @a file, @b if + * it's an Edje file + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise + * + * @note Use @c NULL pointers on the file components you're not + * interested in: they'll be ignored by the function. * * @ingroup Bg */ -EAPI void elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group); +EAPI Eina_Bool elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group); /** - * Set the option used for the background image + * Set the mode of display for a given background widget's image * - * @param obj The bg object - * @param option The desired background option (TILE, SCALE) + * @param obj The background object handle + * @param option The desired background option (see #Elm_Bg_Option) + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise * - * This sets the option used for manipulating the display of the background - * image. The image can be tiled or scaled. + * This sets how the background widget will display its image. This + * will only work if the elm_bg_file_set() was previously called with + * an image file on @a obj. The image can be display tiled, scaled, + * centered or streched. + * + * @see elm_bg_option_get() * * @ingroup Bg */ -EAPI void elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option); +EAPI Eina_Bool elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option); /** - * Get the option used for the background image + * Get the mode of display for a given background widget's image + * + * @param obj The background object handle + * @return The image displaying mode in use for @a obj or + * #ELM_BG_OPTION_LAST, on errors. * - * @param obj The bg object - * @return The desired background option (CENTER, SCALE, STRETCH or TILE) + * @see elm_bg_option_set() for more details * * @ingroup Bg */ EAPI Elm_Bg_Option elm_bg_option_get(const Evas_Object *obj); + /** - * Set the option used for the background color + * Set the color on a given background widget + * + * @param obj The background object handle + * @param r The red color component's value + * @param g The green color component's value + * @param b The blue color component's value + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise * - * @param obj The bg object - * @param r - * @param g - * @param b + * This sets the color used for the background rectangle, in RGB + * format. Each color component's range is from 0 to 255. * - * This sets the color used for the background rectangle. Its range goes - * from 0 to 255. + * @note You probably only want to use this function if you haven't + * previously called elm_bg_file_set(), so that you just want a solid + * color background. + * + * @see elm_bg_color_get() * * @ingroup Bg */ -EAPI void elm_bg_color_set(Evas_Object *obj, int r, int g, int b); +EAPI Eina_Bool elm_bg_color_set(Evas_Object *obj, int r, int g, int b); + /** - * Get the option used for the background color + * Get the color set on a given background widget * - * @param obj The bg object - * @param r - * @param g - * @param b + * @param obj The background object handle + * @param r Where to store the red color component's value + * @param g Where to store the green color component's value + * @param b Where to store the blue color component's value + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise + * + * @note Use @c NULL pointers on the file components you're not + * interested in: they'll be ignored by the function. + * + * @see elm_bg_color_get() for more details * * @ingroup Bg */ -EAPI void elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b); +EAPI Eina_Bool elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b); /** - * Set the size of the pixmap representation of the image. + * Set the size of the pixmap representation of the image set on a + * given background widget. * - * This option just makes sense if an image is going to be set in the bg. - * - * @param obj The bg object + * @param obj The background object handle * @param w The new width of the image pixmap representation. * @param h The new height of the image pixmap representation. * - * This function sets a new size for pixmap representation of the given bg - * image. It allows the image to be loaded already in the specified size, - * reducing the memory usage and load time when loading a big image with load - * size set to a smaller size. + * @warning This function just makes sense if an image file was set on + * @p obj, with elm_bg_file_set(). + * + * This function sets a new size for pixmap representation of the + * given bg image. It allows for the image to be loaded already in the + * specified size, reducing the memory usage and load time (for + * example, when loading a big image file with its load size set to a + * smaller size) * - * NOTE: this is just a hint, the real size of the pixmap may differ - * depending on the type of image being loaded, being bigger than requested. + * @note This is just a hint for the underlying system. The real size + * of the pixmap may differ depending on the type of image being + * loaded, being bigger than requested. * * @ingroup Bg */ -EAPI void elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h); +EAPI Eina_Bool elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h); /** * @} -- 2.7.4