elm_bg - Image background.

The full code for this example can be found at bg_example_02.c, in the function `test_bg_image`. It's part of the `elementary_test` suite, and thus has the code for the three examples referenced by this documentation.

This is the second example, and shows how to use the Elementary background object to set an image as background of your application.

We start this example exactly in the same way as the previous one, even when creating the background object:

elm_main(int argc EINA_UNUSED, char **argv EINA_UNUSED)
{
Evas_Object *win, *bg;
char buf[PATH_MAX];
elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
elm_app_info_set(elm_main, "elementary", "images/plant_01.jpg");
win = elm_win_add(NULL, "bg-image", ELM_WIN_BASIC);
elm_win_title_set(win, "Bg Image");
elm_win_autodel_set(win, EINA_TRUE);
bg = elm_bg_add(win);
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition: eina_types.h:339
elm_app_info_set
void elm_app_info_set(void *mainfunc, const char *dom, const char *checkfile)
Re-locate the application somewhere else after compilation, if the developer wishes for easier distri...
Definition: elm_main.c:496
elm_bg_add
Evas_Object * elm_bg_add(Evas_Object *parent)
Adds a new background to the parent.
Definition: efl_ui_bg.c:304
elm_policy_set
Eina_Bool elm_policy_set(unsigned int policy, int value)
Set a new policy's value (for a given policy group/identifier).
Definition: elm_main.c:1380
ELM_POLICY_QUIT_LAST_WINDOW_CLOSED
@ ELM_POLICY_QUIT_LAST_WINDOW_CLOSED
quit when the application's last window is closed
Definition: elm_general.h:248
ELM_POLICY_QUIT
@ ELM_POLICY_QUIT
under which circumstances the application should quit automatically.
Definition: elm_general.h:227
elm_win_title_set
void elm_win_title_set(Evas_Object *obj, const char *title)
Set the title of the window.
Definition: efl_ui_win.c:8636
elm_win_autodel_set
void elm_win_autodel_set(Eo *obj, Eina_Bool autodel)
Set the window's autodel state.
Definition: efl_ui_win.c:6189
elm_win_add
Evas_Object * elm_win_add(Evas_Object *parent, const char *name, Elm_Win_Type type)
Adds a window object.
Definition: efl_ui_win.c:9544
ELM_WIN_BASIC
@ ELM_WIN_BASIC
A normal window.
Definition: elm_win_legacy.h:65
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition: Evas_Common.h:185

Now it's the different part.

Our background will have an image, that will be displayed over the background color. Before loading the image, we set the load size of the image. The load size is a hint about the size that we want the image displayed in the screen. It's not the exact size that the image will have, but usually a bit bigger. The background object can still be scaled to a size bigger than the one set here. Setting the image load size to something smaller than its real size will reduce the memory used to keep the pixmap representation of the image, and the time to load it. Here we set the load size to 20x20 pixels, but the image is loaded with a size bigger than that (since it's just a hint):

elm_bg_load_size_set(bg, 20, 20);
elm_bg_load_size_set
void elm_bg_load_size_set(Evas_Object *obj, int w, int h)
Sets the size of the pixmap representation of the image set on a given background widget.
Definition: efl_ui_bg.c:181

And set our background image to be centered, instead of stretched or scaled, so the effect of the elm_bg_load_size_set() can be easily understood:

elm_bg_option_set(bg, ELM_BG_OPTION_CENTER);
elm_bg_option_set
void elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option)
Sets the mode of display for a given background widget's image.
Definition: efl_ui_bg.c:82
ELM_BG_OPTION_CENTER
@ ELM_BG_OPTION_CENTER
Center the background image.
Definition: elm_bg_legacy.h:12

We need a filename to set, so we get one from the previous installed images in the `PACKAGE_DATA_DIR`, and write its full path to a buffer. Then we use this buffer to set the filename in the background object:

snprintf(buf, sizeof(buf), "%s/images/plant_01.jpg", elm_app_data_dir_get());
elm_bg_file_set(bg, buf, NULL);
elm_app_data_dir_get
const char * elm_app_data_dir_get(void)
Get the application's run time data prefix directory, as set by elm_app_info_set() and the way (envir...
Definition: elm_main.c:586
elm_bg_file_set
Eina_Bool elm_bg_file_set(Eo *obj, const char *file, const char *group)
Sets the file (image or edje collection) to give life for the background.
Definition: efl_ui_bg.c:188

Notice that the third argument of the elm_bg_file_set() function is `NULL`, since we are setting an image to this background. This function also supports setting an edje group as background, in which case the `group` parameter wouldn't be `NULL`, but be the name of the group instead.

Finally, we can set the size hints, add the background as a resize object, and resize the window, exactly the same thing we do in the elm_bg - Plain color background. example:

evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_win_resize_object_add(win, bg);
evas_object_show(bg);
evas_object_resize(win, 320, 320);
evas_object_show(win);
elm_run();
return 0;
}
EVAS_HINT_EXPAND
#define EVAS_HINT_EXPAND
Use with evas_object_size_hint_weight_set(), evas_object_size_hint_weight_get(), evas_object_size_hin...
Definition: Evas_Common.h:297
elm_run
void elm_run(void)
Run Elementary's main loop.
Definition: elm_main.c:1357
elm_win_resize_object_add
void elm_win_resize_object_add(Eo *obj, Evas_Object *subobj)
Add subobj as a resize object of window obj.
Definition: efl_ui_win.c:8992
evas_object_show
EVAS_API void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition: evas_object_main.c:1814
evas_object_size_hint_weight_set
EVAS_API void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y)
Sets the hints for an object's weight.
Definition: evas_object_main.c:2638
evas_object_resize
EVAS_API void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition: evas_object_main.c:1236

And this is the end of this example.

This example will look like this: