Top Level Functions

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files
- Examples

Functions
Top Level Functions
Evas

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

## Functions
int | evas_init (void)
| Initialize Evas. More...
int | evas_shutdown (void)
| Shutdown Evas. More...
Evas_Alloc_Error | evas_alloc_error (void)
| Return if any allocation errors have occurred during the prior function. More...
int | evas_async_events_fd_get (void)
| Get evas' internal asynchronous events read file descriptor. More...
int | evas_async_events_process (void)
| Trigger the processing of all events waiting on the file descriptor returned by evas_async_events_fd_get(). More...
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...

## Detailed Description

Functions that affect Evas as a whole.

## Function Documentation

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.

1 int main(void)
2 {
3 Evas *canvas;
4 Evas_Object *bg, *r1, *r2, *r3;
5
6 evas_init();
7
8 // create your canvas
9 // NOTE: consider using ecore_evas_buffer_new() instead!
10 canvas = create_canvas(WIDTH, HEIGHT);
11 if (!canvas)
12 return -1;
And being the canvas creation something like:
1 static Evas *create_canvas(int width, int height)
2 {
3 Evas *canvas;
4 Evas_Engine_Info_Buffer *einfo;
5 int method;
6 void *pixels;
7
8 method = evas_render_method_lookup("buffer");
9 if (method <= 0)
10 {
11 fputs("ERROR: evas was not compiled with 'buffer' engine!\n", stderr);
12 return NULL;
13 }
14
15 canvas = evas_new();
16 if (!canvas)
17 {
18 fputs("ERROR: could not instantiate new evas canvas.\n", stderr);
19 return NULL;
20 }
21
22 evas_output_method_set(canvas, method);
23 evas_output_size_set(canvas, width, height);
24 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.

References eet_init(), eina_init(), eina_log_domain_register(), eina_log_domain_unregister(), EINA_LOG_ERR, EINA_LOG_STATE_INIT, eina_log_timing(), eina_shutdown(), EINA_TRUE, eo_init(), evil_init(), and evil_shutdown().

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

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.

1 // NOTE: use ecore_evas_buffer_new() and here ecore_evas_free()
2 destroy_canvas(canvas);
3
4 evas_shutdown();
Where that function would contain:
1 evas_free(canvas);

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

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

Referenced by ecore_evas_init(), ecore_evas_shutdown(), edje_init(), and ethumb_shutdown().

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:

1 extern Evas_Object *object;
2 void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
3
4 evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
5 if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
6 {
7 fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
8 fprintf(stderr, " destroy object now as it cannot be used.\n");
9 evas_object_del(object);
10 object = NULL;
11 fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
12 my_memory_cleanup();
13 }
14 if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
15 {
16 fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
17 my_memory_cleanup();
18 }

Examples:
  evas-events.c.

References EINA_UNUSED.

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.

References DBG, eina_spinlock_release(), eina_spinlock_take(), _Eina_Inarray::len, _Eina_Inarray::max, and _Eina_Inarray::members.

Referenced by ecore_evas_engine_type_supported_get(), and ecore_evas_init().

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.

References EINA_FALSE, EINA_TRUE, ERR, and fcntl().

Referenced by ecore_evas_pixmap_depth_get().

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.

References eina_condition_broadcast(), eina_condition_free(), eina_condition_new(), eina_condition_wait(), EINA_FALSE, eina_inarray_grow(), eina_lock_free(), eina_lock_new(), eina_lock_release(), eina_lock_take(), eina_main_loop_define(), eina_main_loop_is(), eina_spinlock_release(), eina_spinlock_take(), EINA_TRUE, EINA_UNUSED, ERR, evas_async_events_put(), and _Eina_Inarray::len.

Referenced by evas_async_events_put().