Top Level Functions

Functions that affect Evas as a whole. More...

Functions
EVAS_API int	evas_init (void)
	Directly initialize Evas and its required dependencies. More...
EVAS_API int	evas_shutdown (void)
	Directly shutdown Evas. More...
EVAS_API Evas_Alloc_Error	evas_alloc_error (void)
	Get the error status of the most recent memory allocation call. More...
EVAS_API int	evas_async_events_fd_get (void)
	Access the canvas' asynchronous event queue. More...
EVAS_API int	evas_async_events_process (void)
	Process the asynchronous event queue. More...
EVAS_API Eina_Bool	evas_async_events_put (const void *target, Evas_Callback_Type type, void *event_info, Evas_Async_Events_Put_Cb func)
	Insert asynchronous events on the canvas. More...

Variables
EVAS_API Evas_Version *	evas_version
	Evas Version Information.

Detailed Description

Functions that affect Evas as a whole.

Function Documentation

evas_init()

EVAS_API int evas_init

(

void

)

Directly initialize Evas and its required dependencies.

Returns

The number of times evas_init() has been called.

Permits use of Evas independently from Ecore. This can be useful in certain types of examples and test programs, as well as by Ecore-Evas' ecore_evas_init() itself (which is what most EFL applications will be using instead).

The evas-buffer-simple.c example demonstrates use of evas_init(), and then manually setting up the canvas:

