[edje] First commented example, along with infra to build it.

SVN revision: 61903

legacy/edje/configure.ac

@@ -371,6 +371,42 @@ case "$host_os" in
       ;;
 esac
 
+## Examples
+
+install_examples="yes"
+AC_ARG_ENABLE([install-examples],
+   AC_HELP_STRING([--disable-install-examples],
+                  [disable installing examples (compiled or just source).
+                   @<:@default==enabled@:>@]),
+   [
+    if test "x${enableval}" = "xyes" ; then
+       install_examples="yes"
+    else
+       install_examples="no"
+    fi
+   ],
+   [install_examples="yes"])
+AM_CONDITIONAL([INSTALL_EXAMPLES], [test "x${install_examples}" = "xyes"])
+
+build_examples="no"
+AC_ARG_ENABLE([build-examples],
+   AC_HELP_STRING([--enable-build-examples],
+                  [Enable building examples. This requires extra denpendencies. If you don't have them installed yet, don't build with this option or it will fail. Build again when you have it, overriding the previous installation). @<:@default==disabled@:>@]),
+   [
+    if test "x${enableval}" = "xyes" ; then
+       build_examples="yes"
+       edje_cc=$($PKG_CONFIG --variable=prefix edje)/bin/edje_cc
+       # put in here the dependencies for Edje' examples. They are
+       # meant to be 'real world' usage examples, thus one will be
+       # using higher level libraries on these programs
+       PKG_CHECK_MODULES([ECORE_EVAS], [ecore-evas ecore], [], [build_examples="no"])
+       AC_SUBST(edje_cc)
+    else
+       build_examples="no"
+    fi
+   ],
+   [build_examples="no"])
+AM_CONDITIONAL([BUILD_EXAMPLES], [test "x${build_examples}" = "xyes"])
 
 AC_SUBST(requirement_edje)
 
@@ -388,6 +424,7 @@ src/lib/Makefile
 src/bin/Makefile
 src/bin/epp/Makefile
 utils/Makefile
+src/examples/Makefile
 ])
 
 
@@ -409,6 +446,7 @@ echo "  EDJE_PROGRAM_CACHE...: $want_edje_program_cache"
 echo "  EDJE_CALC_CACHE......: $want_edje_calc_cache"
 echo "  Fixed point..........: $want_fixed_point"
 echo "  Documentation........: ${build_doc}"
+echo "  Examples.............: install:${install_examples} build:${build_examples}"
 echo
 echo "Programs:"
 echo

legacy/edje/doc/Doxyfile.in

@@ -586,7 +586,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = @srcdir@/edje.dox @top_srcdir@/src/bin/edje_cc_handlers.c @top_srcdir@/src/lib
+INPUT                  = @srcdir@/edje.dox @srcdir@/examples.dox @top_srcdir@/src/bin/edje_cc_handlers.c @top_srcdir@/src/lib
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is

legacy/edje/src/Makefile.am

@@ -1,4 +1,4 @@
 ## Process this file with automake to produce Makefile.in
 
-SUBDIRS = lib bin
+SUBDIRS = lib bin examples
 MAINTAINERCLEANFILES = Makefile.in

legacy/edje/src/examples/Makefile.am

@@ -0,0 +1,54 @@
+MAINTAINERCLEANFILES = Makefile.in
+
+pkglibdir = $(datadir)/$(PACKAGE)/examples
+
+#put here all EDCs one needs to the examples
+EDCS = basic.edc
+
+filesdir = $(datadir)/$(PACKAGE)/examples
+files_DATA =
+
+if BUILD_EXAMPLES
+
+AM_CPPFLAGS = \
+-I. \
+-I$(top_srcdir)/src/lib \
+-I$(top_srcdir)/src/lib/include \
+-DPACKAGE_BIN_DIR=\"$(bindir)\" \
+-DPACKAGE_LIB_DIR=\"$(libdir)\" \
+-DPACKAGE_DATA_DIR=\"$(datadir)/$(PACKAGE)\" \
+-DPACKAGE_EXAMPLES_DIR=\"$(datadir)/$(PACKAGE)/examples\"
+
+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@
+
+basic.edj: ${edje_basic_DEPS}
+
+.edc.edj:
+	$(edje_cc) -v -id $(srcdir) $< $(builddir)/$(@F)
+
+EDJS = $(EDCS:%.edc=%.edj)
+
+files_DATA += $(EDJS)
+
+endif # if BUILD_EXAMPLES
+
+if INSTALL_EXAMPLES
+
+#put here additional data when installing examples
+files_DATA += $(srcdir)/red.png
+
+files_DATA += \
+	$(EDCS) \
+	$(srcdir)/edje-basic.c
+endif
+
+EXTRA_DIST = $(EDCS) \
+	$(srcdir)/edje-basic.c

