Canvas Functions

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)
 
Evasevas_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_Listevas_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...
 

Detailed Description

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:

  • create/destroy raw canvases, not bound to any displaying engine
  • tell a canvas i got focused (in a windowing context, for example)
  • tell a canvas a region should not be calculated anymore in rendering
  • tell a canvas to render its contents, immediately

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.

Macro Definition Documentation

#define evas_canvas_data_attach_set (   data)    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_DATA_ATTACH_SET), EO_TYPECHECK(void *, data)
Since
1.8

Attaches a specific pointer to the evas for fetching later

Parameters
[in]data
See also
evas_data_attach_set

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)
Since
1.8

Returns the pointer attached by evas_data_attach_set()

Parameters
[out]ret
See also
evas_data_attach_get

Referenced by evas_data_attach_get().

#define evas_canvas_focus_in ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_FOCUS_IN)
Since
1.8

Inform to the evas that it got the focus.

See also
evas_focus_in

Referenced by evas_focus_in().

#define evas_canvas_focus_out ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_FOCUS_OUT)
Since
1.8

Inform to the evas that it lost the focus.

See also
evas_focus_out

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)
Since
1.8

Get the focus state known by the given evas

Parameters
[out]ret
See also
evas_focus_state_get

Referenced by evas_focus_state_get().

#define evas_canvas_nochange_push ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NOCHANGE_PUSH)
Since
1.8

Push the nochange flag up 1

See also
evas_nochange_push

Referenced by evas_nochange_push().

#define evas_canvas_nochange_pop ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NOCHANGE_POP)
Since
1.8

Pop the nochange flag down 1

See also
evas_nochange_pop

Referenced by evas_nochange_pop().

#define evas_canvas_damage_rectangle_add (   x,
  y,
  w,
 
)    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)
Since
1.8

Add a damage rectangle.

Parameters
[in]x
[in]y
[in]w
[in]h
See also
evas_damage_rectangle_add

Referenced by evas_damage_rectangle_add().

#define evas_canvas_obscured_rectangle_add (   x,
  y,
  w,
 
)    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)
Since
1.8

Add an "obscured region" to an Evas canvas.

Parameters
[in]x
[in]y
[in]w
[in]h
See also
evas_obscured_rectangle_add

Referenced by evas_obscured_rectangle_add().

#define evas_canvas_obscured_clear ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_OBSCURED_CLEAR)
Since
1.8

Remove all "obscured regions" from an Evas canvas.

See also
evas_obscured_clear

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)
Since
1.8

Render canvas asynchronously

Parameters
[out]retWhether or not a frame will get rendered after the call
See also
evas_render_async

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)
Since
1.8

Force immediate renderization of the given Evas canvas.

Parameters
[out]ret
See also
evas_render_updates

Referenced by evas_render_updates().

#define evas_canvas_render ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER)
Since
1.8

Force renderization of the given canvas.

See also
evas_render

Referenced by evas_render().

#define evas_canvas_norender ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_NORENDER)
Since
1.8

Update the canvas internal objects but not triggering immediate renderization.

See also
evas_norender

Referenced by evas_norender().

#define evas_canvas_render_idle_flush ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_IDLE_FLUSH)
Since
1.8

Make the canvas discard internally cached data used for rendering.

See also
evas_render_idle_flush

Referenced by evas_render_idle_flush().

#define evas_canvas_render_dump ( )    EVAS_CANVAS_ID(EVAS_CANVAS_SUB_ID_RENDER_DUMP)
Since
1.8

Make the canvas discard as much data as possible used by the engine at

See also
evas_render_dump

Referenced by evas_render_dump().

Typedef Documentation

An opaque handle to an Evas canvas.

See also
evas_new()
evas_free()

Function Documentation

void evas_render_updates_free ( Eina_List updates)

Free the rectangles returned by evas_render_updates().

Parameters
updatesThe 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.

See also
evas_render_updates() for an example

References EAPI, EINA_LIST_FREE, and eina_rectangle_free().

