Box - Basic API

As a special guest tonight, we have the simplebutton example. There are plenty of boxes in it, and to make the cursor buttons that moved a central one around when pressed, we had to use a variety of values for their hints.

To start, let's take a look at the handling of the central button when we were moving it around. To achieve this effect without falling back to a complete manual positioning of the `Evas_Object` in our canvas, we just put it in a box and played with its alignment within it, as seen in the following snippet of the callback for the pressed buttons.

evas_object_size_hint_align_get(app->mid, &ax, &ay);
if (btn == app->cursors.up)
{
ay -= 0.05;
if (ay < 0.0)
ay = 0.0;
}
else if (btn == app->cursors.down)
{
ay += 0.05;
if (ay > 1.0)
ay = 1.0;
}
else if (btn == app->cursors.left)
{
ax -= 0.05;
if (ax < 0.0)
ax = 0.0;
}
else if (btn == app->cursors.right)
{
ax += 0.05;
if (ax > 1.0)
ax = 1.0;
}
evas_object_size_hint_align_set(app->mid, ax, ay);
evas_object_size_hint_align_get
EVAS_API void evas_object_size_hint_align_get(const Evas_Object *obj, double *x, double *y)
Retrieves the hints for on object's alignment.
Definition evas_object_main.c:2656
evas_object_size_hint_align_set
EVAS_API void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y)
Sets the hints for an object's alignment.
Definition evas_object_main.c:2650

Not much to it. We get the current alignment of the object and change it by just a little, depending on which button was pressed, then set it again, making sure we stay within the 0.0-1.0 range so the button moves inside the space it has, instead of disappearing under the other objects.

But as useful as an example as that may have been, the usual case with boxes is to set everything at the moment they are created, like we did for everything else in our main function.

The entire layout of our program is made with boxes. We have one set as the resize object for the window, which means it will always be resized with the window. The weight hints set to `EVAS_HINT_EXPAND` will tell the window that the box can grow past it's minimum size, which allows resizing of it.

box = elm_box_add(win);
evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_win_resize_object_add(win, box);
evas_object_show(box);
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_box_add
Evas_Object * elm_box_add(Evas_Object *parent)
Add a new box to the parent.
Definition elm_box.c:363
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

Two more boxes, set to horizontal, hold the buttons to change the autorepeat configuration used by the buttons. We create each to take over all the available space horizontally, but we don't want them to grow vertically, so we keep that axis of the weight with 0.0. Then it gets packed in the main box.

box2 = elm_box_add(win);
elm_box_horizontal_set(box2, EINA_TRUE);
evas_object_size_hint_weight_set(box2, EVAS_HINT_EXPAND, 0.0);
elm_box_pack_end(box, box2);
evas_object_show(box2);
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition eina_types.h:539
elm_box_horizontal_set
void elm_box_horizontal_set(Elm_Box *obj, Eina_Bool horizontal)
Set the horizontal orientation.
Definition elm_box_eo.legacy.c:27
elm_box_pack_end
void elm_box_pack_end(Elm_Box *obj, Efl_Canvas_Object *subobj)
Add an object at the end of the pack list.
Definition elm_box_eo.legacy.c:57

The buttons in each of those boxes have nothing special, they are just packed in with their default values and the box will use their minimum size, as set by Elementary itself based on the label, icon, finger size and theme.

But the buttons used to move the central one have a special disposition. The top one first, is placed right into the main box like our other smaller boxes. Set to expand horizontally and not vertically, and in this case we also tell it to fill that space, so it gets resized to take the entire width of the window.

btn = elm_button_add(win);
elm_button_autorepeat_set(btn, EINA_TRUE);
elm_button_autorepeat_initial_timeout_set(btn, 1.0);
elm_button_autorepeat_gap_timeout_set(btn, 0.5);
evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, 0.0);
evas_object_size_hint_align_set(btn, EVAS_HINT_FILL, 0.0);
elm_box_pack_end(box, btn);
evas_object_show(btn);
EVAS_HINT_FILL
#define EVAS_HINT_FILL
Use with evas_object_size_hint_align_set(), evas_object_size_hint_align_get(), evas_object_size_hint_...
Definition Evas_Common.h:298
elm_button_autorepeat_set
void elm_button_autorepeat_set(Evas_Object *obj, Eina_Bool on)
Turn on/off the autorepeat event generated when the button is kept pressed.
Definition efl_ui_button.c:364
elm_button_autorepeat_initial_timeout_set
void elm_button_autorepeat_initial_timeout_set(Evas_Object *obj, double t)
The initial timeout before the autorepeat event is generated.
Definition efl_ui_button.c:340
elm_button_add
Evas_Object * elm_button_add(Evas_Object *parent)
Add a new button to the parent's canvas.
Definition efl_ui_button.c:459
elm_button_autorepeat_gap_timeout_set
void elm_button_autorepeat_gap_timeout_set(Evas_Object *obj, double t)
The interval between each generated autorepeat event.
Definition efl_ui_button.c:352

The bottom one will be the same, but for the other two we need to use a second box set to take as much space as we have, so we can place our side buttons in place and have the big empty space where the central button will move.

box2 = elm_box_add(win);
elm_box_horizontal_set(box2, EINA_TRUE);
evas_object_size_hint_weight_set(box2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_size_hint_align_set(box2, EVAS_HINT_FILL, EVAS_HINT_FILL);
elm_box_pack_end(box, box2);
evas_object_show(box2);

Then the buttons will have their hints inverted to the other top and bottom ones, to expand and fill vertically and keep their minimum size horizontally.

btn = elm_button_add(win);
elm_button_autorepeat_set(btn, EINA_TRUE);
elm_button_autorepeat_initial_timeout_set(btn, 1.0);
elm_button_autorepeat_gap_timeout_set(btn, 0.5);
evas_object_size_hint_weight_set(btn, 0.0, EVAS_HINT_EXPAND);
evas_object_size_hint_align_set(btn, 0.0, EVAS_HINT_FILL);
elm_box_pack_end(box2, btn);
evas_object_show(btn);

The central button takes every thing else. It will ask to be expanded in both directions, but without filling its cell. Changing its alignment by pressing the buttons will make it move around.

btn = elm_button_add(win);
evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_box_pack_end(box2, btn);
evas_object_show(btn);

To end, the rightmost button is packed in the smaller box after the central one, and back to the main box we have the bottom button at the end.