Low level Evas canvas functions. More...
Modules | |
Render Engine Functions | |
Functions that are used to set the render engine for a given function, and then get that engine working. | |
Coordinate Mapping Functions | |
Functions that are used to map coordinates from the canvas to the screen or the screen to the canvas. | |
Output and Viewport Resizing Functions | |
Functions that set and retrieve the output and viewport size of an evas. | |
Canvas Events | |
Functions relating to canvas events, which are mainly reports on its internal states changing (an object got focused, the rendering is updated, etc). | |
Image Functions | |
Functions that deals with images at canvas level. | |
Font Functions | |
Functions that deals with fonts. | |
Key Input Functions | |
Functions which feed key events to the canvas. | |
Rendering GL on Evas | |
Functions that are used to do OpenGL rendering on Evas. | |
Pointer (Mouse) Functions | |
Functions that deal with the status of the pointer (mouse cursor). | |
Typedefs | |
typedef Eo | Evas |
An opaque handle to an Evas canvas. More... | |
typedef struct _Evas_Public_Data | Evas_Public_Data |
Public data for an Evas. | |
Functions | |
void | evas_render_updates_free (Eina_List *updates) |
Free the rectangles returned by evas_render_updates(). More... | |
#define | evas_canvas_data_attach_set(data) EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_DATA_ATTACH_SET), EO_TYPECHECK(void *, data) |
#define | evas_canvas_data_attach_get(ret) EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_DATA_ATTACH_GET), EO_TYPECHECK(void **, ret) |
#define | evas_canvas_focus_in() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_FOCUS_IN) |
#define | evas_canvas_focus_out() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_FOCUS_OUT) |
#define | evas_canvas_focus_state_get(ret) EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_FOCUS_STATE_GET), EO_TYPECHECK(Eina_Bool *, ret) |
#define | evas_canvas_nochange_push() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NOCHANGE_PUSH) |
#define | evas_canvas_nochange_pop() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NOCHANGE_POP) |
#define | evas_canvas_damage_rectangle_add(x, y, w, h) EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_DAMAGE_RECTANGLE_ADD), EO_TYPECHECK(int, x), EO_TYPECHECK(int, y), EO_TYPECHECK(int, w), EO_TYPECHECK(int, h) |
#define | evas_canvas_obscured_rectangle_add(x, y, w, h) EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_OBSCURED_RECTANGLE_ADD), EO_TYPECHECK(int, x), EO_TYPECHECK(int, y), EO_TYPECHECK(int, w), EO_TYPECHECK(int, h) |
#define | evas_canvas_obscured_clear() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_OBSCURED_CLEAR) |
#define | evas_canvas_render_async(ret) EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_ASYNC), EO_TYPECHECK(Eina_Bool *, ret) |
#define | evas_canvas_render_updates(ret) EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_UPDATES), EO_TYPECHECK(Eina_List **, ret) |
#define | evas_canvas_render() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER) |
#define | evas_canvas_norender() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NORENDER) |
#define | evas_canvas_render_idle_flush() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_IDLE_FLUSH) |
#define | evas_canvas_render_dump() EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_DUMP) |
Evas * | evas_new (void) |
Creates a new empty evas. More... | |
void | evas_free (Evas *e) |
Frees the given evas and any objects created on it. More... | |
void | evas_focus_in (Evas *e) |
Inform to the evas that it got the focus. More... | |
void | evas_focus_out (Evas *e) |
Inform to the evas that it lost the focus. More... | |
Eina_Bool | evas_focus_state_get (const Evas *e) |
Get the focus state known by the given evas. More... | |
void | evas_nochange_push (Evas *e) |
Push the nochange flag up 1. More... | |
void | evas_nochange_pop (Evas *e) |
Pop the nochange flag down 1. More... | |
void | evas_data_attach_set (Evas *e, void *data) |
Attaches a specific pointer to the evas for fetching later. More... | |
void * | evas_data_attach_get (const Evas *e) |
Returns the pointer attached by evas_data_attach_set() More... | |
void | evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) |
Add a damage rectangle. More... | |
void | evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) |
Add an "obscured region" to an Evas canvas. More... | |
void | evas_obscured_clear (Evas *e) |
Remove all "obscured regions" from an Evas canvas. More... | |
Eina_Bool | evas_render_async (Evas *e) |
Render the given Evas canvas asynchronously. More... | |
Eina_List * | evas_render_updates (Evas *e) |
Force immediate renderization of the given Evas canvas. More... | |
void | evas_render (Evas *e) |
Force renderization of the given canvas. More... | |
void | evas_norender (Evas *e) |
Update the canvas internal objects but not triggering immediate renderization. More... | |
void | evas_render_idle_flush (Evas *e) |
Make the canvas discard internally cached data used for rendering. More... | |
void | evas_render_dump (Evas *e) |
Make the canvas discard as much data as possible used by the engine at runtime. More... | |
Low level Evas canvas functions.
Sub groups will present more high level ones, though.
Most of these functions deal with low level Evas actions, like:
Most users will be using Evas by means of the Ecore_Evas
wrapper, which deals with all the above mentioned issues automatically for them. Thus, you'll be looking at this section only if you're building low level stuff.
The groups within present you functions that deal with the canvas directly, too, and not yet with its objects. They are the functions you need to use at a minimum to get a working canvas.
Some of the functions in this group are exemplified here.
#define evas_canvas_data_attach_set | ( | data | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_DATA_ATTACH_SET), EO_TYPECHECK(void *, data) |
Attaches a specific pointer to the evas for fetching later
[in] | data |
Referenced by evas_data_attach_set().
#define evas_canvas_data_attach_get | ( | ret | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_DATA_ATTACH_GET), EO_TYPECHECK(void **, ret) |
Returns the pointer attached by evas_data_attach_set()
[out] | ret |
Referenced by evas_data_attach_get().
#define evas_canvas_focus_in | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_FOCUS_IN) |
Inform to the evas that it got the focus.
Referenced by evas_focus_in().
#define evas_canvas_focus_out | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_FOCUS_OUT) |
Inform to the evas that it lost the focus.
Referenced by evas_focus_out().
#define evas_canvas_focus_state_get | ( | ret | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_FOCUS_STATE_GET), EO_TYPECHECK(Eina_Bool *, ret) |
Get the focus state known by the given evas
[out] | ret |
Referenced by evas_focus_state_get().
#define evas_canvas_nochange_push | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NOCHANGE_PUSH) |
#define evas_canvas_nochange_pop | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NOCHANGE_POP) |
#define evas_canvas_damage_rectangle_add | ( | x, | |
y, | |||
w, | |||
h | |||
) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_DAMAGE_RECTANGLE_ADD), EO_TYPECHECK(int, x), EO_TYPECHECK(int, y), EO_TYPECHECK(int, w), EO_TYPECHECK(int, h) |
Add a damage rectangle.
[in] | x | |
[in] | y | |
[in] | w | |
[in] | h |
Referenced by evas_damage_rectangle_add().
#define evas_canvas_obscured_rectangle_add | ( | x, | |
y, | |||
w, | |||
h | |||
) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_OBSCURED_RECTANGLE_ADD), EO_TYPECHECK(int, x), EO_TYPECHECK(int, y), EO_TYPECHECK(int, w), EO_TYPECHECK(int, h) |
Add an "obscured region" to an Evas canvas.
[in] | x | |
[in] | y | |
[in] | w | |
[in] | h |
Referenced by evas_obscured_rectangle_add().
#define evas_canvas_obscured_clear | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_OBSCURED_CLEAR) |
Remove all "obscured regions" from an Evas canvas.
Referenced by evas_obscured_clear().
#define evas_canvas_render_async | ( | ret | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_ASYNC), EO_TYPECHECK(Eina_Bool *, ret) |
Render canvas asynchronously
[out] | ret | Whether or not a frame will get rendered after the call |
Referenced by evas_render_async().
#define evas_canvas_render_updates | ( | ret | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_UPDATES), EO_TYPECHECK(Eina_List **, ret) |
Force immediate renderization of the given Evas canvas.
[out] | ret |
Referenced by evas_render_updates().
#define evas_canvas_render | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER) |
#define evas_canvas_norender | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NORENDER) |
Update the canvas internal objects but not triggering immediate renderization.
Referenced by evas_norender().
#define evas_canvas_render_idle_flush | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_IDLE_FLUSH) |
Make the canvas discard internally cached data used for rendering.
Referenced by evas_render_idle_flush().
#define evas_canvas_render_dump | ( | ) | EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_DUMP) |
Make the canvas discard as much data as possible used by the engine at
Referenced by evas_render_dump().
An opaque handle to an Evas canvas.
void evas_render_updates_free | ( | Eina_List * | updates | ) |
Free the rectangles returned by evas_render_updates().
updates | The list of updated rectangles of the canvas. |
This function removes the region from the render updates list. It makes the region doesn't be render updated anymore.
References EINA_LIST_FREE, and eina_rectangle_free().
Evas* evas_new | ( | void | ) |
Creates a new empty evas.
Note that before you can use the evas, you will to at a minimum:
This function should only fail if the memory allocation fails
ecore_evas_new()
. See Ecore.NULL
. Referenced by ecore_evas_buffer_allocfunc_new(), ecore_evas_ews_new(), and ecore_evas_object_image_new().
void evas_free | ( | Evas * | e | ) |
Frees the given evas and any objects created on it.
Any objects with 'free' callbacks will have those callbacks called in this function.
e | The given evas. |
void evas_focus_in | ( | Evas * | e | ) |
Inform to the evas that it got the focus.
e | The evas to change information. |
References evas_canvas_focus_in.
void evas_focus_out | ( | Evas * | e | ) |
Inform to the evas that it lost the focus.
e | The evas to change information. |
References evas_canvas_focus_out.
Get the focus state known by the given evas.
e | The evas to query information. |
EINA_TRUE
if it got the focus, EINA_FALSE
otherwise. References evas_canvas_focus_state_get.
void evas_nochange_push | ( | Evas * | e | ) |
Push the nochange flag up 1.
This tells evas, that while the nochange flag is greater than 0, do not mark objects as "changed" when making changes.
e | The evas to change information. |
References evas_canvas_nochange_push.
void evas_nochange_pop | ( | Evas * | e | ) |
Pop the nochange flag down 1.
This tells evas, that while the nochange flag is greater than 0, do not mark objects as "changed" when making changes.
e | The evas to change information. |
References evas_canvas_nochange_pop.
void evas_data_attach_set | ( | Evas * | e, |
void * | data | ||
) |
Attaches a specific pointer to the evas for fetching later.
e | The canvas to attach the pointer to |
data | The pointer to attach |
References evas_canvas_data_attach_set.
Referenced by ecore_evas_buffer_allocfunc_new(), ecore_evas_ews_new(), and ecore_evas_object_image_new().
void* evas_data_attach_get | ( | const Evas * | e | ) |
Returns the pointer attached by evas_data_attach_set()
e | The canvas to attach the pointer to |
References evas_canvas_data_attach_get.
Referenced by ecore_evas_ecore_evas_get().
void evas_damage_rectangle_add | ( | Evas * | e, |
int | x, | ||
int | y, | ||
int | w, | ||
int | h | ||
) |
Add a damage rectangle.
e | The given canvas pointer. |
x | The rectangle's left position. |
y | The rectangle's top position. |
w | The rectangle's width. |
h | The rectangle's height. |
This is the function by which one tells evas that a part of the canvas has to be repainted.
References evas_canvas_damage_rectangle_add.
Referenced by ecore_evas_rotation_set(), and ecore_evas_rotation_with_resize_set().
void evas_obscured_rectangle_add | ( | Evas * | e, |
int | x, | ||
int | y, | ||
int | w, | ||
int | h | ||
) |
Add an "obscured region" to an Evas canvas.
e | The given canvas pointer. |
x | The rectangle's top left corner's horizontal coordinate. |
y | The rectangle's top left corner's vertical coordinate |
w | The rectangle's width. |
h | The rectangle's height. |
This is the function by which one tells an Evas canvas that a part of it must not be repainted. The region must be rectangular and its coordinates inside the canvas viewport are passed in the call. After this call, the region specified won't participate in any form in Evas' calculations and actions during its rendering updates, having its displaying content frozen as it was just after this function took place.
We call it "obscured region" because the most common use case for this rendering (partial) freeze is something else (most probably other canvas) being on top of the specified rectangular region, thus shading it completely from the user's final scene in a display. To avoid unnecessary processing, one should indicate to the obscured canvas not to bother about the non-important area.
The majority of users won't have to worry about this function, as they'll be using just one canvas in their applications, with nothing inset or on top of it in any form.
To make this region one that has to be repainted again, call the function evas_obscured_clear().
Example code follows.
In that example, pressing the "Ctrl" and "o" keys will impose or remove an obscured region in the middle of the canvas. You'll get the same contents at the time the key was pressed, if toggling it on, until you toggle it off again (make sure the animation is running on to get the idea better). See the full example.
References evas_canvas_obscured_rectangle_add.
void evas_obscured_clear | ( | Evas * | e | ) |
Remove all "obscured regions" from an Evas canvas.
e | The given canvas pointer. |
This function removes all the rectangles from the obscured regions list of the canvas e
. It takes obscured areas added with evas_obscured_rectangle_add() and make them again a regions that have to be repainted on rendering updates.
References evas_canvas_obscured_clear.
Render the given Evas canvas asynchronously.
e | The canvas to render. |
func | Optional function to call with the list of updated areas. |
data | User data to pass to func . |
This function only returns EINA_TRUE when a frame will be rendered. If the previous frame is still rendering, EINA_FALSE will be returned so the users know not to wait for the updates callback and just return to their main loop.
If a func
callback is given, a list of updated areas will be generated and the function will be called from the main thread after the rendered frame is flushed to the screen. The resulting list should be freed with evas_render_updates_free(). The list is given in the event_info
parameter of the callback function.
References EINA_FALSE, and evas_canvas_render_async.
Force immediate renderization of the given Evas canvas.
e | The given canvas pointer. |
Eina_Rectangle
structs). Free this list with evas_render_updates_free().This function forces an immediate renderization update of the given canvas e
.
Example code follows.
See the full example.
References evas_canvas_render_updates.
void evas_render | ( | Evas * | e | ) |
Force renderization of the given canvas.
e | The given canvas pointer. |
References evas_canvas_render.
void evas_norender | ( | Evas * | e | ) |
Update the canvas internal objects but not triggering immediate renderization.
e | The given canvas pointer. |
This function updates the canvas internal objects not triggering renderization. To force renderization function evas_render() should be used.
References evas_canvas_norender.
void evas_render_idle_flush | ( | Evas * | e | ) |
Make the canvas discard internally cached data used for rendering.
e | The given canvas pointer. |
This function flushes the arrays of delete, active and render objects. Other things it may also discard are: shared memory segments, temporary scratch buffers, cached data to avoid re-compute of that data etc.
References evas_canvas_render_idle_flush.
void evas_render_dump | ( | Evas * | e | ) |
Make the canvas discard as much data as possible used by the engine at runtime.
e | The given canvas pointer. |
This function will unload images, delete textures and much more, where possible. You may also want to call evas_render_idle_flush() immediately prior to this to perhaps discard a little more, though evas_render_dump() should implicitly delete most of what evas_render_idle_flush() might discard too.
References evas_canvas_render_dump.