Edje: edje swallow documentation.

git-svn-id: http://svn.enlightenment.org/svn/e/trunk/edje@61905 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/doc/examples.dox b/doc/examples.dox
index e8f4f57..5a7b697 100644 (file)
--- a/doc/examples.dox
+++ b/doc/examples.dox
@@ -4,6 +4,7 @@
  * Here is a page with examples.
  *
  * @ref Example_Edje_Basics
+ * @ref tutorial_edje_swallow
  */
 
 /**
@@ -127,3 +128,26 @@
  * @include edje-basic.c
  * @example edje-basic.c
  */
+
+/**
+ * @page tutorial_edje_swallow Swallow example
+ * @dontinclude edje-swallow.c
+ *
+ * This is a simple example in which we create a rect and swallow it.
+ *
+ * Focusing on the relevant parts of the code we go right to the creation of our
+ * rectangle. It should be noted that we don't resize or show our rect, that is
+ * because when an object is swallowed it's geometry and visibility is
+ * controlled by the theme:
+ * @skip 20
+ * @skipline evas_object_rectangle_add
+ * @until swallow
+ *
+ * The other bit of code that is relevant to us now is our check that the
+ * swallow worked:
+ * @until printf
+ *
+ * The full source code follows:
+ * @include edje-swallow.c
+ * @example edje-swallow.c
+ */
\ No newline at end of file

diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index 6faabdb..0da97fc 100644 (file)
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -3,7 +3,8 @@ MAINTAINERCLEANFILES = Makefile.in
 pkglibdir = $(datadir)/$(PACKAGE)/examples
 
 #put here all EDCs one needs to the examples
-EDCS = basic.edc
+EDCS = basic.edc \
+       swallow.edc
 
 filesdir = $(datadir)/$(PACKAGE)/examples
 files_DATA =
@@ -24,12 +25,11 @@ pkglib_PROGRAMS =
 #the ones using ecore_evas follow
 AM_CPPFLAGS += @ECORE_EVAS_CFLAGS@
 
-pkglib_PROGRAMS += edje_basic
-edje_basic_DEPS = $(srcdir)/basic.edc
-edje_basic_SOURCES = edje-basic.c
-edje_basic_LDADD = $(top_builddir)/src/lib/libedje.la @ECORE_EVAS_LIBS@
+pkglib_PROGRAMS += \
+       edje-basic \
+       edje-swallow
 
-basic.edj: ${edje_basic_DEPS}
+LDADD = $(top_builddir)/src/lib/libedje.la @ECORE_EVAS_LIBS@
 
 .edc.edj:
        $(edje_cc) -v -id $(srcdir) $< $(builddir)/$(@F)
@@ -47,8 +47,10 @@ files_DATA += $(srcdir)/red.png
 
 files_DATA += \
        $(EDCS) \
-       $(srcdir)/edje-basic.c
+       $(srcdir)/edje-basic.c \
+       $(srcdir)/edje-swallow.c
 endif
 
 EXTRA_DIST = $(EDCS) \
-       $(srcdir)/edje-basic.c
\ No newline at end of file
+       $(srcdir)/edje-basic.c \
+       $(srcdir)/edje-swallow.c
\ No newline at end of file

diff --git a/src/examples/edje-swallow.c b/src/examples/edje-swallow.c
new file mode 100644 (file)
index 0000000..6ace1aa
--- /dev/null
+++ b/src/examples/edje-swallow.c
@@ -0,0 +1,95 @@
+/**
+ * Simple Edje example illustrating swallow functions.
+ *
+ * You'll need at least one Evas engine built for it (excluding the
+ * buffer one). See stdout/stderr for output.
+ *
+ * @verbatim
+ * edje_cc swallow.edc && gcc -o edje-swallow edje-swallow.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)
+
+static const char *edje_file_path = PACKAGE_EXAMPLES_DIR "/swallow.edj";
+
+static Ecore_Evas *ee;
+static 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;
+
+   ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
+   evas_object_resize(bg, w, h);
+}
+
+int
+main(void)
+{
+   Evas_Object *edje_obj, *rect, *obj;
+   Evas *evas;
+
+   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 Swallow 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_group");
+   evas_object_move(edje_obj, 20, 20);
+   evas_object_resize(edje_obj, WIDTH - 40, HEIGHT - 40);
+   evas_object_show(edje_obj);
+
+   rect = evas_object_rectangle_add(evas);
+   evas_object_color_set(rect, 255, 0, 0, 255);
+   edje_object_part_swallow(edje_obj, "part_one", rect);
+
+   obj = edje_object_part_swallow_get(edje_obj, "part_one");
+   if(obj == rect)
+      printf("Swallowing worked!\n");
+
+   ecore_main_loop_begin();
+
+   ecore_evas_free(ee);
+   ecore_evas_shutdown();
+   edje_shutdown();
+   return 0;
+}

diff --git a/src/examples/swallow.edc b/src/examples/swallow.edc
new file mode 100644 (file)
index 0000000..a62a0b5
--- /dev/null
+++ b/src/examples/swallow.edc
@@ -0,0 +1,21 @@
+collections {
+   group {
+      name: "example_group";
+      max: 500 500;
+      min: 50 50;
+
+      parts {
+         part {
+            name: "part_one";
+            type: SWALLOW;
+            description {
+               min: 50 50;
+               state: "default" 0.0;
+               rel1.relative: 0.0 0.0;
+               rel2.relative: 1.0 1.0;
+            }
+         }
+      }
+
+   }
+}

diff --git a/src/lib/Edje.h b/src/lib/Edje.h
index e7a61cc..5b67d8c 100644 (file)
--- a/src/lib/Edje.h
+++ b/src/lib/Edje.h
@@ -447,6 +447,7 @@ What follows is a list with varios commented examples, covering a great
 part of Edje's API:
 
 - @ref Example_Edje_Basics
+- @ref tutorial_edje_swallow
 
 
 
@@ -2775,7 +2776,6 @@ EAPI void            *edje_object_text_insert_filter_callback_del       (Evas_Ob
  */
 EAPI void            *edje_object_text_insert_filter_callback_del_full  (Evas_Object *obj, const char *part, Edje_Text_Filter_Cb func, void *data);
 
-
 /**
  * @brief Swallows an object into the edje.
  *
@@ -2798,7 +2798,9 @@ EAPI Eina_Bool        edje_object_part_swallow        (Evas_Object *obj, const c
  * @param obj A valid Evas_Object handle
  * @param obj_swallow The swallowed object
  *
- * Causes the edje to regurgitate a previously swallowed object.  :)
+ * Causes the edje to regurgitate a previously swallowed object. :)
+ *
+ * @note @p obj_swallow will be deleted.
  */
 EAPI void             edje_object_part_unswallow      (Evas_Object *obj, Evas_Object *obj_swallow);