summaryrefslogtreecommitdiff
path: root/src/lib/evas/Evas_Legacy.h
diff options
context:
space:
mode:
authorDaniel Zaoui <daniel.zaoui@samsung.com>2013-04-24 22:56:24 +0300
committerDaniel Zaoui <daniel.zaoui@samsung.com>2013-04-25 03:40:45 +0300
commit80e04b2842872b10b4ed02aae330bdd3510f009f (patch)
treecafb6476113b6e1596372f6680aea229a88ca9a0 /src/lib/evas/Evas_Legacy.h
parent777d51181444966af468892bbd2cf27a3b35fb2f (diff)
Evas: Split Evas headers
Now, Evas.h includes three new files: - Evas_Eo.h: Eo API functions (functions defines, enums, base id). - Evas_Legacy.h: contains the API functions related to objects - Evas_Common.h: common data (structs, enums...) + functions not related to objects. This phase is needed for the EFL 1.8 release to disable Eo APIs if we consider it is not enough mature to be used by applications.
Diffstat (limited to '')
-rw-r--r--src/lib/evas/Evas_Legacy.h8309
1 files changed, 8309 insertions, 0 deletions
diff --git a/src/lib/evas/Evas_Legacy.h b/src/lib/evas/Evas_Legacy.h
new file mode 100644
index 0000000000..5efa2b7d03
--- /dev/null
+++ b/src/lib/evas/Evas_Legacy.h
@@ -0,0 +1,8309 @@
1
2/**
3 * @ingroup Evas_Canvas
4 *
5 * @{
6 */
7/**
8 * Creates a new empty evas.
9 *
10 * Note that before you can use the evas, you will to at a minimum:
11 * @li Set its render method with @ref evas_output_method_set .
12 * @li Set its viewport size with @ref evas_output_viewport_set .
13 * @li Set its size of the canvas with @ref evas_output_size_set .
14 * @li Ensure that the render engine is given the correct settings
15 * with @ref evas_engine_info_set .
16 *
17 * This function should only fail if the memory allocation fails
18 *
19 * @note this function is very low level. Instead of using it
20 * directly, consider using the high level functions in
21 * @ref Ecore_Evas_Group such as @c ecore_evas_new(). See
22 * @ref Ecore.
23 *
24 * @attention it is recommended that one calls evas_init() before
25 * creating new canvas.
26 *
27 * @return A new uninitialised Evas canvas on success. Otherwise, @c NULL.
28 * @ingroup Evas_Canvas
29 */
30EAPI Evas *evas_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
31
32/**
33 * Frees the given evas and any objects created on it.
34 *
35 * Any objects with 'free' callbacks will have those callbacks called
36 * in this function.
37 *
38 * @param e The given evas.
39 *
40 * @ingroup Evas_Canvas
41 */
42EAPI void evas_free(Evas *e) EINA_ARG_NONNULL(1);
43
44/**
45 * Inform to the evas that it got the focus.
46 *
47 * @param e The evas to change information.
48 * @ingroup Evas_Canvas
49 */
50EAPI void evas_focus_in(Evas *e);
51
52/**
53 * Inform to the evas that it lost the focus.
54 *
55 * @param e The evas to change information.
56 * @ingroup Evas_Canvas
57 */
58EAPI void evas_focus_out(Evas *e);
59
60/**
61 * Get the focus state known by the given evas
62 *
63 * @param e The evas to query information.
64 * @ingroup Evas_Canvas
65 */
66EAPI Eina_Bool evas_focus_state_get(const Evas *e);
67
68/**
69 * Push the nochange flag up 1
70 *
71 * This tells evas, that while the nochange flag is greater than 0, do not
72 * mark objects as "changed" when making changes.
73 *
74 * @param e The evas to change information.
75 * @ingroup Evas_Canvas
76 */
77EAPI void evas_nochange_push(Evas *e);
78
79/**
80 * Pop the nochange flag down 1
81 *
82 * This tells evas, that while the nochange flag is greater than 0, do not
83 * mark objects as "changed" when making changes.
84 *
85 * @param e The evas to change information.
86 * @ingroup Evas_Canvas
87 */
88EAPI void evas_nochange_pop(Evas *e);
89
90/**
91 * Attaches a specific pointer to the evas for fetching later
92 *
93 * @param e The canvas to attach the pointer to
94 * @param data The pointer to attach
95 * @ingroup Evas_Canvas
96 */
97EAPI void evas_data_attach_set(Evas *e, void *data) EINA_ARG_NONNULL(1);
98
99/**
100 * Returns the pointer attached by evas_data_attach_set()
101 *
102 * @param e The canvas to attach the pointer to
103 * @return The pointer attached
104 * @ingroup Evas_Canvas
105 */
106EAPI void *evas_data_attach_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
107
108/**
109 * Add a damage rectangle.
110 *
111 * @param e The given canvas pointer.
112 * @param x The rectangle's left position.
113 * @param y The rectangle's top position.
114 * @param w The rectangle's width.
115 * @param h The rectangle's height.
116 *
117 * This is the function by which one tells evas that a part of the
118 * canvas has to be repainted.
119 *
120 * @note All newly created Evas rectangles get the default color values of 255 255 255 255 (opaque white).
121 *
122 * @ingroup Evas_Canvas
123 */
124EAPI void evas_damage_rectangle_add(Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
125
126/**
127 * Add an "obscured region" to an Evas canvas.
128 *
129 * @param e The given canvas pointer.
130 * @param x The rectangle's top left corner's horizontal coordinate.
131 * @param y The rectangle's top left corner's vertical coordinate
132 * @param w The rectangle's width.
133 * @param h The rectangle's height.
134 *
135 * This is the function by which one tells an Evas canvas that a part
136 * of it <b>must not</b> be repainted. The region must be
137 * rectangular and its coordinates inside the canvas viewport are
138 * passed in the call. After this call, the region specified won't
139 * participate in any form in Evas' calculations and actions during
140 * its rendering updates, having its displaying content frozen as it
141 * was just after this function took place.
142 *
143 * We call it "obscured region" because the most common use case for
144 * this rendering (partial) freeze is something else (most probably
145 * other canvas) being on top of the specified rectangular region,
146 * thus shading it completely from the user's final scene in a
147 * display. To avoid unnecessary processing, one should indicate to the
148 * obscured canvas not to bother about the non-important area.
149 *
150 * The majority of users won't have to worry about this function, as
151 * they'll be using just one canvas in their applications, with
152 * nothing inset or on top of it in any form.
153 *
154 * To make this region one that @b has to be repainted again, call the
155 * function evas_obscured_clear().
156 *
157 * @note This is a <b>very low level function</b>, which most of
158 * Evas' users wouldn't care about.
159 *
160 * @note This function does @b not flag the canvas as having its state
161 * changed. If you want to re-render it afterwards expecting new
162 * contents, you have to add "damage" regions yourself (see
163 * evas_damage_rectangle_add()).
164 *
165 * @see evas_obscured_clear()
166 * @see evas_render_updates()
167 *
168 * Example code follows.
169 * @dontinclude evas-events.c
170 * @skip add an obscured
171 * @until evas_obscured_clear(evas);
172 *
173 * In that example, pressing the "Ctrl" and "o" keys will impose or
174 * remove an obscured region in the middle of the canvas. You'll get
175 * the same contents at the time the key was pressed, if toggling it
176 * on, until you toggle it off again (make sure the animation is
177 * running on to get the idea better). See the full @ref
178 * Example_Evas_Events "example".
179 *
180 * @ingroup Evas_Canvas
181 */
182EAPI void evas_obscured_rectangle_add(Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
183
184/**
185 * Remove all "obscured regions" from an Evas canvas.
186 *
187 * @param e The given canvas pointer.
188 *
189 * This function removes all the rectangles from the obscured regions
190 * list of the canvas @p e. It takes obscured areas added with
191 * evas_obscured_rectangle_add() and make them again a regions that @b
192 * have to be repainted on rendering updates.
193 *
194 * @note This is a <b>very low level function</b>, which most of
195 * Evas' users wouldn't care about.
196 *
197 * @note This function does @b not flag the canvas as having its state
198 * changed. If you want to re-render it afterwards expecting new
199 * contents, you have to add "damage" regions yourself (see
200 * evas_damage_rectangle_add()).
201 *
202 * @see evas_obscured_rectangle_add() for an example
203 * @see evas_render_updates()
204 *
205 * @ingroup Evas_Canvas
206 */
207EAPI void evas_obscured_clear(Evas *e) EINA_ARG_NONNULL(1);
208
209/**
210 * Render the given Evas canvas asynchronously.
211 *
212 * @param e The canvas to render.
213 * @param func Optional function to call with the list of updated areas.
214 * @param data User data to pass to @p func.
215 *
216 * @return EINA_TRUE if the canvas will render, EINA_FALSE otherwise.
217 *
218 * This function only returns EINA_TRUE whne a frame will be rendered. If the
219 * previous frame is still rendering, EINA_FALSE will be returned so the users
220 * know not to wait for the updates callback and just return to their main
221 * loop.
222 *
223 * If a @p func callback is given, a list of updated areas will be generated
224 * and the function will be called from the main thread after the rendered
225 * frame is flushed to the screen. The resulting list should be freed with
226 * @f evas_render_updates_free().
227 * The list is given in the @p event_info parameter of the callback function.
228 *
229 * @ingroup Evas_Canvas
230 * @since 1.8
231 */
232EAPI Eina_Bool evas_render_async(Evas *e) EINA_ARG_NONNULL(1);
233
234/**
235 * Force immediate renderization of the given Evas canvas.
236 *
237 * @param e The given canvas pointer.
238 * @return A newly allocated list of updated rectangles of the canvas
239 * (@c Eina_Rectangle structs). Free this list with
240 * evas_render_updates_free().
241 *
242 * This function forces an immediate renderization update of the given
243 * canvas @p e.
244 *
245 * @note This is a <b>very low level function</b>, which most of
246 * Evas' users wouldn't care about. One would use it, for example, to
247 * grab an Evas' canvas update regions and paint them back, using the
248 * canvas' pixmap, on a displaying system working below Evas.
249 *
250 * @note Evas is a stateful canvas. If no operations changing its
251 * state took place since the last rendering action, you won't see no
252 * changes and this call will be a no-op.
253 *
254 * Example code follows.
255 * @dontinclude evas-events.c
256 * @skip add an obscured
257 * @until d.obscured = !d.obscured;
258 *
259 * See the full @ref Example_Evas_Events "example".
260 *
261 * @ingroup Evas_Canvas
262 */
263EAPI Eina_List *evas_render_updates(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
264
265/**
266 * Force renderization of the given canvas.
267 *
268 * @param e The given canvas pointer.
269 *
270 * @ingroup Evas_Canvas
271 */
272EAPI void evas_render(Evas *e) EINA_ARG_NONNULL(1);
273
274/**
275 * Update the canvas internal objects but not triggering immediate
276 * renderization.
277 *
278 * @param e The given canvas pointer.
279 *
280 * This function updates the canvas internal objects not triggering
281 * renderization. To force renderization function evas_render() should
282 * be used.
283 *
284 * @see evas_render.
285 *
286 * @ingroup Evas_Canvas
287 */
288EAPI void evas_norender(Evas *e) EINA_ARG_NONNULL(1);
289
290/**
291 * Make the canvas discard internally cached data used for rendering.
292 *
293 * @param e The given canvas pointer.
294 *
295 * This function flushes the arrays of delete, active and render objects.
296 * Other things it may also discard are: shared memory segments,
297 * temporary scratch buffers, cached data to avoid re-compute of that data etc.
298 *
299 * @ingroup Evas_Canvas
300 */
301EAPI void evas_render_idle_flush(Evas *e) EINA_ARG_NONNULL(1);
302
303/**
304 * Make the canvas discard as much data as possible used by the engine at
305 * runtime.
306 *
307 * @param e The given canvas pointer.
308 *
309 * This function will unload images, delete textures and much more, where
310 * possible. You may also want to call evas_render_idle_flush() immediately
311 * prior to this to perhaps discard a little more, though evas_render_dump()
312 * should implicitly delete most of what evas_render_idle_flush() might
313 * discard too.
314 *
315 * @ingroup Evas_Canvas
316 */
317EAPI void evas_render_dump(Evas *e) EINA_ARG_NONNULL(1);
318
319
320/**
321 * @}
322 */
323
324
325/**
326 * @ingroup Evas_Output_Method
327 *
328 * @{
329 */
330
331/**
332 * Sets the output engine for the given evas.
333 *
334 * Once the output engine for an evas is set, any attempt to change it
335 * will be ignored. The value for @p render_method can be found using
336 * @ref evas_render_method_lookup .
337 *
338 * @param e The given evas.
339 * @param render_method The numeric engine value to use.
340 *
341 * @attention it is mandatory that one calls evas_init() before
342 * setting the output method.
343 *
344 * @ingroup Evas_Output_Method
345 */
346EAPI void evas_output_method_set(Evas *e, int render_method) EINA_ARG_NONNULL(1);
347
348/**
349 * Retrieves the number of the output engine used for the given evas.
350 * @param e The given evas.
351 * @return The ID number of the output engine being used. @c 0 is
352 * returned if there is an error.
353 * @ingroup Evas_Output_Method
354 */
355EAPI int evas_output_method_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
356
357/**
358 * Retrieves the current render engine info struct from the given evas.
359 *
360 * The returned structure is publicly modifiable. The contents are
361 * valid until either @ref evas_engine_info_set or @ref evas_render
362 * are called.
363 *
364 * This structure does not need to be freed by the caller.
365 *
366 * @param e The given evas.
367 * @return A pointer to the Engine Info structure. @c NULL is returned if
368 * an engine has not yet been assigned.
369 * @ingroup Evas_Output_Method
370 */
371EAPI Evas_Engine_Info *evas_engine_info_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
372
373/**
374 * Applies the engine settings for the given evas from the given @c
375 * Evas_Engine_Info structure.
376 *
377 * To get the Evas_Engine_Info structure to use, call @ref
378 * evas_engine_info_get . Do not try to obtain a pointer to an
379 * @c Evas_Engine_Info structure in any other way.
380 *
381 * You will need to call this function at least once before you can
382 * create objects on an evas or render that evas. Some engines allow
383 * their settings to be changed more than once.
384 *
385 * Once called, the @p info pointer should be considered invalid.
386 *
387 * @param e The pointer to the Evas Canvas
388 * @param info The pointer to the Engine Info to use
389 * @return @c EINA_TRUE if no error occurred, @c EINA_FALSE otherwise.
390 * @ingroup Evas_Output_Method
391 */
392EAPI Eina_Bool evas_engine_info_set(Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1);
393/**
394 * @}
395 */
396
397/**
398 * @ingroup Evas_Output_Size
399 *
400 * @{
401 */
402/**
403 * Sets the output size of the render engine of the given evas.
404 *
405 * The evas will render to a rectangle of the given size once this
406 * function is called. The output size is independent of the viewport
407 * size. The viewport will be stretched to fill the given rectangle.
408 *
409 * The units used for @p w and @p h depend on the engine used by the
410 * evas.
411 *
412 * @param e The given evas.
413 * @param w The width in output units, usually pixels.
414 * @param h The height in output units, usually pixels.
415 * @ingroup Evas_Output_Size
416 */
417EAPI void evas_output_size_set(Evas *e, int w, int h) EINA_ARG_NONNULL(1);
418
419/**
420 * Retrieve the output size of the render engine of the given evas.
421 *
422 * The output size is given in whatever the output units are for the
423 * engine.
424 *
425 * If either @p w or @p h is @c NULL, then it is ignored. If @p e is
426 * invalid, the returned results are undefined.
427 *
428 * @param e The given evas.
429 * @param w The pointer to an integer to store the width in.
430 * @param h The pointer to an integer to store the height in.
431 * @ingroup Evas_Output_Size
432 */
433EAPI void evas_output_size_get(const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1);
434
435/**
436 * Sets the output viewport of the given evas in evas units.
437 *
438 * The output viewport is the area of the evas that will be visible to
439 * the viewer. The viewport will be stretched to fit the output
440 * target of the evas when rendering is performed.
441 *
442 * @note The coordinate values do not have to map 1-to-1 with the output
443 * target. However, it is generally advised that it is done for ease
444 * of use.
445 *
446 * @param e The given evas.
447 * @param x The top-left corner x value of the viewport.
448 * @param y The top-left corner y value of the viewport.
449 * @param w The width of the viewport. Must be greater than 0.
450 * @param h The height of the viewport. Must be greater than 0.
451 * @ingroup Evas_Output_Size
452 */
453EAPI void evas_output_viewport_set(Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
454
455/**
456 * Get the render engine's output viewport co-ordinates in canvas units.
457 * @param e The pointer to the Evas Canvas
458 * @param x The pointer to a x variable to be filled in
459 * @param y The pointer to a y variable to be filled in
460 * @param w The pointer to a width variable to be filled in
461 * @param h The pointer to a height variable to be filled in
462 * @ingroup Evas_Output_Size
463 *
464 * Calling this function writes the current canvas output viewport
465 * size and location values into the variables pointed to by @p x, @p
466 * y, @p w and @p h. On success the variables have the output
467 * location and size values written to them in canvas units. Any of @p
468 * x, @p y, @p w or @p h that are @c NULL will not be written to. If @p e
469 * is invalid, the results are undefined.
470 *
471 * Example:
472 * @code
473 * extern Evas *evas;
474 * Evas_Coord x, y, width, height;
475 *
476 * evas_output_viewport_get(evas, &x, &y, &w, &h);
477 * @endcode
478 */
479EAPI void evas_output_viewport_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
480
481/**
482 * Sets the output framespace size of the render engine of the given evas.
483 *
484 * The framespace size is used in the Wayland engines to denote space where
485 * the output is not drawn. This is mainly used in ecore_evas to draw borders
486 *
487 * The units used for @p w and @p h depend on the engine used by the
488 * evas.
489 *
490 * @param e The given evas.
491 * @param x The left coordinate in output units, usually pixels.
492 * @param y The top coordinate in output units, usually pixels.
493 * @param w The width in output units, usually pixels.
494 * @param h The height in output units, usually pixels.
495 * @ingroup Evas_Output_Size
496 * @since 1.1
497 */
498EAPI void evas_output_framespace_set(Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h);
499
500/**
501 * Get the render engine's output framespace co-ordinates in canvas units.
502 *
503 * @param e The pointer to the Evas Canvas
504 * @param x The pointer to a x variable to be filled in
505 * @param y The pointer to a y variable to be filled in
506 * @param w The pointer to a width variable to be filled in
507 * @param h The pointer to a height variable to be filled in
508 * @ingroup Evas_Output_Size
509 * @since 1.1
510 */
511EAPI void evas_output_framespace_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h);
512/**
513 * @}
514 */
515
516/**
517 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
518 *
519 * @param e The pointer to the Evas Canvas
520 * @param x The screen/output x co-ordinate
521 * @return The screen co-ordinate translated to canvas unit co-ordinates
522 * @ingroup Evas_Coord_Mapping_Group
523 *
524 * This function takes in a horizontal co-ordinate as the @p x
525 * parameter and converts it into canvas units, accounting for output
526 * size, viewport size and location, returning it as the function
527 * return value. If @p e is invalid, the results are undefined.
528 *
529 * Example:
530 * @code
531 * extern Evas *evas;
532 * extern int screen_x;
533 * Evas_Coord canvas_x;
534 *
535 * canvas_x = evas_coord_screen_x_to_world(evas, screen_x);
536 * @endcode
537 */
538EAPI Evas_Coord evas_coord_screen_x_to_world(const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
539
540/**
541 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
542 *
543 * @param e The pointer to the Evas Canvas
544 * @param y The screen/output y co-ordinate
545 * @return The screen co-ordinate translated to canvas unit co-ordinates
546 * @ingroup Evas_Coord_Mapping_Group
547 *
548 * This function takes in a vertical co-ordinate as the @p y parameter
549 * and converts it into canvas units, accounting for output size,
550 * viewport size and location, returning it as the function return
551 * value. If @p e is invalid, the results are undefined.
552 *
553 * Example:
554 * @code
555 * extern Evas *evas;
556 * extern int screen_y;
557 * Evas_Coord canvas_y;
558 *
559 * canvas_y = evas_coord_screen_y_to_world(evas, screen_y);
560 * @endcode
561 */
562EAPI Evas_Coord evas_coord_screen_y_to_world(const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
563
564/**
565 * Convert/scale a canvas co-ordinate into output screen co-ordinates
566 *
567 * @param e The pointer to the Evas Canvas
568 * @param x The canvas x co-ordinate
569 * @return The output/screen co-ordinate translated to output co-ordinates
570 * @ingroup Evas_Coord_Mapping_Group
571 *
572 * This function takes in a horizontal co-ordinate as the @p x
573 * parameter and converts it into output units, accounting for output
574 * size, viewport size and location, returning it as the function
575 * return value. If @p e is invalid, the results are undefined.
576 *
577 * Example:
578 * @code
579 * extern Evas *evas;
580 * int screen_x;
581 * extern Evas_Coord canvas_x;
582 *
583 * screen_x = evas_coord_world_x_to_screen(evas, canvas_x);
584 * @endcode
585 */
586EAPI int evas_coord_world_x_to_screen(const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
587
588/**
589 * Convert/scale a canvas co-ordinate into output screen co-ordinates
590 *
591 * @param e The pointer to the Evas Canvas
592 * @param y The canvas y co-ordinate
593 * @return The output/screen co-ordinate translated to output co-ordinates
594 * @ingroup Evas_Coord_Mapping_Group
595 *
596 * This function takes in a vertical co-ordinate as the @p x parameter
597 * and converts it into output units, accounting for output size,
598 * viewport size and location, returning it as the function return
599 * value. If @p e is invalid, the results are undefined.
600 *
601 * Example:
602 * @code
603 * extern Evas *evas;
604 * int screen_y;
605 * extern Evas_Coord canvas_y;
606 *
607 * screen_y = evas_coord_world_y_to_screen(evas, canvas_y);
608 * @endcode
609 */
610EAPI int evas_coord_world_y_to_screen(const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
611
612/**
613 * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
614 *
615 * Functions that deal with the status of the pointer (mouse cursor).
616 *
617 * @ingroup Evas_Canvas
618 */
619
620/**
621 * This function returns the current known pointer co-ordinates
622 *
623 * @param e The pointer to the Evas Canvas
624 * @param x The pointer to an integer to be filled in
625 * @param y The pointer to an integer to be filled in
626 * @ingroup Evas_Pointer_Group
627 *
628 * This function returns the current known screen/output co-ordinates
629 * of the mouse pointer and sets the contents of the integers pointed
630 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
631 * valid canvas the results of this function are undefined.
632 *
633 * Example:
634 * @code
635 * extern Evas *evas;
636 * int mouse_x, mouse_y;
637 *
638 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
639 * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y);
640 * @endcode
641 */
642EAPI void evas_pointer_output_xy_get(const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1);
643
644/**
645 * This function returns the current known pointer co-ordinates
646 *
647 * @param e The pointer to the Evas Canvas
648 * @param x The pointer to a Evas_Coord to be filled in
649 * @param y The pointer to a Evas_Coord to be filled in
650 * @ingroup Evas_Pointer_Group
651 *
652 * This function returns the current known canvas unit co-ordinates of
653 * the mouse pointer and sets the contents of the Evas_Coords pointed
654 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
655 * valid canvas the results of this function are undefined.
656 *
657 * Example:
658 * @code
659 * extern Evas *evas;
660 * Evas_Coord mouse_x, mouse_y;
661 *
662 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
663 * printf("Mouse is at canvas position %d, %d\n", mouse_x, mouse_y);
664 * @endcode
665 */
666EAPI void evas_pointer_canvas_xy_get(const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
667
668/**
669 * Returns a bitmask with the mouse buttons currently pressed, set to 1
670 *
671 * @param e The pointer to the Evas Canvas
672 * @return A bitmask of the currently depressed buttons on the canvas
673 * @ingroup Evas_Pointer_Group
674 *
675 * Calling this function will return a 32-bit integer with the
676 * appropriate bits set to 1 that correspond to a mouse button being
677 * depressed. This limits Evas to a mouse devices with a maximum of 32
678 * buttons, but that is generally in excess of any host system's
679 * pointing device abilities.
680 *
681 * A canvas by default begins with no mouse buttons being pressed and
682 * only calls to evas_event_feed_mouse_down(),
683 * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and
684 * evas_event_feed_mouse_up_data() will alter that.
685 *
686 * The least significant bit corresponds to the first mouse button
687 * (button 1) and the most significant bit corresponds to the last
688 * mouse button (button 32).
689 *
690 * If @p e is not a valid canvas, the return value is undefined.
691 *
692 * Example:
693 * @code
694 * extern Evas *evas;
695 * int button_mask, i;
696 *
697 * button_mask = evas_pointer_button_down_mask_get(evas);
698 * printf("Buttons currently pressed:\n");
699 * for (i = 0; i < 32; i++)
700 * {
701 * if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1);
702 * }
703 * @endcode
704 */
705EAPI int evas_pointer_button_down_mask_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
706
707/**
708 * Returns whether the mouse pointer is logically inside the canvas
709 *
710 * @param e The pointer to the Evas Canvas
711 * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise
712 * @ingroup Evas_Pointer_Group
713 *
714 * When this function is called it will return a value of either 0 or
715 * 1, depending on if evas_event_feed_mouse_in(),
716 * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(),
717 * evas_event_feed_mouse_out_data() have been called to feed in a
718 * mouse enter event into the canvas.
719 *
720 * A return value of 1 indicates the mouse is logically inside the
721 * canvas, and 0 implies it is logically outside the canvas.
722 *
723 * A canvas begins with the mouse being assumed outside (0).
724 *
725 * If @p e is not a valid canvas, the return value is undefined.
726 *
727 * Example:
728 * @code
729 * extern Evas *evas;
730 *
731 * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n");
732 * else printf("Mouse is out!\n");
733 * @endcode
734 */
735EAPI Eina_Bool evas_pointer_inside_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
736
737EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1);
738
739/**
740 * @}
741 */
742
743/**
744 * @ingroup Evas_Canvas_Events
745 *
746 * @{
747 */
748
749/**
750 * Add (register) a callback function to a given canvas event.
751 *
752 * @param e Canvas to attach a callback to
753 * @param type The type of event that will trigger the callback
754 * @param func The (callback) function to be called when the event is
755 * triggered
756 * @param data The data pointer to be passed to @p func
757 *
758 * This function adds a function callback to the canvas @p e when the
759 * event of type @p type occurs on it. The function pointer is @p
760 * func.
761 *
762 * In the event of a memory allocation error during the addition of
763 * the callback to the canvas, evas_alloc_error() should be used to
764 * determine the nature of the error, if any, and the program should
765 * sensibly try and recover.
766 *
767 * A callback function must have the ::Evas_Event_Cb prototype
768 * definition. The first parameter (@p data) in this definition will
769 * have the same value passed to evas_event_callback_add() as the @p
770 * data parameter, at runtime. The second parameter @p e is the canvas
771 * pointer on which the event occurred. The third parameter @p
772 * event_info is a pointer to a data structure that may or may not be
773 * passed to the callback, depending on the event type that triggered
774 * the callback. This is so because some events don't carry extra
775 * context with them, but others do.
776 *
777 * The event type @p type to trigger the function may be one of
778 * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST,
779 * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT,
780 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and
781 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of
782 * event that will trigger the callback to be called. Only the last
783 * two of the event types listed here provide useful event information
784 * data -- a pointer to the recently focused Evas object. For the
785 * others the @p event_info pointer is going to be @c NULL.
786 *
787 * Example:
788 * @dontinclude evas-events.c
789 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE
790 * @until two canvas event callbacks
791 *
792 * Looking to the callbacks registered above,
793 * @dontinclude evas-events.c
794 * @skip called when our rectangle gets focus
795 * @until let's have our events back
796 *
797 * we see that the canvas flushes its rendering pipeline
798 * (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb
799 * routine takes place: it has to redraw that image at a different
800 * size. Also, the callback on an object being focused comes just
801 * after we focus it explicitly, on code.
802 *
803 * See the full @ref Example_Evas_Events "example".
804 *
805 * @note Be careful not to add the same callback multiple times, if
806 * that's not what you want, because Evas won't check if a callback
807 * existed before exactly as the one being registered (and thus, call
808 * it more than once on the event, in this case). This would make
809 * sense if you passed different functions and/or callback data, only.
810 */
811EAPI void evas_event_callback_add(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
812
813/**
814 * Add (register) a callback function to a given canvas event with a
815 * non-default priority set. Except for the priority field, it's exactly the
816 * same as @ref evas_event_callback_add
817 *
818 * @param e Canvas to attach a callback to
819 * @param type The type of event that will trigger the callback
820 * @param priority The priority of the callback, lower values called first.
821 * @param func The (callback) function to be called when the event is
822 * triggered
823 * @param data The data pointer to be passed to @p func
824 *
825 * @see evas_event_callback_add
826 * @since 1.1
827 */
828EAPI void evas_event_callback_priority_add(Evas *e, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 4);
829
830/**
831 * Delete a callback function from the canvas.
832 *
833 * @param e Canvas to remove a callback from
834 * @param type The type of event that was triggering the callback
835 * @param func The function that was to be called when the event was triggered
836 * @return The data pointer that was to be passed to the callback
837 *
838 * This function removes the most recently added callback from the
839 * canvas @p e which was triggered by the event type @p type and was
840 * calling the function @p func when triggered. If the removal is
841 * successful it will also return the data pointer that was passed to
842 * evas_event_callback_add() when the callback was added to the
843 * canvas. If not successful @c NULL will be returned.
844 *
845 * Example:
846 * @code
847 * extern Evas *e;
848 * void *my_data;
849 * void focus_in_callback(void *data, Evas *e, void *event_info);
850 *
851 * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
852 * @endcode
853 */
854EAPI void *evas_event_callback_del(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
855
856/**
857 * Delete (unregister) a callback function registered to a given
858 * canvas event.
859 *
860 * @param e Canvas to remove an event callback from
861 * @param type The type of event that was triggering the callback
862 * @param func The function that was to be called when the event was
863 * triggered
864 * @param data The data pointer that was to be passed to the callback
865 * @return The data pointer that was to be passed to the callback
866 *
867 * This function removes <b>the first</b> added callback from the
868 * canvas @p e matching the event type @p type, the registered
869 * function pointer @p func and the callback data pointer @p data. If
870 * the removal is successful it will also return the data pointer that
871 * was passed to evas_event_callback_add() (that will be the same as
872 * the parameter) when the callback(s) was(were) added to the
873 * canvas. If not successful @c NULL will be returned. A common use
874 * would be to remove an exact match of a callback.
875 *
876 * Example:
877 * @dontinclude evas-events.c
878 * @skip evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
879 * @until _object_focus_in_cb, NULL);
880 *
881 * See the full @ref Example_Evas_Events "example".
882 *
883 * @note For deletion of canvas events callbacks filtering by just
884 * type and function pointer, user evas_event_callback_del().
885 */
886EAPI void *evas_event_callback_del_full(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
887
888/**
889 * Push a callback on the post-event callback stack
890 *
891 * @param e Canvas to push the callback on
892 * @param func The function that to be called when the stack is unwound
893 * @param data The data pointer to be passed to the callback
894 *
895 * Evas has a stack of callbacks that get called after all the callbacks for
896 * an event have triggered (all the objects it triggers on and all the callbacks
897 * in each object triggered). When all these have been called, the stack is
898 * unwond from most recently to least recently pushed item and removed from the
899 * stack calling the callback set for it.
900 *
901 * This is intended for doing reverse logic-like processing, example - when a
902 * child object that happens to get the event later is meant to be able to
903 * "steal" functions from a parent and thus on unwind of this stack have its
904 * function called first, thus being able to set flags, or return 0 from the
905 * post-callback that stops all other post-callbacks in the current stack from
906 * being called (thus basically allowing a child to take control, if the event
907 * callback prepares information ready for taking action, but the post callback
908 * actually does the action).
909 *
910 */
911EAPI void evas_post_event_callback_push(Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
912
913/**
914 * Remove a callback from the post-event callback stack
915 *
916 * @param e Canvas to push the callback on
917 * @param func The function that to be called when the stack is unwound
918 *
919 * This removes a callback from the stack added with
920 * evas_post_event_callback_push(). The first instance of the function in
921 * the callback stack is removed from being executed when the stack is
922 * unwound. Further instances may still be run on unwind.
923 */
924EAPI void evas_post_event_callback_remove(Evas *e, Evas_Object_Event_Post_Cb func);
925
926/**
927 * Remove a callback from the post-event callback stack
928 *
929 * @param e Canvas to push the callback on
930 * @param func The function that to be called when the stack is unwound
931 * @param data The data pointer to be passed to the callback
932 *
933 * This removes a callback from the stack added with
934 * evas_post_event_callback_push(). The first instance of the function and data
935 * in the callback stack is removed from being executed when the stack is
936 * unwound. Further instances may still be run on unwind.
937 */
938EAPI void evas_post_event_callback_remove_full(Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
939
940/**
941 * @}
942 */
943
944/**
945 * @ingroup Evas_Event_Feeding_Group
946 *
947 * @{
948 */
949
950/**
951 * Set the default set of flags an event begins with
952 *
953 * @param e The canvas to set the default event flags of
954 * @param flags The default flags to use
955 *
956 * Events in evas can have an event_flags member. This starts out with
957 * and initial value (no flags). this lets you set the default flags that
958 * an event begins with to be @p flags
959 *
960 * @since 1.2
961 */
962EAPI void evas_event_default_flags_set(Evas *e, Evas_Event_Flags flags) EINA_ARG_NONNULL(1);
963
964/**
965 * Get the defaulty set of flags an event begins with
966 *
967 * @param e The canvas to get the default event flags from
968 * @return The default event flags for that canvas
969 *
970 * This gets the default event flags events are produced with when fed in.
971 *
972 * @see evas_event_default_flags_set()
973 * @since 1.2
974 */
975EAPI Evas_Event_Flags evas_event_default_flags_get(const Evas *e) EINA_ARG_NONNULL(1);
976
977/**
978 * Freeze all input events processing.
979 *
980 * @param e The canvas to freeze input events processing on.
981 *
982 * This function will indicate to Evas that the canvas @p e is to have
983 * all input event processing frozen until a matching
984 * evas_event_thaw() function is called on the same canvas. All events
985 * of this kind during the freeze will get @b discarded. Every freeze
986 * call must be matched by a thaw call in order to completely thaw out
987 * a canvas (i.e. these calls may be nested). The most common use is
988 * when you don't want the user to interact with your user interface
989 * when you're populating a view or changing the layout.
990 *
991 * Example:
992 * @dontinclude evas-events.c
993 * @skip freeze input for 3 seconds
994 * @until }
995 * @dontinclude evas-events.c
996 * @skip let's have our events back
997 * @until }
998 *
999 * See the full @ref Example_Evas_Events "example".
1000 *
1001 * If you run that example, you'll see the canvas ignoring all input
1002 * events for 3 seconds, when the "f" key is pressed. In a more
1003 * realistic code we would be freezing while a toolkit or Edje was
1004 * doing some UI changes, thawing it back afterwards.
1005 */
1006EAPI void evas_event_freeze(Evas *e) EINA_ARG_NONNULL(1);
1007
1008/**
1009 * Thaw a canvas out after freezing (for input events).
1010 *
1011 * @param e The canvas to thaw out.
1012 *
1013 * This will thaw out a canvas after a matching evas_event_freeze()
1014 * call. If this call completely thaws out a canvas, i.e., there's no
1015 * other unbalanced call to evas_event_freeze(), events will start to
1016 * be processed again, but any "missed" events will @b not be
1017 * evaluated.
1018 *
1019 * See evas_event_freeze() for an example.
1020 */
1021EAPI void evas_event_thaw(Evas *e) EINA_ARG_NONNULL(1);
1022
1023/**
1024 * Return the freeze count on input events of a given canvas.
1025 *
1026 * @param e The canvas to fetch the freeze count from.
1027 *
1028 * This returns the number of times the canvas has been told to freeze
1029 * input events. It is possible to call evas_event_freeze() multiple
1030 * times, and these must be matched by evas_event_thaw() calls. This
1031 * call allows the program to discover just how many times things have
1032 * been frozen in case it may want to break out of a deep freeze state
1033 * where the count is high.
1034 *
1035 * Example:
1036 * @code
1037 * extern Evas *evas;
1038 *
1039 * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
1040 * @endcode
1041 *
1042 */
1043EAPI int evas_event_freeze_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1044
1045/**
1046 * After thaw of a canvas, re-evaluate the state of objects and call callbacks
1047 *
1048 * @param e The canvas to evaluate after a thaw
1049 *
1050 * This is normally called after evas_event_thaw() to re-evaluate mouse
1051 * containment and other states and thus also call callbacks for mouse in and
1052 * out on new objects if the state change demands it.
1053 */
1054EAPI void evas_event_thaw_eval(Evas *e) EINA_ARG_NONNULL(1);
1055/**
1056 * @}
1057 */
1058
1059/**
1060 * @ingroup Evas_Event_Feeding_Group
1061 *
1062 * @{
1063 */
1064
1065/**
1066 * Get the number of mouse or multi presses currently active
1067 *
1068 * @p e The given canvas pointer.
1069 * @return The numer of presses (0 if none active).
1070 *
1071 * @since 1.2
1072 */
1073EAPI int evas_event_down_count_get(const Evas *e) EINA_ARG_NONNULL(1);
1074
1075/**
1076 * Mouse down event feed.
1077 *
1078 * @param e The given canvas pointer.
1079 * @param b The button number.
1080 * @param flags The evas button flags.
1081 * @param timestamp The timestamp of the mouse down event.
1082 * @param data The data for canvas.
1083 *
1084 * This function will set some evas properties that is necessary when
1085 * the mouse button is pressed. It prepares information to be treated
1086 * by the callback function.
1087 *
1088 */
1089EAPI void evas_event_feed_mouse_down(Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1090
1091/**
1092 * Mouse up event feed.
1093 *
1094 * @param e The given canvas pointer.
1095 * @param b The button number.
1096 * @param flags evas button flags.
1097 * @param timestamp The timestamp of the mouse up event.
1098 * @param data The data for canvas.
1099 *
1100 * This function will set some evas properties that is necessary when
1101 * the mouse button is released. It prepares information to be treated
1102 * by the callback function.
1103 *
1104 */
1105EAPI void evas_event_feed_mouse_up(Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1106
1107/**
1108 * Mouse move event feed.
1109 *
1110 * @param e The given canvas pointer.
1111 * @param x The horizontal position of the mouse pointer.
1112 * @param y The vertical position of the mouse pointer.
1113 * @param timestamp The timestamp of the mouse up event.
1114 * @param data The data for canvas.
1115 *
1116 * This function will set some evas properties that is necessary when
1117 * the mouse is moved from its last position. It prepares information
1118 * to be treated by the callback function.
1119 *
1120 */
1121EAPI void evas_event_feed_mouse_move(Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1122
1123/**
1124 * Mouse in event feed.
1125 *
1126 * @param e The given canvas pointer.
1127 * @param timestamp The timestamp of the mouse up event.
1128 * @param data The data for canvas.
1129 *
1130 * This function will set some evas properties that is necessary when
1131 * the mouse in event happens. It prepares information to be treated
1132 * by the callback function.
1133 *
1134 */
1135EAPI void evas_event_feed_mouse_in(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1136
1137/**
1138 * Mouse out event feed.
1139 *
1140 * @param e The given canvas pointer.
1141 * @param timestamp Timestamp of the mouse up event.
1142 * @param data The data for canvas.
1143 *
1144 * This function will set some evas properties that is necessary when
1145 * the mouse out event happens. It prepares information to be treated
1146 * by the callback function.
1147 *
1148 */
1149EAPI void evas_event_feed_mouse_out(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1150EAPI void evas_event_feed_multi_down(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
1151EAPI void evas_event_feed_multi_up(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
1152EAPI void evas_event_feed_multi_move(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, unsigned int timestamp, const void *data);
1153
1154/**
1155 * Mouse cancel event feed.
1156 *
1157 * @param e The given canvas pointer.
1158 * @param timestamp The timestamp of the mouse up event.
1159 * @param data The data for canvas.
1160 *
1161 * This function will call evas_event_feed_mouse_up() when a
1162 * mouse cancel event happens.
1163 *
1164 */
1165EAPI void evas_event_feed_mouse_cancel(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1166
1167/**
1168 * Mouse wheel event feed.
1169 *
1170 * @param e The given canvas pointer.
1171 * @param direction The wheel mouse direction.
1172 * @param z How much mouse wheel was scrolled up or down.
1173 * @param timestamp The timestamp of the mouse up event.
1174 * @param data The data for canvas.
1175 *
1176 * This function will set some evas properties that is necessary when
1177 * the mouse wheel is scrolled up or down. It prepares information to
1178 * be treated by the callback function.
1179 *
1180 */
1181EAPI void evas_event_feed_mouse_wheel(Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1182
1183/**
1184 * Key down event feed
1185 *
1186 * @param e The canvas to thaw out
1187 * @param keyname Name of the key
1188 * @param key The key pressed.
1189 * @param string A String
1190 * @param compose The compose string
1191 * @param timestamp Timestamp of the mouse up event
1192 * @param data Data for canvas.
1193 *
1194 * This function will set some evas properties that is necessary when
1195 * a key is pressed. It prepares information to be treated by the
1196 * callback function.
1197 *
1198 */
1199EAPI void evas_event_feed_key_down(Evas *e, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1200
1201/**
1202 * Key up event feed
1203 *
1204 * @param e The canvas to thaw out
1205 * @param keyname Name of the key
1206 * @param key The key released.
1207 * @param string string
1208 * @param compose compose
1209 * @param timestamp Timestamp of the mouse up event
1210 * @param data Data for canvas.
1211 *
1212 * This function will set some evas properties that is necessary when
1213 * a key is released. It prepares information to be treated by the
1214 * callback function.
1215 *
1216 */
1217EAPI void evas_event_feed_key_up(Evas *e, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1218
1219/**
1220 * Hold event feed
1221 *
1222 * @param e The given canvas pointer.
1223 * @param hold The hold.
1224 * @param timestamp The timestamp of the mouse up event.
1225 * @param data The data for canvas.
1226 *
1227 * This function makes the object to stop sending events.
1228 *
1229 */
1230EAPI void evas_event_feed_hold(Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
1231
1232/**
1233 * Re feed event.
1234 *
1235 * @param e The given canvas pointer.
1236 * @param event_copy the event to refeed
1237 * @param event_type Event type
1238 *
1239 * This function re-feeds the event pointed by event_copy
1240 *
1241 * This function call evas_event_feed_* functions, so it can
1242 * cause havoc if not used wisely. Please use it responsibly.
1243 */
1244EAPI void evas_event_refeed_event(Evas *e, void *event_copy, Evas_Callback_Type event_type) EINA_ARG_NONNULL(1);
1245
1246/**
1247 * @}
1248 */
1249
1250/**
1251 * @ingroup Evas_Image_Group
1252 *
1253 * @{
1254 */
1255
1256/**
1257 * Flush the image cache of the canvas.
1258 *
1259 * @param e The given evas pointer.
1260 *
1261 * This function flushes image cache of canvas.
1262 *
1263 */
1264EAPI void evas_image_cache_flush(Evas *e) EINA_ARG_NONNULL(1);
1265
1266/**
1267 * Reload the image cache
1268 *
1269 * @param e The given evas pointer.
1270 *
1271 * This function reloads the image cache of canvas.
1272 *
1273 */
1274EAPI void evas_image_cache_reload(Evas *e) EINA_ARG_NONNULL(1);
1275
1276/**
1277 * Set the image cache.
1278 *
1279 * @param e The given evas pointer.
1280 * @param size The cache size.
1281 *
1282 * This function sets the image cache of canvas in bytes.
1283 *
1284 */
1285EAPI void evas_image_cache_set(Evas *e, int size) EINA_ARG_NONNULL(1);
1286
1287/**
1288 * Get the image cache
1289 *
1290 * @param e The given evas pointer.
1291 *
1292 * This function returns the image cache size of canvas in bytes.
1293 *
1294 */
1295EAPI int evas_image_cache_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1296
1297/**
1298 * Get the maximum image size evas can possibly handle
1299 *
1300 * @param e The given evas pointer.
1301 * @param maxw Pointer to hold the return value in pixels of the maxumum width
1302 * @param maxh Pointer to hold the return value in pixels of the maximum height
1303 *
1304 * This function returns the larges image or surface size that evas can handle
1305 * in pixels, and if there is one, returns @c EINA_TRUE. It returns
1306 * @c EINA_FALSE if no extra constraint on maximum image size exists. You still
1307 * should check the return values of @p maxw and @p maxh as there may still be
1308 * a limit, just a much higher one.
1309 *
1310 * @since 1.1
1311 */
1312EAPI Eina_Bool evas_image_max_size_get(const Evas *e, int *maxw, int *maxh) EINA_ARG_NONNULL(1);
1313/**
1314 * @}
1315 */
1316
1317/**
1318 * @ingroup Evas_Font_Group
1319 *
1320 * @{
1321 */
1322
1323/**
1324 * Changes the font hinting for the given evas.
1325 *
1326 * @param e The given evas.
1327 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
1328 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
1329 * @ingroup Evas_Font_Group
1330 */
1331EAPI void evas_font_hinting_set(Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1);
1332
1333/**
1334 * Retrieves the font hinting used by the given evas.
1335 *
1336 * @param e The given evas to query.
1337 * @return The hinting in use, one of #EVAS_FONT_HINTING_NONE,
1338 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
1339 * @ingroup Evas_Font_Group
1340 */
1341EAPI Evas_Font_Hinting_Flags evas_font_hinting_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1342
1343/**
1344 * Checks if the font hinting is supported by the given evas.
1345 *
1346 * @param e The given evas to query.
1347 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
1348 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
1349 * @return @c EINA_TRUE if it is supported, @c EINA_FALSE otherwise.
1350 * @ingroup Evas_Font_Group
1351 */
1352EAPI Eina_Bool evas_font_hinting_can_hint(const Evas *e, Evas_Font_Hinting_Flags hinting) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1353
1354/**
1355 * Force the given evas and associated engine to flush its font cache.
1356 *
1357 * @param e The given evas to flush font cache.
1358 * @ingroup Evas_Font_Group
1359 */
1360EAPI void evas_font_cache_flush(Evas *e) EINA_ARG_NONNULL(1);
1361
1362/**
1363 * Changes the size of font cache of the given evas.
1364 *
1365 * @param e The given evas to flush font cache.
1366 * @param size The size, in bytes.
1367 *
1368 * @ingroup Evas_Font_Group
1369 */
1370EAPI void evas_font_cache_set(Evas *e, int size) EINA_ARG_NONNULL(1);
1371
1372/**
1373 * Changes the size of font cache of the given evas.
1374 *
1375 * @param e The given evas to flush font cache.
1376 * @return The size, in bytes.
1377 *
1378 * @ingroup Evas_Font_Group
1379 */
1380EAPI int evas_font_cache_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1381
1382/**
1383 * List of available font descriptions known or found by this evas.
1384 *
1385 * The list depends on Evas compile time configuration, such as
1386 * fontconfig support, and the paths provided at runtime as explained
1387 * in @ref Evas_Font_Path_Group.
1388 *
1389 * @param e The evas instance to query.
1390 * @return a newly allocated list of strings. Do not change the
1391 * strings. Be sure to call evas_font_available_list_free()
1392 * after you're done.
1393 *
1394 * @ingroup Evas_Font_Group
1395 */
1396EAPI Eina_List *evas_font_available_list(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1397
1398/**
1399 * Free list of font descriptions returned by evas_font_dir_available_list().
1400 *
1401 * @param e The evas instance that returned such list.
1402 * @param available the list returned by evas_font_dir_available_list().
1403 *
1404 * @ingroup Evas_Font_Group
1405 */
1406EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1);
1407
1408/**
1409 * @defgroup Evas_Font_Path_Group Font Path Functions
1410 *
1411 * Functions that edit the paths being used to load fonts.
1412 *
1413 * @ingroup Evas_Font_Group
1414 */
1415
1416/**
1417 * Removes all font paths loaded into memory for the given evas.
1418 * @param e The given evas.
1419 * @ingroup Evas_Font_Path_Group
1420 */
1421EAPI void evas_font_path_clear(Evas *e) EINA_ARG_NONNULL(1);
1422
1423/**
1424 * Appends a font path to the list of font paths used by the given evas.
1425 * @param e The given evas.
1426 * @param path The new font path.
1427 * @ingroup Evas_Font_Path_Group
1428 */
1429EAPI void evas_font_path_append(Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
1430
1431/**
1432 * Prepends a font path to the list of font paths used by the given evas.
1433 * @param e The given evas.
1434 * @param path The new font path.
1435 * @ingroup Evas_Font_Path_Group
1436 */
1437EAPI void evas_font_path_prepend(Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
1438
1439/**
1440 * Retrieves the list of font paths used by the given evas.
1441 * @param e The given evas.
1442 * @return The list of font paths used.
1443 * @ingroup Evas_Font_Path_Group
1444 */
1445EAPI const Eina_List *evas_font_path_list(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1446/**
1447 * @}
1448 */
1449
1450/**
1451 * @ingroup Evas_Object_Group_Basic
1452 *
1453 * @{
1454 */
1455
1456/**
1457 * Clip one object to another.
1458 *
1459 * @param obj The object to be clipped
1460 * @param clip The object to clip @p obj by
1461 *
1462 * This function will clip the object @p obj to the area occupied by
1463 * the object @p clip. This means the object @p obj will only be
1464 * visible within the area occupied by the clipping object (@p clip).
1465 *
1466 * The color of the object being clipped will be multiplied by the
1467 * color of the clipping one, so the resulting color for the former
1468 * will be <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color
1469 * element (red, green, blue and alpha).
1470 *
1471 * Clipping is recursive, so clipping objects may be clipped by
1472 * others, and their color will in term be multiplied. You may @b not
1473 * set up circular clipping lists (i.e. object 1 clips object 2, which
1474 * clips object 1): the behavior of Evas is undefined in this case.
1475 *
1476 * Objects which do not clip others are visible in the canvas as
1477 * normal; <b>those that clip one or more objects become invisible
1478 * themselves</b>, only affecting what they clip. If an object ceases
1479 * to have other objects being clipped by it, it will become visible
1480 * again.
1481 *
1482 * The visibility of an object affects the objects that are clipped by
1483 * it, so if the object clipping others is not shown (as in
1484 * evas_object_show()), the objects clipped by it will not be shown
1485 * either.
1486 *
1487 * If @p obj was being clipped by another object when this function is
1488 * called, it gets implicitly removed from the old clipper's domain
1489 * and is made now to be clipped by its new clipper.
1490 *
1491 * The following figure illustrates some clipping in Evas:
1492 *
1493 * @image html clipping.png
1494 * @image rtf clipping.png
1495 * @image latex clipping.eps
1496 *
1497 * @note At the moment the <b>only objects that can validly be used to
1498 * clip other objects are rectangle objects</b>. All other object
1499 * types are invalid and the result of using them is undefined. The
1500 * clip object @p clip must be a valid object, but can also be @c
1501 * NULL, in which case the effect of this function is the same as
1502 * calling evas_object_clip_unset() on the @p obj object.
1503 *
1504 * Example:
1505 * @dontinclude evas-object-manipulation.c
1506 * @skip solid white clipper (note that it's the default color for a
1507 * @until evas_object_show(d.clipper);
1508 *
1509 * See the full @ref Example_Evas_Object_Manipulation "example".
1510 */
1511EAPI void evas_object_clip_set(Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2);
1512
1513/**
1514 * Get the object clipping @p obj (if any).
1515 *
1516 * @param obj The object to get the clipper from
1517 *
1518 * This function returns the object clipping @p obj. If @p obj is
1519 * not being clipped at all, @c NULL is returned. The object @p obj
1520 * must be a valid ::Evas_Object.
1521 *
1522 * See also evas_object_clip_set(), evas_object_clip_unset() and
1523 * evas_object_clipees_get().
1524 *
1525 * Example:
1526 * @dontinclude evas-object-manipulation.c
1527 * @skip if (evas_object_clip_get(d.img) == d.clipper)
1528 * @until return
1529 *
1530 * See the full @ref Example_Evas_Object_Manipulation "example".
1531 */
1532EAPI Evas_Object *evas_object_clip_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1533
1534/**
1535 * Disable/cease clipping on a clipped @p obj object.
1536 *
1537 * @param obj The object to cease clipping on
1538 *
1539 * This function disables clipping for the object @p obj, if it was
1540 * already clipped, i.e., its visibility and color get detached from
1541 * the previous clipper. If it wasn't, this has no effect. The object
1542 * @p obj must be a valid ::Evas_Object.
1543 *
1544 * See also evas_object_clip_set() (for an example),
1545 * evas_object_clipees_get() and evas_object_clip_get().
1546 *
1547 */
1548EAPI void evas_object_clip_unset(Evas_Object *obj);
1549
1550/**
1551 * Return a list of objects currently clipped by @p obj.
1552 *
1553 * @param obj The object to get a list of clippees from
1554 * @return a list of objects being clipped by @p obj
1555 *
1556 * This returns the internal list handle that contains all objects
1557 * clipped by the object @p obj. If none are clipped by it, the call
1558 * returns @c NULL. This list is only valid until the clip list is
1559 * changed and should be fetched again with another call to
1560 * evas_object_clipees_get() if any objects being clipped by this
1561 * object are unclipped, clipped by a new object, deleted or get the
1562 * clipper deleted. These operations will invalidate the list
1563 * returned, so it should not be used anymore after that point. Any
1564 * use of the list after this may have undefined results, possibly
1565 * leading to crashes. The object @p obj must be a valid
1566 * ::Evas_Object.
1567 *
1568 * See also evas_object_clip_set(), evas_object_clip_unset() and
1569 * evas_object_clip_get().
1570 *
1571 * Example:
1572 * @code
1573 * extern Evas_Object *obj;
1574 * Evas_Object *clipper;
1575 *
1576 * clipper = evas_object_clip_get(obj);
1577 * if (clipper)
1578 * {
1579 * Eina_List *clippees, *l;
1580 * Evas_Object *obj_tmp;
1581 *
1582 * clippees = evas_object_clipees_get(clipper);
1583 * printf("Clipper clips %i objects\n", eina_list_count(clippees));
1584 * EINA_LIST_FOREACH(clippees, l, obj_tmp)
1585 * evas_object_show(obj_tmp);
1586 * }
1587 * @endcode
1588 */
1589EAPI const Eina_List *evas_object_clipees_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1590
1591/**
1592 * Test if any object is clipped by @p obj.
1593 *
1594 * @param obj The object to get a list of clippees from
1595 * @return EINA_TRUE if @p obj clip any object.
1596 * @since 1.8
1597 */
1598EAPI Eina_Bool evas_object_clipees_has(const Evas_Object *eo_obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1599
1600/**
1601 * Sets or unsets a given object as the currently focused one on its
1602 * canvas.
1603 *
1604 * @param obj The object to be focused or unfocused.
1605 * @param focus @c EINA_TRUE, to set it as focused or @c EINA_FALSE,
1606 * to take away the focus from it.
1607 *
1608 * Changing focus only affects where (key) input events go. There can
1609 * be only one object focused at any time. If @p focus is @c EINA_TRUE,
1610 * @p obj will be set as the currently focused object and it will
1611 * receive all keyboard events that are not exclusive key grabs on
1612 * other objects.
1613 *
1614 * Example:
1615 * @dontinclude evas-events.c
1616 * @skip evas_object_focus_set
1617 * @until evas_object_focus_set
1618 *
1619 * See the full example @ref Example_Evas_Events "here".
1620 *
1621 * @see evas_object_focus_get
1622 * @see evas_focus_get
1623 * @see evas_object_key_grab
1624 * @see evas_object_key_ungrab
1625 */
1626EAPI void evas_object_focus_set(Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
1627
1628/**
1629 * Retrieve whether an object has the focus.
1630 *
1631 * @param obj The object to retrieve focus information from.
1632 * @return @c EINA_TRUE if the object has the focus, @c EINA_FALSE otherwise.
1633 *
1634 * If the passed object is the currently focused one, @c EINA_TRUE is
1635 * returned. @c EINA_FALSE is returned, otherwise.
1636 *
1637 * Example:
1638 * @dontinclude evas-events.c
1639 * @skip And again
1640 * @until something is bad
1641 *
1642 * See the full example @ref Example_Evas_Events "here".
1643 *
1644 * @see evas_object_focus_set
1645 * @see evas_focus_get
1646 * @see evas_object_key_grab
1647 * @see evas_object_key_ungrab
1648 */
1649EAPI Eina_Bool evas_object_focus_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1650
1651/**
1652 * Sets the layer of its canvas that the given object will be part of.
1653 *
1654 * @param obj The given Evas object.
1655 * @param l The number of the layer to place the object on.
1656 * Must be between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
1657 *
1658 * If you don't use this function, you'll be dealing with an @b unique
1659 * layer of objects, the default one. Additional layers are handy when
1660 * you don't want a set of objects to interfere with another set with
1661 * regard to @b stacking. Two layers are completely disjoint in that
1662 * matter.
1663 *
1664 * This is a low-level function, which you'd be using when something
1665 * should be always on top, for example.
1666 *
1667 * @warning Be careful, it doesn't make sense to change the layer of
1668 * smart objects' children. Smart objects have a layer of their own,
1669 * which should contain all their children objects.
1670 *
1671 * @see evas_object_layer_get()
1672 */
1673EAPI void evas_object_layer_set(Evas_Object *obj, short l) EINA_ARG_NONNULL(1);
1674
1675/**
1676 * Retrieves the layer of its canvas that the given object is part of.
1677 *
1678 * @param obj The given Evas object to query layer from
1679 * @return Number of its layer
1680 *
1681 * @see evas_object_layer_set()
1682 */
1683EAPI short evas_object_layer_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1684
1685/**
1686 * Sets the name of the given Evas object to the given name.
1687 *
1688 * @param obj The given object.
1689 * @param name The given name.
1690 *
1691 * There might be occasions where one would like to name his/her
1692 * objects.
1693 *
1694 * Example:
1695 * @dontinclude evas-events.c
1696 * @skip d.bg = evas_object_rectangle_add(d.canvas);
1697 * @until evas_object_name_set(d.bg, "our dear rectangle");
1698 *
1699 * See the full @ref Example_Evas_Events "example".
1700 */
1701EAPI void evas_object_name_set(Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
1702
1703/**
1704 * Retrieves the name of the given Evas object.
1705 *
1706 * @param obj The given object.
1707 * @return The name of the object or @c NULL, if no name has been given
1708 * to it.
1709 *
1710 * Example:
1711 * @dontinclude evas-events.c
1712 * @skip fprintf(stdout, "An object got focused: %s\n",
1713 * @until evas_focus_get
1714 *
1715 * See the full @ref Example_Evas_Events "example".
1716 */
1717EAPI const char *evas_object_name_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1718
1719/**
1720 * Increments object reference count to defer its deletion.
1721 *
1722 * @param obj The given Evas object to reference
1723 *
1724 * This increments the reference count of an object, which if greater
1725 * than 0 will defer deletion by evas_object_del() until all
1726 * references are released back (counter back to 0). References cannot
1727 * go below 0 and unreferencing past that will result in the reference
1728 * count being limited to 0. References are limited to <c>2^32 - 1</c>
1729 * for an object. Referencing it more than this will result in it
1730 * being limited to this value.
1731 *
1732 * @see evas_object_unref()
1733 * @see evas_object_del()
1734 *
1735 * @note This is a <b>very simple</b> reference counting mechanism! For
1736 * instance, Evas is not ready to check for pending references on a
1737 * canvas deletion, or things like that. This is useful on scenarios
1738 * where, inside a code block, callbacks exist which would possibly
1739 * delete an object we are operating on afterwards. Then, one would
1740 * evas_object_ref() it on the beginning of the block and
1741 * evas_object_unref() it on the end. It would then be deleted at this
1742 * point, if it should be.
1743 *
1744 * Example:
1745 * @code
1746 * evas_object_ref(obj);
1747 *
1748 * // action here...
1749 * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
1750 * // more action here...
1751 * evas_object_unref(obj);
1752 * @endcode
1753 *
1754 * @ingroup Evas_Object_Group_Basic
1755 * @since 1.1
1756 */
1757EAPI void evas_object_ref(Evas_Object *obj);
1758
1759/**
1760 * Decrements object reference count.
1761 *
1762 * @param obj The given Evas object to unreference
1763 *
1764 * This decrements the reference count of an object. If the object has
1765 * had evas_object_del() called on it while references were more than
1766 * 0, it will be deleted at the time this function is called and puts
1767 * the counter back to 0. See evas_object_ref() for more information.
1768 *
1769 * @see evas_object_ref() (for an example)
1770 * @see evas_object_del()
1771 *
1772 * @ingroup Evas_Object_Group_Basic
1773 * @since 1.1
1774 */
1775EAPI void evas_object_unref(Evas_Object *obj);
1776
1777/**
1778 * Get the object reference count.
1779 *
1780 * @param obj The given Evas object to query
1781 *
1782 * This gets the reference count for an object (normally 0 until it is
1783 * referenced). Values of 1 or greater mean that someone is holding a
1784 * reference to this object that needs to be unreffed before it can be
1785 * deleted.
1786 *
1787 * @see evas_object_ref()
1788 * @see evas_object_unref()
1789 * @see evas_object_del()
1790 *
1791 * @ingroup Evas_Object_Group_Basic
1792 * @since 1.2
1793 */
1794EAPI int evas_object_ref_get(const Evas_Object *obj);
1795
1796/**
1797 * Marks the given Evas object for deletion (when Evas will free its
1798 * memory).
1799 *
1800 * @param obj The given Evas object.
1801 *
1802 * This call will mark @p obj for deletion, which will take place
1803 * whenever it has no more references to it (see evas_object_ref() and
1804 * evas_object_unref()).
1805 *
1806 * At actual deletion time, which may or may not be just after this
1807 * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks will
1808 * be called. If the object currently had the focus, its
1809 * ::EVAS_CALLBACK_FOCUS_OUT callback will also be called.
1810 *
1811 * @see evas_object_ref()
1812 * @see evas_object_unref()
1813 *
1814 * @ingroup Evas_Object_Group_Basic
1815 */
1816EAPI void evas_object_del(Evas_Object *obj) EINA_ARG_NONNULL(1);
1817
1818/**
1819 * Move the given Evas object to the given location inside its
1820 * canvas' viewport.
1821 *
1822 * @param obj The given Evas object.
1823 * @param x X position to move the object to, in canvas units.
1824 * @param y Y position to move the object to, in canvas units.
1825 *
1826 * Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback
1827 * will be called.
1828 *
1829 * @note Naturally, newly created objects are placed at the canvas'
1830 * origin: <code>0, 0</code>.
1831 *
1832 * Example:
1833 * @dontinclude evas-object-manipulation.c
1834 * @skip evas_object_image_border_set(d.clipper_border, 3, 3, 3, 3);
1835 * @until evas_object_show
1836 *
1837 * See the full @ref Example_Evas_Object_Manipulation "example".
1838 *
1839 * @ingroup Evas_Object_Group_Basic
1840 */
1841EAPI void evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
1842
1843/**
1844 * Changes the size of the given Evas object.
1845 *
1846 * @param obj The given Evas object.
1847 * @param w The new width of the Evas object.
1848 * @param h The new height of the Evas object.
1849 *
1850 * Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback
1851 * will be called.
1852 *
1853 * @note Newly created objects have zeroed dimensions. Then, you most
1854 * probably want to use evas_object_resize() on them after they are
1855 * created.
1856 *
1857 * @note Be aware that resizing an object changes its drawing area,
1858 * but that does imply the object is rescaled! For instance, images
1859 * are filled inside their drawing area using the specifications of
1860 * evas_object_image_fill_set(). Thus to scale the image to match
1861 * exactly your drawing area, you need to change the
1862 * evas_object_image_fill_set() as well.
1863 *
1864 * @note This is more evident in images, but text, textblock, lines
1865 * and polygons will behave similarly. Check their specific APIs to
1866 * know how to achieve your desired behavior. Consider the following
1867 * example:
1868 *
1869 * @code
1870 * // rescale image to fill exactly its area without tiling:
1871 * evas_object_resize(img, w, h);
1872 * evas_object_image_fill_set(img, 0, 0, w, h);
1873 * @endcode
1874 *
1875 * @ingroup Evas_Object_Group_Basic
1876 */
1877EAPI void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
1878
1879/**
1880 * Retrieves the position and (rectangular) size of the given Evas
1881 * object.
1882 *
1883 * @param obj The given Evas object.
1884 * @param x Pointer to an integer in which to store the X coordinate
1885 * of the object.
1886 * @param y Pointer to an integer in which to store the Y coordinate
1887 * of the object.
1888 * @param w Pointer to an integer in which to store the width of the
1889 * object.
1890 * @param h Pointer to an integer in which to store the height of the
1891 * object.
1892 *
1893 * The position, naturally, will be relative to the top left corner of
1894 * the canvas' viewport.
1895 *
1896 * @note Use @c NULL pointers on the geometry components you're not
1897 * interested in: they'll be ignored by the function.
1898 *
1899 * Example:
1900 * @dontinclude evas-events.c
1901 * @skip int w, h, cw, ch;
1902 * @until return
1903 *
1904 * See the full @ref Example_Evas_Events "example".
1905 *
1906 * @ingroup Evas_Object_Group_Basic
1907 */
1908EAPI void evas_object_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
1909
1910/**
1911 * Makes the given Evas object visible.
1912 *
1913 * @param obj The given Evas object.
1914 *
1915 * Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW
1916 * callback will be called.
1917 *
1918 * @see evas_object_hide() for more on object visibility.
1919 * @see evas_object_visible_get()
1920 *
1921 * @ingroup Evas_Object_Group_Basic
1922 */
1923EAPI void evas_object_show(Evas_Object *obj) EINA_ARG_NONNULL(1);
1924
1925/**
1926 * Makes the given Evas object invisible.
1927 *
1928 * @param obj The given Evas object.
1929 *
1930 * Hidden objects, besides not being shown at all in your canvas,
1931 * won't be checked for changes on the canvas rendering
1932 * process. Furthermore, they will not catch input events. Thus, they
1933 * are much ligher (in processing needs) than an object that is
1934 * invisible due to indirect causes, such as being clipped or out of
1935 * the canvas' viewport.
1936 *
1937 * Besides becoming hidden, @p obj object's ::EVAS_CALLBACK_SHOW
1938 * callback will be called.
1939 *
1940 * @note All objects are created in the hidden state! If you want them
1941 * shown, use evas_object_show() after their creation.
1942 *
1943 * @see evas_object_show()
1944 * @see evas_object_visible_get()
1945 *
1946 * Example:
1947 * @dontinclude evas-object-manipulation.c
1948 * @skip if (evas_object_visible_get(d.clipper))
1949 * @until return
1950 *
1951 * See the full @ref Example_Evas_Object_Manipulation "example".
1952 *
1953 * @ingroup Evas_Object_Group_Basic
1954 */
1955EAPI void evas_object_hide(Evas_Object *obj) EINA_ARG_NONNULL(1);
1956
1957/**
1958 * Retrieves whether or not the given Evas object is visible.
1959 *
1960 * @param obj The given Evas object.
1961 * @return @c EINA_TRUE if the object is visible, @c EINA_FALSE
1962 * otherwise.
1963 *
1964 * This retrieves an object's visibility as the one enforced by
1965 * evas_object_show() and evas_object_hide().
1966 *
1967 * @note The value returned isn't, by any means, influenced by
1968 * clippers covering @p obj, it being out of its canvas' viewport or
1969 * stacked below other object.
1970 *
1971 * @see evas_object_show()
1972 * @see evas_object_hide() (for an example)
1973 *
1974 * @ingroup Evas_Object_Group_Basic
1975 */
1976EAPI Eina_Bool evas_object_visible_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1977
1978/**
1979 * Sets the general/main color of the given Evas object to the given
1980 * one.
1981 *
1982 * @param obj The given Evas object.
1983 * @param r The red component of the given color.
1984 * @param g The green component of the given color.
1985 * @param b The blue component of the given color.
1986 * @param a The alpha component of the given color.
1987 *
1988 * @see evas_object_color_get() (for an example)
1989 * @note These color values are expected to be premultiplied by @p a.
1990 *
1991 * @ingroup Evas_Object_Group_Basic
1992 */
1993EAPI void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
1994
1995/**
1996 * Retrieves the general/main color of the given Evas object.
1997 *
1998 * @param obj The given Evas object to retrieve color from.
1999 * @param r Pointer to an integer in which to store the red component
2000 * of the color.
2001 * @param g Pointer to an integer in which to store the green
2002 * component of the color.
2003 * @param b Pointer to an integer in which to store the blue component
2004 * of the color.
2005 * @param a Pointer to an integer in which to store the alpha
2006 * component of the color.
2007 *
2008 * Retrieves the “main” color's RGB component (and alpha channel)
2009 * values, <b>which range from 0 to 255</b>. For the alpha channel,
2010 * which defines the object's transparency level, 0 means totally
2011 * transparent, while 255 means opaque. These color values are
2012 * premultiplied by the alpha value.
2013 *
2014 * Usually you’ll use this attribute for text and rectangle objects,
2015 * where the “main” color is their unique one. If set for objects
2016 * which themselves have colors, like the images one, those colors get
2017 * modulated by this one.
2018 *
2019 * @note All newly created Evas rectangles get the default color
2020 * values of <code>255 255 255 255</code> (opaque white).
2021 *
2022 * @note Use @c NULL pointers on the components you're not interested
2023 * in: they'll be ignored by the function.
2024 *
2025 * Example:
2026 * @dontinclude evas-object-manipulation.c
2027 * @skip int alpha, r, g, b;
2028 * @until return
2029 *
2030 * See the full @ref Example_Evas_Object_Manipulation "example".
2031 *
2032 * @ingroup Evas_Object_Group_Basic
2033 */
2034EAPI void evas_object_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
2035
2036/**
2037 * Retrieves the Evas canvas that the given object lives on.
2038 *
2039 * @param obj The given Evas object.
2040 * @return A pointer to the canvas where the object is on.
2041 *
2042 * This function is most useful at code contexts where you need to
2043 * operate on the canvas but have only the object pointer.
2044 *
2045 * @ingroup Evas_Object_Group_Basic
2046 */
2047EAPI Evas *evas_object_evas_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2048
2049/**
2050 * Retrieves the type of the given Evas object.
2051 *
2052 * @param obj The given object.
2053 * @return The type of the object.
2054 *
2055 * For Evas' builtin types, the return strings will be one of:
2056 * - <c>"rectangle"</c>,
2057 * - <c>"line"</c>,
2058 * - <c>"polygon"</c>,
2059 * - <c>"text"</c>,
2060 * - <c>"textblock"</c> and
2061 * - <c>"image"</c>.
2062 *
2063 * For Evas smart objects (see @ref Evas_Smart_Group), the name of the
2064 * smart class itself is returned on this call. For the built-in smart
2065 * objects, these names are:
2066 * - <c>"EvasObjectSmartClipped"</c>, for the clipped smart object
2067 * - <c>"Evas_Object_Box"</c>, for the box object and
2068 * - <c>"Evas_Object_Table"</c>, for the table object.
2069 *
2070 * Example:
2071 * @dontinclude evas-object-manipulation.c
2072 * @skip d.img = evas_object_image_filled_add(d.canvas);
2073 * @until border on the
2074 *
2075 * See the full @ref Example_Evas_Object_Manipulation "example".
2076 */
2077EAPI const char *evas_object_type_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2078
2079/**
2080 * Raise @p obj to the top of its layer.
2081 *
2082 * @param obj the object to raise
2083 *
2084 * @p obj will, then, be the highest one in the layer it belongs
2085 * to. Object on other layers won't get touched.
2086 *
2087 * @see evas_object_stack_above()
2088 * @see evas_object_stack_below()
2089 * @see evas_object_lower()
2090 */
2091EAPI void evas_object_raise(Evas_Object *obj) EINA_ARG_NONNULL(1);
2092
2093/**
2094 * Lower @p obj to the bottom of its layer.
2095 *
2096 * @param obj the object to lower
2097 *
2098 * @p obj will, then, be the lowest one in the layer it belongs
2099 * to. Objects on other layers won't get touched.
2100 *
2101 * @see evas_object_stack_above()
2102 * @see evas_object_stack_below()
2103 * @see evas_object_raise()
2104 */
2105EAPI void evas_object_lower(Evas_Object *obj) EINA_ARG_NONNULL(1);
2106
2107/**
2108 * Stack @p obj immediately above @p above
2109 *
2110 * @param obj the object to stack
2111 * @param above the object above which to stack
2112 *
2113 * Objects, in a given canvas, are stacked in the order they get added
2114 * to it. This means that, if they overlap, the highest ones will
2115 * cover the lowest ones, in that order. This function is a way to
2116 * change the stacking order for the objects.
2117 *
2118 * This function is intended to be used with <b>objects belonging to
2119 * the same layer</b> in a given canvas, otherwise it will fail (and
2120 * accomplish nothing).
2121 *
2122 * If you have smart objects on your canvas and @p obj is a member of
2123 * one of them, then @p above must also be a member of the same
2124 * smart object.
2125 *
2126 * Similarly, if @p obj is not a member of a smart object, @p above
2127 * must not be either.
2128 *
2129 * @see evas_object_layer_get()
2130 * @see evas_object_layer_set()
2131 * @see evas_object_stack_below()
2132 */
2133EAPI void evas_object_stack_above(Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2);
2134
2135/**
2136 * Stack @p obj immediately below @p below
2137 *
2138 * @param obj the object to stack
2139 * @param below the object below which to stack
2140 *
2141 * Objects, in a given canvas, are stacked in the order they get added
2142 * to it. This means that, if they overlap, the highest ones will
2143 * cover the lowest ones, in that order. This function is a way to
2144 * change the stacking order for the objects.
2145 *
2146 * This function is intended to be used with <b>objects belonging to
2147 * the same layer</b> in a given canvas, otherwise it will fail (and
2148 * accomplish nothing).
2149 *
2150 * If you have smart objects on your canvas and @p obj is a member of
2151 * one of them, then @p below must also be a member of the same
2152 * smart object.
2153 *
2154 * Similarly, if @p obj is not a member of a smart object, @p below
2155 * must not be either.
2156 *
2157 * @see evas_object_layer_get()
2158 * @see evas_object_layer_set()
2159 * @see evas_object_stack_below()
2160 */
2161EAPI void evas_object_stack_below(Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2);
2162
2163/**
2164 * Get the Evas object stacked right above @p obj
2165 *
2166 * @param obj an #Evas_Object
2167 * @return the #Evas_Object directly above @p obj, if any, or @c NULL,
2168 * if none
2169 *
2170 * This function will traverse layers in its search, if there are
2171 * objects on layers above the one @p obj is placed at.
2172 *
2173 * @see evas_object_layer_get()
2174 * @see evas_object_layer_set()
2175 * @see evas_object_below_get()
2176 *
2177 */
2178EAPI Evas_Object *evas_object_above_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2179
2180/**
2181 * Get the Evas object stacked right below @p obj
2182 *
2183 * @param obj an #Evas_Object
2184 * @return the #Evas_Object directly below @p obj, if any, or @c NULL,
2185 * if none
2186 *
2187 * This function will traverse layers in its search, if there are
2188 * objects on layers below the one @p obj is placed at.
2189 *
2190 * @see evas_object_layer_get()
2191 * @see evas_object_layer_set()
2192 * @see evas_object_below_get()
2193 */
2194EAPI Evas_Object *evas_object_below_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2195/**
2196 * @}
2197 */
2198
2199/**
2200 * @ingroup Evas_Object_Group_Events
2201 *
2202 * @{
2203 */
2204
2205/**
2206 * Add (register) a callback function to a given Evas object event.
2207 *
2208 * @param obj Object to attach a callback to
2209 * @param type The type of event that will trigger the callback
2210 * @param func The function to be called when the event is triggered
2211 * @param data The data pointer to be passed to @p func
2212 *
2213 * This function adds a function callback to an object when the event
2214 * of type @p type occurs on object @p obj. The function is @p func.
2215 *
2216 * In the event of a memory allocation error during addition of the
2217 * callback to the object, evas_alloc_error() should be used to
2218 * determine the nature of the error, if any, and the program should
2219 * sensibly try and recover.
2220 *
2221 * A callback function must have the ::Evas_Object_Event_Cb prototype
2222 * definition. The first parameter (@p data) in this definition will
2223 * have the same value passed to evas_object_event_callback_add() as
2224 * the @p data parameter, at runtime. The second parameter @p e is the
2225 * canvas pointer on which the event occurred. The third parameter is
2226 * a pointer to the object on which event occurred. Finally, the
2227 * fourth parameter @p event_info is a pointer to a data structure
2228 * that may or may not be passed to the callback, depending on the
2229 * event type that triggered the callback. This is so because some
2230 * events don't carry extra context with them, but others do.
2231 *
2232 * The event type @p type to trigger the function may be one of
2233 * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT,
2234 * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP,
2235 * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL,
2236 * #EVAS_CALLBACK_MULTI_DOWN, #EVAS_CALLBACK_MULTI_UP,
2237 * #EVAS_CALLBACK_MULTI_MOVE, #EVAS_CALLBACK_FREE,
2238 * #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP,
2239 * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT,
2240 * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE,
2241 * #EVAS_CALLBACK_RESIZE, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL,
2242 * #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS,
2243 * #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED.
2244 *
2245 * This determines the kind of event that will trigger the callback.
2246 * What follows is a list explaining better the nature of each type of
2247 * event, along with their associated @p event_info pointers:
2248 *
2249 * - #EVAS_CALLBACK_MOUSE_IN: @p event_info is a pointer to an
2250 * #Evas_Event_Mouse_In struct\n\n
2251 * This event is triggered when the mouse pointer enters the area
2252 * (not shaded by other objects) of the object @p obj. This may
2253 * occur by the mouse pointer being moved by
2254 * evas_event_feed_mouse_move() calls, or by the object being shown,
2255 * raised, moved, resized, or other objects being moved out of the
2256 * way, hidden or lowered, whatever may cause the mouse pointer to
2257 * get on top of @p obj, having been on top of another object
2258 * previously.
2259 *
2260 * - #EVAS_CALLBACK_MOUSE_OUT: @p event_info is a pointer to an
2261 * #Evas_Event_Mouse_Out struct\n\n
2262 * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is,
2263 * but it occurs when the mouse pointer exits an object's area. Note
2264 * that no mouse out events will be reported if the mouse pointer is
2265 * implicitly grabbed to an object (mouse buttons are down, having
2266 * been pressed while the pointer was over that object). In these
2267 * cases, mouse out events will be reported once all buttons are
2268 * released, if the mouse pointer has left the object's area. The
2269 * indirect ways of taking off the mouse pointer from an object,
2270 * like cited above, for #EVAS_CALLBACK_MOUSE_IN, also apply here,
2271 * naturally.
2272 *
2273 * - #EVAS_CALLBACK_MOUSE_DOWN: @p event_info is a pointer to an
2274 * #Evas_Event_Mouse_Down struct\n\n
2275 * This event is triggered by a mouse button being pressed while the
2276 * mouse pointer is over an object. If the pointer mode for Evas is
2277 * #EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this
2278 * object to <b>passively grab the mouse</b> until all mouse buttons
2279 * have been released: all future mouse events will be reported to
2280 * only this object until no buttons are down. That includes mouse
2281 * move events, mouse in and mouse out events, and further button
2282 * presses. When all buttons are released, event propagation will
2283 * occur as normal (see #Evas_Object_Pointer_Mode).
2284 *
2285 * - #EVAS_CALLBACK_MOUSE_UP: @p event_info is a pointer to an
2286 * #Evas_Event_Mouse_Up struct\n\n
2287 * This event is triggered by a mouse button being released while
2288 * the mouse pointer is over an object's area (or when passively
2289 * grabbed to an object).
2290 *
2291 * - #EVAS_CALLBACK_MOUSE_MOVE: @p event_info is a pointer to an
2292 * #Evas_Event_Mouse_Move struct\n\n
2293 * This event is triggered by the mouse pointer being moved while
2294 * over an object's area (or while passively grabbed to an object).
2295 *
2296 * - #EVAS_CALLBACK_MOUSE_WHEEL: @p event_info is a pointer to an
2297 * #Evas_Event_Mouse_Wheel struct\n\n
2298 * This event is triggered by the mouse wheel being rolled while the
2299 * mouse pointer is over an object (or passively grabbed to an
2300 * object).
2301 *
2302 * - #EVAS_CALLBACK_MULTI_DOWN: @p event_info is a pointer to an
2303 * #Evas_Event_Multi_Down struct
2304 *
2305 * - #EVAS_CALLBACK_MULTI_UP: @p event_info is a pointer to an
2306 * #Evas_Event_Multi_Up struct
2307 *
2308 * - #EVAS_CALLBACK_MULTI_MOVE: @p event_info is a pointer to an
2309 * #Evas_Event_Multi_Move struct
2310 *
2311 * - #EVAS_CALLBACK_FREE: @p event_info is @c NULL \n\n
2312 * This event is triggered just before Evas is about to free all
2313 * memory used by an object and remove all references to it. This is
2314 * useful for programs to use if they attached data to an object and
2315 * want to free it when the object is deleted. The object is still
2316 * valid when this callback is called, but after it returns, there
2317 * is no guarantee on the object's validity.
2318 *
2319 * - #EVAS_CALLBACK_KEY_DOWN: @p event_info is a pointer to an
2320 * #Evas_Event_Key_Down struct\n\n
2321 * This callback is called when a key is pressed and the focus is on
2322 * the object, or a key has been grabbed to a particular object
2323 * which wants to intercept the key press regardless of what object
2324 * has the focus.
2325 *
2326 * - #EVAS_CALLBACK_KEY_UP: @p event_info is a pointer to an
2327 * #Evas_Event_Key_Up struct \n\n
2328 * This callback is called when a key is released and the focus is
2329 * on the object, or a key has been grabbed to a particular object
2330 * which wants to intercept the key release regardless of what
2331 * object has the focus.
2332 *
2333 * - #EVAS_CALLBACK_FOCUS_IN: @p event_info is @c NULL \n\n
2334 * This event is called when an object gains the focus. When it is
2335 * called the object has already gained the focus.
2336 *
2337 * - #EVAS_CALLBACK_FOCUS_OUT: @p event_info is @c NULL \n\n
2338 * This event is triggered when an object loses the focus. When it
2339 * is called the object has already lost the focus.
2340 *
2341 * - #EVAS_CALLBACK_SHOW: @p event_info is @c NULL \n\n
2342 * This event is triggered by the object being shown by
2343 * evas_object_show().
2344 *
2345 * - #EVAS_CALLBACK_HIDE: @p event_info is @c NULL \n\n
2346 * This event is triggered by an object being hidden by
2347 * evas_object_hide().
2348 *
2349 * - #EVAS_CALLBACK_MOVE: @p event_info is @c NULL \n\n
2350 * This event is triggered by an object being
2351 * moved. evas_object_move() can trigger this, as can any
2352 * object-specific manipulations that would mean the object's origin
2353 * could move.
2354 *
2355 * - #EVAS_CALLBACK_RESIZE: @p event_info is @c NULL \n\n
2356 * This event is triggered by an object being resized. Resizes can
2357 * be triggered by evas_object_resize() or by any object-specific
2358 * calls that may cause the object to resize.
2359 *
2360 * - #EVAS_CALLBACK_RESTACK: @p event_info is @c NULL \n\n
2361 * This event is triggered by an object being re-stacked. Stacking
2362 * changes can be triggered by
2363 * evas_object_stack_below()/evas_object_stack_above() and others.
2364 *
2365 * - #EVAS_CALLBACK_DEL: @p event_info is @c NULL.
2366 *
2367 * - #EVAS_CALLBACK_HOLD: @p event_info is a pointer to an
2368 * #Evas_Event_Hold struct
2369 *
2370 * - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @p event_info is @c NULL.
2371 *
2372 * - #EVAS_CALLBACK_IMAGE_PRELOADED: @p event_info is @c NULL.
2373 *
2374 * - #EVAS_CALLBACK_IMAGE_UNLOADED: @p event_info is @c NULL.
2375 *
2376 * @note Be careful not to add the same callback multiple times, if
2377 * that's not what you want, because Evas won't check if a callback
2378 * existed before exactly as the one being registered (and thus, call
2379 * it more than once on the event, in this case). This would make
2380 * sense if you passed different functions and/or callback data, only.
2381 *
2382 * Example:
2383 * @dontinclude evas-events.c
2384 * @skip evas_object_event_callback_add(
2385 * @until }
2386 *
2387 * See the full example @ref Example_Evas_Events "here".
2388 *
2389 */
2390EAPI void evas_object_event_callback_add(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2391
2392/**
2393 * Add (register) a callback function to a given Evas object event with a
2394 * non-default priority set. Except for the priority field, it's exactly the
2395 * same as @ref evas_object_event_callback_add
2396 *
2397 * @param obj Object to attach a callback to
2398 * @param type The type of event that will trigger the callback
2399 * @param priority The priority of the callback, lower values called first.
2400 * @param func The function to be called when the event is triggered
2401 * @param data The data pointer to be passed to @p func
2402 *
2403 * @see evas_object_event_callback_add
2404 * @since 1.1
2405 */
2406EAPI void evas_object_event_callback_priority_add(Evas_Object *obj, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 4);
2407
2408/**
2409 * Delete a callback function from an object
2410 *
2411 * @param obj Object to remove a callback from
2412 * @param type The type of event that was triggering the callback
2413 * @param func The function that was to be called when the event was triggered
2414 * @return The data pointer that was to be passed to the callback
2415 *
2416 * This function removes the most recently added callback from the
2417 * object @p obj which was triggered by the event type @p type and was
2418 * calling the function @p func when triggered. If the removal is
2419 * successful it will also return the data pointer that was passed to
2420 * evas_object_event_callback_add() when the callback was added to the
2421 * object. If not successful @c NULL will be returned.
2422 *
2423 * Example:
2424 * @code
2425 * extern Evas_Object *object;
2426 * void *my_data;
2427 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
2428 *
2429 * my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
2430 * @endcode
2431 */
2432EAPI void *evas_object_event_callback_del(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3);
2433
2434/**
2435 * Delete (unregister) a callback function registered to a given
2436 * Evas object event.
2437 *
2438 * @param obj Object to remove a callback from
2439 * @param type The type of event that was triggering the callback
2440 * @param func The function that was to be called when the event was
2441 * triggered
2442 * @param data The data pointer that was to be passed to the callback
2443 * @return The data pointer that was to be passed to the callback
2444 *
2445 * This function removes the most recently added callback from the
2446 * object @p obj, which was triggered by the event type @p type and was
2447 * calling the function @p func with data @p data, when triggered. If
2448 * the removal is successful it will also return the data pointer that
2449 * was passed to evas_object_event_callback_add() (that will be the
2450 * same as the parameter) when the callback was added to the
2451 * object. In errors, @c NULL will be returned.
2452 *
2453 * @note For deletion of Evas object events callbacks filtering by
2454 * just type and function pointer, user
2455 * evas_object_event_callback_del().
2456 *
2457 * Example:
2458 * @code
2459 * extern Evas_Object *object;
2460 * void *my_data;
2461 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
2462 *
2463 * my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
2464 * @endcode
2465 */
2466EAPI void *evas_object_event_callback_del_full(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2467
2468/**
2469 * Set whether an Evas object is to pass (ignore) events.
2470 *
2471 * @param obj the Evas object to operate on
2472 * @param pass whether @p obj is to pass events (@c EINA_TRUE) or not
2473 * (@c EINA_FALSE)
2474 *
2475 * If @p pass is @c EINA_TRUE, it will make events on @p obj to be @b
2476 * ignored. They will be triggered on the @b next lower object (that
2477 * is not set to pass events), instead (see evas_object_below_get()).
2478 *
2479 * If @p pass is @c EINA_FALSE, events will be processed on that
2480 * object as normal.
2481 *
2482 * @see evas_object_pass_events_get() for an example
2483 * @see evas_object_repeat_events_set()
2484 * @see evas_object_propagate_events_set()
2485 * @see evas_object_freeze_events_set()
2486 */
2487EAPI void evas_object_pass_events_set(Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1);
2488
2489/**
2490 * Determine whether an object is set to pass (ignore) events.
2491 *
2492 * @param obj the Evas object to get information from.
2493 * @return pass whether @p obj is set to pass events (@c EINA_TRUE) or not
2494 * (@c EINA_FALSE)
2495 *
2496 * Example:
2497 * @dontinclude evas-stacking.c
2498 * @skip if (strcmp(ev->keyname, "p") == 0)
2499 * @until }
2500 *
2501 * See the full @ref Example_Evas_Stacking "example".
2502 *
2503 * @see evas_object_pass_events_set()
2504 * @see evas_object_repeat_events_get()
2505 * @see evas_object_propagate_events_get()
2506 * @see evas_object_freeze_events_get()
2507 */
2508EAPI Eina_Bool evas_object_pass_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2509
2510/**
2511 * Set whether an Evas object is to repeat events.
2512 *
2513 * @param obj the Evas object to operate on
2514 * @param repeat whether @p obj is to repeat events (@c EINA_TRUE) or not
2515 * (@c EINA_FALSE)
2516 *
2517 * If @p repeat is @c EINA_TRUE, it will make events on @p obj to also
2518 * be repeated for the @b next lower object in the objects' stack (see
2519 * see evas_object_below_get()).
2520 *
2521 * If @p repeat is @c EINA_FALSE, events occurring on @p obj will be
2522 * processed only on it.
2523 *
2524 * Example:
2525 * @dontinclude evas-stacking.c
2526 * @skip if (strcmp(ev->keyname, "r") == 0)
2527 * @until }
2528 *
2529 * See the full @ref Example_Evas_Stacking "example".
2530 *
2531 * @see evas_object_repeat_events_get()
2532 * @see evas_object_pass_events_set()
2533 * @see evas_object_propagate_events_set()
2534 * @see evas_object_freeze_events_set()
2535 */
2536EAPI void evas_object_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
2537
2538/**
2539 * Determine whether an object is set to repeat events.
2540 *
2541 * @param obj the given Evas object pointer
2542 * @return whether @p obj is set to repeat events (@c EINA_TRUE)
2543 * or not (@c EINA_FALSE)
2544 *
2545 * @see evas_object_repeat_events_set() for an example
2546 * @see evas_object_pass_events_get()
2547 * @see evas_object_propagate_events_get()
2548 * @see evas_object_freeze_events_get()
2549 */
2550EAPI Eina_Bool evas_object_repeat_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2551
2552/**
2553 * Set whether events on a smart object's member should get propagated
2554 * up to its parent.
2555 *
2556 * @param obj the smart object's child to operate on
2557 * @param prop whether to propagate events (@c EINA_TRUE) or not
2558 * (@c EINA_FALSE)
2559 *
2560 * This function has @b no effect if @p obj is not a member of a smart
2561 * object.
2562 *
2563 * If @p prop is @c EINA_TRUE, events occurring on this object will be
2564 * propagated on to the smart object of which @p obj is a member. If
2565 * @p prop is @c EINA_FALSE, events occurring on this object will @b
2566 * not be propagated on to the smart object of which @p obj is a
2567 * member. The default value is @c EINA_TRUE.
2568 *
2569 * @see evas_object_propagate_events_get()
2570 * @see evas_object_repeat_events_set()
2571 * @see evas_object_pass_events_set()
2572 * @see evas_object_freeze_events_set()
2573 */
2574EAPI void evas_object_propagate_events_set(Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1);
2575
2576/**
2577 * Retrieve whether an Evas object is set to propagate events.
2578 *
2579 * @param obj the given Evas object pointer
2580 * @return whether @p obj is set to propagate events (@c EINA_TRUE)
2581 * or not (@c EINA_FALSE)
2582 *
2583 * @see evas_object_propagate_events_set()
2584 * @see evas_object_repeat_events_get()
2585 * @see evas_object_pass_events_get()
2586 * @see evas_object_freeze_events_get()
2587 */
2588EAPI Eina_Bool evas_object_propagate_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2589
2590/**
2591 * Set whether an Evas object is to freeze (discard) events.
2592 *
2593 * @param obj the Evas object to operate on
2594 * @param freeze pass whether @p obj is to freeze events (@c EINA_TRUE) or not
2595 * (@c EINA_FALSE)
2596 *
2597 * If @p freeze is @c EINA_TRUE, it will make events on @p obj to be @b
2598 * discarded. Unlike evas_object_pass_events_set(), events will not be
2599 * passed to @b next lower object. This API can be used for blocking
2600 * events while @p obj is on transiting.
2601 *
2602 * If @p freeze is @c EINA_FALSE, events will be processed on that
2603 * object as normal.
2604 *
2605 * @see evas_object_freeze_events_get()
2606 * @see evas_object_pass_events_set()
2607 * @see evas_object_repeat_events_set()
2608 * @see evas_object_propagate_events_set()
2609 * @since 1.1
2610 */
2611EAPI void evas_object_freeze_events_set(Evas_Object *obj, Eina_Bool freeze) EINA_ARG_NONNULL(1);
2612
2613/**
2614 * Determine whether an object is set to freeze (discard) events.
2615 *
2616 * @param obj the Evas object to get information from.
2617 * @return freeze whether @p obj is set to freeze events (@c EINA_TRUE) or
2618 * not (@c EINA_FALSE)
2619 *
2620 * @see evas_object_freeze_events_set()
2621 * @see evas_object_pass_events_get()
2622 * @see evas_object_repeat_events_get()
2623 * @see evas_object_propagate_events_get()
2624 * @since 1.1
2625 */
2626EAPI Eina_Bool evas_object_freeze_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2627/**
2628 * @}
2629 */
2630
2631/**
2632 * @ingroup Evas_Object_Group_Map
2633 *
2634 * @{
2635 */
2636
2637/**
2638 * Enable or disable the map that is set.
2639 *
2640 * Enable or disable the use of map for the object @p obj.
2641 * On enable, the object geometry will be saved, and the new geometry will
2642 * change (position and size) to reflect the map geometry set.
2643 *
2644 * If the object doesn't have a map set (with evas_object_map_set()), the
2645 * initial geometry will be undefined. It is advised to always set a map
2646 * to the object first, and then call this function to enable its use.
2647 *
2648 * @param obj object to enable the map on
2649 * @param enabled enabled state
2650 */
2651EAPI void evas_object_map_enable_set(Evas_Object *obj, Eina_Bool enabled);
2652
2653/**
2654 * Get the map enabled state
2655 *
2656 * This returns the currently enabled state of the map on the object indicated.
2657 * The default map enable state is off. You can enable and disable it with
2658 * evas_object_map_enable_set().
2659 *
2660 * @param obj object to get the map enabled state from
2661 * @return the map enabled state
2662 */
2663EAPI Eina_Bool evas_object_map_enable_get(const Evas_Object *obj);
2664
2665/**
2666 * Set current object transformation map.
2667 *
2668 * This sets the map on a given object. It is copied from the @p map pointer,
2669 * so there is no need to keep the @p map object if you don't need it anymore.
2670 *
2671 * A map is a set of 4 points which have canvas x, y coordinates per point,
2672 * with an optional z point value as a hint for perspective correction, if it
2673 * is available. As well each point has u and v coordinates. These are like
2674 * "texture coordinates" in OpenGL in that they define a point in the source
2675 * image that is mapped to that map vertex/point. The u corresponds to the x
2676 * coordinate of this mapped point and v, the y coordinate. Note that these
2677 * coordinates describe a bounding region to sample. If you have a 200x100
2678 * source image and want to display it at 200x100 with proper pixel
2679 * precision, then do:
2680 *
2681 * @code
2682 * Evas_Map *m = evas_map_new(4);
2683 * evas_map_point_coord_set(m, 0, 0, 0, 0);
2684 * evas_map_point_coord_set(m, 1, 200, 0, 0);
2685 * evas_map_point_coord_set(m, 2, 200, 100, 0);
2686 * evas_map_point_coord_set(m, 3, 0, 100, 0);
2687 * evas_map_point_image_uv_set(m, 0, 0, 0);
2688 * evas_map_point_image_uv_set(m, 1, 200, 0);
2689 * evas_map_point_image_uv_set(m, 2, 200, 100);
2690 * evas_map_point_image_uv_set(m, 3, 0, 100);
2691 * evas_object_map_set(obj, m);
2692 * evas_map_free(m);
2693 * @endcode
2694 *
2695 * Note that the map points a uv coordinates match the image geometry. If
2696 * the @p map parameter is NULL, the stored map will be freed and geometry
2697 * prior to enabling/setting a map will be restored.
2698 *
2699 * @param obj object to change transformation map
2700 * @param map new map to use
2701 *
2702 * @see evas_map_new()
2703 */
2704EAPI void evas_object_map_set(Evas_Object *obj, const Evas_Map *map);
2705
2706/**
2707 * Get current object transformation map.
2708 *
2709 * This returns the current internal map set on the indicated object. It is
2710 * intended for read-only access and is only valid as long as the object is
2711 * not deleted or the map on the object is not changed. If you wish to modify
2712 * the map and set it back do the following:
2713 *
2714 * @code
2715 * const Evas_Map *m = evas_object_map_get(obj);
2716 * Evas_Map *m2 = evas_map_dup(m);
2717 * evas_map_util_rotate(m2, 30.0, 0, 0);
2718 * evas_object_map_set(obj, m2);
2719 * evas_map_free(m2);
2720 * @endcode
2721 *
2722 * @param obj object to query transformation map.
2723 * @return map reference to map in use. This is an internal data structure, so
2724 * do not modify it.
2725 *
2726 * @see evas_object_map_set()
2727 */
2728EAPI const Evas_Map *evas_object_map_get(const Evas_Object *obj);
2729/**
2730 * @}
2731 */
2732
2733/**
2734 * @ingroup Evas_Object_Group_Size_Hints
2735 *
2736 * @{
2737 */
2738
2739/**
2740 * Retrieves the hints for an object's minimum size.
2741 *
2742 * @param obj The given Evas object to query hints from.
2743 * @param w Pointer to an integer in which to store the minimum width.
2744 * @param h Pointer to an integer in which to store the minimum height.
2745 *
2746 * These are hints on the minimim sizes @p obj should have. This is
2747 * not a size enforcement in any way, it's just a hint that should be
2748 * used whenever appropriate.
2749 *
2750 * @note Use @c NULL pointers on the hint components you're not
2751 * interested in: they'll be ignored by the function.
2752 *
2753 * @see evas_object_size_hint_min_set() for an example
2754 */
2755EAPI void evas_object_size_hint_min_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
2756
2757/**
2758 * Sets the hints for an object's minimum size.
2759 *
2760 * @param obj The given Evas object to query hints from.
2761 * @param w Integer to use as the minimum width hint.
2762 * @param h Integer to use as the minimum height hint.
2763 *
2764 * This is not a size enforcement in any way, it's just a hint that
2765 * should be used whenever appropriate.
2766 *
2767 * Values @c 0 will be treated as unset hint components, when queried
2768 * by managers.
2769 *
2770 * Example:
2771 * @dontinclude evas-hints.c
2772 * @skip evas_object_size_hint_min_set
2773 * @until return
2774 *
2775 * In this example the minimum size hints change the behavior of an
2776 * Evas box when layouting its children. See the full @ref
2777 * Example_Evas_Size_Hints "example".
2778 *
2779 * @see evas_object_size_hint_min_get()
2780 */
2781EAPI void evas_object_size_hint_min_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
2782
2783/**
2784 * Retrieves the hints for an object's maximum size.
2785 *
2786 * @param obj The given Evas object to query hints from.
2787 * @param w Pointer to an integer in which to store the maximum width.
2788 * @param h Pointer to an integer in which to store the maximum height.
2789 *
2790 * These are hints on the maximum sizes @p obj should have. This is
2791 * not a size enforcement in any way, it's just a hint that should be
2792 * used whenever appropriate.
2793 *
2794 * @note Use @c NULL pointers on the hint components you're not
2795 * interested in: they'll be ignored by the function.
2796 *
2797 * @see evas_object_size_hint_max_set()
2798 */
2799EAPI void evas_object_size_hint_max_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
2800
2801/**
2802 * Sets the hints for an object's maximum size.
2803 *
2804 * @param obj The given Evas object to query hints from.
2805 * @param w Integer to use as the maximum width hint.
2806 * @param h Integer to use as the maximum height hint.
2807 *
2808 * This is not a size enforcement in any way, it's just a hint that
2809 * should be used whenever appropriate.
2810 *
2811 * Values @c -1 will be treated as unset hint components, when queried
2812 * by managers.
2813 *
2814 * Example:
2815 * @dontinclude evas-hints.c
2816 * @skip evas_object_size_hint_max_set
2817 * @until return
2818 *
2819 * In this example the maximum size hints change the behavior of an
2820 * Evas box when layouting its children. See the full @ref
2821 * Example_Evas_Size_Hints "example".
2822 *
2823 * @see evas_object_size_hint_max_get()
2824 */
2825EAPI void evas_object_size_hint_max_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
2826
2827/**
2828 * Retrieves the hints for an object's display mode
2829 *
2830 * @param obj The given Evas object to query hints from.
2831 *
2832 * These are hints on the display mode @p obj. This is
2833 * not a size enforcement in any way, it's just a hint that can be
2834 * used whenever appropriate.
2835 * This mode can be used object's display mode like commpress or expand
2836 *
2837 * @see evas_object_size_hint_display_mode_set()
2838 */
2839EAPI Evas_Display_Mode evas_object_size_hint_display_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
2840
2841/**
2842 * Sets the hints for an object's disply mode
2843 *
2844 * @param obj The given Evas object to query hints from.
2845 * @param dispmode to use as the display mode hint.
2846 *
2847 * This is not a size enforcement in any way, it's just a hint that
2848 * can be used whenever appropriate.
2849 *
2850 * @see evas_object_size_hint_display_mode_get()
2851 */
2852EAPI void evas_object_size_hint_display_mode_set(Evas_Object *obj, Evas_Display_Mode dispmode) EINA_ARG_NONNULL(1);
2853
2854/**
2855 * Retrieves the hints for an object's optimum size.
2856 *
2857 * @param obj The given Evas object to query hints from.
2858 * @param w Pointer to an integer in which to store the requested width.
2859 * @param h Pointer to an integer in which to store the requested height.
2860 *
2861 * These are hints on the optimum sizes @p obj should have. This is
2862 * not a size enforcement in any way, it's just a hint that should be
2863 * used whenever appropriate.
2864 *
2865 * @note Use @c NULL pointers on the hint components you're not
2866 * interested in: they'll be ignored by the function.
2867 *
2868 * @see evas_object_size_hint_request_set()
2869 */
2870EAPI void evas_object_size_hint_request_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
2871
2872/**
2873 * Sets the hints for an object's optimum size.
2874 *
2875 * @param obj The given Evas object to query hints from.
2876 * @param w Integer to use as the preferred width hint.
2877 * @param h Integer to use as the preferred height hint.
2878 *
2879 * This is not a size enforcement in any way, it's just a hint that
2880 * should be used whenever appropriate.
2881 *
2882 * Values @c 0 will be treated as unset hint components, when queried
2883 * by managers.
2884 *
2885 * @see evas_object_size_hint_request_get()
2886 */
2887EAPI void evas_object_size_hint_request_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
2888
2889/**
2890 * Retrieves the hints for an object's aspect ratio.
2891 *
2892 * @param obj The given Evas object to query hints from.
2893 * @param aspect Returns the policy/type of aspect ratio applied to @p obj.
2894 * @param w Pointer to an integer in which to store the aspect's width
2895 * ratio term.
2896 * @param h Pointer to an integer in which to store the aspect's
2897 * height ratio term.
2898 *
2899 * The different aspect ratio policies are documented in the
2900 * #Evas_Aspect_Control type. A container respecting these size hints
2901 * would @b resize its children accordingly to those policies.
2902 *
2903 * For any policy, if any of the given aspect ratio terms are @c 0,
2904 * the object's container should ignore the aspect and scale @p obj to
2905 * occupy the whole available area. If they are both positive
2906 * integers, that proportion will be respected, under each scaling
2907 * policy.
2908 *
2909 * These images illustrate some of the #Evas_Aspect_Control policies:
2910 *
2911 * @image html any-policy.png
2912 * @image rtf any-policy.png
2913 * @image latex any-policy.eps
2914 *
2915 * @image html aspect-control-none-neither.png
2916 * @image rtf aspect-control-none-neither.png
2917 * @image latex aspect-control-none-neither.eps
2918 *
2919 * @image html aspect-control-both.png
2920 * @image rtf aspect-control-both.png
2921 * @image latex aspect-control-both.eps
2922 *
2923 * @image html aspect-control-horizontal.png
2924 * @image rtf aspect-control-horizontal.png
2925 * @image latex aspect-control-horizontal.eps
2926 *
2927 * This is not a size enforcement in any way, it's just a hint that
2928 * should be used whenever appropriate.
2929 *
2930 * @note Use @c NULL pointers on the hint components you're not
2931 * interested in: they'll be ignored by the function.
2932 *
2933 * Example:
2934 * @dontinclude evas-aspect-hints.c
2935 * @skip if (strcmp(ev->keyname, "c") == 0)
2936 * @until }
2937 *
2938 * See the full @ref Example_Evas_Aspect_Hints "example".
2939 *
2940 * @see evas_object_size_hint_aspect_set()
2941 */
2942EAPI void evas_object_size_hint_aspect_get(const Evas_Object *obj, Evas_Aspect_Control *aspect, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
2943
2944/**
2945 * Sets the hints for an object's aspect ratio.
2946 *
2947 * @param obj The given Evas object to query hints from.
2948 * @param aspect The policy/type of aspect ratio to apply to @p obj.
2949 * @param w Integer to use as aspect width ratio term.
2950 * @param h Integer to use as aspect height ratio term.
2951 *
2952 * This is not a size enforcement in any way, it's just a hint that should
2953 * be used whenever appropriate.
2954 *
2955 * If any of the given aspect ratio terms are @c 0,
2956 * the object's container will ignore the aspect and scale @p obj to
2957 * occupy the whole available area, for any given policy.
2958 *
2959 * @see evas_object_size_hint_aspect_get() for more information.
2960 */
2961EAPI void evas_object_size_hint_aspect_set(Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
2962
2963/**
2964 * Retrieves the hints for on object's alignment.
2965 *
2966 * @param obj The given Evas object to query hints from.
2967 * @param x Pointer to a double in which to store the horizontal
2968 * alignment hint.
2969 * @param y Pointer to a double in which to store the vertical
2970 * alignment hint.
2971 *
2972 * This is not a size enforcement in any way, it's just a hint that
2973 * should be used whenever appropriate.
2974 *
2975 * @note Use @c NULL pointers on the hint components you're not
2976 * interested in: they'll be ignored by the function.
2977 * @note If @c obj is invalid, then the hint components will be set with 0.5
2978 *
2979 * @see evas_object_size_hint_align_set() for more information
2980 */
2981EAPI void evas_object_size_hint_align_get(const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
2982
2983/**
2984 * Sets the hints for an object's alignment.
2985 *
2986 * @param obj The given Evas object to query hints from.
2987 * @param x Double, ranging from @c 0.0 to @c 1.0 or with the
2988 * special value #EVAS_HINT_FILL, to use as horizontal alignment hint.
2989 * @param y Double, ranging from @c 0.0 to @c 1.0 or with the
2990 * special value #EVAS_HINT_FILL, to use as vertical alignment hint.
2991 *
2992 * These are hints on how to align an object <b>inside the boundaries
2993 * of a container/manager</b>. Accepted values are in the @c 0.0 to @c
2994 * 1.0 range, with the special value #EVAS_HINT_FILL used to specify
2995 * "justify" or "fill" by some users. In this case, maximum size hints
2996 * should be enforced with higher priority, if they are set. Also, any
2997 * padding hint set on objects should add up to the alignment space on
2998 * the final scene composition.
2999 *
3000 * See documentation of possible users: in Evas, they are the @ref
3001 * Evas_Object_Box "box" and @ref Evas_Object_Table "table" smart
3002 * objects.
3003 *
3004 * For the horizontal component, @c 0.0 means to the left, @c 1.0
3005 * means to the right. Analogously, for the vertical component, @c 0.0
3006 * to the top, @c 1.0 means to the bottom.
3007 *
3008 * See the following figure:
3009 *
3010 * @image html alignment-hints.png
3011 * @image rtf alignment-hints.png
3012 * @image latex alignment-hints.eps
3013 *
3014 * This is not a size enforcement in any way, it's just a hint that
3015 * should be used whenever appropriate.
3016 *
3017 * @note Default alignment hint values are 0.5, for both axis.
3018 *
3019 * Example:
3020 * @dontinclude evas-hints.c
3021 * @skip evas_object_size_hint_align_set
3022 * @until return
3023 *
3024 * In this example the alignment hints change the behavior of an Evas
3025 * box when layouting its children. See the full @ref
3026 * Example_Evas_Size_Hints "example".
3027 *
3028 * @see evas_object_size_hint_align_get()
3029 * @see evas_object_size_hint_max_set()
3030 * @see evas_object_size_hint_padding_set()
3031 */
3032EAPI void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
3033
3034/**
3035 * Retrieves the hints for an object's weight.
3036 *
3037 * @param obj The given Evas object to query hints from.
3038 * @param x Pointer to a double in which to store the horizontal weight.
3039 * @param y Pointer to a double in which to store the vertical weight.
3040 *
3041 * Accepted values are zero or positive values. Some users might use
3042 * this hint as a boolean, but some might consider it as a @b
3043 * proportion, see documentation of possible users, which in Evas are
3044 * the @ref Evas_Object_Box "box" and @ref Evas_Object_Table "table"
3045 * smart objects.
3046 *
3047 * This is not a size enforcement in any way, it's just a hint that
3048 * should be used whenever appropriate.
3049 *
3050 * @note Use @c NULL pointers on the hint components you're not
3051 * interested in: they'll be ignored by the function.
3052 * @note If @c obj is invalid, then the hint components will be set with 0.0
3053 *
3054 * @see evas_object_size_hint_weight_set() for an example
3055 */
3056EAPI void evas_object_size_hint_weight_get(const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
3057
3058/**
3059 * Sets the hints for an object's weight.
3060 *
3061 * @param obj The given Evas object to query hints from.
3062 * @param x Nonnegative double value to use as horizontal weight hint.
3063 * @param y Nonnegative double value to use as vertical weight hint.
3064 *
3065 * This is not a size enforcement in any way, it's just a hint that
3066 * should be used whenever appropriate.
3067 *
3068 * This is a hint on how a container object should @b resize a given
3069 * child within its area. Containers may adhere to the simpler logic
3070 * of just expanding the child object's dimensions to fit its own (see
3071 * the #EVAS_HINT_EXPAND helper weight macro) or the complete one of
3072 * taking each child's weight hint as real @b weights to how much of
3073 * its size to allocate for them in each axis. A container is supposed
3074 * to, after @b normalizing the weights of its children (with weight
3075 * hints), distribute the space it has to layout them by those factors
3076 * -- most weighted children get larger in this process than the least
3077 * ones.
3078 *
3079 * Example:
3080 * @dontinclude evas-hints.c
3081 * @skip evas_object_size_hint_weight_set
3082 * @until return
3083 *
3084 * In this example the weight hints change the behavior of an Evas box
3085 * when layouting its children. See the full @ref
3086 * Example_Evas_Size_Hints "example".
3087 *
3088 * @note Default weight hint values are 0.0, for both axis.
3089 *
3090 * @see evas_object_size_hint_weight_get() for more information
3091 */
3092EAPI void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
3093
3094/**
3095 * Retrieves the hints for an object's padding space.
3096 *
3097 * @param obj The given Evas object to query hints from.
3098 * @param l Pointer to an integer in which to store left padding.
3099 * @param r Pointer to an integer in which to store right padding.
3100 * @param t Pointer to an integer in which to store top padding.
3101 * @param b Pointer to an integer in which to store bottom padding.
3102 *
3103 * Padding is extra space an object takes on each of its delimiting
3104 * rectangle sides, in canvas units. This space will be rendered
3105 * transparent, naturally, as in the following figure:
3106 *
3107 * @image html padding-hints.png
3108 * @image rtf padding-hints.png
3109 * @image latex padding-hints.eps
3110 *
3111 * This is not a size enforcement in any way, it's just a hint that
3112 * should be used whenever appropriate.
3113 *
3114 * @note Use @c NULL pointers on the hint components you're not
3115 * interested in: they'll be ignored by the function.
3116 *
3117 * Example:
3118 * @dontinclude evas-hints.c
3119 * @skip evas_object_size_hint_padding_set
3120 * @until return
3121 *
3122 * In this example the padding hints change the behavior of an Evas box
3123 * when layouting its children. See the full @ref
3124 * Example_Evas_Size_Hints "example".
3125 *
3126 * @see evas_object_size_hint_padding_set()
3127 */
3128EAPI void evas_object_size_hint_padding_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) EINA_ARG_NONNULL(1);
3129
3130/**
3131 * Sets the hints for an object's padding space.
3132 *
3133 * @param obj The given Evas object to query hints from.
3134 * @param l Integer to specify left padding.
3135 * @param r Integer to specify right padding.
3136 * @param t Integer to specify top padding.
3137 * @param b Integer to specify bottom padding.
3138 *
3139 * This is not a size enforcement in any way, it's just a hint that
3140 * should be used whenever appropriate.
3141 *
3142 * @see evas_object_size_hint_padding_get() for more information
3143 */
3144EAPI void evas_object_size_hint_padding_set(Evas_Object *obj, Evas_Coord l, Evas_Coord r, Evas_Coord t, Evas_Coord b) EINA_ARG_NONNULL(1);
3145/**
3146 * @}
3147 */
3148
3149/**
3150 * @ingroup Evas_Object_Group_Extras
3151 *
3152 * @{
3153 */
3154
3155/**
3156 * Set an attached data pointer to an object with a given string key.
3157 *
3158 * @param obj The object to attach the data pointer to
3159 * @param key The string key for the data to access it
3160 * @param data The pointer to the data to be attached
3161 *
3162 * This attaches the pointer @p data to the object @p obj, given the
3163 * access string @p key. This pointer will stay "hooked" to the object
3164 * until a new pointer with the same string key is attached with
3165 * evas_object_data_set() or it is deleted with
3166 * evas_object_data_del(). On deletion of the object @p obj, the
3167 * pointers will not be accessible from the object anymore.
3168 *
3169 * You can find the pointer attached under a string key using
3170 * evas_object_data_get(). It is the job of the calling application to
3171 * free any data pointed to by @p data when it is no longer required.
3172 *
3173 * If @p data is @c NULL, the old value stored at @p key will be
3174 * removed but no new value will be stored. This is synonymous with
3175 * calling evas_object_data_del() with @p obj and @p key.
3176 *
3177 * @note This function is very handy when you have data associated
3178 * specifically to an Evas object, being of use only when dealing with
3179 * it. Than you don't have the burden to a pointer to it elsewhere,
3180 * using this family of functions.
3181 *
3182 * Example:
3183 *
3184 * @code
3185 * int *my_data;
3186 * extern Evas_Object *obj;
3187 *
3188 * my_data = malloc(500);
3189 * evas_object_data_set(obj, "name_of_data", my_data);
3190 * printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data"));
3191 * @endcode
3192 */
3193EAPI void evas_object_data_set(Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2);
3194
3195/**
3196 * Return an attached data pointer on an Evas object by its given
3197 * string key.
3198 *
3199 * @param obj The object to which the data was attached
3200 * @param key The string key the data was stored under
3201 * @return The data pointer stored, or @c NULL if none was stored
3202 *
3203 * This function will return the data pointer attached to the object
3204 * @p obj, stored using the string key @p key. If the object is valid
3205 * and a data pointer was stored under the given key, that pointer
3206 * will be returned. If this is not the case, @c NULL will be
3207 * returned, signifying an invalid object or a non-existent key. It is
3208 * possible that a @c NULL pointer was stored given that key, but this
3209 * situation is non-sensical and thus can be considered an error as
3210 * well. @c NULL pointers are never stored as this is the return value
3211 * if an error occurs.
3212 *
3213 * Example:
3214 *
3215 * @code
3216 * int *my_data;
3217 * extern Evas_Object *obj;
3218 *
3219 * my_data = evas_object_data_get(obj, "name_of_my_data");
3220 * if (my_data) printf("Data stored was %p\n", my_data);
3221 * else printf("No data was stored on the object\n");
3222 * @endcode
3223 */
3224EAPI void *evas_object_data_get(const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
3225
3226/**
3227 * Delete an attached data pointer from an object.
3228 *
3229 * @param obj The object to delete the data pointer from
3230 * @param key The string key the data was stored under
3231 * @return The original data pointer stored at @p key on @p obj
3232 *
3233 * This will remove the stored data pointer from @p obj stored under
3234 * @p key and return this same pointer, if actually there was data
3235 * there, or @c NULL, if nothing was stored under that key.
3236 *
3237 * Example:
3238 *
3239 * @code
3240 * int *my_data;
3241 * extern Evas_Object *obj;
3242 *
3243 * my_data = evas_object_data_del(obj, "name_of_my_data");
3244 * @endcode
3245 */
3246EAPI void *evas_object_data_del(Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
3247
3248/**
3249 * Set pointer behavior.
3250 *
3251 * @param obj
3252 * @param setting desired behavior.
3253 *
3254 * This function has direct effect on event callbacks related to
3255 * mouse.
3256 *
3257 * If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse
3258 * is down at this object, events will be restricted to it as source,
3259 * mouse moves, for example, will be emitted even if outside this
3260 * object area.
3261 *
3262 * If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will
3263 * be emitted just when inside this object area.
3264 *
3265 * The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB.
3266 *
3267 * @ingroup Evas_Object_Group_Extras
3268 */
3269EAPI void evas_object_pointer_mode_set(Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1);
3270
3271/**
3272 * Determine how pointer will behave.
3273 * @param obj
3274 * @return pointer behavior.
3275 * @ingroup Evas_Object_Group_Extras
3276 */
3277EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3278
3279/**
3280 * Sets whether or not the given Evas object is to be drawn anti-aliased.
3281 *
3282 * @param obj The given Evas object.
3283 * @param antialias 1 if the object is to be anti_aliased, 0 otherwise.
3284 * @ingroup Evas_Object_Group_Extras
3285 */
3286EAPI void evas_object_anti_alias_set(Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1);
3287
3288/**
3289 * Retrieves whether or not the given Evas object is to be drawn anti_aliased.
3290 * @param obj The given Evas object.
3291 * @return @c 1 if the object is to be anti_aliased. @c 0 otherwise.
3292 * @ingroup Evas_Object_Group_Extras
3293 */
3294EAPI Eina_Bool evas_object_anti_alias_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3295
3296/**
3297 * Sets the scaling factor for an Evas object. Does not affect all
3298 * objects.
3299 *
3300 * @param obj The given Evas object.
3301 * @param scale The scaling factor. <c>1.0</c> means no scaling,
3302 * default size.
3303 *
3304 * This will multiply the object's dimension by the given factor, thus
3305 * altering its geometry (width and height). Useful when you want
3306 * scalable UI elements, possibly at run time.
3307 *
3308 * @note Only text and textblock objects have scaling change
3309 * handlers. Other objects won't change visually on this call.
3310 *
3311 * @see evas_object_scale_get()
3312 *
3313 * @ingroup Evas_Object_Group_Extras
3314 */
3315EAPI void evas_object_scale_set(Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
3316
3317/**
3318 * Retrieves the scaling factor for the given Evas object.
3319 *
3320 * @param obj The given Evas object.
3321 * @return The scaling factor.
3322 *
3323 * @ingroup Evas_Object_Group_Extras
3324 *
3325 * @see evas_object_scale_set()
3326 */
3327EAPI double evas_object_scale_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3328
3329/**
3330 * Sets the render_op to be used for rendering the Evas object.
3331 * @param obj The given Evas object.
3332 * @param op one of the Evas_Render_Op values.
3333 * @ingroup Evas_Object_Group_Extras
3334 */
3335EAPI void evas_object_render_op_set(Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1);
3336
3337/**
3338 * Retrieves the current value of the operation used for rendering the Evas object.
3339 * @param obj The given Evas object.
3340 * @return one of the enumerated values in Evas_Render_Op.
3341 * @ingroup Evas_Object_Group_Extras
3342 */
3343EAPI Evas_Render_Op evas_object_render_op_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3344
3345/**
3346 * Set whether to use precise (usually expensive) point collision
3347 * detection for a given Evas object.
3348 *
3349 * @param obj The given object.
3350 * @param precise Whether to use precise point collision detection or
3351 * not. The default value is false.
3352 *
3353 * Use this function to make Evas treat objects' transparent areas as
3354 * @b not belonging to it with regard to mouse pointer events. By
3355 * default, all of the object's boundary rectangle will be taken in
3356 * account for them.
3357 *
3358 * @warning By using precise point collision detection you'll be
3359 * making Evas more resource intensive.
3360 *
3361 * Example code follows.
3362 * @dontinclude evas-events.c
3363 * @skip if (strcmp(ev->keyname, "p") == 0)
3364 * @until }
3365 *
3366 * See the full example @ref Example_Evas_Events "here".
3367 *
3368 * @see evas_object_precise_is_inside_get()
3369 * @ingroup Evas_Object_Group_Extras
3370 */
3371EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1);
3372
3373/**
3374 * Determine whether an object is set to use precise point collision
3375 * detection.
3376 *
3377 * @param obj The given object.
3378 * @return whether @p obj is set to use precise point collision
3379 * detection or not The default value is false.
3380 *
3381 * @see evas_object_precise_is_inside_set() for an example
3382 *
3383 * @ingroup Evas_Object_Group_Extras
3384 */
3385EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3386
3387/**
3388 * Set a hint flag on the given Evas object that it's used as a "static
3389 * clipper".
3390 *
3391 * @param obj The given object.
3392 * @param is_static_clip @c EINA_TRUE if it's to be used as a static
3393 * clipper, @c EINA_FALSE otherwise.
3394 *
3395 * This is a hint to Evas that this object is used as a big static
3396 * clipper and shouldn't be moved with children and otherwise
3397 * considered specially. The default value for new objects is
3398 * @c EINA_FALSE.
3399 *
3400 * @see evas_object_static_clip_get()
3401 *
3402 * @ingroup Evas_Object_Group_Extras
3403 */
3404EAPI void evas_object_static_clip_set(Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1);
3405
3406/**
3407 * Get the "static clipper" hint flag for a given Evas object.
3408 *
3409 * @param obj The given object.
3410 * @return @c EINA_TRUE if it's set as a static clipper,
3411 * @c EINA_FALSE otherwise.
3412 *
3413 * @see evas_object_static_clip_set() for more details
3414 *
3415 * @ingroup Evas_Object_Group_Extras
3416 */
3417EAPI Eina_Bool evas_object_static_clip_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3418/**
3419 * @}
3420 */
3421
3422/**
3423 * @ingroup Evas_Object_Group_Find
3424 *
3425 * @{
3426 */
3427
3428/**
3429 * Retrieve the object that currently has focus.
3430 *
3431 * @param e The Evas canvas to query for focused object on.
3432 * @return The object that has focus or @c NULL if there is not one.
3433 *
3434 * Evas can have (at most) one of its objects focused at a time.
3435 * Focused objects will be the ones having <b>key events</b> delivered
3436 * to, which the programmer can act upon by means of
3437 * evas_object_event_callback_add() usage.
3438 *
3439 * @note Most users wouldn't be dealing directly with Evas' focused
3440 * objects. Instead, they would be using a higher level library for
3441 * that (like a toolkit, as Elementary) to handle focus and who's
3442 * receiving input for them.
3443 *
3444 * This call returns the object that currently has focus on the canvas
3445 * @p e or @c NULL, if none.
3446 *
3447 * @see evas_object_focus_set
3448 * @see evas_object_focus_get
3449 * @see evas_object_key_grab
3450 * @see evas_object_key_ungrab
3451 *
3452 * Example:
3453 * @dontinclude evas-events.c
3454 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
3455 * @until evas_object_focus_set(d.bg, EINA_TRUE);
3456 * @dontinclude evas-events.c
3457 * @skip called when our rectangle gets focus
3458 * @until }
3459 *
3460 * In this example the @c event_info is exactly a pointer to that
3461 * focused rectangle. See the full @ref Example_Evas_Events "example".
3462 *
3463 * @ingroup Evas_Object_Group_Find
3464 */
3465EAPI Evas_Object *evas_focus_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3466
3467/**
3468 * Retrieves the object on the given evas with the given name.
3469 * @param e The given evas.
3470 * @param name The given name.
3471 * @return If successful, the Evas object with the given name. Otherwise,
3472 * @c NULL.
3473 *
3474 * This looks for the evas object given a name by evas_object_name_set(). If
3475 * the name is not unique canvas-wide, then which one of the many objects
3476 * with that name is returned is undefined, so only use this if you can ensure
3477 * the object name is unique.
3478 *
3479 * @ingroup Evas_Object_Group_Find
3480 */
3481EAPI Evas_Object *evas_object_name_find(const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3482
3483/**
3484 * Retrieves the object from children of the given object with the given name.
3485 * @param obj The parent (smart) object whose children to search.
3486 * @param name The given name.
3487 * @param recurse Set to the number of child levels to recurse (0 == don't recurse, 1 == only look at the children of @p obj or their immediate children, but no further etc.).
3488 * @return If successful, the Evas object with the given name. Otherwise,
3489 * @c NULL.
3490 *
3491 * This looks for the evas object given a name by evas_object_name_set(), but
3492 * it ONLY looks at the children of the object *p obj, and will only recurse
3493 * into those children if @p recurse is greater than 0. If the name is not
3494 * unique within immediate children (or the whole child tree) then it is not
3495 * defined which child object will be returned. If @p recurse is set to -1 then
3496 * it will recurse without limit.
3497 *
3498 * @since 1.2
3499 *
3500 * @ingroup Evas_Object_Group_Find
3501 */
3502EAPI Evas_Object *evas_object_name_child_find(const Evas_Object *obj, const char *name, int recurse) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3503
3504/**
3505 * Retrieve the Evas object stacked at the top of a given position in
3506 * a canvas
3507 *
3508 * @param e A handle to the canvas.
3509 * @param x The horizontal coordinate of the position
3510 * @param y The vertical coordinate of the position
3511 * @param include_pass_events_objects Boolean flag to include or not
3512 * objects which pass events in this calculation
3513 * @param include_hidden_objects Boolean flag to include or not hidden
3514 * objects in this calculation
3515 * @return The Evas object that is over all other objects at the given
3516 * position.
3517 *
3518 * This function will traverse all the layers of the given canvas,
3519 * from top to bottom, querying for objects with areas covering the
3520 * given position. The user can remove from the query
3521 * objects which are hidden and/or which are set to pass events.
3522 *
3523 * @warning This function will @b skip objects parented by smart
3524 * objects, acting only on the ones at the "top level", with regard to
3525 * object parenting.
3526 */
3527EAPI Evas_Object *evas_object_top_at_xy_get(const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3528
3529/**
3530 * Retrieve the Evas object stacked at the top at the position of the
3531 * mouse cursor, over a given canvas
3532 *
3533 * @param e A handle to the canvas.
3534 * @return The Evas object that is over all other objects at the mouse
3535 * pointer's position
3536 *
3537 * This function will traverse all the layers of the given canvas,
3538 * from top to bottom, querying for objects with areas covering the
3539 * mouse pointer's position, over @p e.
3540 *
3541 * @warning This function will @b skip objects parented by smart
3542 * objects, acting only on the ones at the "top level", with regard to
3543 * object parenting.
3544 */
3545EAPI Evas_Object *evas_object_top_at_pointer_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3546
3547/**
3548 * Retrieve the Evas object stacked at the top of a given rectangular
3549 * region in a canvas
3550 *
3551 * @param e A handle to the canvas.
3552 * @param x The top left corner's horizontal coordinate for the
3553 * rectangular region
3554 * @param y The top left corner's vertical coordinate for the
3555 * rectangular region
3556 * @param w The width of the rectangular region
3557 * @param h The height of the rectangular region
3558 * @param include_pass_events_objects Boolean flag to include or not
3559 * objects which pass events in this calculation
3560 * @param include_hidden_objects Boolean flag to include or not hidden
3561 * objects in this calculation
3562 * @return The Evas object that is over all other objects at the given
3563 * rectangular region.
3564 *
3565 * This function will traverse all the layers of the given canvas,
3566 * from top to bottom, querying for objects with areas overlapping
3567 * with the given rectangular region inside @p e. The user can remove
3568 * from the query objects which are hidden and/or which are set to
3569 * pass events.
3570 *
3571 * @warning This function will @b skip objects parented by smart
3572 * objects, acting only on the ones at the "top level", with regard to
3573 * object parenting.
3574 */
3575EAPI Evas_Object *evas_object_top_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3576
3577/**
3578 * Retrieve a list of Evas objects lying over a given position in
3579 * a canvas
3580 *
3581 * @param e A handle to the canvas.
3582 * @param x The horizontal coordinate of the position
3583 * @param y The vertical coordinate of the position
3584 * @param include_pass_events_objects Boolean flag to include or not
3585 * objects which pass events in this calculation
3586 * @param include_hidden_objects Boolean flag to include or not hidden
3587 * objects in this calculation
3588 * @return The list of Evas objects that are over the given position
3589 * in @p e
3590 *
3591 * This function will traverse all the layers of the given canvas,
3592 * from top to bottom, querying for objects with areas covering the
3593 * given position. The user can remove from query
3594 * objects which are hidden and/or which are set to pass events.
3595 *
3596 * @warning This function will @b skip objects parented by smart
3597 * objects, acting only on the ones at the "top level", with regard to
3598 * object parenting.
3599 */
3600EAPI Eina_List *evas_objects_at_xy_get(const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3601EAPI Eina_List *evas_objects_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3602
3603/**
3604 * Get the lowest (stacked) Evas object on the canvas @p e.
3605 *
3606 * @param e a valid canvas pointer
3607 * @return a pointer to the lowest object on it, if any, or @c NULL,
3608 * otherwise
3609 *
3610 * This function will take all populated layers in the canvas into
3611 * account, getting the lowest object for the lowest layer, naturally.
3612 *
3613 * @see evas_object_layer_get()
3614 * @see evas_object_layer_set()
3615 * @see evas_object_below_get()
3616 * @see evas_object_above_get()
3617 *
3618 * @warning This function will @b skip objects parented by smart
3619 * objects, acting only on the ones at the "top level", with regard to
3620 * object parenting.
3621 */
3622EAPI Evas_Object *evas_object_bottom_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3623
3624/**
3625 * Get the highest (stacked) Evas object on the canvas @p e.
3626 *
3627 * @param e a valid canvas pointer
3628 * @return a pointer to the highest object on it, if any, or @c NULL,
3629 * otherwise
3630 *
3631 * This function will take all populated layers in the canvas into
3632 * account, getting the highest object for the highest layer,
3633 * naturally.
3634 *
3635 * @see evas_object_layer_get()
3636 * @see evas_object_layer_set()
3637 * @see evas_object_below_get()
3638 * @see evas_object_above_get()
3639 *
3640 * @warning This function will @b skip objects parented by smart
3641 * objects, acting only on the ones at the "top level", with regard to
3642 * object parenting.
3643 */
3644EAPI Evas_Object *evas_object_top_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3645/**
3646 * @}
3647 */
3648
3649/**
3650 * @ingroup Evas_Object_Group_Interceptors
3651 *
3652 * @{
3653 */
3654
3655/**
3656 * Set the callback function that intercepts a show event of a object.
3657 *
3658 * @param obj The given canvas object pointer.
3659 * @param func The given function to be the callback function.
3660 * @param data The data passed to the callback function.
3661 *
3662 * This function sets a callback function to intercepts a show event
3663 * of a canvas object.
3664 *
3665 * @see evas_object_intercept_show_callback_del().
3666 *
3667 */
3668EAPI void evas_object_intercept_show_callback_add(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3669
3670/**
3671 * Unset the callback function that intercepts a show event of a
3672 * object.
3673 *
3674 * @param obj The given canvas object pointer.
3675 * @param func The given callback function.
3676 *
3677 * This function sets a callback function to intercepts a show event
3678 * of a canvas object.
3679 *
3680 * @see evas_object_intercept_show_callback_add().
3681 *
3682 */
3683EAPI void *evas_object_intercept_show_callback_del(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2);
3684
3685/**
3686 * Set the callback function that intercepts a hide event of a object.
3687 *
3688 * @param obj The given canvas object pointer.
3689 * @param func The given function to be the callback function.
3690 * @param data The data passed to the callback function.
3691 *
3692 * This function sets a callback function to intercepts a hide event
3693 * of a canvas object.
3694 *
3695 * @see evas_object_intercept_hide_callback_del().
3696 *
3697 */
3698EAPI void evas_object_intercept_hide_callback_add(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3699
3700/**
3701 * Unset the callback function that intercepts a hide event of a
3702 * object.
3703 *
3704 * @param obj The given canvas object pointer.
3705 * @param func The given callback function.
3706 *
3707 * This function sets a callback function to intercepts a hide event
3708 * of a canvas object.
3709 *
3710 * @see evas_object_intercept_hide_callback_add().
3711 *
3712 */
3713EAPI void *evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2);
3714
3715/**
3716 * Set the callback function that intercepts a move event of a object.
3717 *
3718 * @param obj The given canvas object pointer.
3719 * @param func The given function to be the callback function.
3720 * @param data The data passed to the callback function.
3721 *
3722 * This function sets a callback function to intercepts a move event
3723 * of a canvas object.
3724 *
3725 * @see evas_object_intercept_move_callback_del().
3726 *
3727 */
3728EAPI void evas_object_intercept_move_callback_add(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3729
3730/**
3731 * Unset the callback function that intercepts a move event of a
3732 * object.
3733 *
3734 * @param obj The given canvas object pointer.
3735 * @param func The given callback function.
3736 *
3737 * This function sets a callback function to intercepts a move event
3738 * of a canvas object.
3739 *
3740 * @see evas_object_intercept_move_callback_add().
3741 *
3742 */
3743EAPI void *evas_object_intercept_move_callback_del(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2);
3744
3745EAPI void evas_object_intercept_resize_callback_add(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3746EAPI void *evas_object_intercept_resize_callback_del(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2);
3747EAPI void evas_object_intercept_raise_callback_add(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3748EAPI void *evas_object_intercept_raise_callback_del(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2);
3749EAPI void evas_object_intercept_lower_callback_add(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3750EAPI void *evas_object_intercept_lower_callback_del(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2);
3751EAPI void evas_object_intercept_stack_above_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3752EAPI void *evas_object_intercept_stack_above_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2);
3753EAPI void evas_object_intercept_stack_below_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3754EAPI void *evas_object_intercept_stack_below_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2);
3755EAPI void evas_object_intercept_layer_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3756EAPI void *evas_object_intercept_layer_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2);
3757EAPI void evas_object_intercept_color_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3758EAPI void *evas_object_intercept_color_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2);
3759EAPI void evas_object_intercept_clip_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3760EAPI void *evas_object_intercept_clip_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2);
3761EAPI void evas_object_intercept_clip_unset_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
3762EAPI void *evas_object_intercept_clip_unset_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2);
3763/**
3764 * @}
3765 */
3766
3767/**
3768 * @ingroup Evas_Object_Rectangle
3769 *
3770 * @{
3771 */
3772
3773/**
3774 * Adds a rectangle to the given evas.
3775 * @param e The given evas.
3776 * @return The new rectangle object.