edje/box - Document edje box API (just fixes) and add example.

SVN revision: 62017

legacy/edje/doc/examples.dox

@@ -8,6 +8,8 @@
  * @li @ref tutorial_edje_text
  * @li @ref tutorial_edje_table
  * @li @ref Example_Edje_Signals_Messages
+ * @li @ref tutorial_edje_box
+ * @li @ref tutorial_edje_box2
  */
 
 /**
@@ -207,7 +209,7 @@
  * @page tutorial_edje_table Table example
  *
  * In this example, we illustrate how to organize your objects on a table, using
- * the evas_object_part_table functions. To be easier to understand the objects
+ * the edje_object_part_table functions. To be easier to understand the objects
  * in this example will be four simple rects, when the user click over one
  * item with the left button its is removed from the table, if any other button
  * was used all items are removed. For each action is printed a message with
@@ -259,6 +261,143 @@
  * @example edje-table.c
  */
 
+/**
+ * @page tutorial_edje_box Box example - basic usage
+ *
+ * This example shows how to append, insert and remove elements from an Edje box
+ * part. It will make use of the edje_object_part_box functions.
+ *
+ * To play with this example, use mouse left click to delete an existing
+ * rectangle from the box and right mouse click to add a new rectangle just
+ * before the clicked one. Use the keyboard keys "a" to append a rectangle, "i"
+ * to prepend, and "c" to remove all rectangles from the box.
+ *
+ * We will store our example global information in the data structure defined
+ * below, and also set some callbacks for resizing the canvas and exiting the
+ * window:
+ *
+ * @dontinclude edje-box.c
+ * @skip static const char
+ * @until ecore_evas_geometry_get
+ * @until }
+ *
+ * In the @c main function, we create our @c Ecore_Evas, add a background to it,
+ * and finally load our @c Edje file that contains a @c Box part. This part is
+ * named @c "example/box" in this case, and we use this name to append elements
+ * to it.
+ *
+ * The code until now is the one that follows:
+ *
+ * @skip main
+ * @until evas_object_show(app.edje)
+ *
+ * Also notice that we set the callback @c _bg_key_down for @c "key down" events
+ * on the background object, and that object is the one with focus.
+ *
+ * Now we add some small rectangles to the box part, using the
+ * edje_object_part_box_append() API, and set some callbacks for @c "mouse down"
+ * events on every object. These callbacks will be used to add or delete objects
+ * from the box part.
+ *
+ * @until evas_object_event
+ * @until }
+ *
+ * Now let's take a look at the callbacks for key down and mouse down events:
+ *
+ * @dontinclude edje-box.c
+ * @skip ecore_evas_geometry_get
+ * @skip static
+ * @until evas_object_event
+ * @until }
+ * @until }
+ *
+ * This callback for mouse down events will get left clicks and remove the
+ * object that received that left click from the box part, and then delete it.
+ * This is done with the edje_object_part_box_remove() function.
+ *
+ * However, on right clicks it will create a new rectangle object, and add it
+ * just before the right clicked object, using
+ * edje_object_part_box_insert_before().
+ *
+ * And this is the key down callback:
+ *
+ * @until remove_all
+ * @until }
+ *
+ * It will insert elements at the beginning of the box if "i" was pressed, using
+ * edje_object_part_box_insert_at(). It will also append objects to the box if
+ * "a" was pressed, just exactly like we did in the @c main function. And will
+ * remove all objects (deleting them) if "c" was pressed.
+ *
+ * As you can see, this example uses the @c "horizontal_flow" layout for the
+ * box, where each item is put linearly in rows, in as many rows as necessary to
+ * store all of them.
+ *
+ * The example's window should look like this picture:
+ *
+ * @image html edje-box-example.png
+ * @image rtf edje-box-example.png
+ * @image latex edje-box-example.eps
+ *
+ * The full source code follows:
+ * @include edje-box.c
+ * @example edje-box.c
+ */
+
+/**
+ * @page tutorial_edje_box2 Box example - custom layout
+ *
+ * This example shows how to register a custom layout to be used by the Edje box
+ * part. It will use edje_box_layout_register() for that.
+ *
+ * To play with this example, use the keyboard modifier keys and number keys
+ * together. The Ctrl key is used for adding elements, and Shift is used for
+ * removing them. For instance, Ctrl + 3 will insert a new rectangle object in
+ * the 3rd position of the box, while Shift + 6 will try to remove the 6th
+ * element of the box.
+ *
+ * This example is very similar to the other box example, has a structure with
+ * global data, a callback for key down events where we create or delete
+ * rectangle objects and add or remove them to/from the box part.
+ *
+ * But the important part is the next one:
+ *
+ * @dontinclude edje-box2.c
+ * @skip static struct _App
+ * @skip static
+ * @until }
+ * @until }
+ *
+ * This code implements our custom layout, which will position every object
+ * added to the box in a diagonal through the size of the box part. Notice that
+ * it just calculates the position and offset based on the size of the box and
+ * number of children, and then moves each child to the respective position.
+ *
+ * Later on the @c main function, everything we need to do is to register this
+ * custom layout function with edje:
+ *
+ * @skipline edje_box_layout_register
+ *
+ * And use it inside the .edc file:
+ *
+ * @dontinclude box.edc
+ * @skip example/group2
+ * @skip example/title
+ * @skip part
+ * @until BOX
+ * @until example/box
+ *
+ * The example's window should look like this picture:
+ *
+ * @image html edje-box2-example.png
+ * @image rtf edje-box2-example.png
+ * @image latex edje-box2-example.eps
+ *
+ * The full source code follows:
+ * @include edje-box2.c
+ * @example edje-box2.c
+ */
+
 /**
  * @page Example_Edje_Signals_Messages Edje signals and messages
  *

legacy/edje/src/examples/Makefile.am

@@ -7,6 +7,7 @@ EDCS = basic.edc \
 	swallow.edc \
 	text.edc \
 	table.edc \
+	box.edc \
 	signals-messages.edc
 
 filesdir = $(datadir)/$(PACKAGE)/examples
@@ -33,6 +34,8 @@ pkglib_PROGRAMS += \
 	edje-swallow \
 	edje-text \
 	edje-table \
+	edje-box \
+	edje-box2 \
 	edje-signals-messages
 
 LDADD = $(top_builddir)/src/lib/libedje.la @EDJE_LIBS@
@@ -57,6 +60,8 @@ files_DATA += \
 	$(srcdir)/edje-swallow.c \
 	$(srcdir)/edje-text.c \
 	$(srcdir)/edje-table.c \
+	$(srcdir)/edje-box.c \
+	$(srcdir)/edje-box2.c \
 	$(srcdir)/edje-signals-messages.c
 endif
 
@@ -66,4 +71,6 @@ EXTRA_DIST = $(EDCS) \
 	$(srcdir)/edje-swallow.c \
 	$(srcdir)/edje-text.c \
 	$(srcdir)/edje-table.c \
+	$(srcdir)/edje-box.c \
+	$(srcdir)/edje-box2.c \
 	$(srcdir)/edje-signals-messages.c

legacy/edje/src/examples/box.edc

@@ -0,0 +1,142 @@
+collections {
+
+   group {
+      name: "example/group";
+
+      parts {
+         part {
+            name: "bg";
+            type: RECT;
+
+            description {
+            state: "default" 0.0;
+               color: 128 128 128 255;
+               rel1.offset: 20 20;
+               rel2.offset: -21 -21;
+            }
+         }
+
+         part {
+            name: "example/title";
+            type: TEXT;
+
+            description {
+               state: "default" 0.0;
+               color: 0 0 0 255;
+               rel1 {
+                  relative: 0.0 0.0;
+                  offset: 0 0;
+                  to: "bg";
+               }
+               rel2 {
+                  relative: 1.0 0.2;
+                  offset: -1 -1;
+                  to: "bg";
+               }
+               text {
+                  text: "Box Example";
+                  size: 16;
+                  font: "sans";
+                  min: 1 1;
+               }
+            }
+         }
+
+         part {
+            name: "example/box";
+            type: BOX;
+
+            description {
+               state: "default" 0.0;
+
+               box {
+                  layout: "horizontal_flow";
+                  padding: 2 2;
+                  align: 0.5 0.5;
+                  min: 1 1;
+               }
+               rel1 {
+                  relative: 0.0 0.2;
+                  offset: 0 0;
+                  to: "bg";
+               }
+               rel2 {
+                  relative: 1.0 1.0;
+                  offset: -1 -61;
+                  to: "bg";
+               }
+            }
+         } // example/box
+      }
+   }
+
+   group {
+      name: "example/group2";
+
+      parts {
+         part {
+            name: "bg";
+            type: RECT;
+
+            description {
+            state: "default" 0.0;
+               color: 128 128 128 255;
+               rel1.offset: 20 20;
+               rel2.offset: -21 -21;
+            }
+         }
+
+         part {
+            name: "example/title";
+            type: TEXT;
+
+            description {
+               state: "default" 0.0;
+               color: 0 0 0 255;
+               rel1 {
+                  relative: 0.0 0.0;
+                  offset: 0 0;
+                  to: "bg";
+               }
+               rel2 {
+                  relative: 1.0 0.2;
+                  offset: -1 -1;
+                  to: "bg";
+               }
+               text {
+                  text: "Box Example 2";
+                  size: 16;
+                  font: "sans";
+                  min: 1 1;
+               }
+            }
+         }
+
+         part {
+            name: "example/box";
+            type: BOX;
+
+            description {
+               state: "default" 0.0;
+
+               box {
+                  layout: "custom_layout";
+                  padding: 2 2;
+                  align: 0.5 0.5;
+                  min: 1 1;
+               }
+               rel1 {
+                  relative: 0.0 0.2;
+                  offset: 0 0;
+                  to: "bg";
+               }
+               rel2 {
+                  relative: 1.0 1.0;
+                  offset: -1 -61;
+                  to: "bg";
+               }
+            }
+         } // example/box
+      }
+   }
+}

legacy/edje/src/examples/edje-basic.c

@@ -31,7 +31,7 @@ static const char *edje_file_path = PACKAGE_EXAMPLES_DIR "/basic.edj";
 static Ecore_Evas *ee;
 static Evas_Object *edje_obj;
 
-static const char *commands = \
+static const char commands[] = \
   "commands are:\n"
   "\ts - change Edje's global scaling factor\n"
   "\tr - change center rectangle's scaling factor\n"

legacy/edje/src/examples/edje-box.c

@@ -0,0 +1,191 @@
+/**
+ * Simple Edje example illustrating box functions.
+ *
+ * You'll need at least one Evas engine built for it (excluding the
+ * buffer one). See stdout/stderr for output.
+ *
+ * @verbatim
+ * edje_cc box.edc && gcc -o edje-box edje-box.c `pkg-config --libs --cflags evas ecore ecore-evas edje`
+ * @endverbatim
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#else
+#define PACKAGE_EXAMPLES_DIR "."
+#define __UNUSED__
+#endif
+
+#include <Ecore.h>
+#include <Ecore_Evas.h>
+#include <Edje.h>
+
+#define WIDTH  300
+#define HEIGHT 300
+
+#define RECTW 30
+#define RECTH 30
+
+#define NRECTS 20
+
+static const char *edje_file_path = PACKAGE_EXAMPLES_DIR "/box.edj";
+
+struct _App {
+    Ecore_Evas *ee;
+    Evas_Object *edje;
+    Evas_Object *bg;
+};
+
+static void
+_on_destroy(Ecore_Evas *ee __UNUSED__)
+{
+   ecore_main_loop_quit();
+}
+
+/* here just to keep our example's window size and background image's
+ * size in synchrony */
+static void
+_canvas_resize_cb(Ecore_Evas *ee)
+{
+   int w, h;
+   struct _App *app = ecore_evas_data_get(ee, "app");
+
+   ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
+   evas_object_resize(app->bg, w, h);
+   evas_object_resize(app->edje, w, h);
+}
+
+static void
+_rect_mouse_down(void *data, Evas *e, Evas_Object *o, void *event_info)
+{
+   struct _App *app = data;
+   Evas_Event_Mouse_Down *ev = event_info;
+
+   if (ev->button == 1)
+     {
+	printf("Removing rect %p under the mouse pointer.\n", o);
+	edje_object_part_box_remove(app->edje, "example/box", o);
+	evas_object_del(o);
+     }
+   else if (ev->button == 3)
+     {
+	Evas_Object *rect;
+	Eina_Bool r;
+
+	rect = evas_object_rectangle_add(e);
+	evas_object_color_set(rect, 0, 0, 255, 255);
+	evas_object_resize(rect, RECTW + 10, RECTH);
+	evas_object_show(rect);
+
+	printf("Inserting rect %p before the rectangle under the mouse pointer.\n", rect);
+	r = edje_object_part_box_insert_before(app->edje, "example/box", rect, o);
+	if (!r)
+	  printf("An error ocurred when appending rect %p to the box.\n", rect);
+
+	evas_object_event_callback_add(rect, EVAS_CALLBACK_MOUSE_DOWN, _rect_mouse_down, app);
+     }
+}
+
+static void
+_bg_key_down(void *data, Evas *e, Evas_Object *o __UNUSED__, void *event_info)
+{
+   struct _App *app = data;
+   Evas_Event_Key_Down *ev = event_info;
+   Evas_Object *rect;
+   Eina_Bool r;
+
+
+   if (!strcmp(ev->keyname, "i"))
+     {
+	rect = evas_object_rectangle_add(e);
+	evas_object_color_set(rect, 0, 0, 128, 255);
+	evas_object_resize(rect, RECTW + 30, RECTH);
+	evas_object_show(rect);
+
+	printf("Inserting rect %p before the rectangle under the mouse pointer.\n", rect);
+	r = edje_object_part_box_insert_at(app->edje, "example/box", rect, 0);
+	if (!r)
+	  printf("An error ocurred when appending rect %p to the box.\n", rect);
+
+	evas_object_event_callback_add(rect, EVAS_CALLBACK_MOUSE_DOWN, _rect_mouse_down, app);
+     }
+   else if (!strcmp(ev->keyname, "a"))
+     {
+	rect = evas_object_rectangle_add(e);
+	evas_object_color_set(rect, 0, 128, 0, 255);
+	evas_object_resize(rect, RECTW, RECTH);
+	evas_object_show(rect);
+
+	printf("Inserting rect %p before the rectangle under the mouse pointer.\n", rect);
+	r = edje_object_part_box_append(app->edje, "example/box", rect);
+	if (!r)
+	  printf("An error ocurred when appending rect %p to the box.\n", rect);
+
+	evas_object_event_callback_add(rect, EVAS_CALLBACK_MOUSE_DOWN, _rect_mouse_down, app);
+     }
+   else if (!strcmp(ev->keyname, "c"))
+     edje_object_part_box_remove_all(app->edje, "example/box", EINA_TRUE);
+}
+
+int
+main(void)
+{
+   Evas *evas;
+   struct _App app;
+   int i;
+
+   ecore_evas_init();
+   edje_init();
+
+   /* this will give you a window with an Evas canvas under the first
+    * engine available */
+   app.ee = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL);
+
+   ecore_evas_callback_destroy_set(app.ee, _on_destroy);
+   ecore_evas_callback_resize_set(app.ee, _canvas_resize_cb);
+   ecore_evas_title_set(app.ee, "Edje Box Example");
+   ecore_evas_show(app.ee);
+
+   ecore_evas_data_set(app.ee, "app", &app);
+
+   evas = ecore_evas_get(app.ee);
+
+   app.bg = evas_object_rectangle_add(evas);
+   evas_object_color_set(app.bg, 255, 255, 255, 255);
+   evas_object_resize(app.bg, WIDTH, HEIGHT);
+   evas_object_focus_set(app.bg, EINA_TRUE);
+   evas_object_show(app.bg);
+
+   evas_object_event_callback_add(app.bg, EVAS_CALLBACK_KEY_DOWN, _bg_key_down, &app);
+
+   app.edje = edje_object_add(evas);
+
+   edje_object_file_set(app.edje, edje_file_path, "example/group");
+   evas_object_move(app.edje, 0, 0);
+   evas_object_resize(app.edje, WIDTH, HEIGHT);
+   evas_object_show(app.edje);
+
+   for (i = 0; i < NRECTS; i++)
+     {
+	Evas_Object *rect;
+	Eina_Bool r = EINA_FALSE;
+	int red = (i * 10) % 256;
+	rect = evas_object_rectangle_add(evas);
+	evas_object_color_set(rect, red, 0, 0, 255);
+	evas_object_resize(rect, RECTW, RECTH);
+	r = edje_object_part_box_append(app.edje, "example/box", rect);
+	if (!r)
+	  printf("An error ocurred when appending rect #%d to the box.\n", i);
+	evas_object_show(rect);
+
+	evas_object_event_callback_add(
+	   rect, EVAS_CALLBACK_MOUSE_DOWN, _rect_mouse_down, &app);
+     }
+
+   ecore_main_loop_begin();
+
+   ecore_evas_free(app.ee);
+   ecore_evas_shutdown();
+   edje_shutdown();
+   return 0;
+}

