Evas box example

In this example, we demonstrate the use of Evas box objects. We cover changing boxes' layouts (with a custom layout, besides the ones provided by Evas), box padding and alignment influence on the layouts, insertion and removal of box items.

The interesting part of the code starts, naturally, when we add a box object to the canvas. Just after it, we place five rectangles, with random colors, inside of it. Those rectangles get a minimum size hint of 50 pixels on each axis, which will be respected by most of the box's possible layouts:

d.box = evas_object_box_add(d.evas);
for (i = 1; i <= 5; i++)
{
o = last = evas_object_rectangle_add(d.evas);
evas_object_size_hint_min_set(o, 50, 50);
o, rand() % 256, rand() % 256, rand() % 256, 255);
if (!evas_object_box_append(d.box, o))
{
fprintf(stderr, "Error appending child object on the box!\n");
goto error;
}
}

Just like in other Evas examples, we have a white background on the canvas and a red border around the container object of interest, the box, to mark its boundaries. Resizing of the canvas will keep the box's proportion with regard to the whole canvas', so that you can experiment with different sizes of the box to accommodate its children:

static void /* adjust canvas' contents on resizes */
_canvas_resize_cb(Ecore_Evas *ee)
{
int w, h;
ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
evas_object_resize(d.bg, w, h);
evas_object_move(d.box, (w / 4), (h / 4));
evas_object_resize(d.box, (w / 2), (h / 2));
evas_object_move(d.border, (w / 4) - 2, (h / 4) - 2);
evas_object_resize(d.border, (w / 2) + 4, (h / 2) + 4);
}

Again, one interacts with this program by means of key commands:

static const char *commands = \
"commands are:\n"
"\ta - change the box's alignment values\n"
"\tp - change the box's padding values\n"
"\t1 - change the box's layout to horizontal\n"
"\t2 - change the box's layout to vertical\n"
"\t3 - change the box's layout to horizontal homogeneous\n"
"\t4 - change the box's layout to vertical homogeneous\n"
"\t5 - change the box's layout to horizontal maximum size homogeneous\n"
"\t6 - change the box's layout to vertical maximum size homogeneous\n"
"\t7 - change the box's layout to horizontal flow\n"
"\t8 - change the box's layout to vertical flow\n"
"\t9 - change the box's layout to stack\n"
"\t0 - change the box's layout to a custom-made one\n"
"\tCtrl + NUMBER - insert a new child object at that position in the box\n"
"\tShift + NUMBER - remove the child object at that position in the box\n"
"\th - print help\n";

Let's start with the numeric ones, each of which will impose a different layout on the box object.

The initial layout the box starts at is the one triggered by the key '1' – the horizontal layout. Thus, the initial appearance of this program, demonstrating this layout, is something like:

The vertical layout ('2' key) is very similar, but just disposing the items vertically:

Note the influence of the (default) 0.5 box alignment property, which will let the children line in the middle of the box's area. Also, because the space required by them extrapolates the box's height (we resized it to be smaller), they'll be drawn out if its bounds.

Next, comes the horizontal homogeneous layout ('3' key). See how it reserves an equal amount of space for each child to take:

Its vertical equivalent can be triggered by the '4' key. The next different layout of interest is the horizontal maximum size homogeneous ('5' key). It will reserve cells to children sized equally to the dimensions of the child with bigger size (or minimum size hints). For this example, all cells would be just the size of our rectangles' minimum size hints and, to prove that, insert a new (smaller) rectangle at position 3, say, with Ctrl and 3 keys together:

The code for the commands inserting and deleting box items is:

