[ecore] Examples for the last batch of documentation

bumps.



SVN revision: 62152

legacy/ecore/doc/examples.dox

@@ -17,7 +17,9 @@
  * @li @ref ecore_evas_callbacks_example_c
  * @li @ref ecore_evas_object_example_c
  * @li @ref ecore_evas_basics_example_c
- *
+ * @li Ecore_Evas_Window_Sizes_Example_c
+ * @li Ecore_Evas_Buffer_Example_01_c
+ * @li Ecore_Evas_Buffer_Example_02_c
  */
 
 /**
@@ -1378,4 +1380,89 @@
  * Here you have the full-source of the code:
  * @include ecore_evas_basics_example.c
  * @example ecore_evas_basics_example.c
- */
+ */
+
+/**
+ * @page Ecore_Evas_Buffer_Example_01_c @c Ecore_Evas buffer example
+ *
+ * Between the Evas examples, there is one in which one creates a
+ * canvas bound to the Evas @b buffer engine and uses its pixel
+ * contents to create an PPM image on disk. There, one does that by
+ * creating the canvas "by hand", with @c evas_new(), @c
+ * evas_engine_info_set(), etc.
+ *
+ * On this example, we accomplish the very same task, but by using the
+ * @c Ecore_Evas helper wrapper functions on a buffer engine
+ * canvas. If you compare both codes, you'll see how much code one is
+ * saved from by using the @Ecore_Evas wrapper functions.
+ *
+ * The code is simple as it can be. After instantianting our canvas
+ * window, with ecore_evas_buffer_new(), we grab its canvas pointer
+ * and create the desired objects scene on it, which in this case is
+ * formed by 3 rectangles over the top left corner of a white
+ * background:
+ * @dontinclude ecore_evas_buffer_example_01.c
+ * @skip main(void)
+ * @until show(r3)
+ *
+ * Since it's a buffer canvas and we're using it to only save its
+ * contents on a file, we even needn't ecore_evas_show() it. We make
+ * it render itself, forcefully, without the aid of Ecore's mainloop,
+ * with ecore_evas_manual_render():
+ * @dontinclude ecore_evas_buffer_example_01.c
+ * @skip manual_render
+ * @until manual_render
+ *
+ * And we're ready to save the window's shiny rendered contents as a
+ * simple PPM image. We do so by grabbing the pixels of the @c
+ * Ecore_Evas' internal canvas, with ecore_evas_buffer_pixels_get():
+ * @dontinclude ecore_evas_buffer_example_01.c
+ * @skip _scene_save
+ * @until }
+ * @dontinclude ecore_evas_buffer_example_01.c
+ * @skip support function
+ * @until }
+ * @until }
+ * @until }
+ *
+ * Check that destination file for the result. The full example
+ * follows.
+ *
+ * @include ecore_evas_buffer_example_01.c
+ * @example ecore_evas_buffer_example_01.c
+ */
+
+/**
+ * @page Ecore_Evas_Buffer_Example_02_c @c Ecore_Evas (image) buffer example
+ *
+ * In this example, we'll demonstrate the use of
+ * ecore_evas_object_image_new().  The idea is to have the same scene
+ * created for @ref Ecore_Evas_Buffer_Example_01_c as the contents of
+ * an image object.
+ *
+ * The canvas receiving this image object will have a white
+ * background, a red border image to delimit this image's boundaries
+ * and the image itself.  After we create the special image, we set
+ * its "fill" property, place and resize it as we want. We have also
+ * to resize its underlying @c Ecore_Evas too, to the same dimensions:
+ * @dontinclude ecore_evas_buffer_example_02.c
+ * @skip object_image_new
+ * @until resize(sub_ee
+ *
+ * Now, we re-create the scene we cited, using the sub-canvas of our
+ * image to parent the objects in question. Because image objects are
+ * created with the alpha channel enabled, by default, we'll be seeing
+ * our white rectangle beneath the scene:
+ * @dontinclude ecore_evas_buffer_example_02.c
+ * @skip rectangle_add(sub_canvas
+ * @until loop_begin
+ *
+ * And that's all. The contents of our image could be updated as one
+ * wished, and they would always be mirrored in the image's area.
+ *
+ * Check that destination file for the result. The full example
+ * follows.
+ *
+ * @include ecore_evas_buffer_example_02.c
+ * @example ecore_evas_buffer_example_02.c
+ */

