Functions that affect Evas as a whole.

Functions
int	evas_init (void)
int	evas_shutdown (void)
Evas_Alloc_Error	evas_alloc_error (void)
int	evas_async_events_fd_get (void)
	Get evas' internal asynchronous events read file descriptor.
int	evas_async_events_process (void)
	Trigger the processing of all events waiting on the file descriptor returned by evas_async_events_fd_get().
Eina_Bool	evas_async_events_put (const void target, Evas_Callback_Type type, void event_info, Evas_Async_Events_Put_Cb func)

Function Documentation

Evas_Alloc_Error evas_alloc_error ( void )

Return if any allocation errors have occurred during the prior function

Returns:: The allocation error flag

This function will return if any memory allocation errors occurred during, and what kind they were. The return value will be one of EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED with each meaning something different.

EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function worked as expected.

EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform its job and will have exited as cleanly as possible. The programmer should consider this as a sign of very low memory and should try and safely recover from the prior functions failure (or try free up memory elsewhere and try again after more memory is freed).

EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was recovered from by evas finding memory of its own it has allocated and freeing what it sees as not really usefully allocated memory. What is freed may vary. Evas may reduce the resolution of images, free cached images or fonts, throw out pre-rendered data, reduce the complexity of change lists etc. Evas and the program will function as per normal after this, but this is a sign of low memory, and it is suggested that the program try and identify memory it doesn't need, and free it.

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: Completely unable to attach callback. Must\n");
     fprintf(stderr, "       destroy object now as it cannot be used.\n");
     evas_object_del(object);
     object = NULL;
     fprintf(stderr, "WARNING: Memory is really low. 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();
   }

Since :: 3.0

Examples:: evas-events.c.

int evas_async_events_fd_get ( void )

Get evas' internal asynchronous events read file descriptor.

Returns:: The canvas' asynchronous events read file descriptor.

Evas' asynchronous events are meant to be dealt with internally, i. e., when building stuff to be glued together into the EFL infrastructure -- a module, for example. The context which demands its use is when calculations need to be done out of the main thread, asynchronously, and some action must be performed after that.

An example of actual use of this API is for image asynchronous preload inside evas. If the canvas was instantiated through ecore-evas usage, ecore itself will take care of calling those events' processing.

This function returns the read file descriptor where to get the asynchronous events of the canvas. Naturally, other mainloops, apart from ecore, may make use of it.

Since :: 3.0

int evas_async_events_process ( void )

Trigger the processing of all events waiting on the file descriptor returned by evas_async_events_fd_get().

Returns:: The number of events processed.

All asynchronous events queued up by evas_async_events_put() are processed here. More precisely, the callback functions, informed together with other event parameters, when queued, get called (with those parameters), in that order.

Since :: 3.0

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.

This is the way, for a routine running outside evas' main thread, to report an asynchronous event. A callback function is informed, whose call is to happen after evas_async_events_process() is called.

Since :: 3.0

int evas_init ( void )

Initialize Evas

Returns:: The init counter value.

This function initializes Evas and increments a counter of the number of calls to it. It returns the new counter's value.

See also:: evas_shutdown().

Most EFL users wouldn't be using this function directly, because they wouldn't access Evas directly by themselves. Instead, they would be using higher level helpers, like ecore_evas_init(). See Ecore.

You should be using this if your use is something like the following. The buffer engine is just one of the many ones Evas provides.

int main(void)
{
   Evas *canvas;
   Evas_Object *bg, *r1, *r2, *r3;

   evas_init();

   // create your canvas
   // NOTE: consider using ecore_evas_buffer_new() instead!
   canvas = create_canvas(WIDTH, HEIGHT);
   if (!canvas)
     return -1;

And being the canvas creation something like:

static Evas *create_canvas(int width, int height)
{
   Evas *canvas;
   Evas_Engine_Info_Buffer *einfo;
   int method;
   void *pixels;

   method = evas_render_method_lookup("buffer");
   if (method <= 0)
     {
    fputs("ERROR: evas was not compiled with 'buffer' engine!\n", stderr);
    return NULL;
     }

   canvas = evas_new();
   if (!canvas)
     {
    fputs("ERROR: could not instantiate new evas canvas.\n", stderr);
    return NULL;
     }

   evas_output_method_set(canvas, method);
   evas_output_size_set(canvas, width, height);
   evas_output_viewport_set(canvas, 0, 0, width, height);

Note that this is code creating an Evas canvas with no usage of Ecore helpers at all -- no linkage with Ecore on this scenario, thus. Again, this wouldn't be on Evas common usage for most developers. See the full example.

Since :: 3.0

Examples:: eina_tiler_01.c, evas-buffer-simple.c, and evas-init-shutdown.c.

int evas_shutdown ( void )

Shutdown Evas

Returns:: Evas' init counter value.

This function finalizes Evas, decrementing the counter of the number of calls to the function evas_init(). This new value for the counter is returned.

See also:: evas_init().

If you were the sole user of Evas, by means of evas_init(), you can check if it's being properly shut down by expecting a return value of 0.

Example code follows.

   // NOTE: use ecore_evas_buffer_new() and here ecore_evas_free()
   destroy_canvas(canvas);

   evas_shutdown();

Where that function would contain:

    evas_free(canvas);

Most users would be using ecore_evas_shutdown() instead, like told in evas_init(). See the full example.

Since :: 3.0

Examples:: eina_tiler_01.c, evas-buffer-simple.c, and evas-init-shutdown.c.