if (evas_key_modifier_is_set(mods, "Shift"))
{
int pos;
Eina_Bool ret;
Eina_List *children;
pos = atoi(ev->key);
children = evas_object_box_children_get(d.box);
obj = eina_list_nth(children, pos);
if (!obj) goto list_free;
ret = evas_object_box_remove_at(d.box, pos);
if (ret) evas_object_del(obj);
list_free:
eina_list_free(children);
return;
}
if (evas_key_modifier_is_set(mods, "Control"))
{
int pos;
pos = atoi(ev->key);
o_ = _new_rectangle_add(d.evas);
if (!evas_object_box_insert_at(d.box, o_, pos))
evas_object_box_append(d.box, o_);
return;
}
static Evas_Object * /* new rectangle to be put in the box */
_new_rectangle_add(Evas *e)
{
evas_object_resize(o, 10, 10);
evas_object_color_set(o, 0, 255, 0, 255);
return o;
}

In that code, we exemplify evas_object_box_children_get(), to fetch a child element at an exact position. After the element removal from the box (leaving it unparented again), we delete it and free that list. The code inserting a new rectangle, there, is straightforward.

Try the '6' key for the vertical equivalent of the last shown layout. Then, comes the flow layout, triggered by the '7' key. We make our box small to demonstrate the effect on the items layouting:

The next two numerical commands are for the vertical equivalent of the last and the stack one, respectively. Try them out to get their looks.

The last numerical key, '0', shows the effect of a custom layout on the box. We wrote one that would split the width and height of the box equally and, then, place the items in the cells in the diagonal:

if (strcmp(ev->key, "0") == 0)
{
evas_object_box_layout_set(d.box, _custom_layout, NULL, NULL);
printf("Applying '%s' layout on the box\n",
"CUSTOM");
return;
}
static void /* custom 'diagonal' layout */
_custom_layout(Evas_Object *o,
void *data EINA_UNUSED)
{
int x, y, w, h;
int xx, yy, ww, hh;
int count;
evas_object_geometry_get(o, &x, &y, &w, &h);
count = eina_list_count(p->children);
ww = w / (count ? : 1);
hh = h / (count ? : 1);
if (ww < 1) ww = 1;
if (hh < 1) hh = 1;
xx = x;
yy = y;
EINA_LIST_FOREACH(p->children, l, opt)
{
evas_object_move(opt->obj, xx, yy);
xx += ww;
yy += hh;
}
}

Finally, the 'a' and 'p' commands will change the box's alignment and padding property values, respectively. For each of the layouts above, see the effects they make by setting different values on those properties.

The full code for this example follows. For an exercise on the effect of children box elements' size hints on a box layout, try the Evas alignment, minimum size, maximum size, padding and weight hints example.

