Edje: edje table documentation.

By: ceolin <flavio.ceolin@profusion.mobi>



SVN revision: 61965

legacy/edje/doc/examples.dox

@@ -6,6 +6,7 @@
  * @li @ref Example_Edje_Basics
  * @li @ref tutorial_edje_swallow
  * @li @ref tutorial_edje_text
+ * @li@ref tutorial_edje_table
  */
 
 /**
@@ -199,4 +200,60 @@
  * The theme used in this example is:
  * @include text.edc
  * @example text.edc
- */
+ */
+
+/**
+ * @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
+ * 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
+ * the current number of rows and columns.
+ *
+ * We started creating an EDC file with one part of the type TABLE called
+ * @b "table_part", that is the part which we will refer to access the table:
+ * @include table.edc
+ *
+ * On the other hand, in the C file we first create the rectangles and added a
+ * callback for mouse down, as you can see bellow:
+ * @dontinclude edje-table.c
+ * @skip _rects_create
+ * @until }
+ * @skip }
+ * @until }
+ *
+ * With the objects created we have to pack them into the table, to do this, we
+ * just have to use the function edje_object_part_table_pack().
+ * @dontinclude edje-table.c
+ * @skip (!edje_object_part_table_pack
+ * @until 4
+ *
+ * The other bit of code that is relevant to us now is our event handler for
+ * when the user click over the rectangle. Here we use the function
+ * edje_object_part_table_unpack() to remove the item from the table or
+ * edje_object_part_table_clear() to remove all items, it depends on which mouse
+ * button the user uses.
+ * @dontinclude edje-table.c
+ * @skip _on_mouse_down
+ * @until }
+ *
+ * Finally, the last important thing in this example is about how to know how many
+ * columns and rows are there in the table, It should be noted that this function
+ * don't tell you how many items are there in the table, just the number of the
+ * columns and rows of the table.
+ * @dontinclude edje-table.c
+ * @skip _columns_rows_
+ * @until }
+ *
+ * The example's window should look like this picture:
+ *
+ * @image html edje-table-example.png
+ * @image rtf edje-table-example.png
+ * @image latex edje-table-example.eps
+ *
+ * The full source code follows:
+ * @include edje-table.c
+ * @example edje-table.c
+ */

legacy/edje/src/examples/Makefile.am

@@ -5,7 +5,8 @@ pkglibdir = $(datadir)/$(PACKAGE)/examples
 #put here all EDCs one needs to the examples
 EDCS = basic.edc \
 	swallow.edc \
-	text.edc
+	text.edc \
+	table.edc
 
 filesdir = $(datadir)/$(PACKAGE)/examples
 files_DATA =
@@ -29,7 +30,8 @@ AM_CPPFLAGS += @ECORE_EVAS_CFLAGS@
 pkglib_PROGRAMS += \
 	edje-basic \
 	edje-swallow \
-	edje-text
+	edje-text \
+	edje-table
 
 LDADD = $(top_builddir)/src/lib/libedje.la @ECORE_EVAS_LIBS@
 
@@ -52,10 +54,12 @@ files_DATA += \
 	$(srcdir)/edje-basic.c \
 	$(srcdir)/edje-swallow.c \
 	$(srcdir)/edje-text.c \
+	$(srcdir)/edje-table.c
 endif
 
 EXTRA_DIST = $(EDCS) \
 	$(srcdir)/red.png \
 	$(srcdir)/edje-basic.c \
 	$(srcdir)/edje-swallow.c \
-	$(srcdir)/edje-text.c
+	$(srcdir)/edje-text.c \
+	$(srcdir)/edje-table.c

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

