2 * @defgroup Bg Background
5 * @image html bg_inheritance_tree.png
6 * @image latex bg_inheritance_tree.eps
8 * @image html img/widget/bg/preview-00.png
9 * @image latex img/widget/bg/preview-00.eps
11 * @brief Background object, used for setting a solid color, image or
12 * Edje group as a background to a window or any container object.
14 * The bg (background) widget is used for setting (solid) background
15 * decorations to a window (unless it has transparency enabled) or to
16 * any container object. It works just like an image, but has some
17 * properties useful to a background, like setting it to tiled,
18 * centered, scaled or stretched.
20 * This widget inherits from the @ref Layout one, so that all the
21 * functions acting on it also work for background objects.
23 * Default content parts of the bg widget that you can use for are:
24 * @li @c "overlay" - overlay of the bg
26 * Here is some sample code using it:
27 * @li @ref bg_01_example_page
28 * @li @ref bg_02_example_page
29 * @li @ref bg_03_example_page
33 * Identifiers on how a background widget is to display its image --
34 * if it was set to use an image file.
36 * @see elm_bg_option_set()
37 * @see elm_bg_option_get()
43 ELM_BG_OPTION_CENTER, /**< center the background image */
44 ELM_BG_OPTION_SCALE, /**< scale the background image, retaining aspect ratio */
45 ELM_BG_OPTION_STRETCH, /**< stretch the background image to fill the widget's area */
46 ELM_BG_OPTION_TILE, /**< tile background image at its original size */
47 ELM_BG_OPTION_LAST /**< sentinel value, also used to indicate errors */
51 * Add a new background to the parent
53 * @param parent The parent object
54 * @return The new object or @c NULL if it cannot be created
58 EAPI Evas_Object *elm_bg_add(Evas_Object *parent);
61 * Set the file (image or edje collection) to give life for the
64 * @param obj The background object handle
65 * @param file The file path
66 * @param group Optional key (group in Edje) within the file
67 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
69 * This sets the image file used in the background object. If the
70 * image comes from an Edje group, it will be stretched to completely
71 * fill the background object. If it comes from a traditional image file, it
72 * will by default be centered in this widget's are (thus retaining
73 * its aspect), what could lead to some parts being not visible. You
74 * may change the mode of exhibition for a real image file with
75 * elm_bg_option_set().
77 * @note Once the image of @p obj is set, a previously set one will be
78 * deleted, even if @p file is @c NULL.
80 * @note This will only affect the contents of one of the background's
81 * swallow spots, namely @c "elm.swallow.background". If you want to
82 * achieve the @c Layout's file setting behavior, you'll have to call
83 * that method on this object.
87 EAPI Eina_Bool elm_bg_file_set(Evas_Object *obj, const char *file, const char *group);
90 * Get the file (image or edje collection) set on a given background
93 * @param obj The background object handle
94 * @param file Where to store the requested file's path
95 * @param group Where to store the optional key within @a file, @b if
98 * @note Use @c NULL pointers on the file components you're not
99 * interested in: they'll be ignored by the function.
103 EAPI void elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group);
106 * Set the mode of display for a given background widget's image
108 * @param obj The background object handle
109 * @param option The desired background option (see #Elm_Bg_Option)
111 * This sets how the background widget will display its image. This
112 * will only work if the elm_bg_file_set() was previously called with
113 * an image file on @a obj. The image can be display tiled, scaled,
114 * centered or stretched.
116 * @see elm_bg_option_get()
120 EAPI void elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option);
123 * Get the mode of display for a given background widget's image
125 * @param obj The background object handle
126 * @return The image displaying mode in use for @a obj or #ELM_BG_OPTION_LAST,
129 * @see elm_bg_option_set() for more details
133 EAPI Elm_Bg_Option elm_bg_option_get(const Evas_Object *obj);
136 * Set the color on a given background widget
138 * @param obj The background object handle
139 * @param r The red color component's value
140 * @param g The green color component's value
141 * @param b The blue color component's value
143 * This sets the color used for the background rectangle, in RGB
144 * format. Each color component's range is from 0 to 255.
146 * @note You probably only want to use this function if you haven't
147 * previously called elm_bg_file_set(), so that you just want a solid
150 * @see elm_bg_color_get()
154 EAPI void elm_bg_color_set(Evas_Object *obj, int r, int g, int b);
157 * Get the color set on a given background widget
159 * @param obj The background object handle
160 * @param r Where to store the red color component's value
161 * @param g Where to store the green color component's value
162 * @param b Where to store the blue color component's value
164 * @note Use @c NULL pointers on the file components you're not
165 * interested in: they'll be ignored by the function.
167 * @see elm_bg_color_get() for more details
171 EAPI void elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b);
174 * Set the size of the pixmap representation of the image set on a
175 * given background widget.
177 * @param obj The background object handle
178 * @param w The new width of the image pixmap representation.
179 * @param h The new height of the image pixmap representation.
181 * @warning This function just makes sense if an image file was set on
182 * @p obj, with elm_bg_file_set().
184 * This function sets a new size for pixmap representation of the
185 * given bg image. It allows for the image to be loaded already in the
186 * specified size, reducing the memory usage and load time (for
187 * example, when loading a big image file with its load size set to a
190 * @note This is just a hint for the underlying system. The real size
191 * of the pixmap may differ depending on the type of image being
192 * loaded, being bigger than requested.
196 EAPI void elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);