elm::bg - Image background using C++ binding

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

The first part consists of including the headers. In this case we are only working with the Elementary C++ binding and thus we need only to include him.

#include <Elementary.hh>

Attention
If necessary the C and/or the C++ headers should be include here as well.

Now we need to actually start the code and set the elm_policy, which defines for a given policy group/identifier a new policy's value, respectively. In this example the only policy we need to set a value for is ELM_POLICY_QUIT, possibles values for it are:

EAPI_MAIN int
elm_main (int argc, char *argv[])
{
elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN);

As you can see, the policy we chose was to quit when the last win is hidden as opose to examples with the C bindings where we perpetually set it to quit when last win was closed. This changed was necessary because in C++ binding as the elm mainloop stop running all object are destroyed, references are unreferenced and events are stopped at ELM_MAIN().

See also
For more details consult elm_policy_set

Next step is creating an Elementary window, where win calls a constructor and sets the type of the win to ELM_WIN_BASIC (Elm_Win_Type), which is the indicated type for most of our examples. Here we also set the title that will appear at the top of our window and then the autohide state for it.

The autohide works similarly to autodel, automatically handling "delete,request" signals when set to true, with the difference that it will hide the window, instead of destroying it.

It is specially designed to work together with ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting Elementary's main loop when all the windows are hidden.

win.title_set("Bg Image");
win.autohide_set(true);

Note
autodel and autohide are not mutually exclusive. The window will be destructed if both autodel and autohide is set to EINA_TRUE or true.

Our background will have an image, that will be displayed over the background color.

To do so, first we set the directory and archive for the image. And create the background that will display it.

elm_app_info_set(reinterpret_cast<void*>(elm_main), "elementary", "images/plant_01.jpg");
::elm::bg bg(efl::eo::parent = win);

Before loading this 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):

bg.load_size_set(20,20);

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

bg.option_set(ELM_BG_OPTION_CENTER);

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 std::stringstream. Then we use this stringstream to set the file name in the background object:

std::stringstream ss;
ss << elm_app_data_dir_get() << "/images/plant_01.jpg";
bg.file_set(ss.str(), nullptr);

Notice that the second argument of the file_set() function is nullptr, since we are setting an image to this background. This function also supports setting an Eet file as background, in which case the key parameter wouldn't be nullptr, but be the name of the Eet key instead.

To better understand, the function size_hint_weight_set for C++ bindings originated from C bindings function evas_object_size_hint_weight_set, that is EFL Evas type function. With this function we set the hints for an object's weight. The parameters are:

This is not a size enforcement in any way, it's just a hint that should be used whenever appropriate.

This is a hint on how a container object should resize a given child within its area.

Containers may adhere to the simpler logic of just expanding the child object's dimensions to fit its own (see the EVAS_HINT_EXPAND helper weight macro in the EFL Evas Documentation) or the complete one of taking each child's weight hint as real weights to how much of its size to allocate for them in each axis. A container is supposed to, after normalizing the weights of its children (with weight hints), distribute the space it has to layout them by those factors – most weighted children get larger in this process than the least ones.

bg.size_hint_weight_set(EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);

Note
Default weight hint values are 0.0, for both axis.

Now we add the background as a resize_object to win informing that when the size of the win changes so should the background's size. And finally we make background.

Now we only have to set the size for our window and make it visible.

Finally we just have to start the elm mainloop, starting to handle events and drawing operations.

The full code for this example can be found at bg_cxx_example_02.cc .

This example will look like this:

bg_cxx_example_02.png