emotion/example - basic usage of emotion commented.

SVN revision: 61007

legacy/emotion/configure.ac

@@ -225,6 +225,10 @@ PKG_CHECK_MODULES([EIO],
 
 AM_CONDITIONAL([HAVE_EIO], [test "x${have_eio}" = "xyes"])
 
+### install and build examples
+
+EFL_CHECK_BUILD_EXAMPLES([enable_build_examples="yes"], [enable_build_examples="no"])
+EFL_CHECK_INSTALL_EXAMPLES([enable_install_examples="yes"], [enable_install_examples="no"])
 
 AC_SUBST(requirement_emotion)
 
@@ -242,6 +246,7 @@ src/modules/xine/Makefile
 src/modules/gstreamer/Makefile
 src/edje_external/Makefile
 src/bin/Makefile
+src/examples/Makefile
 doc/Makefile
 doc/Doxyfile
 doc/emotion.dox
@@ -275,6 +280,8 @@ echo "  Xattr................: ${have_xattr}"
 echo "  Eio..................: ${have_eio}"
 echo
 echo "Documentation..........: ${build_doc}"
+echo "Examples.............: ${enable_build_examples}"
+echo "Examples installed...: ${enable_install_examples}"
 echo
 echo "Compilation............: make (or gmake)"
 echo "  CPPFLAGS.............: $CPPFLAGS"

legacy/emotion/doc/examples.dox

@@ -0,0 +1,98 @@
+/**
+ * @page Examples Examples
+ *
+ * Here is a page with some Emotion examples explained:
+ *
+ * @li @ref emotion_basic_example_c
+ * @li @ref emotion_signals_example.c "Emotion signals"
+ *
+ */
+
+/**
+ * @page emotion_basic_example_c Emotion - Basic library usage
+ *
+ * This example shows how to setup a simple Emotion object, make it start
+ * playing and register a callback that tells when the playback started. See @ref
+ * emotion_basic_example.c "the full code here".
+ *
+ * @dontinclude emotion_basic_example.c
+ *
+ * We start this example by including some header files that will be necessary
+ * to work with Emotion, and to display some debug messages:
+ *
+ * @until stdio.h
+ *
+ * Then a callback will be declared, to be called when the object starts its
+ * playback:
+ *
+ * @until }
+ *
+ * Some basic setup of our canvas, window and background is necessary before
+ * displaying our object on it. This setup also includes reading the file to be
+ * opened from the program's argument list. Since this is not directly related
+ * to Emotion itself, we are just displaying the code for this without an
+ * explanation for it:
+ *
+ * @until evas_object_show(bg);
+ *
+ * Finally, we start the Emotion part. First we have to create the object in
+ * this canvas, and initialize it:
+ *
+ * @until emotion_object_init
+ *
+ * Notice that we didn't specify which module will be used, so emotion will use
+ * the first module found. There's no guarantee of the order that the modules
+ * will be found, so if you need to use one of them specifically, please be
+ * explicit in the second argument of the function emotion_object_init().
+ *
+ * Now the callback can be registered to this object. It's a normal Evas smart
+ * object callback, so we add it with evas_object_smart_callback_add():
+ *
+ * @until NULL
+ *
+ * The object itself is ready for use, but we need to load a file to it. This is
+ * done by the following function:
+ *
+ * @until file_set
+ *
+ * This object can play audio or video files. For the latter, the image must be
+ * displayed in our canvas, and that's why we need to add the object to the
+ * canvas. So, like any other Evas object in the canvas, we have to specify its
+ * position and size, and explicitly set its visibility. These are the position
+ * and dimension where the video will be displayed:
+ *
+ * @until evas_object_show
+ *
+ * Since the basic steps were done, we can now start playing our file. For this,
+ * we can just call the basic playback control function, and then we can go to
+ * the main loop and watch the audio/video playing:
+ *
+ * @until main_loop_begin
+ *
+ * The rest of the code doesn't contain anything special:
+ *
+ * @until }
+ *
+ * This code just free the canvas, shutdown the library, and has an entry point
+ * for exiting on error.
+ */
+
+
+/**
+ * @example emotion_basic_example.c
+ * This example show how to create and play an Emotion object. See @ref
+ * emotion_basic_example_c "the explanation here".
+ */
+
+/**
+ * @example emotion_signals_example.c
+ *
+ * This example shows that some of the information available from the emotion
+ * object, like the media file play length, aspect ratio, etc. can be not
+ * available just after setting the file to the emotion object.
+ *
+ * One callback is declared for each of the following signals, and some of the
+ * info about the file is displayed. Also notice that the order that these
+ * signals are emitted can change depending on the module being used. Following
+ * is the full source code of this example:
+ */

legacy/emotion/m4/efl_examples.m4

@@ -0,0 +1,63 @@
+dnl Copyright (C) 2008 Vincent Torri <vtorri at univ-evry dot fr>
+dnl That code is public domain and can be freely used or copied.
+
+dnl Macro that check if building examples is wanted.
+
+dnl Usage: EFL_CHECK_BUILD_EXAMPLES([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]])
+dnl Defines the automake conditionnal EFL_ENABLE_BUILD_EXAMPLES
+
+AC_DEFUN([EFL_CHECK_BUILD_EXAMPLES],
+[
+
+dnl configure option
+
+AC_ARG_ENABLE([build-examples],
+   [AC_HELP_STRING([--enable-build-examples], [enable building examples @<:@default=disabled@:>@])],
+   [
+    if test "x${enableval}" = "xyes" ; then
+       _efl_enable_build_examples="yes"
+    else
+       _efl_enable_build_examples="no"
+    fi
+   ],
+   [_efl_enable_build_examples="no"])
+
+AC_MSG_CHECKING([whether examples are built])
+AC_MSG_RESULT([${_efl_enable_build_examples}])
+
+AM_CONDITIONAL(EFL_BUILD_EXAMPLES, test "x${_efl_enable_build_examples}" = "xyes")
+
+AS_IF([test "x$_efl_enable_build_examples" = "xyes"], [$1], [$2])
+])
+
+
+dnl Macro that check if installing examples is wanted.
+
+dnl Usage: EFL_CHECK_INSTALL_EXAMPLES([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]])
+dnl Defines the automake conditionnal EFL_ENABLE_INSTALL_EXAMPLES
+
+AC_DEFUN([EFL_CHECK_INSTALL_EXAMPLES],
+[
+
+dnl configure option
+
+AC_ARG_ENABLE([install-examples],
+   [AC_HELP_STRING([--enable-install-examples], [enable installing example source files @<:@default=disabled@:>@])],
+   [
+    if test "x${enableval}" = "xyes" ; then
+       _efl_enable_install_examples="yes"
+    else
+       _efl_enable_install_examples="no"
+    fi
+   ],
+   [_efl_enable_install_examples="no"])
+
+AC_MSG_CHECKING([whether examples are installed])
+AC_MSG_RESULT([${_efl_enable_install_examples}])
+
+AM_CONDITIONAL(EFL_INSTALL_EXAMPLES, test "x${_efl_enable_install_examples}" = "xyes")
+
+AS_IF([test "x$_efl_enable_install_examples" = "xyes"], [$1], [$2])
+])
+
+dnl End of efl_examples.m4

