Elementary migration revision 70341
[framework/uifw/elementary.git] / src / lib / elm_bg.h
1 /**
2  * @defgroup Bg Bg
3  * @ingroup Elementary
4  *
5  * @image html img/widget/bg/preview-00.png
6  * @image latex img/widget/bg/preview-00.eps
7  *
8  * @brief Background object, used for setting a solid color, image or
9  * Edje group as a background to a window or any container object.
10  *
11  * The bg (background) widget is used for setting (solid) background
12  * decorations to a window (unless it has transparency enabled) or to
13  * any container object. It works just like an image, but has some
14  * properties useful to a background, like setting it to tiled,
15  * centered, scaled or stretched.
16  *
17  * Default content parts of the bg widget that you can use for are:
18  * @li "overlay" - overlay of the bg
19  *
20  * Supported elm_object common APIs.
21  * @li @ref elm_object_part_content_set
22  * @li @ref elm_object_part_content_get
23  * @li @ref elm_object_part_content_unset
24  *
25  * Here is some sample code using it:
26  * @li @ref bg_01_example_page
27  * @li @ref bg_02_example_page
28  * @li @ref bg_03_example_page
29  */
30
31 /**
32  * Identifiers on how a background widget is to display its image --
33  * if it was set to use an image file.
34  *
35  * @see elm_bg_option_set()
36  * @see elm_bg_option_get()
37  *
38  * @ingroup Bg
39  */
40 typedef enum
41 {
42    ELM_BG_OPTION_CENTER, /**< center the background image */
43    ELM_BG_OPTION_SCALE, /**< scale the background image, retaining aspect ratio */
44    ELM_BG_OPTION_STRETCH, /**< stretch the background image to fill the widget's area */
45    ELM_BG_OPTION_TILE, /**< tile background image at its original size */
46    ELM_BG_OPTION_LAST /**< sentinel value, also used to indicate errors */
47 } Elm_Bg_Option;
48
49 /**
50  * Add a new background to the parent
51  *
52  * @param parent The parent object
53  * @return The new object or NULL if it cannot be created
54  *
55  * @ingroup Bg
56  */
57 EAPI Evas_Object                 *elm_bg_add(Evas_Object *parent);
58
59 /**
60  * Set the file (image or edje collection) to give life for the
61  * background
62  *
63  * @param obj The background object handle
64  * @param file The file path
65  * @param group Optional key (group in Edje) within the file
66  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
67  *
68  * This sets the image file used in the background object. If the
69  * image comes from an Edje group, it will be stretched to completely
70  * fill the background object. If it comes from a traditional image file, it
71  * will by default be centered in this widget's are (thus retaining
72  * its aspect), what could lead to some parts being not visible. You
73  * may change the mode of exhibition for a real image file with
74  * elm_bg_option_set().
75  *
76  * @note Once the image of @p obj is set, a previously set one will be
77  * deleted, even if @p file is NULL.
78  *
79  * @note This will only affect the contents of one of the background's
80  * swallow spots, namely @c "elm.swallow.background". If you want to
81  * achieve the @c Layout's file setting behavior, you'll have to call
82  * that method on this object.
83  *
84  * @ingroup Bg
85  */
86 EAPI Eina_Bool                    elm_bg_file_set(Evas_Object *obj, const char *file, const char *group);
87
88 /**
89  * Get the file (image or edje collection) set on a given background
90  * widget
91  *
92  * @param obj The background object handle
93  * @param file Where to store the requested file's path
94  * @param group Where to store the optional key within @a file, @b if
95  * it's an Edje file
96  *
97  * @note Use @c NULL pointers on the file components you're not
98  * interested in: they'll be ignored by the function.
99  *
100  * @ingroup Bg
101  */
102 EAPI void                         elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group);
103
104 /**
105  * Set the mode of display for a given background widget's image
106  *
107  * @param obj The background object handle
108  * @param option The desired background option (see #Elm_Bg_Option)
109  *
110  * This sets how the background widget will display its image. This
111  * will only work if the elm_bg_file_set() was previously called with
112  * an image file on @a obj. The image can be display tiled, scaled,
113  * centered or stretched.
114  *
115  * @see elm_bg_option_get()
116  *
117  * @ingroup Bg
118  */
119 EAPI void                         elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option);
120
121 /**
122  * Get the mode of display for a given background widget's image
123  *
124  * @param obj The background object handle
125  * @return The image displaying mode in use for @a obj or
126  * #ELM_BG_OPTION_LAST, on errors.
127  *
128  * @see elm_bg_option_set() for more details
129  *
130  * @ingroup Bg
131  */
132 EAPI Elm_Bg_Option                elm_bg_option_get(const Evas_Object *obj);
133
134 /**
135  * Set the color on a given background widget
136  *
137  * @param obj The background object handle
138  * @param r The red color component's value
139  * @param g The green color component's value
140  * @param b The blue color component's value
141  *
142  * This sets the color used for the background rectangle, in RGB
143  * format. Each color component's range is from 0 to 255.
144  *
145  * @note You probably only want to use this function if you haven't
146  * previously called elm_bg_file_set(), so that you just want a solid
147  * color background.
148  *
149  * @see elm_bg_color_get()
150  *
151  * @ingroup Bg
152  */
153 EAPI void                         elm_bg_color_set(Evas_Object *obj, int r, int g, int b);
154
155 /**
156  * Get the color set on a given background widget
157  *
158  * @param obj The background object handle
159  * @param r Where to store the red color component's value
160  * @param g Where to store the green color component's value
161  * @param b Where to store the blue color component's value
162  *
163  * @note Use @c NULL pointers on the file components you're not
164  * interested in: they'll be ignored by the function.
165  *
166  * @see elm_bg_color_get() for more details
167  *
168  * @ingroup Bg
169  */
170 EAPI void                         elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b);
171
172 /**
173  * Set the size of the pixmap representation of the image set on a
174  * given background widget.
175  *
176  * @param obj The background object handle
177  * @param w The new width of the image pixmap representation.
178  * @param h The new height of the image pixmap representation.
179  *
180  * @warning This function just makes sense if an image file was set on
181  * @p obj, with elm_bg_file_set().
182  *
183  * This function sets a new size for pixmap representation of the
184  * given bg image. It allows for the image to be loaded already in the
185  * specified size, reducing the memory usage and load time (for
186  * example, when loading a big image file with its load size set to a
187  * smaller size)
188  *
189  * @note This is just a hint for the underlying system. The real size
190  * of the pixmap may differ depending on the type of image being
191  * loaded, being bigger than requested.
192  *
193  * @ingroup Bg
194  */
195 EAPI void                         elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
196
197 /**
198  * @}
199  */