legacy/edje/src/examples/basic.edc

@@ -0,0 +1,39 @@
+collections {
+   group {
+      name: "example_group";
+      max: 500 500;
+      min: 50 50;
+
+      data {
+         item: "example_data" "a string";
+      }
+
+      parts {
+         part {
+            name: "part_one";
+            type: RECT;
+            scale: 1;
+            description {
+               min: 50 50;
+               max: 50 50;
+               state: "default" 0.0;
+               color: 0 0 255 255; /* blue */
+               rel1.relative: 0.0 0.0;
+               rel2.relative: 1.0 1.0;
+            }
+         }
+
+         part {
+            name: "part_two";
+            type: RECT;
+            description {
+               state: "default" 0.0;
+               color: 0 255 0 255; /* green */
+               rel1.relative: -1.0 -1.0;
+               rel2.relative: 0.0 0.0;
+            }
+         }
+      }
+
+   }
+}

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

@@ -0,0 +1,226 @@
+/**
+ * Simple Edje example illustrating the very basic functions of the
+ * library
+ *
+ * You'll need at least one Evas engine built for it (excluding the
+ * buffer one). See stdout/stderr for output.
+ *
+ * @verbatim
+ * gcc -o edje-basic edje-basic.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>
+#include <stdio.h>
+
+#define WIDTH  (300)
+#define HEIGHT (300)
+
+static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png";
+static const char *edje_file_path = PACKAGE_EXAMPLES_DIR "/basic.edj";
+
+static Ecore_Evas *ee;
+static Evas_Object *edje_obj;
+
+static const char *commands = \
+  "commands are:\n"
+  "\ts - change Edje's global scaling factor\n"
+  "\tr - change center rectangle's scaling factor\n"
+  "\th - print help\n";
+
+static void
+_on_keydown(void        *data __UNUSED__,
+            Evas        *evas __UNUSED__,
+            Evas_Object *o __UNUSED__,
+            void        *einfo)
+{
+   Evas_Event_Key_Down *ev = einfo;
+
+   if (strcmp(ev->keyname, "h") == 0) /* print help */
+     {
+        fprintf(stdout, commands);
+        return;
+     }
+
+   if (strcmp(ev->keyname, "s") == 0) /* global scaling factor */
+     {
+        double scale = edje_scale_get();
+
+        printf("got scale %f\n", scale);
+
+        if (scale != 1.0) scale = 1.0;
+        else scale = 2.0;
+
+        edje_scale_set(scale);
+
+        fprintf(stdout, "Setting global scaling factor to %f.\n", scale);
+
+        return;
+     }
+
+   if (strcmp(ev->keyname, "r") == 0) /* individual scaling factor */
+     {
+        double scale = edje_object_scale_get(edje_obj);
+
+        printf("got scale %f\n", scale);
+
+        if (!scale) scale = 1.0;
+        else if (scale == 1.0) scale = 2.0;
+        else scale = 0.0;
+
+        edje_object_scale_set(edje_obj, scale);
+
+        fprintf(stdout, "Setting center rectangle's scaling factor to %f.\n",
+                scale);
+
+        return;
+     }
+}
+
+static void
+_on_destroy(Ecore_Evas *ee __UNUSED__)
+{
+   ecore_main_loop_quit();
+}
+
+int
+main(void)
+{
+   Evas_Object *border, *bg;
+   int x, y, w, h;
+   Evas *evas;
+
+   if (!ecore_evas_init())
+     return EXIT_FAILURE;
+
+   if (!edje_init())
+     return EXIT_FAILURE;
+
+   /* 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);
+   if (!ee)
+     goto error;
+
+   ecore_evas_callback_destroy_set(ee, _on_destroy);
+   ecore_evas_title_set(ee, "Edje Basics 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);
+   ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE);
+
+   evas_object_focus_set(bg, EINA_TRUE);
+   evas_object_event_callback_add(
+       bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL);
+
+   edje_obj = edje_object_add(evas);
+
+   /* exercising Edje loading error, on purpose */
+   if (!edje_object_file_set(edje_obj, edje_file_path, "unexistant_group"))
+     {
+        int err = edje_object_load_error_get(edje_obj);
+        const char *errmsg = edje_load_error_str(err);
+        fprintf(stderr, "Could not load 'unexistant_group' from basic.edj:"
+                        " %s\n", errmsg);
+     }
+
+   if (!edje_object_file_set(edje_obj, edje_file_path, "example_group"))
+     {
+        int err = edje_object_load_error_get(edje_obj);
+        const char *errmsg = edje_load_error_str(err);
+        fprintf(stderr, "Could not load 'example_group' from basic.edj: %s\n",
+                errmsg);
+
+        evas_object_del(edje_obj);
+        goto error_edj;
+     }
+
+   fprintf(stdout, "Loaded Edje object bound to group 'example_group' from"
+                   " file basic.edj with success!\n");
+
+   evas_object_move(edje_obj, 20, 20);
+   evas_object_resize(edje_obj, WIDTH - 40, HEIGHT - 40);
+   evas_object_show(edje_obj);
+
+   /* this is a border around the Edje object above, here just to
+    * emphasize its geometry */
+   border = evas_object_image_filled_add(evas);
+   evas_object_image_file_set(border, border_img_path, NULL);
+   evas_object_image_border_set(border, 2, 2, 2, 2);
+   evas_object_image_border_center_fill_set(border, EVAS_BORDER_FILL_NONE);
+
+   evas_object_resize(border, WIDTH - 40 + 4, HEIGHT - 40 + 4);
+   evas_object_move(border, 20 - 2, 20 - 2);
+   evas_object_show(border);
+
+   fprintf(stdout, "'example_data' data field in group 'example_group' has "
+                   "the value: %s\n", edje_object_data_get(edje_obj,
+                                                           "example_data"));
+
+   fprintf(stdout, "Testing if 'part_one' part exists: %s\n",
+           edje_object_part_exists(edje_obj, "part_one") ? "yes!" : "no");
+
+   edje_object_part_geometry_get(edje_obj, "part_one", &x, &y, &w, &h);
+   fprintf(stdout, "The geometry of that part inside the Edje object's area "
+                   "is: x = %d, y = %d, w = %d, h = %d\n", x, y, w, h);
+
+   evas_object_color_get(edje_object_part_object_get(edje_obj, "part_one"),
+                         &x, &y, &w, &h);
+   fprintf(stdout, "That part's color components are: r = %d, g = %d, b = %d,"
+                   " a = %d\n", x, y, w, h);
+
+   edje_object_size_max_get(edje_obj, &w, &h);
+   fprintf(stdout, "The Edje object's max. size is: %d, %d\n", w, h);
+
+   edje_object_size_min_get(edje_obj, &w, &h);
+   fprintf(stdout, "The Edje object's min. size is: %d, %d\n", w, h);
+
+   edje_object_size_min_calc(edje_obj, &w, &h);
+   fprintf(stdout, "The Edje object's min. size reported by min. size"
+                   " calculation is: w = %d, h = %d\n", w, h);
+
+   edje_object_size_min_restricted_calc(edje_obj, &w, &h, 500, 500);
+   fprintf(stdout, "The Edje object's min. size reported by *restricted* "
+                   "min. size calculation is: w = %d, h = %d\n", w, h);
+
+   edje_object_parts_extends_calc(edje_obj, &x, &y, &w, &h);
+   fprintf(stdout, "The Edje object's \"extended\" geometry is: x = %d, "
+                   "y = %d, w = %d, h = %d\n", x, y, w, h);
+
+   fprintf(stdout, commands);
+   ecore_main_loop_begin();
+
+   ecore_evas_free(ee);
+   ecore_evas_shutdown();
+   edje_shutdown();
+   return 0;
+
+error:
+   fprintf(stderr, "You got to have at least one evas engine built"
+                   " and linked up to ecore-evas for this example to run"
+                   " properly.\n");
+   ecore_evas_shutdown();
+   return -1;
+
+error_edj:
+   fprintf(stderr, "Failed to load basic.edj!\n");
+
+   ecore_evas_shutdown();
+   return -2;
+}
+