Referenced by evas_obscured_clear().

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

Note
this function is very low level. Instead of using it directly, consider using the high level functions in Ecore_Evas wrapper/helper set of functions such as ecore_evas_new(). See Ecore.
Attention
it is recommended that one calls evas_init() before creating new canvas.
Returns
A new uninitialised Evas canvas on success. Otherwise, NULL.

References EAPI, eina_clist_init(), eina_hash_string_superfast_new(), EINA_UNUSED, and EVAS_FONT_HINTING_BYTECODE.

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.

Parameters
eThe given evas.

References EAPI, eina_array_flush(), EINA_FALSE, eina_hash_free(), EINA_INLIST_FOREACH, eina_list_free(), EINA_LIST_FREE, eina_rectangle_free(), EINA_TRUE, EINA_UNUSED, evas_font_path_clear(), and evas_render_idle_flush().

Referenced by ecore_evas_pixmap_depth_get(), and evas_nochange_pop().

void evas_focus_in ( Evas e)

Inform to the evas that it got the focus.

Parameters
eThe evas to change information.

References EAPI, EINA_UNUSED, EVAS_CALLBACK_CANVAS_FOCUS_IN, and evas_canvas_focus_in.

void evas_focus_out ( Evas e)

Inform to the evas that it lost the focus.

Parameters
eThe evas to change information.

References EAPI, EINA_UNUSED, EVAS_CALLBACK_CANVAS_FOCUS_OUT, and evas_canvas_focus_out.

Eina_Bool evas_focus_state_get ( const Evas e)

Get the focus state known by the given evas.

Parameters
eThe evas to query information.
Returns
EINA_TRUE if it got the focus, EINA_FALSE otherwise.

References EAPI, EINA_UNUSED, and 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.

Parameters
eThe evas to change information.

References EAPI, EINA_UNUSED, and 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.

Parameters
eThe evas to change information.

References EAPI, EINA_UNUSED, evas_canvas_nochange_pop, and evas_free().

void evas_data_attach_set ( Evas e,
void *  data 
)

Attaches a specific pointer to the evas for fetching later.

Parameters
eThe canvas to attach the pointer to
dataThe pointer to attach

References EAPI, EINA_UNUSED, and 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()

Parameters
eThe canvas to attach the pointer to
Returns
The pointer attached

References EAPI, EINA_UNUSED, and 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.

Parameters
eThe given canvas pointer.
xThe rectangle's left position.
yThe rectangle's top position.
wThe rectangle's width.
hThe rectangle's height.

This is the function by which one tells evas that a part of the canvas has to be repainted.

Note
All newly created Evas rectangles get the default color values of 255 255 255 255 (opaque white).

References EAPI, eina_list_append(), EINA_TRUE, EINA_UNUSED, and evas_canvas_damage_rectangle_add.

Referenced by ecore_evas_rotation_set(), ecore_evas_rotation_with_resize_set(), evas_object_clip_set(), and evas_object_clip_unset().

void evas_obscured_rectangle_add ( Evas e,
int  x,
int  y,
int  w,
int  h 
)

Add an "obscured region" to an Evas canvas.

Parameters
eThe given canvas pointer.
xThe rectangle's top left corner's horizontal coordinate.
yThe rectangle's top left corner's vertical coordinate
wThe rectangle's width.
hThe 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().

Note
This is a very low level function, which most of Evas' users wouldn't care about.
This function does not flag the canvas as having its state changed. If you want to re-render it afterwards expecting new contents, you have to add "damage" regions yourself (see evas_damage_rectangle_add()).
See also
evas_obscured_clear()
evas_render_updates()

Example code follows.