legacy/emotion/src/Makefile.am

@@ -1,7 +1,7 @@
 
 MAINTAINERCLEANFILES = Makefile.in
 
-SUBDIRS = lib bin modules
+SUBDIRS = lib bin modules examples
 
 if ENABLE_EDJE_EXTERNAL
 SUBDIRS += edje_external

legacy/emotion/src/examples/Makefile.am

@@ -0,0 +1,35 @@
+MAINTAINERCLEANFILES = Makefile.in
+
+pkglibdir = $(datadir)/$(PACKAGE)/examples
+
+AM_CPPFLAGS = \
+-I. \
+-I$(top_srcdir) \
+-I$(top_srcdir)/src/lib \
+@EMOTION_CFLAGS@ \
+@EMOTION_CPPFLAGS@ \
+@EMOTION_BIN_CFLAGS@
+
+LDADD = \
+	$(top_builddir)/src/lib/libemotion.la \
+	@EMOTION_BIN_LIBS@
+
+SRCS = \
+	emotion_basic_example.c \
+	emotion_signals_example.c
+
+EXTRA_DIST = $(SRCS)
+
+pkglib_PROGRAMS =
+
+if EFL_INSTALL_EXAMPLES
+filesdir = $(datadir)/$(PACKAGE)/examples
+files_DATA = $(SRCS)
+endif
+
+if EFL_BUILD_EXAMPLES
+pkglib_PROGRAMS += \
+	emotion_basic_example \
+	emotion_signals_example
+endif
+