@@ -0,0 +1,165 @@
+/**
+ * Simple Edje example illustrating table functions.
+ *
+ * You'll need at least one Evas engine built for it (excluding the
+ * buffer one). See stdout/stderr for output.
+ *
+ * @verbatim
+ * edje_cc table.edc && gcc -o edje-table edje-table.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  (400)
+#define HEIGHT (400)
+
+static const char *edje_file_path = PACKAGE_EXAMPLES_DIR "/table.edj";
+
+static Ecore_Evas *ee;
+static Evas *evas;
+static Evas_Object *bg, *edje_obj, *rects[4];
+
+static void
+_on_destroy(Ecore_Evas *ee __UNUSED__)
+{
+   ecore_main_loop_quit();
+}
+
+/* Try to get the number of columns and rows of the table
+ * and print them. */
+static void
+_columns_rows_print(void)
+{
+   int cols, rows;
+
+   if (edje_object_part_table_col_row_size_get(edje_obj, "table_part", &cols,
+                                               &rows))
+     fprintf(stdout, "Number of columns: %d\nNumber of rows: %d\n", cols, rows);
+   else
+     fprintf(stderr, "Cannot get the number of columns and rows\n");
+}
+
+/* here just to keep our example's window size and table items
+ * size in synchrony. */
+static void
+_canvas_resize_cb(Ecore_Evas *ee)
+{
+   int i, w, h;
+
+   ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
+
+   evas_object_resize(bg, w, h);
+   evas_object_resize(edje_obj, w, h);
+
+   for (i = 0; i < 4; i++)
+     evas_object_size_hint_min_set(rects[i], w/2, h/2);
+}
+
+/* Mouse button 1 = remove the clicked item
+ * any other button = remove all items. */
+static void
+_on_mouse_down(void *data, Evas *evas, Evas_Object *obj, void *event_info)
+{
+   Evas_Event_Mouse_Down *ev = event_info;
+
+   if (ev->button != 1)
+     edje_object_part_table_clear(edje_obj, "table_part", EINA_TRUE);
+   else if (!edje_object_part_table_unpack(edje_obj, "table_part", obj))
+     fprintf(stderr, "Cannot remove the selected rectangle\n");
+
+   evas_object_del(obj);
+   _columns_rows_print();
+}
+
+static void
+_rects_create(void)
+{
+   int i;
+
+   for (i = 0; i < 4; i++)
+     {
+        rects[i] = evas_object_rectangle_add(evas);
+        evas_object_size_hint_min_set(rects[i], 200, 200);
+        evas_object_size_hint_weight_set(rects[i], 1.0, 1.0);
+        evas_object_show(rects[i]);
+        evas_object_event_callback_add(rects[i], EVAS_CALLBACK_MOUSE_DOWN,
+                                       _on_mouse_down, NULL);
+     }
+}
+
+int
+main(void)
+{
+   int i;
+
+   ecore_evas_init();
+   edje_init();
+
+   /* this will give you a window with an Evas canvas under the first
+    * engine available */
+   ee = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL);
+
+   ecore_evas_callback_destroy_set(ee, _on_destroy);
+   ecore_evas_callback_resize_set(ee, _canvas_resize_cb);
+   ecore_evas_title_set(ee, "Edje Table Example");
+   ecore_evas_show(ee);
+
+   evas = ecore_evas_get(ee);
+
+   bg = evas_object_rectangle_add(evas);
+   evas_object_color_set(bg, 255, 255, 255, 255); /* white bg */
+   evas_object_move(bg, 0, 0); /* at canvas' origin */
+   evas_object_resize(bg, WIDTH, HEIGHT); /* covers full canvas */
+   evas_object_show(bg);
+
+   edje_obj = edje_object_add(evas);
+
+   edje_object_file_set(edje_obj, edje_file_path, "example_table");
+   evas_object_move(edje_obj, 0, 0); /* at canvas' origin */
+   evas_object_resize(edje_obj, WIDTH, HEIGHT);
+   evas_object_show(edje_obj);
+
+   _rects_create();
+
+   /* Colouring the rectangles */
+   evas_object_color_set(rects[0], 255, 0, 0, 255);
+   evas_object_color_set(rects[1], 0, 255, 0, 255);
+   evas_object_color_set(rects[2], 0, 0, 255, 255);
+   evas_object_color_set(rects[3], 128, 128, 128, 255);
+
+   /* Packing the rectangles into the table */
+   if (!edje_object_part_table_pack(edje_obj, "table_part", rects[0],
+                                    0, 0, 1, 2))
+     fprintf(stderr, "Cannot add the rectangle 1 to table\n");
+
+   if (!edje_object_part_table_pack(edje_obj, "table_part", rects[1],
+                                    0, 1, 1, 1))
+     fprintf(stderr, "Cannot add the rectangle 2 to table\n");
+
+   if (!edje_object_part_table_pack(edje_obj, "table_part", rects[2],
+                                    1, 0, 1, 1))
+     fprintf(stderr, "Cannot add the rectangle 3 to table\n");
+
+   if (!edje_object_part_table_pack(edje_obj, "table_part", rects[3],
+                                    1, 1, 1, 1))
+     fprintf(stderr, "Cannot add the rectangle 4 to table\n");
+
+   _columns_rows_print();
+
+   ecore_main_loop_begin();
+
+   ecore_evas_free(ee);
+   ecore_evas_shutdown();
+   edje_shutdown();
+   return 0;
+}