legacy/edje/src/lib/Edje.h

@@ -441,8 +441,12 @@ Unlike Ebits, Edje separates the layout and behavior logic.
 
 
 
+@section Edje_Examples Examples on Edje's usage
 
+What follows is a list with varios commented examples, covering a great
+part of Edje's API:
 
+- @ref Example_Edje_Basics
 
 
 
@@ -1154,16 +1158,20 @@ EAPI const char  *edje_fontset_append_get         (void);
  *
  * Edje allows one to build scalable interfaces. Scaling factors,
  * which are set to neutral (@c 1.0) values by default (no scaling,
- * actual sizes), are of two types: @b global and @b
- * individual. Edje's global scaling factor will affect all its
- * objects which hadn't their individual scaling factors altered from
- * the default value. If they had it set differently, by
+ * actual sizes), are of two types: @b global and @b individual.
+ * Edje's global scaling factor will affect all its objects which
+ * hadn't their individual scaling factors altered from the default
+ * value (which is zero). If they had it set differently, by
  * edje_object_scale_set(), that factor will @b override the global
  * one.
  *
- * Scaling affects the values of mininum/maximum object sizes, which
+ * Scaling affects the values of mininum/maximum @b part sizes, which
  * are @b multiplied by it. Font sizes are scaled, too.
  *