int main(void)
{
   Evas *canvas;
   Evas_Object *bg, *r1, *r2, *r3;
 
   evas_init();
 
   /* After turning Evas on, we create an Evas canvas to work in.
    * Canvases are graphical workspaces used for placing and organizing
    * graphical objects.  Normally we'd be using Ecore-Evas to create
    * the canvas, but for this example we'll hide the details in a
    * separate routine for convenience.
    */
   canvas = create_canvas(WIDTH, HEIGHT);
   if (!canvas)
     return -1;

The canvas is set up using the example's create_canvas() routine, which forces selection of Evas' "buffer" rendering engine. The buffer engine simply renders to a memory buffer with no hardware acceleration.

static Evas *create_canvas(int width, int height)
{
   Evas *canvas;
   Evas_Engine_Info_Buffer *einfo;
   int method;
   void *pixels;
 
   /* Request a handle for the 'buffer' type of rendering engine. */
   method = evas_render_method_lookup("buffer");
   if (method <= 0)
     {
        fputs("ERROR: evas was not compiled with 'buffer' engine!\n", stderr);
        return NULL;
     }
 
   /* Create a general canvas object.
    * Note that we are responsible for freeing the canvas when we're done. */
   canvas = evas_new();
   if (!canvas)
     {
        fputs("ERROR: could not instantiate new evas canvas.\n", stderr);
        return NULL;
     }
 
   /* Specify that the canvas will be rendering using the buffer engine method.
    * We also size the canvas and viewport to the same width and height, with
    * the viewport set to the origin of the canvas.
    */
   evas_output_method_set(canvas, method);
   evas_output_size_set(canvas, width, height);
   evas_output_viewport_set(canvas, 0, 0, width, height);

See also

evas_shutdown().

References ecore_init(), eet_init(), eet_shutdown(), eina_init(), eina_log_domain_register(), eina_log_domain_unregister(), EINA_LOG_ERR, EINA_LOG_STATE_INIT, EINA_LOG_STATE_STOP, eina_log_timing(), EINA_SAFETY_ON_FALSE_GOTO, eina_shutdown(), EINA_TRUE, evil_init(), and evil_shutdown().

Referenced by ecore_evas_init(), edje_init(), and elm_quicklaunch_fork().

evas_shutdown()

EVAS_API int evas_shutdown

(

void

)

Directly shutdown Evas.

Returns

The (decremented) init reference counter.

Low level routine to finalize Evas. Decrements a counter of the number of times evas_init() has been called, and, if appropriate, shuts down associated dependency modules and libraries. A return value of 0 indicates that everything has been properly shut down.

Ecore-Evas applications will typically use ecore_evas_shutdown() instead, as described in evas_init().

The evas-buffer-simple.c example shows use of evas_shutdown() in its destroy_canvas() routine:

static void destroy_canvas(Evas *canvas);
static void draw_scene(Evas *canvas);
static void save_scene(Evas *canvas, const char *dest);
 
int main(void)
{
   Evas *canvas;
   Evas_Object *bg, *r1, *r2, *r3;
 
   evas_init();
 
   /* After turning Evas on, we create an Evas canvas to work in.
    * Canvases are graphical workspaces used for placing and organizing
    * graphical objects.  Normally we'd be using Ecore-Evas to create
    * the canvas, but for this example we'll hide the details in a
    * separate routine for convenience.
    */
   canvas = create_canvas(WIDTH, HEIGHT);
   if (!canvas)
     return -1;
 
   /* Next set the background to solid white.  This is typically done by
    * creating a rectangle sized to the canvas, placed at the canvas
    * origin.
    *
    * Note that if the canvas were to change size, our background
    * rectangle will not automatically resize itself; we'd need to do
    * that manually with another evas_object_resize() call.  In a real
    * application using Ecore-Evas, functionality in Ecore will take
    * care of resizing things.  For this example, we'll just keep the
    * canvas dimensions fixed to avoid the problem.
    */
   bg = evas_object_rectangle_add(canvas);
   evas_object_color_set(bg, 255, 255, 255, 255); // white bg, no transparency
   evas_object_move(bg, 0, 0);                    // at origin
   evas_object_resize(bg, WIDTH, HEIGHT);         // covers full canvas
   evas_object_show(bg);
 
   puts("initial scene, with just background:");
   draw_scene(canvas);
 
   /* To make the scene interesting let's add a few more rectangles of
    * various sizes and colors, starting with a big red one.
    *
    * By default all Evas objects are created in a 'hidden' state,
    * meaning they are not visible, won't be checked for changes during
    * canvas rendering, and won't receive input events.  Thus, like we
    * did for the background object we must call evas_object_show() to
    * make our graphics objects usable.
    */
   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);
 
   /* Let's add a partly transparent rectangle on top of the red one.
    *
    * Graphics objects are treated as a stack in the canvas for drawing
    * purposes, so subsequent objects are drawn above the ones we've
    * already added to the canvas.  This is important in objects that
    * have partially transparent fill coloring since we'll see part of
    * what's "behind" our object.
    *
    * In Evas, color values are pre-multiplied by their alpha.  This means
    * that if we want a green rectangle that's half transparent, we'd have:
    *
    * non-premul: r=0, g=255, b=0    a=128 (50% alpha)
    * premul:
    *         r_premul = r * a / 255 =      0 * 128 / 255 =      0
    *         g_premul = g * a / 255 =    255 * 128 / 255 =    128
    *         b_premul = b * a / 255 =      0 * 128 / 255 =      0
    *
    * Since we're placing our half transparent green rectangle on top of
    * a red one, in the final output we will actually see a yellow square
    * (since in RGBA color green + red = yellow).
    */
   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);
 
   /* Lastly, for comparison add a dark green rectangle with no
    * transparency. */
   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);
 
   puts("final scene (note updates):");
   draw_scene(canvas);
 
   /* In addition to displaying the canvas to the screen, let's also
    * output the buffer to a graphics file, for comparison.  Evas
    * supports a range of graphics file formats, but PPM is particularly
    * trivial to write, so our save_scene routine will output as PPM.
    */
   save_scene(canvas, "/tmp/evas-buffer-simple-render.ppm");
 
   destroy_canvas(canvas);
 
   evas_shutdown();
 
   return 0;
}
 
/* Convenience routine to allocate and initialize the canvas.
 * In a real application we'd be using ecore_evas_buffer_new() instead.
 */