legacy/edje/src/examples/edje-box2.c

@@ -0,0 +1,204 @@
+/**
+ * Simple Edje example illustrating a custom box layout.
+ *
+ * You'll need at least one Evas engine built for it (excluding the
+ * buffer one). See stdout/stderr for output.
+ *
+ * @verbatim
+ * edje_cc box.edc && gcc -o edje-box2 edje-box2.c `pkg-config --libs --cflags evas ecore ecore-evas edje`
+ * @endverbatim
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#else
+#define PACKAGE_EXAMPLES_DIR "."
+#define __UNUSED__
+#endif
+
+#include <Ecore.h>
+#include <Evas.h>
+#include <Ecore_Evas.h>
+#include <Edje.h>
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+static const char *edje_file_path = PACKAGE_EXAMPLES_DIR "/box.edj";
+
+struct _App {
+   Ecore_Evas *ee;
+   Evas *evas;
+   Evas_Object *bg;
+   Evas_Object *box;
+};
+
+static struct _App app;
+
+static void
+custom_layout(Evas_Object *o, Evas_Object_Box_Data *p, void *data)
+{
+   int x, y, w, h;
+   int xx, yy, ww, hh;
+   int count;
+   Eina_List *l;
+   Evas_Object_Box_Option *opt;
+
+   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_greenie_block(Evas *e)
+{
+   Evas_Object *o;
+
+   o = evas_object_rectangle_add(e);
+   evas_object_resize(o, 10, 10);
+   evas_object_color_set(o, 0, 255, 0, 255);
+   evas_object_show(o);
+
+   return o;
+}
+
+static void
+on_keydown(void *data, Evas *evas, Evas_Object *o, void *einfo)
+{
+   struct _App *app = data;
+   Evas_Event_Key_Down *ev = einfo;
+   const Evas_Modifier *mods;
+
+   mods = evas_key_modifier_get(evas);
+   if (evas_key_modifier_is_set(mods, "Shift"))
+     {
+	int pos;
+	Evas_Object *obj = NULL;
+	pos = atoi(ev->keyname);
+	obj = edje_object_part_box_remove_at(app->box, "example/box", pos);
+	if (obj)
+	  evas_object_del(obj);
+	return;
+     }
+   if (evas_key_modifier_is_set(mods, "Control"))
+     {
+	Evas_Object *o;
+	int pos;
+	pos = atoi(ev->keyname);
+	o = new_greenie_block(app->evas);
+	if (!edje_object_part_box_insert_at(app->box, "example/box", o, pos))
+	  edje_object_part_box_append(app->box, "example/box", o);
+	return;
+     }
+   if (strcmp(ev->keyname, "Escape") == 0)
+     ecore_main_loop_quit();
+}
+
+static Evas_Object *
+box_new(Evas *evas, const char *name, int x, int y, int w, int h)
+{
+   Evas_Object *o;
+
+   o = edje_object_add(evas);
+   evas_object_move(o, x, y);
+   evas_object_resize(o, w, h);
+   if (!edje_object_file_set(o, edje_file_path, "example/group2"))
+     {
+	printf("error: could not load file object.\n");
+     }
+   evas_object_show(o);
+
+   evas_object_name_set(o, name);
+
+   return o;
+}
+
+static void
+on_resize(Ecore_Evas *ee)
+{
+   int w, h;
+
+   evas_output_viewport_get(app.evas, NULL, NULL, &w, &h);
+   evas_object_resize(app.bg, w, h);
+   evas_object_resize(app.box, w, h);
+}
+
+static void
+on_destroy(Ecore_Evas *ee)
+{
+   ecore_main_loop_quit();
+}
+
+int
+main(int argc, char *argv[])
+{
+   Ecore_Evas *ee;
+   int w, h, i;
+   Evas_Object *last;
+   Evas_Object *o;
+
+   evas_init();
+   ecore_init();
+   ecore_evas_init();
+   edje_init();
+
+   ee = ecore_evas_new(NULL, 0, 0, 640, 480, NULL);
+   ecore_evas_show(ee);
+
+   app.ee = ee;
+   app.evas = ecore_evas_get(ee);
+
+   ecore_evas_callback_resize_set(ee, on_resize);
+   ecore_evas_callback_destroy_set(ee, on_destroy);
+
+   evas_output_viewport_get(app.evas, NULL, NULL, &w, &h);
+
+   app.bg = evas_object_rectangle_add(app.evas);
+   evas_object_resize(app.bg, w, h);
+   evas_object_show(app.bg);
+   evas_object_focus_set(app.bg, 1);
+   evas_object_event_callback_add(
+      app.bg, EVAS_CALLBACK_KEY_DOWN, on_keydown, &app);
+
+   edje_box_layout_register("custom_layout", custom_layout, NULL, NULL, NULL, NULL);
+
+   app.box = box_new(app.evas, "box", 0, 0, w, h);
+
+   for (i = 1; i <= 5; i++)
+     {
+	o = last = evas_object_rectangle_add(app.evas);
+        evas_object_size_hint_min_set(o, 50, 50);
+        evas_object_resize(o, 50, 50);
+	evas_object_color_set(o, 255, 0, 0, 128);
+	evas_object_show(o);
+
+	if (!edje_object_part_box_append(app.box, "example/box", o))
+	  {
+	     fprintf(stderr, "error appending child object!\n");
+	     return 1;
+	  }
+     }
+
+   ecore_main_loop_begin();
+
+   edje_shutdown();
+   ecore_evas_shutdown();
+   ecore_shutdown();
+   evas_shutdown();
+
+
+   return 0;
+}

legacy/edje/src/lib/Edje.h

@@ -449,6 +449,8 @@ part of Edje's API:
 - @ref Example_Edje_Basics
 - @ref tutorial_edje_swallow
 - @ref tutorial_edje_table
+- @ref tutorial_edje_box
+- @ref tutorial_edje_box2
 - @ref Example_Edje_Signals_Messages
 
 
@@ -3090,10 +3092,14 @@ EAPI Edje_External_Param_Type  edje_object_part_external_param_type_get (const E
  * @param part The part name
  * @param child The object to append
  *
- * @return 1: Successfully added.\n
- * 0: An error occurred.
+ * @return @c EINA_TRUE: Successfully added.\n
+ * @c EINA_FALSE: An error occurred.
  *
  * Appends child to the box indicated by part.
+ *
+ * @see edje_object_part_box_prepend()
+ * @see edje_object_part_box_insert_before()
+ * @see edje_object_part_box_insert_at()
  */
 EAPI Eina_Bool    edje_object_part_box_append             (Evas_Object *obj, const char *part, Evas_Object *child);
 