#ifdef HAVE_CONFIG_H
#include "config.h"
#else
#define PACKAGE_EXAMPLES_DIR "."
#endif
#include <Ecore.h>
#include <Ecore_Evas.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#define WIDTH (640)
#define HEIGHT (480)
static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png";
static const char *commands = \
"commands are:\n"
"\ta - change the box's alignment values\n"
"\tp - change the box's padding values\n"
"\t1 - change the box's layout to horizontal\n"
"\t2 - change the box's layout to vertical\n"
"\t3 - change the box's layout to horizontal homogeneous\n"
"\t4 - change the box's layout to vertical homogeneous\n"
"\t5 - change the box's layout to horizontal maximum size homogeneous\n"
"\t6 - change the box's layout to vertical maximum size homogeneous\n"
"\t7 - change the box's layout to horizontal flow\n"
"\t8 - change the box's layout to vertical flow\n"
"\t9 - change the box's layout to stack\n"
"\t0 - change the box's layout to a custom-made one\n"
"\tCtrl + NUMBER - insert a new child object at that position in the box\n"
"\tShift + NUMBER - remove the child object at that position in the box\n"
"\th - print help\n";
struct example_data
{
Ecore_Evas *ee;
Evas *evas;
Evas_Object *bg, *box, *border;
};
static struct example_data d;
static void /* custom 'diagonal' layout */
_custom_layout(Evas_Object *o,
void *data EINA_UNUSED)
{
int x, y, w, h;
int xx, yy, ww, hh;
int count;
evas_object_geometry_get(o, &x, &y, &w, &h);
count = eina_list_count(p->children);
ww = w / (count ? : 1);
hh = h / (count ? : 1);
if (ww < 1) ww = 1;
if (hh < 1) hh = 1;
xx = x;
yy = y;
EINA_LIST_FOREACH(p->children, l, opt)
{
evas_object_move(opt->obj, xx, yy);
xx += ww;
yy += hh;
}
}
static Evas_Object * /* new rectangle to be put in the box */
_new_rectangle_add(Evas *e)
{
evas_object_resize(o, 10, 10);
evas_object_color_set(o, 0, 255, 0, 255);
return o;
}
/* use the following commands to interact with this example - 'h' is
* the key for help */
static void
_on_keydown(void *data EINA_UNUSED,
void *einfo)
{
Evas_Event_Key_Down *ev = einfo;
const Evas_Modifier *mods = evas_key_modifier_get(evas);
if (strcmp(ev->key, "h") == 0) /* print help */
{
printf("%s", commands);
return;
}
if (evas_key_modifier_is_set(mods, "Shift"))
{
int pos;
Eina_Bool ret;
Eina_List *children;
pos = atoi(ev->key);
children = evas_object_box_children_get(d.box);
obj = eina_list_nth(children, pos);
if (!obj) goto list_free;
ret = evas_object_box_remove_at(d.box, pos);
if (ret) evas_object_del(obj);
list_free:
eina_list_free(children);
return;
}
if (evas_key_modifier_is_set(mods, "Control"))
{
int pos;
pos = atoi(ev->key);
o_ = _new_rectangle_add(d.evas);
if (!evas_object_box_insert_at(d.box, o_, pos))
evas_object_box_append(d.box, o_);
return;
}
if (strcmp(ev->key, "a") == 0)
{
double h, v;
evas_object_box_align_get(d.box, &h, &v);
if (h == 0.5)
h = v = 1.0;
else if (h == 1.0)
h = v = -1.0;
else if (h == -1.0)
h = v = 0.0;
else if (h == 0.0)
h = v = 0.5;
evas_object_box_align_set(d.box, h, v);
printf("Applying new alignment values (%.1f, %.1f) on the box\n",
h, v);
return;
}
if (strcmp(ev->key, "p") == 0)
{
int h, v;
evas_object_box_padding_get(d.box, &h, &v);
if (h == 0)
h = v = 50;
else
h = v = 0;
evas_object_box_padding_set(d.box, h, v);
printf("Applying new padding values (%d, %d) on the box\n",
h, v);
return;
}
if (strcmp(ev->key, "1") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_horizontal, NULL, NULL);
printf("Applying '%s' layout on the box\n",
"horizontal");
return;
}
if (strcmp(ev->key, "2") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_vertical, NULL, NULL);
printf("Applying '%s' layout on the box\n",
"vertical");
return;
}
if (strcmp(ev->key, "3") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_homogeneous_horizontal, NULL,
NULL);
printf("Applying '%s' layout on the box\n",
"horizontal homogeneous");
return;
}
if (strcmp(ev->key, "4") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_homogeneous_vertical, NULL, NULL);
printf("Applying '%s' layout on the box\n",
"vertical homogeneous");
return;
}
if (strcmp(ev->key, "5") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_homogeneous_max_size_horizontal,
NULL, NULL);
printf("Applying '%s' layout on the box\n",
"horizontal maximum size homogeneous");
return;
}
if (strcmp(ev->key, "6") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_homogeneous_max_size_vertical,
NULL, NULL);
printf("Applying '%s' layout on the box\n",
"vertical maximum size homogeneous");
return;
}
if (strcmp(ev->key, "7") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_flow_horizontal, NULL, NULL);
printf("Applying '%s' layout on the box\n",
"horizontal flow");
return;
}
if (strcmp(ev->key, "8") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_flow_vertical, NULL, NULL);
printf("Applying '%s' layout on the box\n",
"vertical flow");
return;
}
if (strcmp(ev->key, "9") == 0)
{
evas_object_box_layout_set(
d.box, evas_object_box_layout_stack, NULL, NULL);
printf("Applying '%s' layout on the box\n",
"stack");
return;
}
if (strcmp(ev->key, "0") == 0)
{
evas_object_box_layout_set(d.box, _custom_layout, NULL, NULL);
printf("Applying '%s' layout on the box\n",
"CUSTOM");
return;
}
}
static void
_on_delete(Ecore_Evas *ee EINA_UNUSED)
{
}
static void /* adjust canvas' contents on resizes */
_canvas_resize_cb(Ecore_Evas *ee)
{
int w, h;
ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
evas_object_resize(d.bg, w, h);
evas_object_move(d.box, (w / 4), (h / 4));
evas_object_resize(d.box, (w / 2), (h / 2));
evas_object_move(d.border, (w / 4) - 2, (h / 4) - 2);
evas_object_resize(d.border, (w / 2) + 4, (h / 2) + 4);
}
int
main(void)
{
Evas_Object *last, *o;
int i;
srand(time(NULL));
return EXIT_FAILURE;
/* this will give you a window with an Evas canvas under the first
* engine available */
d.ee = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL);
if (!d.ee)
goto panic;
ecore_evas_callback_resize_set(d.ee, _canvas_resize_cb);
d.evas = ecore_evas_get(d.ee);
d.bg = evas_object_rectangle_add(d.evas);
evas_object_color_set(d.bg, 255, 255, 255, 255); /* white bg */
d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL);
d.box = evas_object_box_add(d.evas);
for (i = 1; i <= 5; i++)
{
o = last = evas_object_rectangle_add(d.evas);
evas_object_size_hint_min_set(o, 50, 50);
o, rand() % 256, rand() % 256, rand() % 256, 255);
if (!evas_object_box_append(d.box, o))
{
fprintf(stderr, "Error appending child object on the box!\n");
goto error;
}
}
/* this is a border around the box, container of the rectangles we
* are going to experiment with. this way you can see how the
* container relates to the children */
d.border = evas_object_image_filled_add(d.evas);
evas_object_image_file_set(d.border, border_img_path, NULL);
evas_object_image_border_set(d.border, 2, 2, 2, 2);
evas_object_image_border_center_fill_set(d.border, EVAS_BORDER_FILL_NONE);
evas_object_show(d.border);
printf("%s", commands);
_canvas_resize_cb(d.ee);
return 0;
error:
return -1;
panic:
fprintf(stderr, "error: Requires at least one Evas engine built and linked"
" to ecore-evas for this example to run properly.\n");
return -2;
}
ecore_evas_new
EAPI Ecore_Evas * ecore_evas_new(const char *engine_name, int x, int y, int w, int h, const char *extra_options)
Creates a new Ecore_Evas based on engine name and common parameters.
Definition: ecore_evas.c:1059
ecore_evas_shutdown
EAPI int ecore_evas_shutdown(void)
Shuts down the Ecore_Evas system.
Definition: ecore_evas.c:668
ecore_evas_geometry_get
EAPI void ecore_evas_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h)
Gets the geometry of an Ecore_Evas.
Definition: ecore_evas.c:1382
ecore_evas_callback_resize_set
EAPI void ecore_evas_callback_resize_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func)
Sets a callback for Ecore_Evas resize events.
Definition: ecore_evas.c:1160
evas_object_box_add
Evas_Object * evas_object_box_add(Evas *evas)
Add a new box object on the provided canvas.
Definition: evas_object_box.c:481
ecore_main_loop_quit
void ecore_main_loop_quit(void)
Quits the main loop once all the events currently on the queue have been processed.
Definition: ecore_main.c:1289
_Evas_Event_Key_Down
Key press event.
Definition: Evas_Legacy.h:313
EINA_LIST_FOREACH
#define EINA_LIST_FOREACH(list, l, _data)
Definition for the macro to iterate over a list.
Definition: eina_list.h:1427
EINA_UNUSED
#define EINA_UNUSED
Definition: eina_types.h:321
ecore_evas_init
EAPI int ecore_evas_init(void)
Inits the Ecore_Evas system.
Definition: ecore_evas.c:604
eina_list_nth
EAPI void * eina_list_nth(const Eina_List *list, unsigned int n)
Gets the nth member's data pointer in a list, or NULL on error.
Definition: eina_list.c:994
Evas_Object
Efl_Canvas_Object Evas_Object
Definition: Evas_Common.h:180
ecore_evas_callback_delete_request_set
EAPI void ecore_evas_callback_delete_request_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func)
Sets a callback for Ecore_Evas delete request events.
Definition: ecore_evas.c:1196
Ecore_Evas.h
Evas wrapper functions.
ecore_evas_get
EAPI Evas * ecore_evas_get(const Ecore_Evas *ee)
Gets an Ecore_Evas's Evas.
Definition: ecore_evas.c:1320
evas_key_modifier_get
const Evas_Modifier * evas_key_modifier_get(const Evas *eo_e)
Returns a handle to the list of modifier keys registered in the canvas e.
Definition: evas_key.c:35
evas_object_geometry_get
void evas_object_geometry_get(const Evas_Object *eo_obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h)
Retrieves the position and (rectangular) size of the given Evas object.
Definition: evas_object_main.c:1374
evas_object_event_callback_add
void evas_object_event_callback_add(Evas_Object *eo_obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data)
Add (register) a callback function to a given Evas object event.
Definition: evas_callbacks.c:482
EVAS_CALLBACK_KEY_DOWN
Key Press Event.
Definition: Evas_Common.h:414
_Evas_Event_Key_Down::key
const char * key
The logical key : (eg shift+1 == exclamation)
Definition: Evas_Legacy.h:320
ecore_main_loop_begin
void ecore_main_loop_begin(void)
Runs the application main loop.
Definition: ecore_main.c:1279
evas_object_focus_set
void evas_object_focus_set(Efl_Canvas_Object *obj, Eina_Bool focus)
Indicates that this object is the keyboard event receiver on its canvas.
Definition: efl_canvas_object_eo.legacy.c:39
evas_object_show
void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition: evas_object_main.c:1853
Evas
Eo Evas
Definition: Evas_Common.h:158
EINA_TRUE
#define EINA_TRUE
Definition: eina_types.h:508
eina_list_free
EAPI Eina_List * eina_list_free(Eina_List *list)
Frees an entire list and all the nodes, ignoring the data contained.
Definition: eina_list.c:823
_Evas_Object_Box_Option::obj
Evas_Object * obj
Pointer to the box child object, itself.
Definition: Evas_Common.h:2862
Eina_Bool
unsigned char Eina_Bool
Definition: eina_types.h:496
_Evas_Object_Box_Data
Definition: Evas_Common.h:2837
evas_object_del
void evas_object_del(Evas_Object *obj)
Marks the given Evas object for deletion (when Evas will free its memory).
Definition: evas_object_main.c:962
evas_object_rectangle_add
Evas_Object * evas_object_rectangle_add(Evas *e)
Adds a rectangle to the given evas.
Definition: evas_object_rectangle.c:78
_Eina_List
Definition: eina_list.h:326
_Evas_Object_Box_Option
Evas_Object_Box_Option struct fields
Definition: Evas_Common.h:2860
evas_key_modifier_is_set
Eina_Bool evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname)
Checks the state of a given modifier of the default seat, at the time of the call.
Definition: evas_key.c:76
evas_object_box_children_get
Eina_List * evas_object_box_children_get(const Evas_Object *o)
Get the list of children objects in a given box object.
Definition: evas_object_box.c:1924
ecore_evas_show
EAPI void ecore_evas_show(Ecore_Evas *ee)
Shows an Ecore_Evas' window.
Definition: ecore_evas.c:1500
evas_object_color_set
void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a)
Sets the general/main color of the given Evas object to the given one.
Definition: evas_object_main.c:2063
eina_list_count
static unsigned int eina_list_count(const Eina_List *list)
Gets the count of the number of items in a list.