legacy/edje/src/examples/table.edc

@@ -0,0 +1,19 @@
+collections {
+   group {
+      name: "example_table";
+      min: 50 50;
+
+      parts {
+         part {
+            name: "table_part";
+            type: TABLE;
+            description {
+               min: 50 50;
+               state: "default" 0.0;
+               rel1.relative: 0.0 0.0;
+               rel2.relative: 1.0 1.0;
+            }
+         }
+      }
+   }
+}

legacy/edje/src/lib/Edje.h

@@ -448,6 +448,7 @@ part of Edje's API:
 
 - @ref Example_Edje_Basics
 - @ref tutorial_edje_swallow
+- @ref tutorial_edje_table
 
 
 
@@ -3183,8 +3184,7 @@ EAPI Evas_Object *edje_object_part_table_child_get        (Evas_Object *obj, con
  * @param colspan Columns the child will take
  * @param rowspan Rows the child will take
  *
- * @return 1: Successfully added.\n
- * 0: An error occurred.
+ * @return @c EINA_TRUE object was added, @c EINA_FALSE on failure
  *
  * Packs an object into the table indicated by part.
  */
@@ -3197,8 +3197,7 @@ EAPI Eina_Bool    edje_object_part_table_pack             (Evas_Object *obj, con
  * @param part The part name
  * @param child_obj The object to pack in
  *
- * @return 1: Successfully removed.\n
- * 0: An error occurred.
+ * @return @c EINA_TRUE object removed, @c EINA_FALSE on failure
  *
  * Removes an object from the table indicated by part.
  */
@@ -3212,8 +3211,7 @@ EAPI Eina_Bool    edje_object_part_table_unpack           (Evas_Object *obj, con
  * @param cols Pointer where to store number of columns (can be NULL)
  * @param rows Pointer where to store number of rows (can be NULL)
  *
- * @return 1: Successfully get some data.\n
- * 0: An error occurred.
+ * @return @c EINA_TRUE get some data, @c EINA_FALSE on failure
  *
  * Retrieves the size of the table in number of columns and rows.
  */
@@ -3226,8 +3224,7 @@ EAPI Eina_Bool    edje_object_part_table_col_row_size_get (const Evas_Object *ob
  * @param part The part name
  * @param clear If set, will delete subobjs on remove
  *
- * @return 1: Successfully clear table.\n
- * 0: An error occurred.
+ * @return @c EINA_TRUE clear the table, @c EINA_FALSE on failure
  *
  * Removes all object from the table indicated by part, except the
  * internal ones set from the theme.