legacy/ecore/src/examples/Makefile.am

@@ -2,12 +2,16 @@ MAINTAINERCLEANFILES = Makefile.in
 
 pkglibdir = $(datadir)/$(PACKAGE)/examples
 
+filesdir = $(datadir)/$(PACKAGE)/examples
+files_DATA =
+
 AM_CPPFLAGS = \
 -I. \
 -I$(top_srcdir)/src/lib/ecore \
 -I$(top_srcdir)/src/lib/ecore_evas \
 -I$(top_srcdir)/src/lib/ecore_input \
 -I$(top_srcdir)/src/lib/ecore_con \
+-DPACKAGE_EXAMPLES_DIR=\"$(datadir)/$(PACKAGE)/examples\" \
 @GLIB_CFLAGS@ @EVIL_CFLAGS@ @EVAS_CFLAGS@ @EINA_CFLAGS@ @WIN32_CPPFLAGS@ @EFL_ECORE_BUILD@
 
 ECOREBASELDADD = \
@@ -47,15 +51,18 @@ SRCS = \
 	ecore_evas_callbacks.c \
 	ecore_evas_window_sizes_example.c \
 	ecore_evas_object_example.c \
-	ecore_evas_basics_example.c
+	ecore_evas_basics_example.c \
+	ecore_evas_buffer_example_01.c \
+	ecore_evas_buffer_example_02.c
 
-EXTRA_DIST = $(SRCS)
+EXTRA_DIST = $(SRCS) \
+	$(srcdir)/red.png
 
 pkglib_PROGRAMS =
 
 if EFL_INSTALL_EXAMPLES
-filesdir = $(datadir)/$(PACKAGE)/examples
-files_DATA = $(SRCS)
+files_DATA += $(SRCS) \
+	$(srcdir)/red.png
 endif
 
 if EFL_BUILD_EXAMPLES
@@ -80,7 +87,9 @@ pkglib_PROGRAMS += \
 	ecore_evas_callbacks \
 	ecore_evas_window_sizes_example \
 	ecore_evas_object_example \
-	ecore_evas_basics_example
+	ecore_evas_basics_example \
+	ecore_evas_buffer_example_01 \
+	ecore_evas_buffer_example_02
 
 ecore_con_lookup_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la
 ecore_con_url_headers_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la
@@ -90,6 +99,7 @@ ecore_con_server_simple_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/li
 ecore_con_server_http_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la
 ecore_con_client_simple_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la
 ecore_evas_window_sizes_example_LDADD = $(ECOREBASELDADD) @EVAS_LIBS@ $(top_builddir)/src/lib/ecore_evas/libecore_evas.la
+ecore_evas_buffer_example_01_LDADD = $(ECOREBASELDADD) @EVAS_LIBS@ $(top_builddir)/src/lib/ecore_evas/libecore_evas.la
+ecore_evas_buffer_example_02_LDADD = $(ECOREBASELDADD) @EVAS_LIBS@ $(top_builddir)/src/lib/ecore_evas/libecore_evas.la
 
 endif
-

legacy/ecore/src/examples/ecore_evas_buffer_example_01.c