+ * @warning Only parts which, at EDC level, had the @c "scale"
+ * property set to @c 1, will be affected by this function. Check the
+ * complete @ref edcref "syntax reference" for EDC files.
+ *
  * @see edje_scale_get().
  */
 EAPI void         edje_scale_set                  (double scale);
@@ -1213,16 +1221,19 @@ EAPI void edje_password_show_last_timeout_set(double password_show_last_timeout)
  * @brief Set the scaling factor for a given Edje object.
  *
  * @param obj A handle to an Edje object
- * @param scale The scaling factor (the defaul value is @c 1.0)
+ * @param scale The scaling factor (the default value is @c 0.0,
+ * meaning indivinual scaling @b not set)
  *
  * This function sets an @b individual scaling factor on the @a obj
  * Edje object. This property (or Edje's global scaling factor, when
- * applicable), will affect this object's parts. However, only parts
- * which, at the EDC language level, were declared which the
- * @c "scale" attribute set to @c 1 (default value being @c 0) will be
- * affected. That EDC attribute means that the given part is subject
- * to scaling. Check the complete @ref edcref "syntax reference" for
- * EDC files.
+ * applicable), will affect this object's part sizes. If @p scale is
+ * not zero, than the individual scaling will @b override any global
+ * scaling set, for the object @p obj's parts. Put it back to zero to
+ * get the effects of the global scaling again.
+ *
+ * @warning Only parts which, at EDC level, had the @c "scale"
+ * property set to @c 1, will be affected by this function. Check the
+ * complete @ref edcref "syntax reference" for EDC files.
  *
  * @see edje_object_scale_get()
  * @see edje_scale_get() for more details
@@ -1628,9 +1639,11 @@ EAPI Evas_Object *edje_object_add                 (Evas *evas);
  * @return The data's value string
  *
  * This function fetches an EDC data field's value, which is declared
- * on the objects building EDC file, <b>under its group</b>.
+ * on the objects building EDC file, <b>under its group</b>. EDC data
+ * blocks are most commonly used to pass arbitrary parameters from an
+ * application's theme to its code.
  *
- * Data fields in EDC files are @c "data" blocks, like the following:
+ * They look like the following:
  *
  * @code
  * collections {
@@ -2162,7 +2175,7 @@ EAPI void         edje_object_calc_force              (Evas_Object *obj);
  *
  * This call works exactly as edje_object_size_min_restricted_calc(),
  * with the last two arguments set to 0. Please refer to its
- * documentation, than.
+ * documentation, then.
  */
 EAPI void         edje_object_size_min_calc           (Evas_Object *obj, Evas_Coord *minw, Evas_Coord *minh);
 
@@ -2221,8 +2234,7 @@ EAPI Eina_Bool    edje_object_parts_extends_calc      (Evas_Object *obj, Evas_Co
  * sizes. The caller is the one up to change its geometry or not.
  *
  * @warning Be advised that invisible parts in @p obj @b will be taken
- * into account in this calculation. If you don't want that to happen,
- * resize those parts to zeroed dimensions.
+ * into account in this calculation.
  */
 EAPI void         edje_object_size_min_restricted_calc(Evas_Object *obj, Evas_Coord *minw, Evas_Coord *minh, Evas_Coord restrictedw, Evas_Coord restrictedh);