Box Container

Most of the time, you want to display widgets on the screen in a specific order. In Form Tutorial, for example, the user information is arranged vertically. This basic container is called a box. There is no theme for a box layout. It is just a linear method of arranging widgets horizontally or vertically.

Table of Contents

Creating a Box

By default, the box will start in the vertical orientation, placing its elements ordered from top to bottom.

To create a new vertical box:

Evas_Object *vbox = elm_box_add(parent);

By default, the elm_box_add() function creates a vertical box. If you want to create a horizontal box, use the function:

To change the orientation, use elm_box_horizontal_set() function. When horizontal is set, the order will go from left to right.

Evas_Object *hbox = elm_box_add(parent);
elm_box_horizontal_set(hbox, EINA_TRUE);
A box is a non-graphical object. It adds no graphics to or around the objects it holds.

Addind Objects to the Box

You can add any Evas object to the box. There are multiples ways to add an object to a box, 4 functions can be used:

elm_box_pack_end()Add an object at the end of the pack list.

Pack the object into the box, placing it last in the list of children objects. The actual position the object will get on screen depends on the layout used. If no custom layout is set, it will be at the bottom or right, depending if the box is vertical or horizontal, respectively.
elm_box_pack_start()Add an object to the beginning of the pack list.

Pack object into the box, placing it first in the list of children objects. The actual position the object will get on screen depends on the layout used. If no custom layout is set, it will be at the top or left, depending if the box is vertical or horizontal, respectively.
elm_box_pack_before()Adds an object to the box before the indicated object.

This will add the object to the box indicated before the object indicated with before. If before is not already in the box, results are undefined. Before means either to the left of the indicated object or above it depending on orientation.
elm_box_pack_after()Adds an object to the box after the indicated object.

This will add the object to the box indicated after the object indicated with after. If after is not already in the box, results are undefined. After means either to the right of the indicated object or below it depending on orientation.

Below, an example shows how works these 4 functions. First, 2 button widgets are added to the box with elm_box_pack_end() then elm_box_pack_before() function adds a button before the last added button and elm_box_pack_start() adds a button at the top of the box list. Finally a button is added just after the top button in the box list with elm_box_pach_after():

Evas_Object *bt_end, *bt_start, *bt_before, *bt_after;
int i;
char tmp[16];
//add 2 buttons
for (i = 0; i < 2; i++)
     snprintf(tmp, sizeof(tmp), "Button %d", i);
     bt_end = elm_button_add(vbox);
     elm_object_text_set(bt_end, tmp);
     elm_box_pack_end(vbox, bt_end);
//add bt_before before bt_end(button 1)
bt_before = elm_button_add(vbox);
elm_object_text_set(bt_before, "Button Before");
elm_box_pack_before(vbox, bt_before, bt_end);
//add bt_start
bt_start = elm_button_add(vbox);
elm_object_text_set(bt_start, "Button Start");
elm_box_pack_start(vbox, bt_start);
//add bt_start
bt_after = elm_button_add(vbox);
elm_object_text_set(bt_after, "Button After");
elm_box_pack_after(vbox, bt_after,bt_start);

Setting the Padding

You can set the padding between the objects in a box by using the elm_box_padding_set() function. The padding values are the number of pixels horizontally and vertically.

elm_box_padding_set(vbox, 16, 6);

Handling Element Size

You can add different-size elements to a container. For example, to add an image with a size of 128×128 pixels as the first element in a box, use the elm_box_pack_start() function:

Evas_Object *ic = elm_icon_add(vbox);
elm_image_file_set(ic, "./c1.png", NULL);
evas_object_size_hint_min_set(ic, 128, 128);
elm_box_pack_start(vbox, ic);

We ask Evas to set the size hint for the icon object by using the elm_object_size_hint_min_set() function. Evas will try to set the minimum size of this object accordingly.

If you want to create a homogeneous box, where all objects have the same height or width, depending on the orientation of the box, use the elm_box_homogeneous_set() function:

elm_box_homogeneous_set(vbox, EINA_TRUE);

Elementary will set the height of the tallest object as the height of all objects, or the width of the widest element as the width of all objects.

Setting the Alignment

You can set the alignment of widgets inside a box using the elm_box_align_set() function. The function takes two doubles values, a horizontal value and a vertical value, representing the percentage between 0 and 1.0 of the alignment in the horizontal and vertical axes. When you add a widget with the elm_box_pack_end() or elm_box_pack_start() function, Elementary computes the global size of the box. If the global size is bigger than the size of the box's parent, the box will take up all the space occupied by the parent, and the size of the parent may be extended to hold the box. If the global size is smaller than the parent's size, the alignment values will set the position of the box inside the parent.

Here, we set an alignment of 0.8 vertically:

elm_box_align_set(vbox, 0.0, 0.8);
The alignment only takes effect in the opposite direction than the one defined with the elm_box_horizontal_set() function.

The elm_box_layout_transition() function provides the ability to animate the motion of the objects in a box when switching from one layout to another.

Using Size Hints

Size hints are a set of functions that can be used on any Evas object. You request Evas to take care of various properties, and Evas will honor these requests if it can. This is why they are called “hints”. The size hint functions are:

  • evas_object_size_hint_min_set()
  • evas_object_size_hint_max_set()
  • evas_object_size_hint_aspect_set()
  • evas_object_size_hint_align_set()
  • evas_object_size_hint_weight_set()

You can also use the respective get functions to get the current hint values.

In case of the evas_object_size_hint_min_set() function, you ask Evas to respect the minimum size you define for the object. For example, to set the minimum size of an icon to 64×46 pixels:

evas_object_size_hint_min_set(ic, 64, 64);

You can also set a maximum size for the same icon:

evas_object_size_hint_max_set(ic, 128, 128);

When you resize the parent of the icon, if there are no constraints to the parent, the minimum size of the parent will be the minimum hint size of the icon. If you increase the parent size, the icon will grow larger until its maximum hint size is reached. After this point, the icon will not grow any larger and there will be empty space around the icon within the parent.

When the aspect size hint is set, Evas tries to fix the dimensional proportions of the object. Here, the proportion of the icon is respected, and the width will be the same as the height:

evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1,1);

Here, the width will be twice the height:

evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 2,1);

If we want to change the alignment of the icon relative to the parent, we can use the evas_object_size_hint_align() function. By default, the icon is centered, so it is aligned with a value of 0.5. You can change the alignment as follows:

evas_object_size_hint_align_set(ic, EVAS_HINT_FILL, EVAS_HINT_FILL);

In the above case, the icon is aligned to the bottom left corner of the parent.

We can also play with the size of the icon inside its container by using the weight size hint. By default, the weight is not set, so the size of the icon will be the minimum size. But if you set this value to 1, the icon will be expand as much as it can inside the container:

evas_object_size_hint_weight_set(ic, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);

You can also use the alignment and weight hints together. Here, we want the icon to take up all the space in its parent:

evas_object_size_hint_align_set(ic, EVAS_HINT_FILL, EVAS_HINT_FILL);
evas_object_size_hint_weight_set(ic, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);

A Basic Box Example - A Layout Transition Example