@@ -0,0 +1,121 @@
+/**
+ * Simple Ecore_Evas example on the Evas buffer engine wrapper
+ * functions.
+ *
+ * You must have Evas compiled with the buffer engine.
+ *
+ * Compile with:
+ *
+ * @verbatim
+ * gcc -o evas-buffer-simple evas-buffer-simple.c `pkg-config --libs --cflags evas evas-software-buffer`
+ * @endverbatim
+ *
+ */
+
+#ifdef HAVE_CONFIG_H
+
+#include "config.h"
+#else
+#define __UNUSED__
+#endif
+
+#include <Ecore_Evas.h>
+#include <stdio.h>
+
+#define WIDTH  (320)
+#define HEIGHT (240)
+
+static Ecore_Evas *ee;
+
+/* support function to save scene as PPM image */
+static void
+_scene_save(Evas       *canvas,
+            const char *dest)
+{
+   const unsigned int *pixels, *pixels_end;
+   int width, height;
+   FILE *f;
+
+   evas_output_size_get(canvas, &width, &height);
+
+   f = fopen(dest, "wb+");
+   if (!f)
+     {
+        fprintf(stderr, "ERROR: could not open for writing '%s': %s\n",
+                dest, strerror(errno));
+        return;
+     }
+
+   pixels = ecore_evas_buffer_pixels_get(ee);
+   pixels_end = pixels + (width * height);
+
+   /* PPM P6 format is dead simple to write: */
+   fprintf(f, "P6\n%d %d\n255\n", width, height);
+   for (; pixels < pixels_end; pixels++)
+     {
+        int r, g, b;
+
+        r = ((*pixels) & 0xff0000) >> 16;
+        g = ((*pixels) & 0x00ff00) >> 8;
+        b = (*pixels) & 0x0000ff;
+
+        fprintf(f, "%c%c%c", r, g, b);
+     }
+
+   fclose(f);
+   printf("Saved scene as '%s'\n", dest);
+}
+
+int
+main(void)
+{
+   Evas *canvas;
+   Evas_Object *bg, *r1, *r2, *r3;
+
+   ecore_evas_init();
+
+   ee = ecore_evas_buffer_new(WIDTH, HEIGHT);
+   if (!ee) goto error;
+
+   canvas = ecore_evas_get(ee);
+
+   bg = evas_object_rectangle_add(canvas);
+   evas_object_color_set(bg, 255, 255, 255, 255); /* white bg */
+   evas_object_move(bg, 0, 0); /* at origin */
+   evas_object_resize(bg, WIDTH, HEIGHT); /* covers full canvas */
+   evas_object_show(bg);
+
+   r1 = evas_object_rectangle_add(canvas);
+   evas_object_color_set(r1, 255, 0, 0, 255); /* 100% opaque red */
+   evas_object_move(r1, 10, 10);
+   evas_object_resize(r1, 100, 100);
+   evas_object_show(r1);
+
+   r2 = evas_object_rectangle_add(canvas);
+   evas_object_color_set(r2, 0, 128, 0, 128); /* 50% opaque green */
+   evas_object_move(r2, 10, 10);
+   evas_object_resize(r2, 50, 50);
+   evas_object_show(r2);
+
+   r3 = evas_object_rectangle_add(canvas);
+   evas_object_color_set(r3, 0, 128, 0, 255); /* 100% opaque dark green */
+   evas_object_move(r3, 60, 60);
+   evas_object_resize(r3, 50, 50);
+   evas_object_show(r3);
+
+   ecore_evas_manual_render(ee);
+   _scene_save(canvas, "/tmp/evas-buffer-simple-render.ppm");
+
+   ecore_evas_free(ee);
+   ecore_evas_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;
+}
+

legacy/ecore/src/examples/ecore_evas_buffer_example_02.c