legacy/emotion/src/examples/emotion_basic_example.c

@@ -0,0 +1,82 @@
+#include <Ecore.h>
+#include <Ecore_Evas.h>
+#include <Evas.h>
+#include <Emotion.h>
+#include <stdio.h>
+
+#define WIDTH  (320)
+#define HEIGHT (240)
+
+static void
+_playback_started_cb(void *data, Evas_Object *o, void *event_info)
+{
+    printf("Emotion object started playback.\n");
+}
+
+int
+main(int argc, const char *argv[])
+{
+   int err;
+   Ecore_Evas *ee;
+   Evas *e;
+   Evas_Object *bg, *em;
+   const char *filename = NULL;
+
+   if (argc < 2)
+     {
+	printf("One argument is necessary. Usage:\n");
+	printf("\t%s <filename>\n", argv[0]);
+     }
+
+   filename = argv[1];
+
+   if (!ecore_evas_init())
+     return EXIT_FAILURE;
+
+   /* this will give you a window with an Evas canvas under the first
+    * engine available */
+   ee = ecore_evas_new(NULL, 10, 10, WIDTH, HEIGHT, NULL);
+   if (!ee)
+     goto error;
+
+   ecore_evas_show(ee);
+
+   /* the canvas pointer, de facto */
+   e = ecore_evas_get(ee);
+
+   /* adding a background to this example */
+   bg = evas_object_rectangle_add(e);
+   evas_object_name_set(bg, "our dear rectangle");
+   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);
+
+   /* Creating the emotion object */
+   em = emotion_object_add(e);
+   emotion_object_init(em, NULL);
+
+   evas_object_smart_callback_add(
+       em, "playback_started", _playback_started_cb, NULL);
+
+   emotion_object_file_set(em, filename);
+
+   evas_object_move(em, 0, 0);
+   evas_object_resize(em, WIDTH, HEIGHT);
+   evas_object_show(em);
+
+   emotion_object_play_set(em, EINA_TRUE);
+
+   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/emotion/src/examples/emotion_signals_example.c

