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:8646
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:6199
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:9555
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:9002
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: