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