@@ -0,0 +1,126 @@
+/**
+ * Simple Ecore_Evas example on the Evas buffer engine wrapper
+ * functions.
+ *
+ * You must have Evas compiled with the buffer engine.
+ *
+ * Compile with:
+ *
+ * @verbatim
+ * gcc -o evas-buffer-simple evas-buffer-simple.c `pkg-config --libs --cflags evas evas-software-buffer`
+ * @endverbatim
+ *
+ */
+
+#ifdef HAVE_CONFIG_H
+
+#include "config.h"
+#else
+#define __UNUSED__
+#define PACKAGE_EXAMPLES_DIR "."
+#endif
+
+#include <Ecore.h>
+#include <Ecore_Evas.h>
+#include <stdio.h>
+
+#define WIDTH  (320)
+#define HEIGHT (240)
+
+static Ecore_Evas *ee;
+static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png";
+
+static void
+_on_destroy(Ecore_Evas *ee __UNUSED__)
+{
+   ecore_main_loop_quit();
+}
+
+int
+main(void)
+{
+   Evas *canvas, *sub_canvas;
+   Evas_Object *bg, *r1, *r2, *r3; /* "sub" canvas objects */
+   Evas_Object *border, *img; /* canvas objects */
+   Ecore_Evas *sub_ee;
+
+   ecore_evas_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);
+   if (!ee) goto error;
+
+   ecore_evas_size_min_set(ee, WIDTH, HEIGHT);
+   ecore_evas_size_max_set(ee, WIDTH, HEIGHT);
+
+   ecore_evas_callback_delete_request_set(ee, _on_destroy);
+   ecore_evas_title_set(ee, "Ecore_Evas buffer (image) example");
+   ecore_evas_show(ee);
+
+   canvas = ecore_evas_get(ee);
+
+   bg = evas_object_rectangle_add(canvas);
+   evas_object_color_set(bg, 255, 255, 255, 255); /* white bg */
+   evas_object_move(bg, 0, 0); /* at origin */
+   evas_object_resize(bg, WIDTH, HEIGHT); /* covers full canvas */
+   evas_object_show(bg);
+
+   /* this is a border around the image containing a scene of another
+    * canvas */
+   border = evas_object_image_filled_add(canvas);
+   evas_object_image_file_set(border, border_img_path, NULL);
+   evas_object_image_border_set(border, 3, 3, 3, 3);
+   evas_object_image_border_center_fill_set(border, EVAS_BORDER_FILL_NONE);
+
+   evas_object_move(border, WIDTH / 6, HEIGHT / 6);
+   evas_object_resize(border, (2 * WIDTH) / 3, (2 * HEIGHT) / 3);
+   evas_object_show(border);
+
+   img = ecore_evas_object_image_new(ee);
+   evas_object_image_filled_set(img, EINA_TRUE);
+   evas_object_image_size_set(
+       img, ((2 * WIDTH) / 3) - 6, ((2 * HEIGHT) / 3) - 6);
+   sub_ee = ecore_evas_object_ecore_evas_get(img);
+   sub_canvas = ecore_evas_object_evas_get(img);
+
+   evas_object_move(img, (WIDTH / 6) + 3, (HEIGHT / 6) + 3);
+
+   /* apply the same size on both! */
+   evas_object_resize(img, ((2 * WIDTH) / 3) - 6, ((2 * HEIGHT) / 3) - 6);
+   ecore_evas_resize(sub_ee, ((2 * WIDTH) / 3) - 6, ((2 * HEIGHT) / 3) - 6);
+
+   r1 = evas_object_rectangle_add(sub_canvas);
+   evas_object_color_set(r1, 255, 0, 0, 255); /* 100% opaque red */
+   evas_object_move(r1, 10, 10);
+   evas_object_resize(r1, 100, 100);
+   evas_object_show(r1);
+
+   r2 = evas_object_rectangle_add(sub_canvas);
+   evas_object_color_set(r2, 0, 128, 0, 128); /* 50% opaque green */
+   evas_object_move(r2, 10, 10);
+   evas_object_resize(r2, 50, 50);
+   evas_object_show(r2);
+
+   r3 = evas_object_rectangle_add(sub_canvas);
+   evas_object_color_set(r3, 0, 128, 0, 255); /* 100% opaque dark green */
+   evas_object_move(r3, 60, 60);
+   evas_object_resize(r3, 50, 50);
+   evas_object_show(r3);
+
+   evas_object_show(img);
+   ecore_main_loop_begin();
+
+   ecore_evas_free(ee);
+   ecore_evas_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;
+}
+

legacy/ecore/src/lib/ecore_evas/Ecore_Evas.h

@@ -62,6 +62,8 @@ extern "C" {
  *
  * This is a list of examples of these functions:
  * - @ref Ecore_Evas_Window_Sizes_Example_c
+ * - @ref Ecore_Evas_Buffer_Example_01_c
+ * - @ref Ecore_Evas_Buffer_Example_02_c
  * @{
  */
 
@@ -750,16 +752,20 @@ EAPI const void     *ecore_evas_buffer_pixels_get(Ecore_Evas *ee);
  * the canvas of @p ee, though, being exactly the image data of the
  * object returned by this function.
  *
- * This is a helper function for the scenario of one willing to grab a
+ * This is a helper function for the scenario of one wanting to grab a
  * buffer canvas' contents (with ecore_evas_buffer_pixels_get()) to be
  * used on another canvas, for whichever reason. The most common goal
  * of this setup is to @b save an image file with a whole canvas as
  * contents, which could not be achieved by using an image file within
  * the target canvas.
  *
- * @warning Always resize the returned image and its underlying @c
- * Ecore_Evas handle accordingly and successively. They must be kept
- * with same sizes for things to work as expected.
+ * @warning Always resize the returned image and its underlying
+ * @c Ecore_Evas handle accordingly. They must be kept with same sizes
+ * for things to work as expected. Also, you @b must issue
+ * @c evas_object_image_size_set() on the image with that same size. If
+ * the image is to be shown in a canvas bound to an engine different
+ * than the buffer one, then you must also set this image's @b fill
+ * properties accordingly.
  *
  * @note The image returned will always be bound to the
  * @c EVAS_COLORSPACE_ARGB8888 colorspace, always.