static Evas *create_canvas(int width, int height)
{
   Evas *canvas;
   Evas_Engine_Info_Buffer *einfo;
   int method;
   void *pixels;
 
   /* Request a handle for the 'buffer' type of rendering engine. */
   method = evas_render_method_lookup("buffer");
   if (method <= 0)
     {
        fputs("ERROR: evas was not compiled with 'buffer' engine!\n", stderr);
        return NULL;
     }
 
   /* Create a general canvas object.
    * Note that we are responsible for freeing the canvas when we're done. */
   canvas = evas_new();
   if (!canvas)
     {
        fputs("ERROR: could not instantiate new evas canvas.\n", stderr);
        return NULL;
     }
 
   /* Specify that the canvas will be rendering using the buffer engine method.
    * We also size the canvas and viewport to the same width and height, with
    * the viewport set to the origin of the canvas.
    */
   evas_output_method_set(canvas, method);
   evas_output_size_set(canvas, width, height);
   evas_output_viewport_set(canvas, 0, 0, width, height);
 
   /* Before we can use the engine, we *must* set its configuration
    * parameters.  The available parameters are kept in a struct
    * named Evas_Engine_Info which is internal to Evas.  Thus to set
    * parameters we must first request the current info object from
    * our canvas:
    */
   einfo = (Evas_Engine_Info_Buffer *)evas_engine_info_get(canvas);
   if (!einfo)
     {
        fputs("ERROR: could not get evas engine info!\n", stderr);
        evas_free(canvas);

See also

evas_init().

References ecore_shutdown(), eet_shutdown(), eina_cow_del(), eina_log_domain_unregister(), EINA_LOG_ERR, EINA_LOG_STATE_SHUTDOWN, EINA_LOG_STATE_START, eina_log_timing(), eina_shutdown(), evas_font_path_global_clear(), and evil_shutdown().

Referenced by ecore_evas_init(), and ecore_evas_shutdown().

evas_alloc_error()

EVAS_API Evas_Alloc_Error evas_alloc_error

(

void

)

Get the error status of the most recent memory allocation call.

Returns

Allocation error codes EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED.

Accesses the current error status for memory allocation, or EVAS_ALLOC_ERROR_NONE if allocation succeeded with no errors.

EVAS_ALLOC_ERROR_FATAL means that no memory allocation was possible, but the function call exited as cleanly as possible. This is a sign of very low memory, and indicates the caller should attempt a safe recovery and possibly re-try after freeing up additional memory.

EVAS_ALLOC_ERROR_RECOVERED indicates that Evas was able to free up sufficient memory internally to perform the requested memory allocation and the program will continue to function normally, but memory is in a low state and the program should strive to free memory itself. Evas' approach to free memory internally may reduce the resolution of images, free cached fonts or images, throw out pre-rendered data, or reduce the complexity of change lists.

Example:

extern Evas_Object *object;
void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
 
evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
  {
    fprintf(stderr, "ERROR: Failed to attach callback.  Out of memory.\n");
    fprintf(stderr, "       Must destroy object now as it cannot be used.\n");
    evas_object_del(object);
    object = NULL;
    fprintf(stderr, "WARNING: Cleaning out RAM.\n");
    my_memory_cleanup();
  }
if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
  {
    fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
    my_memory_cleanup();
  }

Examples

evas-events.c.

evas_async_events_fd_get()

EVAS_API int evas_async_events_fd_get

(

void

)

Access the canvas' asynchronous event queue.

Returns

A file descriptor to the asynchronous events.

Normally, Evas handles asynchronous events internally, particularly in Evas-using modules that are part of the EFL infrastructure. Notably, ecore-evas takes care of processing these events for canvases instantiated through it.

However, when asynchronous calculations need to be done outside the main thread (in some other mainloop) with some followup action, this function permits accessing the events. An example would be asynchronous image preloading.

evas_async_events_process()

EVAS_API int evas_async_events_process

(

void

)

Process the asynchronous event queue.

Returns

The number of events processed.

Triggers the callback functions for asynchronous events that were queued up by evas_async_events_put(). The callbacks are called in the same order that they were queued.

References ecore_pipe_wait().

evas_async_events_put()

EVAS_API Eina_Bool evas_async_events_put	(	const void *	target,
		Evas_Callback_Type	type,
		void *	event_info,
		Evas_Async_Events_Put_Cb	func
	)

Insert asynchronous events on the canvas.

Parameters

target	The target to be affected by the events.
type	The type of callback function.
event_info	Information about the event.
func	The callback function pointer.

Returns

EINA_FALSE if an error occurred, EINA_TRUE otherwise.

Allows routines running outside Evas' main thread to report an asynchronous event. The target, type, and event info will be passed to the callback function when evas_async_events_process() is called.

References ecore_pipe_write(), EINA_FALSE, eina_inarray_grow(), eina_spinlock_release(), eina_spinlock_take(), EINA_TRUE, and _Eina_Inarray::len.