@@ -3104,10 +3110,14 @@ EAPI Eina_Bool    edje_object_part_box_append             (Evas_Object *obj, con
  * @param part The part name
  * @param child The object to prepend
  *
- * @return 1: Successfully added.\n
- * 0: An error occurred.
+ * @return @c EINA_TRUE: Successfully added.\n
+ * @c EINA_FALSE: An error occurred.
  *
  * Prepends child to the box indicated by part.
+ *
+ * @see edje_object_part_box_append()
+ * @see edje_object_part_box_insert_before()
+ * @see edje_object_part_box_insert_at()
  */
 EAPI Eina_Bool    edje_object_part_box_prepend            (Evas_Object *obj, const char *part, Evas_Object *child);
 
@@ -3119,11 +3129,15 @@ EAPI Eina_Bool    edje_object_part_box_prepend            (Evas_Object *obj, con
  * @param child The object to insert
  * @param reference The object to be used as reference
  *
- * @return 1: Successfully added.\n
- * 0: An error occurred.
+ * @return @c EINA_TRUE: Successfully added.\n
+ * @c EINA_FALSE: An error occurred.
  *
  * Inserts child in the box given by part, in the position marked by
  * reference.
+ *
+ * @see edje_object_part_box_append()
+ * @see edje_object_part_box_prepend()
+ * @see edje_object_part_box_insert_at()
  */
 EAPI Eina_Bool    edje_object_part_box_insert_before      (Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference);
 
@@ -3135,11 +3149,15 @@ EAPI Eina_Bool    edje_object_part_box_insert_before      (Evas_Object *obj, con
  * @param child The object to insert
  * @param pos The position where to insert child
  *
- * @return 1: Successfully added.\n
- * 0: An error occurred.
+ * @return @c EINA_TRUE: Successfully added.\n
+ * @c EINA_FALSE: An error occurred.
  *
  * Adds child to the box indicated by part, in the position given by
  * pos.
+ *
+ * @see edje_object_part_box_append()
+ * @see edje_object_part_box_prepend()
+ * @see edje_object_part_box_insert_before()
  */
 EAPI Eina_Bool    edje_object_part_box_insert_at          (Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos);
 
@@ -3150,9 +3168,12 @@ EAPI Eina_Bool    edje_object_part_box_insert_at          (Evas_Object *obj, con
  * @param part The part name
  * @param child The object to remove
  *
- * @return Pointer to the object removed, or NULL.
+ * @return Pointer to the object removed, or @c NULL.
  *
  * Removes child from the box indicated by part.
+ *
+ * @see edje_object_part_box_remove_at()
+ * @see edje_object_part_box_remove_all()
  */
 EAPI Evas_Object *edje_object_part_box_remove             (Evas_Object *obj, const char *part, Evas_Object *child);
 
@@ -3161,12 +3182,15 @@ EAPI Evas_Object *edje_object_part_box_remove             (Evas_Object *obj, con
  *
  * @param obj A valid Evas_Object handle
  * @param part The part name
- * @param pos
+ * @param pos The position index of the object (starts counting from 0)
  *
- * @return Pointer to the object removed, or NULL.
+ * @return Pointer to the object removed, or @c NULL.
  *
  * Removes from the box indicated by part, the object in the position
  * pos.
+ *
+ * @see edje_object_part_box_remove()
+ * @see edje_object_part_box_remove_all()
  */
 EAPI Evas_Object *edje_object_part_box_remove_at          (Evas_Object *obj, const char *part, unsigned int pos);
 
@@ -3182,6 +3206,9 @@ EAPI Evas_Object *edje_object_part_box_remove_at          (Evas_Object *obj, con
  *
  * Removes all the external objects from the box indicated by part.
  * Elements created from the theme will not be removed.
+ *
+ * @see edje_object_part_box_remove()
+ * @see edje_object_part_box_remove_at()
  */
 EAPI Eina_Bool    edje_object_part_box_remove_all         (Evas_Object *obj, const char *part, Eina_Bool clear);