1  "\tControl + o - add an obscured rectangle\n"
2  "\th - print help\n";
3 
4 struct test_data
5 {
6  Ecore_Evas *ee;
7  Evas *canvas;
8  Evas_Object *img, *bg;
9  Ecore_Timer *resize_timer, *freeze_timer;
10  Eina_Bool obscured, focus;
11 };
12 
13 static struct test_data d = {0};
14 
15 /* here to keep our example's window size and background image's
16  * size in synchrony */
17 static void
18 _canvas_resize_cb(Ecore_Evas *ee)
19 {
20  int w, h;
21 
22  ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
23  evas_object_resize(d.bg, w, h);
24 }
25 
26 /* called when our rectangle gets focus */
27 static void
28 _object_focus_in_cb(void *data EINA_UNUSED,
29  Evas *e,
30  void *event_info)
31 {
32  fprintf(stdout, "An object got focused: %s\n",
33  evas_object_name_get(event_info));
34 
35  fprintf(stdout, "Let's recheck it: %s\n",
36  evas_object_name_get(evas_focus_get(e)));
37 
38  fprintf(stdout, "And again: %s\n", evas_object_focus_get(event_info) ?
39  "OK!" : "Oops, something is bad.");
40 }
41 
42 /* render flush callback */
43 static void
44 _render_flush_cb(void *data EINA_UNUSED,
45  Evas *e EINA_UNUSED,
46  void *event_info EINA_UNUSED)
47 {
48  fprintf(stdout, "Canvas is about to flush its rendering pipeline!\n");
49 }
50 
51 /* put some action in the canvas */
52 static Eina_Bool
53 _resize_cb(void *data EINA_UNUSED)
54 {
55  int w, h, cw, ch;
56 
57  evas_object_geometry_get(d.img, NULL, NULL, &w, &h);
58  ecore_evas_geometry_get(d.ee, NULL, NULL, &cw, &ch);
59 
60  if (w < cw)
61  evas_object_resize(d.img, cw, ch);
62  else
63  evas_object_resize(d.img, cw / 2, ch / 2);
64 
65  return EINA_TRUE; /* re-issue the timer */
66 }
67 
68 /* let's have our events back */
69 static Eina_Bool
70 _thaw_cb(void *data EINA_UNUSED)
71 {
72  fprintf(stdout, "Canvas was frozen %d times, now thawing.\n",
73  evas_event_freeze_get(d.canvas));
74  evas_event_thaw(d.canvas);
75  return EINA_FALSE; /* do not re-issue the timer */
76 }
77 
78 /* mouse enters the object's area */
79 static void
80 _on_mouse_in(void *data EINA_UNUSED,
81  Evas *evas EINA_UNUSED,
82  Evas_Object *o EINA_UNUSED,
83  void *einfo EINA_UNUSED)
84 {
85  fprintf(stdout, "Enlightenment logo has had the mouse in.\n");
86 }
87 
88 static void
89 _on_mouse_out(void *data EINA_UNUSED,
90  Evas *evas EINA_UNUSED,
91  Evas_Object *o EINA_UNUSED,
92  void *einfo EINA_UNUSED)
93 {
94  fprintf(stdout, "Enlightenment logo has had the mouse out.\n");
95 } /* mouse exits the object's area */
96 
97 /* examine the keys pressed */
98 static void
99 _on_keydown(void *data EINA_UNUSED,
100  Evas *evas,
101  Evas_Object *o EINA_UNUSED,
102  void *einfo)
103 {
104  const Evas_Modifier *mods;
105  Evas_Event_Key_Down *ev = einfo;
106 
107  fprintf(stdout, "We've got key input: %s\n", ev->key);
108  fprintf(stdout, "It actually came from %s\n", d.focus ?
109  "focus" : "key grab");
110 
111  if (strcmp(ev->key, "h") == 0) /* print help */
112  {
113  fprintf(stdout, commands);
114  return;
115  }
116 
117  if (strcmp(ev->key, "a") == 0) /* toggle animation timer */
118  {
119  if (d.resize_timer != NULL)
120  {
121  fprintf(stdout, "Stopping animation timer\n");
122  ecore_timer_del(d.resize_timer);
123  d.resize_timer = NULL;
124  }
125  else
126  {
127  fprintf(stdout, "Re-issuing animation timer\n");
128  d.resize_timer = ecore_timer_add(2, _resize_cb, NULL);
129  }
130  return;
131  }
132 
133  if (strcmp(ev->key, "c") == 0) /* cycle between focus and key
134  * grabs for key input */
135  {
136  Eina_Bool ret;
137  Evas_Modifier_Mask mask =
138  evas_key_modifier_mask_get(d.canvas, "Control");
139 
140  fprintf(stdout, "Switching to %s for key input\n", d.focus ?
141  "key grabs" : "focus");
142 
143  if (d.focus)
144  {
145  evas_object_focus_set(d.bg, EINA_FALSE);
146  fprintf(stdout, "Focused object is now %s\n",
147  evas_focus_get(d.canvas) ?
148  "still valid! Something went wrong." : "none.");
149 
150  ret = evas_object_key_grab(d.bg, "a", 0, 0, EINA_TRUE);
151  if (!ret)
152  {
153  fprintf(stdout, "Something went wrong with key grabs.\n");
154  goto c_end;
155  }
156  ret = evas_object_key_grab(d.bg, "c", 0, 0, EINA_TRUE);
157  if (!ret)
158  {
159  fprintf(stdout, "Something went wrong with key grabs.\n");
160  goto c_end;
161  }
162  ret = evas_object_key_grab(d.bg, "d", 0, 0, EINA_TRUE);
163  if (!ret)
164  {
165  fprintf(stdout, "Something went wrong with key grabs.\n");
166  goto c_end;
167  }
168  ret = evas_object_key_grab(d.bg, "f", 0, 0, EINA_TRUE);
169  if (!ret)
170  {
171  fprintf(stdout, "Something went wrong with key grabs.\n");
172  goto c_end;
173  }
174  ret = evas_object_key_grab(d.bg, "p", 0, 0, EINA_TRUE);
175  if (!ret)
176  {
177  fprintf(stdout, "Something went wrong with key grabs.\n");
178  goto c_end;
179  }
180  ret = evas_object_key_grab(d.bg, "o", mask, 0, EINA_TRUE);
181  if (!ret)
182  {
183  fprintf(stdout, "Something went wrong with key grabs.\n");
184  goto c_end;
185  }
186  ret = evas_object_key_grab(d.bg, "h", 0, 0, EINA_TRUE);
187  if (!ret)
188  {
189  fprintf(stdout, "Something went wrong with key grabs.\n");
190  goto c_end;
191  }
192  }
193  else /* got here by key grabs */
194  {
195  evas_object_key_ungrab(d.bg, "a", 0, 0);
196  evas_object_key_ungrab(d.bg, "c", 0, 0);
197  evas_object_key_ungrab(d.bg, "d", 0, 0);
198  evas_object_key_ungrab(d.bg, "f", 0, 0);
199  evas_object_key_ungrab(d.bg, "p", 0, 0);
200  evas_object_key_ungrab(d.bg, "o", mask, 0);
201  evas_object_key_ungrab(d.bg, "h", 0, 0);
202 
203  evas_object_focus_set(d.bg, EINA_TRUE);
204  }
205 
206 c_end:
207  d.focus = !d.focus;
208 
209  return;
210  }
211 
212  if (strcmp(ev->key, "d") == 0) /* delete canvas' callbacks */
213  {
214  fprintf(stdout, "Deleting canvas event callbacks\n");
215  evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
216  _render_flush_cb, NULL);
217  evas_event_callback_del_full(
218  evas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
219  _object_focus_in_cb, NULL);
220  return;
221  }
222 
223  if (strcmp(ev->key, "f") == 0) /* freeze input for 3 seconds */
224  {
225  fprintf(stdout, "Freezing input for 3 seconds\n");
226  evas_event_freeze(evas);
227  d.freeze_timer = ecore_timer_add(3, _thaw_cb, NULL);
228  return;
229  }
230 
231  if (strcmp(ev->key, "p") == 0) /* toggle precise point
232  * collision detection */
233  {
234  Eina_Bool precise = evas_object_precise_is_inside_get(d.img);
235 
236  fprintf(stdout, "Toggling precise point collision detection %s on"
237  " Enlightenment logo\n", precise ? "off" : "on");
238  evas_object_precise_is_inside_set(d.img, !precise);
239 
240  return;
241  }
242 
243  mods = evas_key_modifier_get(evas);
244  if (evas_key_modifier_is_set(mods, "Control") &&
245  (strcmp(ev->key, "o") == 0)) /* add an obscured
246  * rectangle to the middle
247  * of the canvas */
248  {
249  fprintf(stdout, "Toggling obscured rectangle on canvas\n");
250  if (!d.obscured)
251  {
252  int w, h;
253  evas_output_viewport_get(evas, NULL, NULL, &w, &h);
254  evas_obscured_rectangle_add(evas, w / 4, h / 4, w / 2, h / 2);
255  }
256  else
257  {
258  int w, h;
259  Eina_Rectangle *rect;
260  Eina_List *updates, *l;
261 
262  evas_output_viewport_get(evas, NULL, NULL, &w, &h);
263  evas_obscured_clear(evas);

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 EAPI, eina_list_append(), and evas_canvas_obscured_rectangle_add.

void evas_obscured_clear ( Evas e)

Remove all "obscured regions" from an Evas canvas.

Parameters
eThe 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.

Note
This is a very low level function, which most of Evas' users wouldn't care about.
This function does not flag the canvas as having its state changed. If you want to re-render it afterwards expecting new contents, you have to add "damage" regions yourself (see evas_damage_rectangle_add()).
See also
evas_obscured_rectangle_add() for an example
evas_render_updates()

References EAPI, eina_array_clean(), eina_array_flush(), eina_array_foreach(), eina_array_remove(), EINA_COW_WRITE_BEGIN, EINA_COW_WRITE_END, EINA_FALSE, EINA_INLIST_FOREACH, eina_list_append(), eina_list_count(), eina_list_data_get(), EINA_LIST_FOREACH, EINA_LIST_FOREACH_SAFE, EINA_LIST_FREE, eina_list_last(), eina_list_remove(), eina_list_remove_list(), eina_rectangle_free(), eina_rectangle_new(), EINA_RECTANGLE_SET, EINA_TRUE, evas_async_events_put(), EVAS_CALLBACK_RENDER_FLUSH_POST, EVAS_CALLBACK_RENDER_FLUSH_PRE, EVAS_CALLBACK_RENDER_POST, EVAS_CALLBACK_RENDER_PRE, evas_canvas_obscured_clear, evas_event_freeze(), evas_event_thaw(), EVAS_LAYER_MIN, evas_object_clip_get(), evas_object_clip_set(), evas_object_clip_unset(), evas_object_clipees_get(), evas_object_color_set(), evas_object_del(), evas_object_hide(), evas_object_image_size_get(), evas_object_layer_set(), evas_object_move(), evas_object_pass_events_set(), evas_object_rectangle_add(), evas_object_resize(), evas_object_show(), evas_object_type_get(), EVAS_RENDER_BLEND, EVAS_RENDER_COPY, evas_render_updates_free(), _Eina_Rectangle::h, _Eina_Inlist::prev, _Evas_Event_Render_Post::updated_area, _Eina_Rectangle::w, _Eina_Rectangle::x, and _Eina_Rectangle::y.

Eina_Bool evas_render_async ( Evas e)

Render the given Evas canvas asynchronously.

Parameters
eThe canvas to render.
funcOptional function to call with the list of updated areas.
dataUser data to pass to func.
Returns
EINA_TRUE if the canvas will render, EINA_FALSE otherwise.

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.

Since
1.8

References EAPI, EINA_FALSE, EINA_TRUE, and evas_canvas_render_async.

Eina_List* evas_render_updates ( Evas e)

Force immediate renderization of the given Evas canvas.

Parameters
eThe given canvas pointer.
Returns
A newly allocated list of updated rectangles of the canvas (Eina_Rectangle structs). Free this list with evas_render_updates_free().

This function forces an immediate renderization update of the given canvas e.

Note
This is a very low level function, which most of Evas' users wouldn't care about. One would use it, for example, to grab an Evas' canvas update regions and paint them back, using the canvas' pixmap, on a displaying system working below Evas.
Evas is a stateful canvas. If no operations changing its state took place since the last rendering action, you won't see no changes and this call will be a no-op.

Example code follows.

1  "\tControl + o - add an obscured rectangle\n"
2  "\th - print help\n";
3 
4 struct test_data
5 {
6  Ecore_Evas *ee;
7  Evas *canvas;
8  Evas_Object *img, *bg;
9  Ecore_Timer *resize_timer, *freeze_timer;
10  Eina_Bool obscured, focus;
11 };
12 
13 static struct test_data d = {0};
14 
15 /* here to keep our example's window size and background image's
16  * size in synchrony */
17 static void
18 _canvas_resize_cb(Ecore_Evas *ee)
19 {
20  int w, h;
21 
22  ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
23  evas_object_resize(d.bg, w, h);
24 }
25 
26 /* called when our rectangle gets focus */
27 static void
28 _object_focus_in_cb(void *data EINA_UNUSED,
29  Evas *e,
30  void *event_info)
31 {
32  fprintf(stdout, "An object got focused: %s\n",
33  evas_object_name_get(event_info));
34 
35  fprintf(stdout, "Let's recheck it: %s\n",
36  evas_object_name_get(evas_focus_get(e)));
37 
38  fprintf(stdout, "And again: %s\n", evas_object_focus_get(event_info) ?
39  "OK!" : "Oops, something is bad.");
40 }
41 
42 /* render flush callback */
43 static void
44 _render_flush_cb(void *data EINA_UNUSED,
45  Evas *e EINA_UNUSED,
46  void *event_info EINA_UNUSED)
47 {
48  fprintf(stdout, "Canvas is about to flush its rendering pipeline!\n");
49 }
50 
51 /* put some action in the canvas */
52 static Eina_Bool
53 _resize_cb(void *data EINA_UNUSED)
54 {
55  int w, h, cw, ch;
56 
57  evas_object_geometry_get(d.img, NULL, NULL, &w, &h);
58  ecore_evas_geometry_get(d.ee, NULL, NULL, &cw, &ch);
59 
60  if (w < cw)
61  evas_object_resize(d.img, cw, ch);
62  else
63  evas_object_resize(d.img, cw / 2, ch / 2);
64 
65  return EINA_TRUE; /* re-issue the timer */
66 }
67 
68 /* let's have our events back */
69 static Eina_Bool
70 _thaw_cb(void *data EINA_UNUSED)
71 {
72  fprintf(stdout, "Canvas was frozen %d times, now thawing.\n",
73  evas_event_freeze_get(d.canvas));
74  evas_event_thaw(d.canvas);
75  return EINA_FALSE; /* do not re-issue the timer */
76 }
77 
78 /* mouse enters the object's area */
79 static void
80 _on_mouse_in(void *data EINA_UNUSED,
81  Evas *evas EINA_UNUSED,
82  Evas_Object *o EINA_UNUSED,
83  void *einfo EINA_UNUSED)
84 {
85  fprintf(stdout, "Enlightenment logo has had the mouse in.\n");
86 }
87 
88 static void
89 _on_mouse_out(void *data EINA_UNUSED,
90  Evas *evas EINA_UNUSED,
91  Evas_Object *o EINA_UNUSED,
92  void *einfo EINA_UNUSED)
93 {
94  fprintf(stdout, "Enlightenment logo has had the mouse out.\n");
95 } /* mouse exits the object's area */
96 
97 /* examine the keys pressed */
98 static void
99 _on_keydown(void *data EINA_UNUSED,
100  Evas *evas,
101  Evas_Object *o EINA_UNUSED,
102  void *einfo)
103 {
104  const Evas_Modifier *mods;
105  Evas_Event_Key_Down *ev = einfo;
106 
107  fprintf(stdout, "We've got key input: %s\n", ev->key);
108  fprintf(stdout, "It actually came from %s\n", d.focus ?
109  "focus" : "key grab");
110 
111  if (strcmp(ev->key, "h") == 0) /* print help */
112  {
113  fprintf(stdout, commands);
114  return;
115  }
116 
117  if (strcmp(ev->key, "a") == 0) /* toggle animation timer */
118  {
119  if (d.resize_timer != NULL)
120  {
121  fprintf(stdout, "Stopping animation timer\n");
122  ecore_timer_del(d.resize_timer);
123  d.resize_timer = NULL;
124  }
125  else
126  {
127  fprintf(stdout, "Re-issuing animation timer\n");
128  d.resize_timer = ecore_timer_add(2, _resize_cb, NULL);
129  }
130  return;
131  }
132 
133  if (strcmp(ev->key, "c") == 0) /* cycle between focus and key
134  * grabs for key input */
135  {
136  Eina_Bool ret;
137  Evas_Modifier_Mask mask =
138  evas_key_modifier_mask_get(d.canvas, "Control");
139 
140  fprintf(stdout, "Switching to %s for key input\n", d.focus ?
141  "key grabs" : "focus");
142 
143  if (d.focus)
144  {
145  evas_object_focus_set(d.bg, EINA_FALSE);
146  fprintf(stdout, "Focused object is now %s\n",
147  evas_focus_get(d.canvas) ?
148  "still valid! Something went wrong." : "none.");
149 
150  ret = evas_object_key_grab(d.bg, "a", 0, 0, EINA_TRUE);
151  if (!ret)
152  {
153  fprintf(stdout, "Something went wrong with key grabs.\n");
154  goto c_end;
155  }
156  ret = evas_object_key_grab(d.bg, "c", 0, 0, EINA_TRUE);
157  if (!ret)
158  {
159  fprintf(stdout, "Something went wrong with key grabs.\n");
160  goto c_end;
161  }
162  ret = evas_object_key_grab(d.bg, "d", 0, 0, EINA_TRUE);
163  if (!ret)
164  {
165  fprintf(stdout, "Something went wrong with key grabs.\n");
166  goto c_end;
167  }
168  ret = evas_object_key_grab(d.bg, "f", 0, 0, EINA_TRUE);
169  if (!ret)
170  {
171  fprintf(stdout, "Something went wrong with key grabs.\n");
172  goto c_end;
173  }
174  ret = evas_object_key_grab(d.bg, "p", 0, 0, EINA_TRUE);
175  if (!ret)
176  {
177  fprintf(stdout, "Something went wrong with key grabs.\n");
178  goto c_end;
179  }
180  ret = evas_object_key_grab(d.bg, "o", mask, 0, EINA_TRUE);
181  if (!ret)
182  {
183  fprintf(stdout, "Something went wrong with key grabs.\n");
184  goto c_end;
185  }
186  ret = evas_object_key_grab(d.bg, "h", 0, 0, EINA_TRUE);
187  if (!ret)
188  {
189  fprintf(stdout, "Something went wrong with key grabs.\n");
190  goto c_end;
191  }
192  }
193  else /* got here by key grabs */
194  {
195  evas_object_key_ungrab(d.bg, "a", 0, 0);
196  evas_object_key_ungrab(d.bg, "c", 0, 0);
197  evas_object_key_ungrab(d.bg, "d", 0, 0);
198  evas_object_key_ungrab(d.bg, "f", 0, 0);
199  evas_object_key_ungrab(d.bg, "p", 0, 0);
200  evas_object_key_ungrab(d.bg, "o", mask, 0);
201  evas_object_key_ungrab(d.bg, "h", 0, 0);
202 
203  evas_object_focus_set(d.bg, EINA_TRUE);
204  }
205 
206 c_end:
207  d.focus = !d.focus;
208 
209  return;
210  }
211 
212  if (strcmp(ev->key, "d") == 0) /* delete canvas' callbacks */
213  {
214  fprintf(stdout, "Deleting canvas event callbacks\n");
215  evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
216  _render_flush_cb, NULL);
217  evas_event_callback_del_full(
218  evas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
219  _object_focus_in_cb, NULL);
220  return;
221  }
222 
223  if (strcmp(ev->key, "f") == 0) /* freeze input for 3 seconds */
224  {
225  fprintf(stdout, "Freezing input for 3 seconds\n");
226  evas_event_freeze(evas);
227  d.freeze_timer = ecore_timer_add(3, _thaw_cb, NULL);
228  return;
229  }
230 
231  if (strcmp(ev->key, "p") == 0) /* toggle precise point
232  * collision detection */
233  {
234  Eina_Bool precise = evas_object_precise_is_inside_get(d.img);
235 
236  fprintf(stdout, "Toggling precise point collision detection %s on"
237  " Enlightenment logo\n", precise ? "off" : "on");
238  evas_object_precise_is_inside_set(d.img, !precise);
239 
240  return;
241  }
242 
243  mods = evas_key_modifier_get(evas);
244  if (evas_key_modifier_is_set(mods, "Control") &&
245  (strcmp(ev->key, "o") == 0)) /* add an obscured
246  * rectangle to the middle
247  * of the canvas */
248  {
249  fprintf(stdout, "Toggling obscured rectangle on canvas\n");
250  if (!d.obscured)
251  {
252  int w, h;
253  evas_output_viewport_get(evas, NULL, NULL, &w, &h);
254  evas_obscured_rectangle_add(evas, w / 4, h / 4, w / 2, h / 2);
255  }
256  else
257  {
258  int w, h;
259  Eina_Rectangle *rect;
260  Eina_List *updates, *l;
261 
262  evas_output_viewport_get(evas, NULL, NULL, &w, &h);
263  evas_obscured_clear(evas);
264 
265  /* we have to flag a damage region here because
266  * evas_obscured_clear() doesn't change the canvas'
267  * state. we'd have to wait for an animation step, for
268  * example, to get the result, without it */
269  evas_damage_rectangle_add(evas, 0, 0, w, h);
270 
271  updates = evas_render_updates(evas);
272 
273  EINA_LIST_FOREACH(updates, l, rect)
274  {
275  fprintf(stdout, "Rectangle (%d, %d, %d, %d) on canvas got a"
276  " rendering update.\n", rect->x, rect->y,
277  rect->w,
278  rect->h);
279  }
280  evas_render_updates_free(updates);
281  }
282  d.obscured = !d.obscured;

See the full example.

References EAPI, EINA_FALSE, and evas_canvas_render_updates.

void evas_render ( Evas e)

Force renderization of the given canvas.

Parameters
eThe given canvas pointer.

References EAPI, and evas_canvas_render.

void evas_norender ( Evas e)

Update the canvas internal objects but not triggering immediate renderization.

Parameters
eThe given canvas pointer.

This function updates the canvas internal objects not triggering renderization. To force renderization function evas_render() should be used.

See also
evas_render.

References EAPI, and evas_canvas_norender.

void evas_render_idle_flush ( Evas e)

Make the canvas discard internally cached data used for rendering.

Parameters
eThe 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 EAPI, eina_array_clean(), eina_array_foreach(), EINA_COW_WRITE_BEGIN, EINA_COW_WRITE_END, EINA_INLIST_FOREACH, EINA_TRUE, evas_canvas_render_idle_flush, and evas_canvas_sync.

Referenced by ecore_evas_pixmap_depth_get(), and evas_free().

void evas_render_dump ( Evas e)

Make the canvas discard as much data as possible used by the engine at runtime.

Parameters
eThe 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 eina_array_clean(), eina_array_foreach(), EINA_COW_WRITE_BEGIN, EINA_COW_WRITE_END, EINA_INLIST_FOREACH, EINA_TRUE, and evas_canvas_render_dump.