@@ -0,0 +1,175 @@
+#include <Ecore.h>
+#include <Ecore_Evas.h>
+#include <Evas.h>
+#include <Emotion.h>
+#include <stdio.h>
+
+#define WIDTH  (320)
+#define HEIGHT (240)
+
+static void
+_display_info(Evas_Object *o)
+{
+   int w, h;
+   printf("playing: %d\n", emotion_object_play_get(o));
+   printf("meta title: %s\n",
+	  emotion_object_meta_info_get(o, EMOTION_META_INFO_TRACK_TITLE));
+   printf("seek position: %0.3f\n",
+	  emotion_object_position_get(o));
+   printf("play length: %0.3f\n",
+	  emotion_object_play_length_get(o));
+   printf("is seekable: %d\n",
+	  emotion_object_seekable_get(o));
+   emotion_object_size_get(o, &w, &h);
+   printf("video geometry: %dx%d\n", w, h);
+   printf("video width / height ratio: %0.3f\n",
+	  emotion_object_ratio_get(o));
+   printf("\n");
+}
+
+static void
+_playback_started_cb(void *data, Evas_Object *o, void *event_info)
+{
+   printf(">>> Emotion object started playback.\n");
+   _display_info(o);
+}
+
+static void
+_playback_finished_cb(void *data, Evas_Object *o, void *event_info)
+{
+   printf(">>> Emotion object finished playback.\n");
+   _display_info(o);
+}
+
+static void
+_open_done_cb(void *data, Evas_Object *o, void *event_info)
+{
+   printf(">>> Emotion object open done.\n");
+   _display_info(o);
+}
+
+static void
+_position_update_cb(void *data, Evas_Object *o, void *event_info)
+{
+   printf(">>> Emotion object first position update.\n");
+   evas_object_smart_callback_del(o, "position_update", _position_update_cb);
+   _display_info(o);
+}
+
+static void
+_frame_decode_cb(void *data, Evas_Object *o, void *event_info)
+{
+   printf(">>> Emotion object first frame decode.\n");
+   evas_object_smart_callback_del(o, "frame_decode", _frame_decode_cb);
+   _display_info(o);
+}
+
+static void
+_decode_stop_cb(void *data, Evas_Object *o, void *event_info)
+{
+   printf(">>> Emotion object decode stop.\n");
+   _display_info(o);
+}
+
+static void
+_frame_resize_cb(void *data, Evas_Object *o, void *event_info)
+{
+   printf(">>> Emotion object frame resize.\n");
+   _display_info(o);
+}
+
+static void
+_setup_emotion_callbacks(Evas_Object *o)
+{
+   evas_object_smart_callback_add(
+      o, "playback_started", _playback_started_cb, NULL);
+   evas_object_smart_callback_add(
+      o, "playback_finished", _playback_finished_cb, NULL);
+   evas_object_smart_callback_add(
+      o, "open_done", _open_done_cb, NULL);
+   evas_object_smart_callback_add(
+      o, "position_update", _position_update_cb, NULL);
+   evas_object_smart_callback_add(
+      o, "frame_decode", _frame_decode_cb, NULL);
+   evas_object_smart_callback_add(
+      o, "decode_stop", _decode_stop_cb, NULL);
+   evas_object_smart_callback_add(
+      o, "frame_resize", _frame_resize_cb, NULL);
+}
+
+int
+main(int argc, const char *argv[])
+{
+   int err;
+   Ecore_Evas *ee;
+   Evas *e;
+   Evas_Object *bg, *em;
+   const char *filename = NULL;
+   const char *module = NULL;
+
+   if (argc < 2)
+     {
+	printf("At least one argument is necessary. Usage:\n");
+	printf("\t%s <filename> [module_name]\n", argv[0]);
+	goto error;
+     }
+
+   filename = argv[1];
+
+   if (argc >= 3)
+     module = argv[2];
+
+   if (!ecore_evas_init())
+     return EXIT_FAILURE;
+
+   /* this will give you a window with an Evas canvas under the first
+    * engine available */
+   ee = ecore_evas_new(NULL, 10, 10, WIDTH, HEIGHT, NULL);
+   if (!ee)
+     goto error;
+
+   ecore_evas_show(ee);
+
+   /* the canvas pointer, de facto */
+   e = ecore_evas_get(ee);
+
+   /* adding a background to this example */
+   bg = evas_object_rectangle_add(e);
+   evas_object_name_set(bg, "our dear rectangle");
+   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);
+
+   /* Creating the emotion object */
+   em = emotion_object_add(e);
+
+   /* Try to load the specified module - NULL for auto-discover */
+   if (!emotion_object_init(em, module))
+     fprintf(stderr, "Emotion: \"%s\" module could not be initialized.\n", module);
+
+   _display_info(em);
+   _setup_emotion_callbacks(em);
+
+   if (!emotion_object_file_set(em, filename))
+     fprintf(stderr, "Emotion: Could not load the file \"%s\"\n", filename);
+
+   evas_object_move(em, 0, 0);
+   evas_object_resize(em, WIDTH, HEIGHT);
+   evas_object_show(em);
+
+   emotion_object_play_set(em, EINA_TRUE);
+
+   ecore_main_loop_begin();
+
+   ecore_evas_free(ee);
+   ecore_evas_shutdown();
+   return 0;
+
+emotion_error:
+   ecore_evas_free(ee);
+
+error:
+   ecore_evas_shutdown();
+   return -1;
+}