Top Level Functions
Evas

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

## Functions

EVAS_API int | evas_init (void)
| Directly initialize Evas and its required dependencies.
EVAS_API int | evas_shutdown (void)
| Directly shutdown Evas.
EVAS_API Evas_Alloc_Error | evas_alloc_error (void)
| Get the error status of the most recent memory allocation call.
EVAS_API int | evas_async_events_fd_get (void)
| Access the canvas' asynchronous event queue.
EVAS_API int | evas_async_events_process (void)
| Process the asynchronous event queue.
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.

## 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;
Evas
Eo Evas
An opaque handle to an Evas canvas.
Definition Evas_Common.h:163
evas_init
EVAS_API int evas_init(void)
Directly initialize Evas and its required dependencies.
Definition evas_main.c:152
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition Evas_Common.h:185

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);
evas_output_method_set
EVAS_API void evas_output_method_set(Evas *eo_e, int render_method)
Sets the output engine for the given evas.
Definition evas_main.c:1292
evas_output_size_set
EVAS_API void evas_output_size_set(Evas *eo_e, int w, int h)
Sets the output size of the render engine of the given evas.
Definition evas_main.c:1374
evas_output_viewport_set
EVAS_API void evas_output_viewport_set(Evas *eo_e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h)
Sets the output viewport of the given evas in evas units.
Definition evas_main.c:1413
evas_new
EVAS_API Evas * evas_new(void)
Creates a new empty evas.
Definition evas_main.c:309
evas_render_method_lookup
EVAS_API int evas_render_method_lookup(const char *name)
Look up a numeric ID from a string name of a rendering engine.
Definition evas_main.c:754

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);
evas_engine_info_get
EVAS_API Evas_Engine_Info * evas_engine_info_get(const Evas *obj)
Retrieves the current render engine info struct from the given evas.
Definition evas_main.c:677
evas_free
EVAS_API void evas_free(Evas *eo_e)
Frees the given evas and any objects created on it.
Definition evas_main.c:391
evas_shutdown
EVAS_API int evas_shutdown(void)
Directly shutdown Evas.
Definition evas_main.c:239
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_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_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

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(), ecore_evas_shutdown(), and edje_init().

## 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();
}
EVAS_ALLOC_ERROR_RECOVERED
@ EVAS_ALLOC_ERROR_RECOVERED
Allocation succeeded after freeing up speculative resource memory.
Definition Evas_Common.h:272
EVAS_ALLOC_ERROR_FATAL
@ EVAS_ALLOC_ERROR_FATAL
Allocation failed despite attempts to free up memory.
Definition Evas_Common.h:271
EVAS_CALLBACK_MOUSE_DOWN
@ EVAS_CALLBACK_MOUSE_DOWN
Mouse Button Down Event.
Definition Evas_Common.h:422
evas_alloc_error
EVAS_API Evas_Alloc_Error evas_alloc_error(void)
Get the error status of the most recent memory allocation call.
Definition main.c:17
evas_object_del
EVAS_API void evas_object_del(Evas_Object *obj)
Marks the given Evas object for deletion (when Evas will free its memory).
Definition evas_object_main.c:928
evas_object_event_callback_add
EVAS_API void evas_object_event_callback_add(Evas_Object *eo_obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data)
Add (register) a callback function to a given Evas object event.
Definition evas_callbacks.c:478

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(), and EINA_TRUE.