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 the full code here.

We start this example by including some header files that will be necessary to work with Emotion, and to display some debug messages:

//Compile with:
// gcc -o emotion_basic_example emotion_basic_example.c `pkg-config --libs --cflags emotion evas ecore ecore-evas eo`
#ifndef EFL_BETA_API_SUPPORT
# define EFL_BETA_API_SUPPORT
#endif
#include <Eo.h>
#include <Ecore.h>
#include <Ecore_Evas.h>
#include <Evas.h>
#include <Emotion.h>
#include <stdio.h>
Ecore_Evas.h
Evas wrapper functions.
Emotion.h
Emotion Media Library.

Then a callback will be declared, to be called when the object starts its playback:

#define WIDTH (320)
#define HEIGHT (240)
static void
_playback_started_cb(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
printf("Emotion object started playback.\n");
}
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition eina_types.h:339

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:

int
main(int argc, const char *argv[])
{
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);
ecore_evas_init
EAPI int ecore_evas_init(void)
Inits the Ecore_Evas system.
Definition ecore_evas.c:608
ecore_evas_show
EAPI void ecore_evas_show(Ecore_Evas *ee)
Shows an Ecore_Evas' window.
Definition ecore_evas.c:1494
ecore_evas_get
EAPI Evas * ecore_evas_get(const Ecore_Evas *ee)
Gets an Ecore_Evas's Evas.
Definition ecore_evas.c:1314
ecore_evas_new
EAPI Ecore_Evas * ecore_evas_new(const char *engine_name, int x, int y, int w, int h, const char *extra_options)
Creates a new Ecore_Evas based on engine name and common parameters.
Definition ecore_evas.c:1053
Evas
Eo Evas
An opaque handle to an Evas canvas.
Definition Evas_Common.h:163
evas_object_show
EVAS_API void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition evas_object_main.c:1814
evas_object_name_set
EVAS_API void evas_object_name_set(Evas_Object *eo_obj, const char *name)
Sets the name of the given Evas object to the given name.
Definition evas_name.c:5
evas_object_color_set
EVAS_API void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a)
Sets the general/main color of the given Evas object to the given one.
Definition evas_object_main.c:2024
evas_object_move
EVAS_API void evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y)
Move the given Evas object to the given location inside its canvas' viewport.
Definition evas_object_main.c:1171
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition Evas_Common.h:185
evas_object_resize
EVAS_API void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition evas_object_main.c:1236
evas_object_rectangle_add
EVAS_API Evas_Object * evas_object_rectangle_add(Evas *e)
Adds a rectangle to the given evas.
Definition evas_object_rectangle.c:78

Finally, we start the Emotion part. First we have to create the object in this canvas, and initialize it:

/* Creating the emotion object */
em = emotion_object_add(e);
emotion_object_init(em, NULL);
emotion_object_add
EMOTION_API Evas_Object * emotion_object_add(Evas *evas)
Add an emotion object to the canvas.
Definition emotion_smart.c:237

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():

efl_event_callback_add
(em, EFL_CANVAS_VIDEO_EVENT_PLAYBACK_START, _playback_started_cb, NULL);

The object itself is ready for use, but we need to load a file to it. This is done by the following function:

emotion_object_file_set(em, filename);
emotion_object_file_set
EMOTION_API Eina_Bool emotion_object_file_set(Evas_Object *obj, const char *filename)
Set the file to be played in the Emotion object.
Definition emotion_smart.c:355

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:

evas_object_move(em, 0, 0);
evas_object_resize(em, WIDTH, HEIGHT);
evas_object_show(em);

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:

emotion_object_play_set(em, EINA_TRUE);
ecore_main_loop_begin();
ecore_main_loop_begin
void ecore_main_loop_begin(void)
Runs the application main loop.
Definition ecore_main.c:1311
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition eina_types.h:539
emotion_object_play_set
EMOTION_API void emotion_object_play_set(Evas_Object *obj, Eina_Bool play)
Set play/pause state of the media file.
Definition emotion_smart.c:653

The rest of the code doesn't contain anything special:

ecore_evas_free(ee);
ecore_evas_shutdown();
return 0;
error:
fprintf(stderr, "error: Requires at least one Evas engine built and linked"
" to ecore-evas for this example to run properly.\n");
ecore_evas_shutdown();
return -1;
}
ecore_evas_shutdown
EAPI int ecore_evas_shutdown(void)
Shuts down the Ecore_Evas system.
Definition ecore_evas.c:672
ecore_evas_free
EAPI void ecore_evas_free(Ecore_Evas *ee)
Frees an Ecore_Evas.
Definition ecore_evas.c:1097

This code just free the canvas, shutdown the library, and has an entry point for exiting on error.