aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/evas/src/lib/Evas.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/evas/src/lib/Evas.h')
-rw-r--r--libraries/evas/src/lib/Evas.h12569
1 files changed, 0 insertions, 12569 deletions
diff --git a/libraries/evas/src/lib/Evas.h b/libraries/evas/src/lib/Evas.h
deleted file mode 100644
index 67d3018..0000000
--- a/libraries/evas/src/lib/Evas.h
+++ /dev/null
@@ -1,12569 +0,0 @@
1/**
2@mainpage Evas
3
4@version 1.1
5@date 2000-2012
6
7Please see the @ref authors page for contact details.
8@link Evas.h Evas API @endlink
9
10@link Evas.h Evas API @endlink
11
12@section toc Table of Contents
13
14@li @ref intro
15@li @ref work
16@li @ref compiling
17@li @ref install
18@li @ref next_steps
19@li @ref intro_example
20
21
22@section intro What is Evas?
23
24Evas is a clean display canvas API for several target display systems
25that can draw anti-aliased text, smooth super and sub-sampled scaled
26images, alpha-blend objects and much more.
27
28It abstracts any need to know much about what the characteristics of
29your display system are or what graphics calls are used to draw them
30and how. It deals on an object level where all you do is create and
31manipulate objects in a canvas, set their properties, and the rest is
32done for you.
33
34Evas optimises the rendering pipeline to minimise effort in redrawing
35changes made to the canvas and so takes this work out of the
36programmers hand, saving a lot of time and energy.
37
38It's small and lean, designed to work on embedded systems all the way
39to large and powerful multi-cpu workstations. It can be compiled to
40only have the features you need for your target platform if you so
41wish, thus keeping it small and lean. It has several display
42back-ends, letting it display on several display systems, making it
43portable for cross-device and cross-platform development.
44
45@subsection intro_not_evas What Evas is not?
46
47Evas is not a widget set or widget toolkit, however it is their
48base. See Elementary (http://docs.enlightenment.org/auto/elementary/)
49for a toolkit based on Evas, Edje, Ecore and other Enlightenment
50technologies.
51
52It is not dependent or aware of main loops, input or output
53systems. Input should be polled from various sources and fed to
54Evas. Similarly, it will not create windows or report windows updates
55to your system, rather just drawing the pixels and reporting to the
56user the areas that were changed. Of course these operations are quite
57common and thus they are ready to use in Ecore, particularly in
58Ecore_Evas (http://docs.enlightenment.org/auto/ecore/).
59
60
61@section work How does Evas work?
62
63Evas is a canvas display library. This is markedly different from most
64display and windowing systems as a canvas is structural and is also a
65state engine, whereas most display and windowing systems are immediate
66mode display targets. Evas handles the logic between a structural
67display via its state engine, and controls the target windowing system
68in order to produce rendered results of the current canvas' state on
69the display.
70
71Immediate mode display systems retain very little, or no state. A
72program will execute a series of commands, as in the pseudo code:
73
74@verbatim
75draw line from position (0, 0) to position (100, 200);
76
77draw rectangle from position (10, 30) to position (50, 500);
78
79bitmap_handle = create_bitmap();
80scale bitmap_handle to size 100 x 100;
81draw image bitmap_handle at position (10, 30);
82@endverbatim
83
84The series of commands is executed by the windowing system and the
85results are displayed on the screen (normally). Once the commands are
86executed the display system has little or no idea of how to reproduce
87this image again, and so has to be instructed by the application how
88to redraw sections of the screen whenever needed. Each successive
89command will be executed as instructed by the application and either
90emulated by software or sent to the graphics hardware on the device to
91be performed.
92
93The advantage of such a system is that it is simple, and gives a
94program tight control over how something looks and is drawn. Given the
95increasing complexity of displays and demands by users to have better
96looking interfaces, more and more work is needing to be done at this
97level by the internals of widget sets, custom display widgets and
98other programs. This means more and more logic and display rendering
99code needs to be written time and time again, each time the
100application needs to figure out how to minimise redraws so that
101display is fast and interactive, and keep track of redraw logic. The
102power comes at a high-price, lots of extra code and work. Programmers
103not very familiar with graphics programming will often make mistakes
104at this level and produce code that is sub optimal. Those familiar
105with this kind of programming will simply get bored by writing the
106same code again and again.
107
108For example, if in the above scene, the windowing system requires the
109application to redraw the area from 0, 0 to 50, 50 (also referred as
110"expose event"), then the programmer must calculate manually the
111updates and repaint it again:
112
113@verbatim
114Redraw from position (0, 0) to position (50, 50):
115
116// what was in area (0, 0, 50, 50)?
117
118// 1. intersection part of line (0, 0) to (100, 200)?
119 draw line from position (0, 0) to position (25, 50);
120
121// 2. intersection part of rectangle (10, 30) to (50, 500)?
122 draw rectangle from position (10, 30) to position (50, 50)
123
124// 3. intersection part of image at (10, 30), size 100 x 100?
125 bitmap_subimage = subregion from position (0, 0) to position (40, 20)
126 draw image bitmap_subimage at position (10, 30);
127@endverbatim
128
129The clever reader might have noticed that, if all elements in the
130above scene are opaque, then the system is doing useless paints: part
131of the line is behind the rectangle, and part of the rectangle is
132behind the image. These useless paints tend to be very costly, as
133pixels tend to be 4 bytes in size, thus an overlapping region of 100 x
134100 pixels is around 40000 useless writes! The developer could write
135code to calculate the overlapping areas and avoid painting then, but
136then it should be mixed with the "expose event" handling mentioned
137above and quickly one realizes the initially simpler method became
138really complex.
139
140Evas is a structural system in which the programmer creates and
141manages display objects and their properties, and as a result of this
142higher level state management, the canvas is able to redraw the set of
143objects when needed to represent the current state of the canvas.
144
145For example, the pseudo code:
146
147@verbatim
148line_handle = create_line();
149set line_handle from position (0, 0) to position (100, 200);
150show line_handle;
151
152rectangle_handle = create_rectangle();
153move rectangle_handle to position (10, 30);
154resize rectangle_handle to size 40 x 470;
155show rectangle_handle;
156
157bitmap_handle = create_bitmap();
158scale bitmap_handle to size 100 x 100;
159move bitmap_handle to position (10, 30);
160show bitmap_handle;
161
162render scene;
163@endverbatim
164
165This may look longer, but when the display needs to be refreshed or
166updated, the programmer only moves, resizes, shows, hides etc. the
167objects that need to change. The programmer simply thinks at the
168object logic level, and the canvas software does the rest of the work
169for them, figuring out what actually changed in the canvas since it
170was last drawn, how to most efficiently redraw the canvas and its
171contents to reflect the current state, and then it can go off and do
172the actual drawing of the canvas.
173
174This lets the programmer think in a more natural way when dealing with
175a display, and saves time and effort of working out how to load and
176display images, render given the current display system etc. Since
177Evas also is portable across different display systems, this also
178gives the programmer the ability to have their code ported and
179displayed on different display systems with very little work.
180
181Evas can be seen as a display system that stands somewhere between a
182widget set and an immediate mode display system. It retains basic
183display logic, but does very little high-level logic such as
184scrollbars, sliders, push buttons etc.
185
186
187@section compiling How to compile using Evas ?
188
189Evas is a library your application links to. The procedure for this is
190very simple. You simply have to compile your application with the
191appropriate compiler flags that the @c pkg-config script outputs. For
192example:
193
194Compiling C or C++ files into object files:
195
196@verbatim
197gcc -c -o main.o main.c `pkg-config --cflags evas`
198@endverbatim
199
200Linking object files into a binary executable:
201
202@verbatim
203gcc -o my_application main.o `pkg-config --libs evas`
204@endverbatim
205
206You simply have to make sure that @c pkg-config is in your shell's @c
207PATH (see the manual page for your appropriate shell) and @c evas.pc
208in @c /usr/lib/pkgconfig or its path in the @c PKG_CONFIG_PATH
209environment variable. It's that simple to link and use Evas once you
210have written your code to use it.
211
212Since the program is linked to Evas, it is now able to use any
213advertised API calls to display graphics in a canvas managed by it, as
214well as use the API calls provided to manage data.
215
216You should make sure you add any extra compile and link flags to your
217compile commands that your application may need as well. The above
218example is only guaranteed to make Evas add it's own requirements.
219
220
221@section install How is it installed?
222
223Simple:
224
225@verbatim
226./configure
227make
228su -
229...
230make install
231@endverbatim
232
233@section next_steps Next Steps
234
235After you understood what Evas is and installed it in your system you
236should proceed understanding the programming interface for all
237objects, then see the specific for the most used elements. We'd
238recommend you to take a while to learn Ecore
239(http://docs.enlightenment.org/auto/ecore/) and Edje
240(http://docs.enlightenment.org/auto/edje/) as they will likely save
241you tons of work compared to using just Evas directly.
242
243Recommended reading:
244
245@li @ref Evas_Object_Group, where you'll get how to basically
246 manipulate generic objects lying on an Evas canvas, handle canvas
247 and object events, etc.
248@li @ref Evas_Object_Rectangle, to learn about the most basic object
249 type on Evas -- the rectangle.
250@li @ref Evas_Object_Polygon, to learn how to create polygon elements
251 on the canvas.
252@li @ref Evas_Line_Group, to learn how to create line elements on the
253 canvas.
254@li @ref Evas_Object_Image, to learn about image objects, over which
255 Evas can do a plethora of operations.
256@li @ref Evas_Object_Text, to learn how to create textual elements on
257 the canvas.
258@li @ref Evas_Object_Textblock, to learn how to create multiline
259 textual elements on the canvas.
260@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define
261 new objects that provide @b custom functions to handle clipping,
262 hiding, moving, resizing, color setting and more. These could
263 be as simple as a group of objects that move together (see @ref
264 Evas_Smart_Object_Clipped) up to implementations of what
265 ends to be a widget, providing some intelligence (thus the name)
266 to Evas objects -- like a button or check box, for example.
267
268@section intro_example Introductory Example
269
270@include evas-buffer-simple.c
271*/
272
273/**
274@page authors Authors
275@author Carsten Haitzler <raster@@rasterman.com>
276@author Till Adam <till@@adam-lilienthal.de>
277@author Steve Ireland <sireland@@pobox.com>
278@author Brett Nash <nash@@nash.id.au>
279@author Tilman Sauerbeck <tilman@@code-monkey.de>
280@author Corey Donohoe <atmos@@atmos.org>
281@author Yuri Hudobin <glassy_ape@@users.sourceforge.net>
282@author Nathan Ingersoll <ningerso@@d.umn.edu>
283@author Willem Monsuwe <willem@@stack.nl>
284@author Jose O Gonzalez <jose_ogp@@juno.com>
285@author Bernhard Nemec <Bernhard.Nemec@@viasyshc.com>
286@author Jorge Luis Zapata Muga <jorgeluis.zapata@@gmail.com>
287@author Cedric Bail <cedric.bail@@free.fr>
288@author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
289@author Vincent Torri <vtorri@@univ-evry.fr>
290@author Tim Horton <hortont424@@gmail.com>
291@author Tom Hacohen <tom@@stosb.com>
292@author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
293@author Iván Briano <ivan@@profusion.mobi>
294@author Gustavo Lima Chaves <glima@@profusion.mobi>
295@author Samsung Electronics <tbd>
296@author Samsung SAIT <tbd>
297@author Sung W. Park <sungwoo@@gmail.com>
298@author Jiyoun Park <jy0703.park@@samsung.com>
299@author Myoungwoon Roy Kim(roy_kim) <myoungwoon.kim@@samsung.com> <myoungwoon@@gmail.com>
300@author Thierry el Borgi <thierry@@substantiel.fr>
301@author ChunEon Park <hermet@@hermet.pe.kr>
302@author Christopher 'devilhorns' Michael <cpmichael1@comcast.net>
303@author Seungsoo Woo <om101.woo@samsung.com>
304
305Please contact <enlightenment-devel@lists.sourceforge.net> to get in
306contact with the developers and maintainers.
307*/
308
309#ifndef _EVAS_H
310#define _EVAS_H
311
312#include <time.h>
313
314#include <Eina.h>
315
316#ifdef EAPI
317# undef EAPI
318#endif
319
320#ifdef _WIN32
321# ifdef EFL_EVAS_BUILD
322# ifdef DLL_EXPORT
323# define EAPI __declspec(dllexport)
324# else
325# define EAPI
326# endif /* ! DLL_EXPORT */
327# else
328# define EAPI __declspec(dllimport)
329# endif /* ! EFL_EVAS_BUILD */
330#else
331# ifdef __GNUC__
332# if __GNUC__ >= 4
333# define EAPI __attribute__ ((visibility("default")))
334# else
335# define EAPI
336# endif
337# else
338# define EAPI
339# endif
340#endif /* ! _WIN32 */
341
342#ifdef __cplusplus
343extern "C" {
344#endif
345
346#define EVAS_VERSION_MAJOR 1
347#define EVAS_VERSION_MINOR 2
348
349typedef struct _Evas_Version
350{
351 int major;
352 int minor;
353 int micro;
354 int revision;
355} Evas_Version;
356
357EAPI extern Evas_Version *evas_version;
358
359/**
360 * @file
361 * @brief These routines are used for Evas library interaction.
362 *
363 * @todo check boolean return values and convert to Eina_Bool
364 * @todo change all api to use EINA_SAFETY_*
365 * @todo finish api documentation
366 */
367
368/* BiDi exposed stuff */
369 /*FIXME: document */
370typedef enum _Evas_BiDi_Direction
371{
372 EVAS_BIDI_DIRECTION_NATURAL,
373 EVAS_BIDI_DIRECTION_NEUTRAL = EVAS_BIDI_DIRECTION_NATURAL,
374 EVAS_BIDI_DIRECTION_LTR,
375 EVAS_BIDI_DIRECTION_RTL
376} Evas_BiDi_Direction;
377
378/**
379 * Identifier of callbacks to be set for Evas canvases or Evas
380 * objects.
381 *
382 * The following figure illustrates some Evas callbacks:
383 *
384 * @image html evas-callbacks.png
385 * @image rtf evas-callbacks.png
386 * @image latex evas-callbacks.eps
387 *
388 * @see evas_object_event_callback_add()
389 * @see evas_event_callback_add()
390 */
391typedef enum _Evas_Callback_Type
392{
393 /*
394 * The following events are only for use with Evas objects, with
395 * evas_object_event_callback_add():
396 */
397 EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */
398 EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
399 EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
400 EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
401 EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
402 EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
403 EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
404 EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
405 EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
406 EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
407 EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
408 EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
409 EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
410 EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
411 EVAS_CALLBACK_SHOW, /**< Show Event */
412 EVAS_CALLBACK_HIDE, /**< Hide Event */
413 EVAS_CALLBACK_MOVE, /**< Move Event */
414 EVAS_CALLBACK_RESIZE, /**< Resize Event */
415 EVAS_CALLBACK_RESTACK, /**< Restack Event */
416 EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
417 EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
418 EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
419 EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */
420
421 /*
422 * The following events are only for use with Evas canvases, with
423 * evas_event_callback_add():
424 */
425 EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
426 EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
427 EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */
428 EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
429 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
430 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
431
432 /*
433 * More Evas object event types - see evas_object_event_callback_add():
434 */
435 EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanims in Evas that throw out original image data) */
436
437 EVAS_CALLBACK_RENDER_PRE, /**< Called just before rendering starts on the canvas target @since 1.2 */
438 EVAS_CALLBACK_RENDER_POST, /**< Called just after rendering stops on the canvas target @since 1.2 */
439
440 EVAS_CALLBACK_LAST /**< kept as last element/sentinel -- not really an event */
441} Evas_Callback_Type; /**< The types of events triggering a callback */
442
443/**
444 * @def EVAS_CALLBACK_PRIORITY_BEFORE
445 * Slightly more prioritized than default.
446 * @since 1.1.0
447 */
448#define EVAS_CALLBACK_PRIORITY_BEFORE -100
449/**
450 * @def EVAS_CALLBACK_PRIORITY_DEFAULT
451 * Default callback priority level
452 * @since 1.1.0
453 */
454#define EVAS_CALLBACK_PRIORITY_DEFAULT 0
455/**
456 * @def EVAS_CALLBACK_PRIORITY_AFTER
457 * Slightly less prioritized than default.
458 * @since 1.1.0
459 */
460#define EVAS_CALLBACK_PRIORITY_AFTER 100
461
462/**
463 * @typedef Evas_Callback_Priority
464 *
465 * Callback priority value. Range is -32k - 32k. The lower the number, the
466 * bigger the priority.
467 *
468 * @see EVAS_CALLBACK_PRIORITY_AFTER
469 * @see EVAS_CALLBACK_PRIORITY_BEFORE
470 * @see EVAS_CALLBACK_PRIORITY_DEFAULT
471 *
472 * @since 1.1.0
473 */
474typedef short Evas_Callback_Priority;
475
476/**
477 * Flags for Mouse Button events
478 */
479typedef enum _Evas_Button_Flags
480{
481 EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
482 EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< This mouse button press was the 2nd press of a double click */
483 EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< This mouse button press was the 3rd press of a triple click */
484} Evas_Button_Flags; /**< Flags for Mouse Button events */
485
486/**
487 * Flags for Events
488 */
489typedef enum _Evas_Event_Flags
490{
491 EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
492 EVAS_EVENT_FLAG_ON_HOLD = (1 << 0), /**< This event is being delivered but should be put "on hold" until the on hold flag is unset. the event should be used for informational purposes and maybe some indications visually, but not actually perform anything */
493 EVAS_EVENT_FLAG_ON_SCROLL = (1 << 1) /**< This event flag indicates the event occurs while scrolling; for example, DOWN event occurs during scrolling; the event should be used for informational purposes and maybe some indications visually, but not actually perform anything */
494} Evas_Event_Flags; /**< Flags for Events */
495
496/**
497 * State of Evas_Coord_Touch_Point
498 */
499typedef enum _Evas_Touch_Point_State
500{
501 EVAS_TOUCH_POINT_DOWN, /**< Touch point is pressed down */
502 EVAS_TOUCH_POINT_UP, /**< Touch point is released */
503 EVAS_TOUCH_POINT_MOVE, /**< Touch point is moved */
504 EVAS_TOUCH_POINT_STILL, /**< Touch point is not moved after pressed */
505 EVAS_TOUCH_POINT_CANCEL /**< Touch point is cancelled */
506} Evas_Touch_Point_State;
507
508/**
509 * Flags for Font Hinting
510 * @ingroup Evas_Font_Group
511 */
512typedef enum _Evas_Font_Hinting_Flags
513{
514 EVAS_FONT_HINTING_NONE, /**< No font hinting */
515 EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
516 EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
517} Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */
518
519/**
520 * Colorspaces for pixel data supported by Evas
521 * @ingroup Evas_Object_Image
522 */
523typedef enum _Evas_Colorspace
524{
525 EVAS_COLORSPACE_ARGB8888, /**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */
526 /* these are not currently supported - but planned for the future */
527 EVAS_COLORSPACE_YCBCR422P601_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */
528 EVAS_COLORSPACE_YCBCR422P709_PL,/**< YCbCr 4:2:2 Planar, ITU.BT-709 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */
529 EVAS_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */
530 EVAS_COLORSPACE_GRY8, /**< 8bit grayscale */
531 EVAS_COLORSPACE_YCBCR422601_PL, /**< YCbCr 4:2:2, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to line of Y,Cb,Y,Cr bytes */
532 EVAS_COLORSPACE_YCBCR420NV12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb,Cr rows. */
533 EVAS_COLORSPACE_YCBCR420TM12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of tiled row pointer, pointing to the Y rows, then the Cb,Cr rows. */
534} Evas_Colorspace; /**< Colorspaces for pixel data supported by Evas */
535
536/**
537 * How to pack items into cells in a table.
538 * @ingroup Evas_Object_Table
539 *
540 * @see evas_object_table_homogeneous_set() for an explanation of the function of
541 * each one.
542 */
543typedef enum _Evas_Object_Table_Homogeneous_Mode
544{
545 EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0,
546 EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1,
547 EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2
548} Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode. */
549
550typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< A generic rectangle handle */
551typedef struct _Evas_Point Evas_Point; /**< integer point */
552
553typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */
554typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */
555
556typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */
557typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */
558
559/**
560 * @typedef Evas_Smart_Class
561 *
562 * A smart object's @b base class definition
563 *
564 * @ingroup Evas_Smart_Group
565 */
566typedef struct _Evas_Smart_Class Evas_Smart_Class;
567
568/**
569 * @typedef Evas_Smart_Cb_Description
570 *
571 * A smart object callback description, used to provide introspection
572 *
573 * @ingroup Evas_Smart_Group
574 */
575typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
576
577/**
578 * @typedef Evas_Map
579 *
580 * An opaque handle to map points
581 *
582 * @see evas_map_new()
583 * @see evas_map_free()
584 * @see evas_map_dup()
585 *
586 * @ingroup Evas_Object_Group_Map
587 */
588typedef struct _Evas_Map Evas_Map;
589
590/**
591 * @typedef Evas
592 *
593 * An opaque handle to an Evas canvas.
594 *
595 * @see evas_new()
596 * @see evas_free()
597 *
598 * @ingroup Evas_Canvas
599 */
600typedef struct _Evas Evas;
601
602/**
603 * @typedef Evas_Object
604 * An Evas Object handle.
605 * @ingroup Evas_Object_Group
606 */
607typedef struct _Evas_Object Evas_Object;
608
609typedef void Evas_Performance; /**< An Evas Performance handle */
610typedef struct _Evas_Modifier Evas_Modifier; /**< An opaque type containing information on which modifier keys are registered in an Evas canvas */
611typedef struct _Evas_Lock Evas_Lock; /**< An opaque type containing information on which lock keys are registered in an Evas canvas */
612typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
613typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< A generic datatype for engine specific native surface information */
614
615 /**
616 * @typedef Evas_Video_Surface
617 *
618 * A generic datatype for video specific surface information
619 * @see evas_object_image_video_surface_set
620 * @see evas_object_image_video_surface_get
621 * @since 1.1.0
622 */
623typedef struct _Evas_Video_Surface Evas_Video_Surface;
624
625typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */
626
627typedef int Evas_Coord;
628typedef int Evas_Font_Size;
629typedef int Evas_Angle;
630
631struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */
632{
633 Evas_Coord x; /**< top-left x co-ordinate of rectangle */
634 Evas_Coord y; /**< top-left y co-ordinate of rectangle */
635 Evas_Coord w; /**< width of rectangle */
636 Evas_Coord h; /**< height of rectangle */
637};
638
639struct _Evas_Point
640{
641 int x, y;
642};
643
644struct _Evas_Coord_Point
645{
646 Evas_Coord x, y;
647};
648
649struct _Evas_Coord_Precision_Point
650{
651 Evas_Coord x, y;
652 double xsub, ysub;
653};
654
655struct _Evas_Position
656{
657 Evas_Point output;
658 Evas_Coord_Point canvas;
659};
660
661struct _Evas_Precision_Position
662{
663 Evas_Point output;
664 Evas_Coord_Precision_Point canvas;
665};
666
667typedef enum _Evas_Aspect_Control
668{
669 EVAS_ASPECT_CONTROL_NONE = 0, /**< Preference on scaling unset */
670 EVAS_ASPECT_CONTROL_NEITHER = 1, /**< Same effect as unset preference on scaling */
671 EVAS_ASPECT_CONTROL_HORIZONTAL = 2, /**< Use all horizontal container space to place an object, using the given aspect */
672 EVAS_ASPECT_CONTROL_VERTICAL = 3, /**< Use all vertical container space to place an object, using the given aspect */
673 EVAS_ASPECT_CONTROL_BOTH = 4 /**< Use all horizontal @b and vertical container spaces to place an object (never growing it out of those bounds), using the given aspect */
674} Evas_Aspect_Control; /**< Aspect types/policies for scaling size hints, used for evas_object_size_hint_aspect_set() */
675
676typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< A source description of pixels for importing pixels */
677typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< A generic Evas Engine information structure */
678typedef struct _Evas_Device Evas_Device; /**< A source device handle - where the event came from */
679typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
680typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
681typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
682typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
683typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
684typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
685typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
686typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
687typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
688typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
689typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
690typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< Event structure for #EVAS_CALLBACK_HOLD event callbacks */
691
692typedef enum _Evas_Load_Error
693{
694 EVAS_LOAD_ERROR_NONE = 0, /**< No error on load */
695 EVAS_LOAD_ERROR_GENERIC = 1, /**< A non-specific error occurred */
696 EVAS_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< File (or file path) does not exist */
697 EVAS_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission denied to an existing file (or path) */
698 EVAS_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Allocation of resources failure prevented load */
699 EVAS_LOAD_ERROR_CORRUPT_FILE = 5, /**< File corrupt (but was detected as a known format) */
700 EVAS_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */
701} Evas_Load_Error; /**< Evas image load error codes one can get - see evas_load_error_str() too. */
702
703
704typedef enum _Evas_Alloc_Error
705{
706 EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */
707 EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */
708 EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded, but extra memory had to be found by freeing up speculative resources */
709} Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */
710
711typedef enum _Evas_Fill_Spread
712{
713 EVAS_TEXTURE_REFLECT = 0, /**< image fill tiling mode - tiling reflects */
714 EVAS_TEXTURE_REPEAT = 1, /**< tiling repeats */
715 EVAS_TEXTURE_RESTRICT = 2, /**< tiling clamps - range offset ignored */
716 EVAS_TEXTURE_RESTRICT_REFLECT = 3, /**< tiling clamps and any range offset reflects */
717 EVAS_TEXTURE_RESTRICT_REPEAT = 4, /**< tiling clamps and any range offset repeats */
718 EVAS_TEXTURE_PAD = 5 /**< tiling extends with end values */
719} Evas_Fill_Spread; /**< Fill types used for evas_object_image_fill_spread_set() */
720
721typedef enum _Evas_Pixel_Import_Pixel_Format
722{
723 EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
724 EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
725 EVAS_PIXEL_FORMAT_YUV420P_601 = 2 /**< YUV 420 Planar format with CCIR 601 color encoding with contiguous planes in the order Y, U and V */
726} Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
727
728struct _Evas_Pixel_Import_Source
729{
730 Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
731 int w, h; /**< width and height of source in pixels */
732 void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
733};
734
735/* magic version number to know what the native surf struct looks like */
736#define EVAS_NATIVE_SURFACE_VERSION 2
737
738typedef enum _Evas_Native_Surface_Type
739{
740 EVAS_NATIVE_SURFACE_NONE,
741 EVAS_NATIVE_SURFACE_X11,
742 EVAS_NATIVE_SURFACE_OPENGL
743} Evas_Native_Surface_Type;
744
745struct _Evas_Native_Surface
746{
747 int version;
748 Evas_Native_Surface_Type type;
749 union {
750 struct {
751 void *visual; /**< visual of the pixmap to use (Visual) */
752 unsigned long pixmap; /**< pixmap id to use (Pixmap) */
753 } x11;
754 struct {
755 unsigned int texture_id; /**< opengl texture id to use from glGenTextures() */
756 unsigned int framebuffer_id; /**< 0 if not a FBO, FBO id otherwise from glGenFramebuffers() */
757 unsigned int internal_format; /**< same as 'internalFormat' for glTexImage2D() */
758 unsigned int format; /**< same as 'format' for glTexImage2D() */
759 unsigned int x, y, w, h; /**< region inside the texture to use (image size is assumed as texture size, with 0, 0 being the top-left and co-ordinates working down to the right and bottom being positive) */
760 } opengl;
761 } data;
762};
763
764/**
765 * @def EVAS_VIDEO_SURFACE_VERSION
766 * Magic version number to know what the video surf struct looks like
767 * @since 1.1.0
768 */
769#define EVAS_VIDEO_SURFACE_VERSION 1
770
771typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface);
772typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b);
773
774struct _Evas_Video_Surface
775{
776 int version;
777
778 Evas_Video_Coord_Cb move; /**< Move the video surface to this position */
779 Evas_Video_Coord_Cb resize; /**< Resize the video surface to that size */
780 Evas_Video_Cb show; /**< Show the video overlay surface */
781 Evas_Video_Cb hide; /**< Hide the video overlay surface */
782 Evas_Video_Cb update_pixels; /**< Please update the Evas_Object_Image pixels when called */
783
784 Evas_Object *parent;
785 void *data;
786};
787
788#define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
789#define EVAS_LAYER_MAX 32767 /**< top-most layer number */
790
791#define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
792#define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
793#define EVAS_TEXT_INVALID -1 /**< Not used for anything */
794#define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
795
796#define EVAS_HINT_EXPAND 1.0 /**< Use with evas_object_size_hint_weight_set(), evas_object_size_hint_weight_get(), evas_object_size_hint_expand_set(), evas_object_size_hint_expand_get() */
797#define EVAS_HINT_FILL -1.0 /**< Use with evas_object_size_hint_align_set(), evas_object_size_hint_align_get(), evas_object_size_hint_fill_set(), evas_object_size_hint_fill_get() */
798#define evas_object_size_hint_fill_set evas_object_size_hint_align_set /**< Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align) */
799#define evas_object_size_hint_fill_get evas_object_size_hint_align_get /**< Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align) */
800#define evas_object_size_hint_expand_set evas_object_size_hint_weight_set /**< Convenience macro to make it easier to understand that weight is also used for expand properties */
801#define evas_object_size_hint_expand_get evas_object_size_hint_weight_get /**< Convenience macro to make it easier to understand that weight is also used for expand properties */
802
803/**
804 * How the object should be rendered to output.
805 * @ingroup Evas_Object_Group_Extras
806 */
807typedef enum _Evas_Render_Op
808{
809 EVAS_RENDER_BLEND = 0, /**< default op: d = d*(1-sa) + s */
810 EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
811 EVAS_RENDER_COPY = 2, /**< d = s */
812 EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
813 EVAS_RENDER_ADD = 4, /* d = d + s */
814 EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
815 EVAS_RENDER_SUB = 6, /**< d = d - s */
816 EVAS_RENDER_SUB_REL = 7, /* d = d - s*da */
817 EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
818 EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
819 EVAS_RENDER_MASK = 10, /**< d = d*sa */
820 EVAS_RENDER_MUL = 11 /**< d = d*s */
821} Evas_Render_Op; /**< How the object should be rendered to output. */
822
823typedef enum _Evas_Border_Fill_Mode
824{
825 EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */
826 EVAS_BORDER_FILL_DEFAULT = 1, /**< Image's center region is to be @b blended with objects underneath it, if it has transparency. This is the default behavior for image objects */
827 EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */
828} Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */
829
830typedef enum _Evas_Image_Scale_Hint
831{
832 EVAS_IMAGE_SCALE_HINT_NONE = 0, /**< No scale hint at all */
833 EVAS_IMAGE_SCALE_HINT_DYNAMIC = 1, /**< Image is being re-scaled over time, thus turning scaling cache @b off for its data */
834 EVAS_IMAGE_SCALE_HINT_STATIC = 2 /**< Image is not being re-scaled over time, thus turning scaling cache @b on for its data */
835} Evas_Image_Scale_Hint; /**< How an image's data is to be treated by Evas, with regard to scaling cache */
836
837typedef enum _Evas_Image_Animated_Loop_Hint
838{
839 EVAS_IMAGE_ANIMATED_HINT_NONE = 0,
840 EVAS_IMAGE_ANIMATED_HINT_LOOP = 1, /**< Image's animation mode is loop like 1->2->3->1->2->3 */
841 EVAS_IMAGE_ANIMATED_HINT_PINGPONG = 2 /**< Image's animation mode is pingpong like 1->2->3->2->1-> ... */
842} Evas_Image_Animated_Loop_Hint;
843
844typedef enum _Evas_Engine_Render_Mode
845{
846 EVAS_RENDER_MODE_BLOCKING = 0,
847 EVAS_RENDER_MODE_NONBLOCKING = 1,
848} Evas_Engine_Render_Mode;
849
850typedef enum _Evas_Image_Content_Hint
851{
852 EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
853 EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents will change over time */
854 EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents won't change over time */
855} Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
856
857struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
858{
859 int magic; /**< Magic number */
860};
861
862struct _Evas_Event_Mouse_Down /** Mouse button press event */
863{
864 int button; /**< Mouse button number that went down (1 - 32) */
865
866 Evas_Point output; /**< The X/Y location of the cursor */
867 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
868
869 void *data;
870 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
871 Evas_Lock *locks;
872
873 Evas_Button_Flags flags; /**< button flags set during the event */
874 unsigned int timestamp;
875 Evas_Event_Flags event_flags;
876 Evas_Device *dev;
877};
878
879struct _Evas_Event_Mouse_Up /** Mouse button release event */
880{
881 int button; /**< Mouse button number that was raised (1 - 32) */
882
883 Evas_Point output;
884 Evas_Coord_Point canvas;
885
886 void *data;
887 Evas_Modifier *modifiers;
888 Evas_Lock *locks;
889
890 Evas_Button_Flags flags;
891 unsigned int timestamp;
892 Evas_Event_Flags event_flags;
893 Evas_Device *dev;
894};
895
896struct _Evas_Event_Mouse_In /** Mouse enter event */
897{
898 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
899
900 Evas_Point output;
901 Evas_Coord_Point canvas;
902
903 void *data;
904 Evas_Modifier *modifiers;
905 Evas_Lock *locks;
906 unsigned int timestamp;
907 Evas_Event_Flags event_flags;
908 Evas_Device *dev;
909};
910
911struct _Evas_Event_Mouse_Out /** Mouse leave event */
912{
913 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
914
915
916 Evas_Point output;
917 Evas_Coord_Point canvas;
918
919 void *data;
920 Evas_Modifier *modifiers;
921 Evas_Lock *locks;
922 unsigned int timestamp;
923 Evas_Event_Flags event_flags;
924 Evas_Device *dev;
925};
926
927struct _Evas_Event_Mouse_Move /** Mouse button down event */
928{
929 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
930
931 Evas_Position cur, prev;
932
933 void *data;
934 Evas_Modifier *modifiers;
935 Evas_Lock *locks;
936 unsigned int timestamp;
937 Evas_Event_Flags event_flags;
938 Evas_Device *dev;
939};
940
941struct _Evas_Event_Mouse_Wheel /** Wheel event */
942{
943 int direction; /* 0 = default up/down wheel FIXME: more wheel types */
944 int z; /* ...,-2,-1 = down, 1,2,... = up */
945
946 Evas_Point output;
947 Evas_Coord_Point canvas;
948
949 void *data;
950 Evas_Modifier *modifiers;
951 Evas_Lock *locks;
952 unsigned int timestamp;
953 Evas_Event_Flags event_flags;
954 Evas_Device *dev;
955};
956
957struct _Evas_Event_Multi_Down /** Multi button press event */
958{
959 int device; /**< Multi device number that went down (1 or more for extra touches) */
960 double radius, radius_x, radius_y;
961 double pressure, angle;
962
963 Evas_Point output;
964 Evas_Coord_Precision_Point canvas;
965
966 void *data;
967 Evas_Modifier *modifiers;
968 Evas_Lock *locks;
969
970 Evas_Button_Flags flags;
971 unsigned int timestamp;
972 Evas_Event_Flags event_flags;
973 Evas_Device *dev;
974};
975
976struct _Evas_Event_Multi_Up /** Multi button release event */
977{
978 int device; /**< Multi device number that went up (1 or more for extra touches) */
979 double radius, radius_x, radius_y;
980 double pressure, angle;
981
982 Evas_Point output;
983 Evas_Coord_Precision_Point canvas;
984
985 void *data;
986 Evas_Modifier *modifiers;
987 Evas_Lock *locks;
988
989 Evas_Button_Flags flags;
990 unsigned int timestamp;
991 Evas_Event_Flags event_flags;
992 Evas_Device *dev;
993};
994
995struct _Evas_Event_Multi_Move /** Multi button down event */
996{
997 int device; /**< Multi device number that moved (1 or more for extra touches) */
998 double radius, radius_x, radius_y;
999 double pressure, angle;
1000
1001 Evas_Precision_Position cur;
1002
1003 void *data;
1004 Evas_Modifier *modifiers;
1005 Evas_Lock *locks;
1006 unsigned int timestamp;
1007 Evas_Event_Flags event_flags;
1008 Evas_Device *dev;
1009};
1010
1011struct _Evas_Event_Key_Down /** Key press event */
1012{
1013 char *keyname; /**< the name string of the key pressed */
1014 void *data;
1015 Evas_Modifier *modifiers;
1016 Evas_Lock *locks;
1017
1018 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
1019 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
1020 const char *compose; /**< A UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */
1021 unsigned int timestamp;
1022 Evas_Event_Flags event_flags;
1023 Evas_Device *dev;
1024};
1025
1026struct _Evas_Event_Key_Up /** Key release event */
1027{
1028 char *keyname; /**< the name string of the key released */
1029 void *data;
1030 Evas_Modifier *modifiers;
1031 Evas_Lock *locks;
1032
1033 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
1034 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
1035 const char *compose; /**< A UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */
1036 unsigned int timestamp;
1037 Evas_Event_Flags event_flags;
1038 Evas_Device *dev;
1039};
1040
1041struct _Evas_Event_Hold /** Hold change event */
1042{
1043 int hold; /**< The hold flag */
1044 void *data;
1045
1046 unsigned int timestamp;
1047 Evas_Event_Flags event_flags;
1048 Evas_Device *dev;
1049};
1050
1051/**
1052 * How the mouse pointer should be handled by Evas.
1053 *
1054 * In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button
1055 * is pressed down over an object and held, with the mouse pointer
1056 * being moved outside of it, the pointer still behaves as being bound
1057 * to that object, albeit out of its drawing region. When the button
1058 * is released, the event will be fed to the object, that may check if
1059 * the final position is over it or not and do something about it.
1060 *
1061 * In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will
1062 * always be bound to the object right below it.
1063 *
1064 * @ingroup Evas_Object_Group_Extras
1065 */
1066typedef enum _Evas_Object_Pointer_Mode
1067{
1068 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
1069 EVAS_OBJECT_POINTER_MODE_NOGRAB, /**< pointer always bound to the object right below it */
1070 EVAS_OBJECT_POINTER_MODE_NOGRAB_NO_REPEAT_UPDOWN /**< useful on object with "repeat events" enabled, where mouse/touch up and down events WONT be repeated to objects and these objects wont be auto-grabbed. @since 1.2 */
1071} Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
1072
1073typedef void (*Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info); /**< Evas smart objects' "smart callback" function signature */
1074typedef void (*Evas_Event_Cb) (void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
1075typedef Eina_Bool (*Evas_Object_Event_Post_Cb) (void *data, Evas *e);
1076typedef void (*Evas_Object_Event_Cb) (void *data, Evas *e, Evas_Object *obj, void *event_info); /**< Evas object event callback function signature */
1077typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
1078
1079/**
1080 * @defgroup Evas_Group Top Level Functions
1081 *
1082 * Functions that affect Evas as a whole.
1083 */
1084
1085/**
1086 * Initialize Evas
1087 *
1088 * @return The init counter value.
1089 *
1090 * This function initializes Evas and increments a counter of the
1091 * number of calls to it. It returns the new counter's value.
1092 *
1093 * @see evas_shutdown().
1094 *
1095 * Most EFL users wouldn't be using this function directly, because
1096 * they wouldn't access Evas directly by themselves. Instead, they
1097 * would be using higher level helpers, like @c ecore_evas_init().
1098 * See http://docs.enlightenment.org/auto/ecore/.
1099 *
1100 * You should be using this if your use is something like the
1101 * following. The buffer engine is just one of the many ones Evas
1102 * provides.
1103 *
1104 * @dontinclude evas-buffer-simple.c
1105 * @skip int main
1106 * @until return -1;
1107 * And being the canvas creation something like:
1108 * @skip static Evas *create_canvas
1109 * @until evas_output_viewport_set(canvas,
1110 *
1111 * Note that this is code creating an Evas canvas with no usage of
1112 * Ecore helpers at all -- no linkage with Ecore on this scenario,
1113 * thus. Again, this wouldn't be on Evas common usage for most
1114 * developers. See the full @ref Example_Evas_Buffer_Simple "example".
1115 *
1116 * @ingroup Evas_Group
1117 */
1118EAPI int evas_init (void);
1119
1120/**
1121 * Shutdown Evas
1122 *
1123 * @return Evas' init counter value.
1124 *
1125 * This function finalizes Evas, decrementing the counter of the
1126 * number of calls to the function evas_init(). This new value for the
1127 * counter is returned.
1128 *
1129 * @see evas_init().
1130 *
1131 * If you were the sole user of Evas, by means of evas_init(), you can
1132 * check if it's being properly shut down by expecting a return value
1133 * of 0.
1134 *
1135 * Example code follows.
1136 * @dontinclude evas-buffer-simple.c
1137 * @skip // NOTE: use ecore_evas_buffer_new
1138 * @until evas_shutdown
1139 * Where that function would contain:
1140 * @skip evas_free(canvas)
1141 * @until evas_free(canvas)
1142 *
1143 * Most users would be using ecore_evas_shutdown() instead, like told
1144 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
1145 * "example".
1146 *
1147 * @ingroup Evas_Group
1148 */
1149EAPI int evas_shutdown (void);
1150
1151
1152/**
1153 * Return if any allocation errors have occurred during the prior function
1154 * @return The allocation error flag
1155 *
1156 * This function will return if any memory allocation errors occurred during,
1157 * and what kind they were. The return value will be one of
1158 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
1159 * with each meaning something different.
1160 *
1161 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
1162 * worked as expected.
1163 *
1164 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
1165 * its job and will have exited as cleanly as possible. The programmer
1166 * should consider this as a sign of very low memory and should try and safely
1167 * recover from the prior functions failure (or try free up memory elsewhere
1168 * and try again after more memory is freed).
1169 *
1170 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
1171 * recovered from by evas finding memory of its own it has allocated and
1172 * freeing what it sees as not really usefully allocated memory. What is freed
1173 * may vary. Evas may reduce the resolution of images, free cached images or
1174 * fonts, trhow out pre-rendered data, reduce the complexity of change lists
1175 * etc. Evas and the program will function as per normal after this, but this
1176 * is a sign of low memory, and it is suggested that the program try and
1177 * identify memory it doesn't need, and free it.
1178 *
1179 * Example:
1180 * @code
1181 * extern Evas_Object *object;
1182 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
1183 *
1184 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
1185 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
1186 * {
1187 * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
1188 * fprintf(stderr, " destroy object now as it cannot be used.\n");
1189 * evas_object_del(object);
1190 * object = NULL;
1191 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1192 * my_memory_cleanup();
1193 * }
1194 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
1195 * {
1196 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1197 * my_memory_cleanup();
1198 * }
1199 * @endcode
1200 *
1201 * @ingroup Evas_Group
1202 */
1203EAPI Evas_Alloc_Error evas_alloc_error (void);
1204
1205
1206/**
1207 * @brief Get evas' internal asynchronous events read file descriptor.
1208 *
1209 * @return The canvas' asynchronous events read file descriptor.
1210 *
1211 * Evas' asynchronous events are meant to be dealt with internally,
1212 * i. e., when building stuff to be glued together into the EFL
1213 * infrastructure -- a module, for example. The context which demands
1214 * its use is when calculations need to be done out of the main
1215 * thread, asynchronously, and some action must be performed after
1216 * that.
1217 *
1218 * An example of actual use of this API is for image asynchronous
1219 * preload inside evas. If the canvas was instantiated through
1220 * ecore-evas usage, ecore itself will take care of calling those
1221 * events' processing.
1222 *
1223 * This function returns the read file descriptor where to get the
1224 * asynchronous events of the canvas. Naturally, other mainloops,
1225 * apart from ecore, may make use of it.
1226 *
1227 * @ingroup Evas_Group
1228 */
1229EAPI int evas_async_events_fd_get (void) EINA_WARN_UNUSED_RESULT;
1230
1231/**
1232 * @brief Trigger the processing of all events waiting on the file
1233 * descriptor returned by evas_async_events_fd_get().
1234 *
1235 * @return The number of events processed.
1236 *
1237 * All asynchronous events queued up by evas_async_events_put() are
1238 * processed here. More precisely, the callback functions, informed
1239 * together with other event parameters, when queued, get called (with
1240 * those parameters), in that order.
1241 *
1242 * @ingroup Evas_Group
1243 */
1244EAPI int evas_async_events_process (void);
1245
1246/**
1247* Insert asynchronous events on the canvas.
1248 *
1249 * @param target The target to be affected by the events.
1250 * @param type The type of callback function.
1251 * @param event_info Information about the event.
1252 * @param func The callback function pointer.
1253 *
1254 * This is the way, for a routine running outside evas' main thread,
1255 * to report an asynchronous event. A callback function is informed,
1256 * whose call is to happen after evas_async_events_process() is
1257 * called.
1258 *
1259 * @ingroup Evas_Group
1260 */
1261EAPI Eina_Bool evas_async_events_put (const void *target, Evas_Callback_Type type, void *event_info, Evas_Async_Events_Put_Cb func) EINA_ARG_NONNULL(1, 4);
1262
1263/**
1264 * @defgroup Evas_Canvas Canvas Functions
1265 *
1266 * Low level Evas canvas functions. Sub groups will present more high
1267 * level ones, though.
1268 *
1269 * Most of these functions deal with low level Evas actions, like:
1270 * @li create/destroy raw canvases, not bound to any displaying engine
1271 * @li tell a canvas i got focused (in a windowing context, for example)
1272 * @li tell a canvas a region should not be calculated anymore in rendering
1273 * @li tell a canvas to render its contents, immediately
1274 *
1275 * Most users will be using Evas by means of the @c Ecore_Evas
1276 * wrapper, which deals with all the above mentioned issues
1277 * automatically for them. Thus, you'll be looking at this section
1278 * only if you're building low level stuff.
1279 *
1280 * The groups within present you functions that deal with the canvas
1281 * directly, too, and not yet with its @b objects. They are the
1282 * functions you need to use at a minimum to get a working canvas.
1283 *
1284 * Some of the functions in this group are exemplified @ref
1285 * Example_Evas_Events "here".
1286 */
1287
1288/**
1289 * Creates a new empty evas.
1290 *
1291 * Note that before you can use the evas, you will to at a minimum:
1292 * @li Set its render method with @ref evas_output_method_set .
1293 * @li Set its viewport size with @ref evas_output_viewport_set .
1294 * @li Set its size of the canvas with @ref evas_output_size_set .
1295 * @li Ensure that the render engine is given the correct settings
1296 * with @ref evas_engine_info_set .
1297 *
1298 * This function should only fail if the memory allocation fails
1299 *
1300 * @note this function is very low level. Instead of using it
1301 * directly, consider using the high level functions in
1302 * Ecore_Evas such as @c ecore_evas_new(). See
1303 * http://docs.enlightenment.org/auto/ecore/.
1304 *
1305 * @attention it is recommended that one calls evas_init() before
1306 * creating new canvas.
1307 *
1308 * @return A new uninitialised Evas canvas on success. Otherwise, @c
1309 * NULL.
1310 * @ingroup Evas_Canvas
1311 */
1312EAPI Evas *evas_new (void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
1313
1314/**
1315 * Frees the given evas and any objects created on it.
1316 *
1317 * Any objects with 'free' callbacks will have those callbacks called
1318 * in this function.
1319 *
1320 * @param e The given evas.
1321 *
1322 * @ingroup Evas_Canvas
1323 */
1324EAPI void evas_free (Evas *e) EINA_ARG_NONNULL(1);
1325
1326/**
1327 * Inform to the evas that it got the focus.
1328 *
1329 * @param e The evas to change information.
1330 * @ingroup Evas_Canvas
1331 */
1332EAPI void evas_focus_in (Evas *e);
1333
1334/**
1335 * Inform to the evas that it lost the focus.
1336 *
1337 * @param e The evas to change information.
1338 * @ingroup Evas_Canvas
1339 */
1340EAPI void evas_focus_out (Evas *e);
1341
1342/**
1343 * Get the focus state known by the given evas
1344 *
1345 * @param e The evas to query information.
1346 * @ingroup Evas_Canvas
1347 */
1348EAPI Eina_Bool evas_focus_state_get (const Evas *e);
1349
1350/**
1351 * Push the nochange flag up 1
1352 *
1353 * This tells evas, that while the nochange flag is greater than 0, do not
1354 * mark objects as "changed" when making changes.
1355 *
1356 * @param e The evas to change information.
1357 * @ingroup Evas_Canvas
1358 */
1359EAPI void evas_nochange_push (Evas *e);
1360
1361/**
1362 * Pop the nochange flag down 1
1363 *
1364 * This tells evas, that while the nochange flag is greater than 0, do not
1365 * mark objects as "changed" when making changes.
1366 *
1367 * @param e The evas to change information.
1368 * @ingroup Evas_Canvas
1369 */
1370EAPI void evas_nochange_pop (Evas *e);
1371
1372
1373/**
1374 * Attaches a specific pointer to the evas for fetching later
1375 *
1376 * @param e The canvas to attach the pointer to
1377 * @param data The pointer to attach
1378 * @ingroup Evas_Canvas
1379 */
1380EAPI void evas_data_attach_set (Evas *e, void *data) EINA_ARG_NONNULL(1);
1381
1382/**
1383 * Returns the pointer attached by evas_data_attach_set()
1384 *
1385 * @param e The canvas to attach the pointer to
1386 * @return The pointer attached
1387 * @ingroup Evas_Canvas
1388 */
1389EAPI void *evas_data_attach_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1390
1391
1392/**
1393 * Add a damage rectangle.
1394 *
1395 * @param e The given canvas pointer.
1396 * @param x The rectangle's left position.
1397 * @param y The rectangle's top position.
1398 * @param w The rectangle's width.
1399 * @param h The rectangle's height.
1400 *
1401 * This is the function by which one tells evas that a part of the
1402 * canvas has to be repainted.
1403 *
1404 * @ingroup Evas_Canvas
1405 */
1406EAPI void evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1407
1408/**
1409 * Add an "obscured region" to an Evas canvas.
1410 *
1411 * @param e The given canvas pointer.
1412 * @param x The rectangle's top left corner's horizontal coordinate.
1413 * @param y The rectangle's top left corner's vertical coordinate
1414 * @param w The rectangle's width.
1415 * @param h The rectangle's height.
1416 *
1417 * This is the function by which one tells an Evas canvas that a part
1418 * of it <b>must not</b> be repainted. The region must be
1419 * rectangular and its coordinates inside the canvas viewport are
1420 * passed in the call. After this call, the region specified won't
1421 * participate in any form in Evas' calculations and actions during
1422 * its rendering updates, having its displaying content frozen as it
1423 * was just after this function took place.
1424 *
1425 * We call it "obscured region" because the most common use case for
1426 * this rendering (partial) freeze is something else (most probably
1427 * other canvas) being on top of the specified rectangular region,
1428 * thus shading it completely from the user's final scene in a
1429 * display. To avoid unnecessary processing, one should indicate to the
1430 * obscured canvas not to bother about the non-important area.
1431 *
1432 * The majority of users won't have to worry about this function, as
1433 * they'll be using just one canvas in their applications, with
1434 * nothing inset or on top of it in any form.
1435 *
1436 * To make this region one that @b has to be repainted again, call the
1437 * function evas_obscured_clear().
1438 *
1439 * @note This is a <b>very low level function</b>, which most of
1440 * Evas' users wouldn't care about.
1441 *
1442 * @note This function does @b not flag the canvas as having its state
1443 * changed. If you want to re-render it afterwards expecting new
1444 * contents, you have to add "damage" regions yourself (see
1445 * evas_damage_rectangle_add()).
1446 *
1447 * @see evas_obscured_clear()
1448 * @see evas_render_updates()
1449 *
1450 * Example code follows.
1451 * @dontinclude evas-events.c
1452 * @skip add an obscured
1453 * @until evas_obscured_clear(evas);
1454 *
1455 * In that example, pressing the "Ctrl" and "o" keys will impose or
1456 * remove an obscured region in the middle of the canvas. You'll get
1457 * the same contents at the time the key was pressed, if toggling it
1458 * on, until you toggle it off again (make sure the animation is
1459 * running on to get the idea better). See the full @ref
1460 * Example_Evas_Events "example".
1461 *
1462 * @ingroup Evas_Canvas
1463 */
1464EAPI void evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1465
1466/**
1467 * Remove all "obscured regions" from an Evas canvas.
1468 *
1469 * @param e The given canvas pointer.
1470 *
1471 * This function removes all the rectangles from the obscured regions
1472 * list of the canvas @p e. It takes obscured areas added with
1473 * evas_obscured_rectangle_add() and make them again a regions that @b
1474 * have to be repainted on rendering updates.
1475 *
1476 * @note This is a <b>very low level function</b>, which most of
1477 * Evas' users wouldn't care about.
1478 *
1479 * @note This function does @b not flag the canvas as having its state
1480 * changed. If you want to re-render it afterwards expecting new
1481 * contents, you have to add "damage" regions yourself (see
1482 * evas_damage_rectangle_add()).
1483 *
1484 * @see evas_obscured_rectangle_add() for an example
1485 * @see evas_render_updates()
1486 *
1487 * @ingroup Evas_Canvas
1488 */
1489EAPI void evas_obscured_clear (Evas *e) EINA_ARG_NONNULL(1);
1490
1491/**
1492 * Force immediate renderization of the given Evas canvas.
1493 *
1494 * @param e The given canvas pointer.
1495 * @return A newly allocated list of updated rectangles of the canvas
1496 * (@c Eina_Rectangle structs). Free this list with
1497 * evas_render_updates_free().
1498 *
1499 * This function forces an immediate renderization update of the given
1500 * canvas @e.
1501 *
1502 * @note This is a <b>very low level function</b>, which most of
1503 * Evas' users wouldn't care about. One would use it, for example, to
1504 * grab an Evas' canvas update regions and paint them back, using the
1505 * canvas' pixmap, on a displaying system working below Evas.
1506 *
1507 * @note Evas is a stateful canvas. If no operations changing its
1508 * state took place since the last rendering action, you won't see no
1509 * changes and this call will be a no-op.
1510 *
1511 * Example code follows.
1512 * @dontinclude evas-events.c
1513 * @skip add an obscured
1514 * @until d.obscured = !d.obscured;
1515 *
1516 * See the full @ref Example_Evas_Events "example".
1517 *
1518 * @ingroup Evas_Canvas
1519 */
1520EAPI Eina_List *evas_render_updates (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1521
1522/**
1523 * Free the rectangles returned by evas_render_updates().
1524 *
1525 * @param updates The list of updated rectangles of the canvas.
1526 *
1527 * This function removes the region from the render updates list. It
1528 * makes the region doesn't be render updated anymore.
1529 *
1530 * @see evas_render_updates() for an example
1531 *
1532 * @ingroup Evas_Canvas
1533 */
1534EAPI void evas_render_updates_free (Eina_List *updates);
1535
1536/**
1537 * Force renderization of the given canvas.
1538 *
1539 * @param e The given canvas pointer.
1540 *
1541 * @ingroup Evas_Canvas
1542 */
1543EAPI void evas_render (Evas *e) EINA_ARG_NONNULL(1);
1544
1545/**
1546 * Update the canvas internal objects but not triggering immediate
1547 * renderization.
1548 *
1549 * @param e The given canvas pointer.
1550 *
1551 * This function updates the canvas internal objects not triggering
1552 * renderization. To force renderization function evas_render() should
1553 * be used.
1554 *
1555 * @see evas_render.
1556 *
1557 * @ingroup Evas_Canvas
1558 */
1559EAPI void evas_norender (Evas *e) EINA_ARG_NONNULL(1);
1560
1561/**
1562 * Make the canvas discard internally cached data used for rendering.
1563 *
1564 * @param e The given canvas pointer.
1565 *
1566 * This function flushes the arrays of delete, active and render objects.
1567 * Other things it may also discard are: shared memory segments,
1568 * temporary scratch buffers, cached data to avoid re-compute of that data etc.
1569 *
1570 * @ingroup Evas_Canvas
1571 */
1572EAPI void evas_render_idle_flush (Evas *e) EINA_ARG_NONNULL(1);
1573
1574/**
1575 * Make the canvas discard as much data as possible used by the engine at
1576 * runtime.
1577 *
1578 * @param e The given canvas pointer.
1579 *
1580 * This function will unload images, delete textures and much more, where
1581 * possible. You may also want to call evas_render_idle_flush() immediately
1582 * prior to this to perhaps discard a little more, though evas_render_dump()
1583 * should implicitly delete most of what evas_render_idle_flush() might
1584 * discard too.
1585 *
1586 * @ingroup Evas_Canvas
1587 */
1588EAPI void evas_render_dump (Evas *e) EINA_ARG_NONNULL(1);
1589
1590/**
1591 * @defgroup Evas_Output_Method Render Engine Functions
1592 *
1593 * Functions that are used to set the render engine for a given
1594 * function, and then get that engine working.
1595 *
1596 * The following code snippet shows how they can be used to
1597 * initialise an evas that uses the X11 software engine:
1598 * @code
1599 * Evas *evas;
1600 * Evas_Engine_Info_Software_X11 *einfo;
1601 * extern Display *display;
1602 * extern Window win;
1603 *
1604 * evas_init();
1605 *
1606 * evas = evas_new();
1607 * evas_output_method_set(evas, evas_render_method_lookup("software_x11"));
1608 * evas_output_size_set(evas, 640, 480);
1609 * evas_output_viewport_set(evas, 0, 0, 640, 480);
1610 * einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas);
1611 * einfo->info.display = display;
1612 * einfo->info.visual = DefaultVisual(display, DefaultScreen(display));
1613 * einfo->info.colormap = DefaultColormap(display, DefaultScreen(display));
1614 * einfo->info.drawable = win;
1615 * einfo->info.depth = DefaultDepth(display, DefaultScreen(display));
1616 * evas_engine_info_set(evas, (Evas_Engine_Info *)einfo);
1617 * @endcode
1618 *
1619 * @ingroup Evas_Canvas
1620 */
1621
1622/**
1623 * Look up a numeric ID from a string name of a rendering engine.
1624 *
1625 * @param name the name string of an engine
1626 * @return A numeric (opaque) ID for the rendering engine
1627 * @ingroup Evas_Output_Method
1628 *
1629 * This function looks up a numeric return value for the named engine
1630 * in the string @p name. This is a normal C string, NUL byte
1631 * terminated. The name is case sensitive. If the rendering engine is
1632 * available, a numeric ID for that engine is returned that is not
1633 * 0. If the engine is not available, 0 is returned, indicating an
1634 * invalid engine.
1635 *
1636 * The programmer should NEVER rely on the numeric ID of an engine
1637 * unless it is returned by this function. Programs should NOT be
1638 * written accessing render method ID's directly, without first
1639 * obtaining it from this function.
1640 *
1641 * @attention it is mandatory that one calls evas_init() before
1642 * looking up the render method.
1643 *
1644 * Example:
1645 * @code
1646 * int engine_id;
1647 * Evas *evas;
1648 *
1649 * evas_init();
1650 *
1651 * evas = evas_new();
1652 * if (!evas)
1653 * {
1654 * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
1655 * exit(-1);
1656 * }
1657 * engine_id = evas_render_method_lookup("software_x11");
1658 * if (!engine_id)
1659 * {
1660 * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
1661 * exit(-1);
1662 * }
1663 * evas_output_method_set(evas, engine_id);
1664 * @endcode
1665 */
1666EAPI int evas_render_method_lookup (const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1667
1668/**
1669 * List all the rendering engines compiled into the copy of the Evas library
1670 *
1671 * @return A linked list whose data members are C strings of engine names
1672 * @ingroup Evas_Output_Method
1673 *
1674 * Calling this will return a handle (pointer) to an Evas linked
1675 * list. Each node in the linked list will have the data pointer be a
1676 * (char *) pointer to the name string of the rendering engine
1677 * available. The strings should never be modified, neither should the
1678 * list be modified. This list should be cleaned up as soon as the
1679 * program no longer needs it using evas_render_method_list_free(). If
1680 * no engines are available from Evas, NULL will be returned.
1681 *
1682 * Example:
1683 * @code
1684 * Eina_List *engine_list, *l;
1685 * char *engine_name;
1686 *
1687 * engine_list = evas_render_method_list();
1688 * if (!engine_list)
1689 * {
1690 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1691 * exit(-1);
1692 * }
1693 * printf("Available Evas Engines:\n");
1694 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1695 * printf("%s\n", engine_name);
1696 * evas_render_method_list_free(engine_list);
1697 * @endcode
1698 */
1699EAPI Eina_List *evas_render_method_list (void) EINA_WARN_UNUSED_RESULT;
1700
1701/**
1702 * This function should be called to free a list of engine names
1703 *
1704 * @param list The Eina_List base pointer for the engine list to be freed
1705 * @ingroup Evas_Output_Method
1706 *
1707 * When this function is called it will free the engine list passed in
1708 * as @p list. The list should only be a list of engines generated by
1709 * calling evas_render_method_list(). If @p list is NULL, nothing will
1710 * happen.
1711 *
1712 * Example:
1713 * @code
1714 * Eina_List *engine_list, *l;
1715 * char *engine_name;
1716 *
1717 * engine_list = evas_render_method_list();
1718 * if (!engine_list)
1719 * {
1720 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1721 * exit(-1);
1722 * }
1723 * printf("Available Evas Engines:\n");
1724 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1725 * printf("%s\n", engine_name);
1726 * evas_render_method_list_free(engine_list);
1727 * @endcode
1728 */
1729EAPI void evas_render_method_list_free (Eina_List *list);
1730
1731
1732/**
1733 * Sets the output engine for the given evas.
1734 *
1735 * Once the output engine for an evas is set, any attempt to change it
1736 * will be ignored. The value for @p render_method can be found using
1737 * @ref evas_render_method_lookup .
1738 *
1739 * @param e The given evas.
1740 * @param render_method The numeric engine value to use.
1741 *
1742 * @attention it is mandatory that one calls evas_init() before
1743 * setting the output method.
1744 *
1745 * @ingroup Evas_Output_Method
1746 */
1747EAPI void evas_output_method_set (Evas *e, int render_method) EINA_ARG_NONNULL(1);
1748
1749/**
1750 * Retrieves the number of the output engine used for the given evas.
1751 * @param e The given evas.
1752 * @return The ID number of the output engine being used. @c 0 is
1753 * returned if there is an error.
1754 * @ingroup Evas_Output_Method
1755 */
1756EAPI int evas_output_method_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1757
1758
1759/**
1760 * Retrieves the current render engine info struct from the given evas.
1761 *
1762 * The returned structure is publicly modifiable. The contents are
1763 * valid until either @ref evas_engine_info_set or @ref evas_render
1764 * are called.
1765 *
1766 * This structure does not need to be freed by the caller.
1767 *
1768 * @param e The given evas.
1769 * @return A pointer to the Engine Info structure. @c NULL is returned if
1770 * an engine has not yet been assigned.
1771 * @ingroup Evas_Output_Method
1772 */
1773EAPI Evas_Engine_Info *evas_engine_info_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1774
1775/**
1776 * Applies the engine settings for the given evas from the given @c
1777 * Evas_Engine_Info structure.
1778 *
1779 * To get the Evas_Engine_Info structure to use, call @ref
1780 * evas_engine_info_get . Do not try to obtain a pointer to an
1781 * @c Evas_Engine_Info structure in any other way.
1782 *
1783 * You will need to call this function at least once before you can
1784 * create objects on an evas or render that evas. Some engines allow
1785 * their settings to be changed more than once.
1786 *
1787 * Once called, the @p info pointer should be considered invalid.
1788 *
1789 * @param e The pointer to the Evas Canvas
1790 * @param info The pointer to the Engine Info to use
1791 * @return 1 if no error occurred, 0 otherwise
1792 * @ingroup Evas_Output_Method
1793 */
1794EAPI Eina_Bool evas_engine_info_set (Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1);
1795
1796/**
1797 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1798 *
1799 * Functions that set and retrieve the output and viewport size of an
1800 * evas.
1801 *
1802 * @ingroup Evas_Canvas
1803 */
1804
1805/**
1806 * Sets the output size of the render engine of the given evas.
1807 *
1808 * The evas will render to a rectangle of the given size once this
1809 * function is called. The output size is independent of the viewport
1810 * size. The viewport will be stretched to fill the given rectangle.
1811 *
1812 * The units used for @p w and @p h depend on the engine used by the
1813 * evas.
1814 *
1815 * @param e The given evas.
1816 * @param w The width in output units, usually pixels.
1817 * @param h The height in output units, usually pixels.
1818 * @ingroup Evas_Output_Size
1819 */
1820EAPI void evas_output_size_set (Evas *e, int w, int h) EINA_ARG_NONNULL(1);
1821
1822/**
1823 * Retrieve the output size of the render engine of the given evas.
1824 *
1825 * The output size is given in whatever the output units are for the
1826 * engine.
1827 *
1828 * If either @p w or @p h is @c NULL, then it is ignored. If @p e is
1829 * invalid, the returned results are undefined.
1830 *
1831 * @param e The given evas.
1832 * @param w The pointer to an integer to store the width in.
1833 * @param h The pointer to an integer to store the height in.
1834 * @ingroup Evas_Output_Size
1835 */
1836EAPI void evas_output_size_get (const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1);
1837
1838/**
1839 * Sets the output viewport of the given evas in evas units.
1840 *
1841 * The output viewport is the area of the evas that will be visible to
1842 * the viewer. The viewport will be stretched to fit the output
1843 * target of the evas when rendering is performed.
1844 *
1845 * @note The coordinate values do not have to map 1-to-1 with the output
1846 * target. However, it is generally advised that it is done for ease
1847 * of use.
1848 *
1849 * @param e The given evas.
1850 * @param x The top-left corner x value of the viewport.
1851 * @param y The top-left corner y value of the viewport.
1852 * @param w The width of the viewport. Must be greater than 0.
1853 * @param h The height of the viewport. Must be greater than 0.
1854 * @ingroup Evas_Output_Size
1855 */
1856EAPI void evas_output_viewport_set (Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
1857
1858/**
1859 * Get the render engine's output viewport co-ordinates in canvas units.
1860 * @param e The pointer to the Evas Canvas
1861 * @param x The pointer to a x variable to be filled in
1862 * @param y The pointer to a y variable to be filled in
1863 * @param w The pointer to a width variable to be filled in
1864 * @param h The pointer to a height variable to be filled in
1865 * @ingroup Evas_Output_Size
1866 *
1867 * Calling this function writes the current canvas output viewport
1868 * size and location values into the variables pointed to by @p x, @p
1869 * y, @p w and @p h. On success the variables have the output
1870 * location and size values written to them in canvas units. Any of @p
1871 * x, @p y, @p w or @p h that are NULL will not be written to. If @p e
1872 * is invalid, the results are undefined.
1873 *
1874 * Example:
1875 * @code
1876 * extern Evas *evas;
1877 * Evas_Coord x, y, width, height;
1878 *
1879 * evas_output_viewport_get(evas, &x, &y, &w, &h);
1880 * @endcode
1881 */
1882EAPI void evas_output_viewport_get (const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
1883
1884/**
1885 * Sets the output framespace size of the render engine of the given evas.
1886 *
1887 * The framespace size is used in the Wayland engines to denote space where
1888 * the output is not drawn. This is mainly used in ecore_evas to draw borders
1889 *
1890 * The units used for @p w and @p h depend on the engine used by the
1891 * evas.
1892 *
1893 * @param e The given evas.
1894 * @param x The left coordinate in output units, usually pixels.
1895 * @param y The top coordinate in output units, usually pixels.
1896 * @param w The width in output units, usually pixels.
1897 * @param h The height in output units, usually pixels.
1898 * @ingroup Evas_Output_Size
1899 * @since 1.1.0
1900 */
1901EAPI void evas_output_framespace_set (Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h);
1902
1903/**
1904 * Get the render engine's output framespace co-ordinates in canvas units.
1905 *
1906 * @param e The pointer to the Evas Canvas
1907 * @param x The pointer to a x variable to be filled in
1908 * @param y The pointer to a y variable to be filled in
1909 * @param w The pointer to a width variable to be filled in
1910 * @param h The pointer to a height variable to be filled in
1911 * @ingroup Evas_Output_Size
1912 * @since 1.1.0
1913 */
1914EAPI void evas_output_framespace_get (const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h);
1915
1916/**
1917 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1918 *
1919 * Functions that are used to map coordinates from the canvas to the
1920 * screen or the screen to the canvas.
1921 *
1922 * @ingroup Evas_Canvas
1923 */
1924
1925/**
1926 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1927 *
1928 * @param e The pointer to the Evas Canvas
1929 * @param x The screen/output x co-ordinate
1930 * @return The screen co-ordinate translated to canvas unit co-ordinates
1931 * @ingroup Evas_Coord_Mapping_Group
1932 *
1933 * This function takes in a horizontal co-ordinate as the @p x
1934 * parameter and converts it into canvas units, accounting for output
1935 * size, viewport size and location, returning it as the function
1936 * return value. If @p e is invalid, the results are undefined.
1937 *
1938 * Example:
1939 * @code
1940 * extern Evas *evas;
1941 * extern int screen_x;
1942 * Evas_Coord canvas_x;
1943 *
1944 * canvas_x = evas_coord_screen_x_to_world(evas, screen_x);
1945 * @endcode
1946 */
1947EAPI Evas_Coord evas_coord_screen_x_to_world (const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1948
1949/**
1950 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1951 *
1952 * @param e The pointer to the Evas Canvas
1953 * @param y The screen/output y co-ordinate
1954 * @return The screen co-ordinate translated to canvas unit co-ordinates
1955 * @ingroup Evas_Coord_Mapping_Group
1956 *
1957 * This function takes in a vertical co-ordinate as the @p y parameter
1958 * and converts it into canvas units, accounting for output size,
1959 * viewport size and location, returning it as the function return
1960 * value. If @p e is invalid, the results are undefined.
1961 *
1962 * Example:
1963 * @code
1964 * extern Evas *evas;
1965 * extern int screen_y;
1966 * Evas_Coord canvas_y;
1967 *
1968 * canvas_y = evas_coord_screen_y_to_world(evas, screen_y);
1969 * @endcode
1970 */
1971EAPI Evas_Coord evas_coord_screen_y_to_world (const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1972
1973/**
1974 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1975 *
1976 * @param e The pointer to the Evas Canvas
1977 * @param x The canvas x co-ordinate
1978 * @return The output/screen co-ordinate translated to output co-ordinates
1979 * @ingroup Evas_Coord_Mapping_Group
1980 *
1981 * This function takes in a horizontal co-ordinate as the @p x
1982 * parameter and converts it into output units, accounting for output
1983 * size, viewport size and location, returning it as the function
1984 * return value. If @p e is invalid, the results are undefined.
1985 *
1986 * Example:
1987 * @code
1988 * extern Evas *evas;
1989 * int screen_x;
1990 * extern Evas_Coord canvas_x;
1991 *
1992 * screen_x = evas_coord_world_x_to_screen(evas, canvas_x);
1993 * @endcode
1994 */
1995EAPI int evas_coord_world_x_to_screen (const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1996
1997/**
1998 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1999 *
2000 * @param e The pointer to the Evas Canvas
2001 * @param y The canvas y co-ordinate
2002 * @return The output/screen co-ordinate translated to output co-ordinates
2003 * @ingroup Evas_Coord_Mapping_Group
2004 *
2005 * This function takes in a vertical co-ordinate as the @p x parameter
2006 * and converts it into output units, accounting for output size,
2007 * viewport size and location, returning it as the function return
2008 * value. If @p e is invalid, the results are undefined.
2009 *
2010 * Example:
2011 * @code
2012 * extern Evas *evas;
2013 * int screen_y;
2014 * extern Evas_Coord canvas_y;
2015 *
2016 * screen_y = evas_coord_world_y_to_screen(evas, canvas_y);
2017 * @endcode
2018 */
2019EAPI int evas_coord_world_y_to_screen (const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2020
2021/**
2022 * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
2023 *
2024 * Functions that deal with the status of the pointer (mouse cursor).
2025 *
2026 * @ingroup Evas_Canvas
2027 */
2028
2029/**
2030 * This function returns the current known pointer co-ordinates
2031 *
2032 * @param e The pointer to the Evas Canvas
2033 * @param x The pointer to an integer to be filled in
2034 * @param y The pointer to an integer to be filled in
2035 * @ingroup Evas_Pointer_Group
2036 *
2037 * This function returns the current known screen/output co-ordinates
2038 * of the mouse pointer and sets the contents of the integers pointed
2039 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
2040 * valid canvas the results of this function are undefined.
2041 *
2042 * Example:
2043 * @code
2044 * extern Evas *evas;
2045 * int mouse_x, mouse_y;
2046 *
2047 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
2048 * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y);
2049 * @endcode
2050 */
2051EAPI void evas_pointer_output_xy_get (const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1);
2052
2053/**
2054 * This function returns the current known pointer co-ordinates
2055 *
2056 * @param e The pointer to the Evas Canvas
2057 * @param x The pointer to a Evas_Coord to be filled in
2058 * @param y The pointer to a Evas_Coord to be filled in
2059 * @ingroup Evas_Pointer_Group
2060 *
2061 * This function returns the current known canvas unit co-ordinates of
2062 * the mouse pointer and sets the contents of the Evas_Coords pointed
2063 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
2064 * valid canvas the results of this function are undefined.
2065 *
2066 * Example:
2067 * @code
2068 * extern Evas *evas;
2069 * Evas_Coord mouse_x, mouse_y;
2070 *
2071 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
2072 * printf("Mouse is at canvas position %f, %f\n", mouse_x, mouse_y);
2073 * @endcode
2074 */
2075EAPI void evas_pointer_canvas_xy_get (const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
2076
2077/**
2078 * Returns a bitmask with the mouse buttons currently pressed, set to 1
2079 *
2080 * @param e The pointer to the Evas Canvas
2081 * @return A bitmask of the currently depressed buttons on the canvas
2082 * @ingroup Evas_Pointer_Group
2083 *
2084 * Calling this function will return a 32-bit integer with the
2085 * appropriate bits set to 1 that correspond to a mouse button being
2086 * depressed. This limits Evas to a mouse devices with a maximum of 32
2087 * buttons, but that is generally in excess of any host system's
2088 * pointing device abilities.
2089 *
2090 * A canvas by default begins with no mouse buttons being pressed and
2091 * only calls to evas_event_feed_mouse_down(),
2092 * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and
2093 * evas_event_feed_mouse_up_data() will alter that.
2094 *
2095 * The least significant bit corresponds to the first mouse button
2096 * (button 1) and the most significant bit corresponds to the last
2097 * mouse button (button 32).
2098 *
2099 * If @p e is not a valid canvas, the return value is undefined.
2100 *
2101 * Example:
2102 * @code
2103 * extern Evas *evas;
2104 * int button_mask, i;
2105 *
2106 * button_mask = evas_pointer_button_down_mask_get(evas);
2107 * printf("Buttons currently pressed:\n");
2108 * for (i = 0; i < 32; i++)
2109 * {
2110 * if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1);
2111 * }
2112 * @endcode
2113 */
2114EAPI int evas_pointer_button_down_mask_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2115
2116/**
2117 * Returns whether the mouse pointer is logically inside the canvas
2118 *
2119 * @param e The pointer to the Evas Canvas
2120 * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise
2121 * @ingroup Evas_Pointer_Group
2122 *
2123 * When this function is called it will return a value of either 0 or
2124 * 1, depending on if evas_event_feed_mouse_in(),
2125 * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(),
2126 * evas_event_feed_mouse_out_data() have been called to feed in a
2127 * mouse enter event into the canvas.
2128 *
2129 * A return value of 1 indicates the mouse is logically inside the
2130 * canvas, and 0 implies it is logically outside the canvas.
2131 *
2132 * A canvas begins with the mouse being assumed outside (0).
2133 *
2134 * If @p e is not a valid canvas, the return value is undefined.
2135 *
2136 * Example:
2137 * @code
2138 * extern Evas *evas;
2139 *
2140 * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n");
2141 * else printf("Mouse is out!\n");
2142 * @endcode
2143 */
2144EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2145 EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1);
2146
2147/**
2148 * @defgroup Evas_Canvas_Events Canvas Events
2149 *
2150 * Functions relating to canvas events, which are mainly reports on
2151 * its internal states changing (an object got focused, the rendering
2152 * is updated, etc).
2153 *
2154 * Some of the functions in this group are exemplified @ref
2155 * Example_Evas_Events "here".
2156 *
2157 * @ingroup Evas_Canvas
2158 */
2159
2160/**
2161 * @addtogroup Evas_Canvas_Events
2162 * @{
2163 */
2164
2165/**
2166 * Add (register) a callback function to a given canvas event.
2167 *
2168 * @param e Canvas to attach a callback to
2169 * @param type The type of event that will trigger the callback
2170 * @param func The (callback) function to be called when the event is
2171 * triggered
2172 * @param data The data pointer to be passed to @p func
2173 *
2174 * This function adds a function callback to the canvas @p e when the
2175 * event of type @p type occurs on it. The function pointer is @p
2176 * func.
2177 *
2178 * In the event of a memory allocation error during the addition of
2179 * the callback to the canvas, evas_alloc_error() should be used to
2180 * determine the nature of the error, if any, and the program should
2181 * sensibly try and recover.
2182 *
2183 * A callback function must have the ::Evas_Event_Cb prototype
2184 * definition. The first parameter (@p data) in this definition will
2185 * have the same value passed to evas_event_callback_add() as the @p
2186 * data parameter, at runtime. The second parameter @p e is the canvas
2187 * pointer on which the event occurred. The third parameter @p
2188 * event_info is a pointer to a data structure that may or may not be
2189 * passed to the callback, depending on the event type that triggered
2190 * the callback. This is so because some events don't carry extra
2191 * context with them, but others do.
2192 *
2193 * The event type @p type to trigger the function may be one of
2194 * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST,
2195 * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT,
2196 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and
2197 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of
2198 * event that will trigger the callback to be called. Only the last
2199 * two of the event types listed here provide useful event information
2200 * data -- a pointer to the recently focused Evas object. For the
2201 * others the @p event_info pointer is going to be @c NULL.
2202 *
2203 * Example:
2204 * @dontinclude evas-events.c
2205 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE
2206 * @until two canvas event callbacks
2207 *
2208 * Looking to the callbacks registered above,
2209 * @dontinclude evas-events.c
2210 * @skip called when our rectangle gets focus
2211 * @until let's have our events back
2212 *
2213 * we see that the canvas flushes its rendering pipeline
2214 * (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb
2215 * routine takes place: it has to redraw that image at a different
2216 * size. Also, the callback on an object being focused comes just
2217 * after we focus it explicitly, on code.
2218 *
2219 * See the full @ref Example_Evas_Events "example".
2220 *
2221 * @note Be careful not to add the same callback multiple times, if
2222 * that's not what you want, because Evas won't check if a callback
2223 * existed before exactly as the one being registered (and thus, call
2224 * it more than once on the event, in this case). This would make
2225 * sense if you passed different functions and/or callback data, only.
2226 */
2227EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2228
2229/**
2230 * Add (register) a callback function to a given canvas event with a
2231 * non-default priority set. Except for the priority field, it's exactly the
2232 * same as @ref evas_event_callback_add
2233 *
2234 * @param e Canvas to attach a callback to
2235 * @param type The type of event that will trigger the callback
2236 * @param priority The priority of the callback, lower values called first.
2237 * @param func The (callback) function to be called when the event is
2238 * triggered
2239 * @param data The data pointer to be passed to @p func
2240 *
2241 * @see evas_event_callback_add
2242 * @since 1.1.0
2243 */
2244EAPI 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);
2245
2246/**
2247 * Delete a callback function from the canvas.
2248 *
2249 * @param e Canvas to remove a callback from
2250 * @param type The type of event that was triggering the callback
2251 * @param func The function that was to be called when the event was triggered
2252 * @return The data pointer that was to be passed to the callback
2253 *
2254 * This function removes the most recently added callback from the
2255 * canvas @p e which was triggered by the event type @p type and was
2256 * calling the function @p func when triggered. If the removal is
2257 * successful it will also return the data pointer that was passed to
2258 * evas_event_callback_add() when the callback was added to the
2259 * canvas. If not successful NULL will be returned.
2260 *
2261 * Example:
2262 * @code
2263 * extern Evas *e;
2264 * void *my_data;
2265 * void focus_in_callback(void *data, Evas *e, void *event_info);
2266 *
2267 * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
2268 * @endcode
2269 */
2270EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
2271
2272/**
2273 * Delete (unregister) a callback function registered to a given
2274 * canvas event.
2275 *
2276 * @param e Canvas to remove an event callback from
2277 * @param type The type of event that was triggering the callback
2278 * @param func The function that was to be called when the event was
2279 * triggered
2280 * @param data The data pointer that was to be passed to the callback
2281 * @return The data pointer that was to be passed to the callback
2282 *
2283 * This function removes <b>the first</b> added callback from the
2284 * canvas @p e matching the event type @p type, the registered
2285 * function pointer @p func and the callback data pointer @p data. If
2286 * the removal is successful it will also return the data pointer that
2287 * was passed to evas_event_callback_add() (that will be the same as
2288 * the parameter) when the callback(s) was(were) added to the
2289 * canvas. If not successful @c NULL will be returned. A common use
2290 * would be to remove an exact match of a callback.
2291 *
2292 * Example:
2293 * @dontinclude evas-events.c
2294 * @skip evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
2295 * @until _object_focus_in_cb, NULL);
2296 *
2297 * See the full @ref Example_Evas_Events "example".
2298 *
2299 * @note For deletion of canvas events callbacks filtering by just
2300 * type and function pointer, user evas_event_callback_del().
2301 */
2302EAPI void *evas_event_callback_del_full (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2303
2304/**
2305 * Push a callback on the post-event callback stack
2306 *
2307 * @param e Canvas to push the callback on
2308 * @param func The function that to be called when the stack is unwound
2309 * @param data The data pointer to be passed to the callback
2310 *
2311 * Evas has a stack of callbacks that get called after all the callbacks for
2312 * an event have triggered (all the objects it triggers on and all the callbacks
2313 * in each object triggered). When all these have been called, the stack is
2314 * unwond from most recently to least recently pushed item and removed from the
2315 * stack calling the callback set for it.
2316 *
2317 * This is intended for doing reverse logic-like processing, example - when a
2318 * child object that happens to get the event later is meant to be able to
2319 * "steal" functions from a parent and thus on unwind of this stack have its
2320 * function called first, thus being able to set flags, or return 0 from the
2321 * post-callback that stops all other post-callbacks in the current stack from
2322 * being called (thus basically allowing a child to take control, if the event
2323 * callback prepares information ready for taking action, but the post callback
2324 * actually does the action).
2325 *
2326 */
2327EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2328
2329/**
2330 * Remove a callback from the post-event callback stack
2331 *
2332 * @param e Canvas to push the callback on
2333 * @param func The function that to be called when the stack is unwound
2334 *
2335 * This removes a callback from the stack added with
2336 * evas_post_event_callback_push(). The first instance of the function in
2337 * the callback stack is removed from being executed when the stack is
2338 * unwound. Further instances may still be run on unwind.
2339 */
2340EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func);
2341
2342/**
2343 * Remove a callback from the post-event callback stack
2344 *
2345 * @param e Canvas to push the callback on
2346 * @param func The function that to be called when the stack is unwound
2347 * @param data The data pointer to be passed to the callback
2348 *
2349 * This removes a callback from the stack added with
2350 * evas_post_event_callback_push(). The first instance of the function and data
2351 * in the callback stack is removed from being executed when the stack is
2352 * unwound. Further instances may still be run on unwind.
2353 */
2354EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2355
2356/**
2357 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
2358 *
2359 * Functions that deal with the freezing of input event processing of
2360 * an Evas canvas.
2361 *
2362 * There might be scenarios during a graphical user interface
2363 * program's use when the developer wishes the users wouldn't be able
2364 * to deliver input events to this application. It may, for example,
2365 * be the time for it to populate a view or to change some
2366 * layout. Assuming proper behavior with user interaction during this
2367 * exact time would be hard, as things are in a changing state. The
2368 * programmer can then tell the canvas to ignore input events,
2369 * bringing it back to normal behavior when he/she wants.
2370 *
2371 * Most of the time use of freezing events is done like this:
2372 * @code
2373 * evas_event_freeze(my_evas_canvas);
2374 * function_that_does_work_which_cant_be_interrupted_by_events();
2375 * evas_event_thaw(my_evas_canvas);
2376 * @endcode
2377 *
2378 * Some of the functions in this group are exemplified @ref
2379 * Example_Evas_Events "here".
2380 *
2381 * @ingroup Evas_Canvas_Events
2382 */
2383
2384/**
2385 * @addtogroup Evas_Event_Freezing_Group
2386 * @{
2387 */
2388
2389/**
2390 * Set the default set of flags an event begins with
2391 *
2392 * @param e The canvas to set the default event flags of
2393 * @param flags The default flags to use
2394 *
2395 * Events in evas can have an event_flags member. This starts out with
2396 * and initial value (no flags). this lets you set the default flags that
2397 * an event begins with to be @p flags
2398 *
2399 * @since 1.2
2400 */
2401EAPI void evas_event_default_flags_set (Evas *e, Evas_Event_Flags flags) EINA_ARG_NONNULL(1);
2402
2403/**
2404 * Get the defaulty set of flags an event begins with
2405 *
2406 * @param e The canvas to get the default event flags from
2407 * @return The default event flags for that canvas
2408 *
2409 * This gets the default event flags events are produced with when fed in.
2410 *
2411 * @see evas_event_default_flags_set()
2412 * @since 1.2
2413 */
2414EAPI Evas_Event_Flags evas_event_default_flags_get (const Evas *e) EINA_ARG_NONNULL(1);
2415
2416/**
2417 * Freeze all input events processing.
2418 *
2419 * @param e The canvas to freeze input events processing on.
2420 *
2421 * This function will indicate to Evas that the canvas @p e is to have
2422 * all input event processing frozen until a matching
2423 * evas_event_thaw() function is called on the same canvas. All events
2424 * of this kind during the freeze will get @b discarded. Every freeze
2425 * call must be matched by a thaw call in order to completely thaw out
2426 * a canvas (i.e. these calls may be nested). The most common use is
2427 * when you don't want the user to interact with your user interface
2428 * when you're populating a view or changing the layout.
2429 *
2430 * Example:
2431 * @dontinclude evas-events.c
2432 * @skip freeze input for 3 seconds
2433 * @until }
2434 * @dontinclude evas-events.c
2435 * @skip let's have our events back
2436 * @until }
2437 *
2438 * See the full @ref Example_Evas_Events "example".
2439 *
2440 * If you run that example, you'll see the canvas ignoring all input
2441 * events for 3 seconds, when the "f" key is pressed. In a more
2442 * realistic code we would be freezing while a toolkit or Edje was
2443 * doing some UI changes, thawing it back afterwards.
2444 */
2445EAPI void evas_event_freeze (Evas *e) EINA_ARG_NONNULL(1);
2446
2447/**
2448 * Thaw a canvas out after freezing (for input events).
2449 *
2450 * @param e The canvas to thaw out.
2451 *
2452 * This will thaw out a canvas after a matching evas_event_freeze()
2453 * call. If this call completely thaws out a canvas, i.e., there's no
2454 * other unbalanced call to evas_event_freeze(), events will start to
2455 * be processed again, but any "missed" events will @b not be
2456 * evaluated.
2457 *
2458 * See evas_event_freeze() for an example.
2459 */
2460EAPI void evas_event_thaw (Evas *e) EINA_ARG_NONNULL(1);
2461
2462/**
2463 * Return the freeze count on input events of a given canvas.
2464 *
2465 * @param e The canvas to fetch the freeze count from.
2466 *
2467 * This returns the number of times the canvas has been told to freeze
2468 * input events. It is possible to call evas_event_freeze() multiple
2469 * times, and these must be matched by evas_event_thaw() calls. This
2470 * call allows the program to discover just how many times things have
2471 * been frozen in case it may want to break out of a deep freeze state
2472 * where the count is high.
2473 *
2474 * Example:
2475 * @code
2476 * extern Evas *evas;
2477 *
2478 * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
2479 * @endcode
2480 *
2481 */
2482EAPI int evas_event_freeze_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2483
2484/**
2485 * After thaw of a canvas, re-evaluate the state of objects and call callbacks
2486 *
2487 * @param e The canvas to evaluate after a thaw
2488 *
2489 * This is normally called after evas_event_thaw() to re-evaluate mouse
2490 * containment and other states and thus also call callbacks for mouse in and
2491 * out on new objects if the state change demands it.
2492 */
2493EAPI void evas_event_thaw_eval (Evas *e) EINA_ARG_NONNULL(1);
2494
2495/**
2496 * @}
2497 */
2498
2499/**
2500 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
2501 *
2502 * Functions to tell Evas that input events happened and should be
2503 * processed.
2504 *
2505 * @warning Most of the time these functions are @b not what you're looking for.
2506 * These functions should only be used if you're not working with ecore evas(or
2507 * another input handling system). If you're not using ecore evas please
2508 * consider using it, in most situation it will make life a lot easier.
2509 *
2510 * As explained in @ref intro_not_evas, Evas does not know how to poll
2511 * for input events, so the developer should do it and then feed such
2512 * events to the canvas to be processed. This is only required if
2513 * operating Evas directly. Modules such as Ecore_Evas do that for
2514 * you.
2515 *
2516 * Some of the functions in this group are exemplified @ref
2517 * Example_Evas_Events "here".
2518 *
2519 * @ingroup Evas_Canvas_Events
2520 */
2521
2522/**
2523 * @addtogroup Evas_Event_Feeding_Group
2524 * @{
2525 */
2526
2527/**
2528 * Get the number of mouse or multi presses currently active
2529 *
2530 * @p e The given canvas pointer.
2531 * @return The numer of presses (0 if none active).
2532 *
2533 * @since 1.2
2534 */
2535EAPI int evas_event_down_count_get (const Evas *e) EINA_ARG_NONNULL(1);
2536
2537/**
2538 * Mouse down event feed.
2539 *
2540 * @param e The given canvas pointer.
2541 * @param b The button number.
2542 * @param flags The evas button flags.
2543 * @param timestamp The timestamp of the mouse down event.
2544 * @param data The data for canvas.
2545 *
2546 * This function will set some evas properties that is necessary when
2547 * the mouse button is pressed. It prepares information to be treated
2548 * by the callback function.
2549 *
2550 */
2551EAPI void evas_event_feed_mouse_down (Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2552
2553/**
2554 * Mouse up event feed.
2555 *
2556 * @param e The given canvas pointer.
2557 * @param b The button number.
2558 * @param flags evas button flags.
2559 * @param timestamp The timestamp of the mouse up event.
2560 * @param data The data for canvas.
2561 *
2562 * This function will set some evas properties that is necessary when
2563 * the mouse button is released. It prepares information to be treated
2564 * by the callback function.
2565 *
2566 */
2567EAPI void evas_event_feed_mouse_up (Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2568
2569/**
2570 * Mouse move event feed.
2571 *
2572 * @param e The given canvas pointer.
2573 * @param x The horizontal position of the mouse pointer.
2574 * @param y The vertical position of the mouse pointer.
2575 * @param timestamp The timestamp of the mouse up event.
2576 * @param data The data for canvas.
2577 *
2578 * This function will set some evas properties that is necessary when
2579 * the mouse is moved from its last position. It prepares information
2580 * to be treated by the callback function.
2581 *
2582 */
2583EAPI void evas_event_feed_mouse_move (Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2584
2585/**
2586 * Mouse in event feed.
2587 *
2588 * @param e The given canvas pointer.
2589 * @param timestamp The timestamp of the mouse up event.
2590 * @param data The data for canvas.
2591 *
2592 * This function will set some evas properties that is necessary when
2593 * the mouse in event happens. It prepares information to be treated
2594 * by the callback function.
2595 *
2596 */
2597EAPI void evas_event_feed_mouse_in (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2598
2599/**
2600 * Mouse out event feed.
2601 *
2602 * @param e The given canvas pointer.
2603 * @param timestamp Timestamp of the mouse up event.
2604 * @param data The data for canvas.
2605 *
2606 * This function will set some evas properties that is necessary when
2607 * the mouse out event happens. It prepares information to be treated
2608 * by the callback function.
2609 *
2610 */
2611EAPI void evas_event_feed_mouse_out (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2612 EAPI 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);
2613 EAPI 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);
2614 EAPI 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);
2615
2616/**
2617 * Mouse cancel event feed.
2618 *
2619 * @param e The given canvas pointer.
2620 * @param timestamp The timestamp of the mouse up event.
2621 * @param data The data for canvas.
2622 *
2623 * This function will call evas_event_feed_mouse_up() when a
2624 * mouse cancel event happens.
2625 *
2626 */
2627EAPI void evas_event_feed_mouse_cancel (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2628
2629/**
2630 * Mouse wheel event feed.
2631 *
2632 * @param e The given canvas pointer.
2633 * @param direction The wheel mouse direction.
2634 * @param z How much mouse wheel was scrolled up or down.
2635 * @param timestamp The timestamp of the mouse up event.
2636 * @param data The data for canvas.
2637 *
2638 * This function will set some evas properties that is necessary when
2639 * the mouse wheel is scrolled up or down. It prepares information to
2640 * be treated by the callback function.
2641 *
2642 */
2643EAPI void evas_event_feed_mouse_wheel (Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2644
2645/**
2646 * Key down event feed
2647 *
2648 * @param e The canvas to thaw out
2649 * @param keyname Name of the key
2650 * @param key The key pressed.
2651 * @param string A String
2652 * @param compose The compose string
2653 * @param timestamp Timestamp of the mouse up event
2654 * @param data Data for canvas.
2655 *
2656 * This function will set some evas properties that is necessary when
2657 * a key is pressed. It prepares information to be treated by the
2658 * callback function.
2659 *
2660 */
2661EAPI 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);
2662
2663/**
2664 * Key up event feed
2665 *
2666 * @param e The canvas to thaw out
2667 * @param keyname Name of the key
2668 * @param key The key released.
2669 * @param string string
2670 * @param compose compose
2671 * @param timestamp Timestamp of the mouse up event
2672 * @param data Data for canvas.
2673 *
2674 * This function will set some evas properties that is necessary when
2675 * a key is released. It prepares information to be treated by the
2676 * callback function.
2677 *
2678 */
2679EAPI 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);
2680
2681/**
2682 * Hold event feed
2683 *
2684 * @param e The given canvas pointer.
2685 * @param hold The hold.
2686 * @param timestamp The timestamp of the mouse up event.
2687 * @param data The data for canvas.
2688 *
2689 * This function makes the object to stop sending events.
2690 *
2691 */
2692EAPI void evas_event_feed_hold (Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2693
2694/**
2695 * Re feed event.
2696 *
2697 * @param e The given canvas pointer.
2698 * @param event_copy the event to refeed
2699 * @param event_type Event type
2700 *
2701 * This function re-feeds the event pointed by event_copy
2702 *
2703 * This function call evas_event_feed_* functions, so it can
2704 * cause havoc if not used wisely. Please use it responsibly.
2705 */
2706EAPI void evas_event_refeed_event (Evas *e, void *event_copy, Evas_Callback_Type event_type) EINA_ARG_NONNULL(1);
2707
2708
2709/**
2710 * @}
2711 */
2712
2713/**
2714 * @}
2715 */
2716
2717/**
2718 * @defgroup Evas_Image_Group Image Functions
2719 *
2720 * Functions that deals with images at canvas level.
2721 *
2722 * @ingroup Evas_Canvas
2723 */
2724
2725/**
2726 * @addtogroup Evas_Image_Group
2727 * @{
2728 */
2729
2730/**
2731 * Flush the image cache of the canvas.
2732 *
2733 * @param e The given evas pointer.
2734 *
2735 * This function flushes image cache of canvas.
2736 *
2737 */
2738EAPI void evas_image_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2739
2740/**
2741 * Reload the image cache
2742 *
2743 * @param e The given evas pointer.
2744 *
2745 * This function reloads the image cache of canvas.
2746 *
2747 */
2748EAPI void evas_image_cache_reload (Evas *e) EINA_ARG_NONNULL(1);
2749
2750/**
2751 * Set the image cache.
2752 *
2753 * @param e The given evas pointer.
2754 * @param size The cache size.
2755 *
2756 * This function sets the image cache of canvas in bytes.
2757 *
2758 */
2759EAPI void evas_image_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2760
2761/**
2762 * Get the image cache
2763 *
2764 * @param e The given evas pointer.
2765 *
2766 * This function returns the image cache size of canvas in bytes.
2767 *
2768 */
2769EAPI int evas_image_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2770
2771/**
2772 * Get the maximum image size evas can possibly handle
2773 *
2774 * @param e The given evas pointer.
2775 * @param maxw Pointer to hold the return value in pixels of the maxumum width
2776 * @param maxh Pointer to hold the return value in pixels of the maximum height
2777 *
2778 * This function returns the larges image or surface size that evas can handle
2779 * in pixels, and if there is one, returns EINA_TRUE. It returns EINA_FALSE
2780 * if no extra constraint on maximum image size exists. You still should
2781 * check the return values of @p maxw and @p maxh as there may still be a
2782 * limit, just a much higher one.
2783 *
2784 * @since 1.1
2785 */
2786EAPI Eina_Bool evas_image_max_size_get (const Evas *e, int *maxw, int *maxh) EINA_ARG_NONNULL(1);
2787
2788/**
2789 * @}
2790 */
2791
2792/**
2793 * @defgroup Evas_Font_Group Font Functions
2794 *
2795 * Functions that deals with fonts.
2796 *
2797 * @ingroup Evas_Canvas
2798 */
2799
2800/**
2801 * Changes the font hinting for the given evas.
2802 *
2803 * @param e The given evas.
2804 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2805 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2806 * @ingroup Evas_Font_Group
2807 */
2808EAPI void evas_font_hinting_set (Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1);
2809
2810/**
2811 * Retrieves the font hinting used by the given evas.
2812 *
2813 * @param e The given evas to query.
2814 * @return The hinting in use, one of #EVAS_FONT_HINTING_NONE,
2815 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2816 * @ingroup Evas_Font_Group
2817 */
2818EAPI Evas_Font_Hinting_Flags evas_font_hinting_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2819
2820/**
2821 * Checks if the font hinting is supported by the given evas.
2822 *
2823 * @param e The given evas to query.
2824 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2825 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2826 * @return @c EINA_TRUE if it is supported, @c EINA_FALSE otherwise.
2827 * @ingroup Evas_Font_Group
2828 */
2829EAPI Eina_Bool evas_font_hinting_can_hint (const Evas *e, Evas_Font_Hinting_Flags hinting) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2830
2831
2832/**
2833 * Force the given evas and associated engine to flush its font cache.
2834 *
2835 * @param e The given evas to flush font cache.
2836 * @ingroup Evas_Font_Group
2837 */
2838EAPI void evas_font_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2839
2840/**
2841 * Changes the size of font cache of the given evas.
2842 *
2843 * @param e The given evas to flush font cache.
2844 * @param size The size, in bytes.
2845 *
2846 * @ingroup Evas_Font_Group
2847 */
2848EAPI void evas_font_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2849
2850/**
2851 * Changes the size of font cache of the given evas.
2852 *
2853 * @param e The given evas to flush font cache.
2854 * @return The size, in bytes.
2855 *
2856 * @ingroup Evas_Font_Group
2857 */
2858EAPI int evas_font_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2859
2860
2861/**
2862 * List of available font descriptions known or found by this evas.
2863 *
2864 * The list depends on Evas compile time configuration, such as
2865 * fontconfig support, and the paths provided at runtime as explained
2866 * in @ref Evas_Font_Path_Group.
2867 *
2868 * @param e The evas instance to query.
2869 * @return a newly allocated list of strings. Do not change the
2870 * strings. Be sure to call evas_font_available_list_free()
2871 * after you're done.
2872 *
2873 * @ingroup Evas_Font_Group
2874 */
2875EAPI Eina_List *evas_font_available_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2876
2877/**
2878 * Free list of font descriptions returned by evas_font_dir_available_list().
2879 *
2880 * @param e The evas instance that returned such list.
2881 * @param available the list returned by evas_font_dir_available_list().
2882 *
2883 * @ingroup Evas_Font_Group
2884 */
2885EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1);
2886
2887/**
2888 * @defgroup Evas_Font_Path_Group Font Path Functions
2889 *
2890 * Functions that edit the paths being used to load fonts.
2891 *
2892 * @ingroup Evas_Font_Group
2893 */
2894
2895/**
2896 * Removes all font paths loaded into memory for the given evas.
2897 * @param e The given evas.
2898 * @ingroup Evas_Font_Path_Group
2899 */
2900EAPI void evas_font_path_clear (Evas *e) EINA_ARG_NONNULL(1);
2901
2902/**
2903 * Appends a font path to the list of font paths used by the given evas.
2904 * @param e The given evas.
2905 * @param path The new font path.
2906 * @ingroup Evas_Font_Path_Group
2907 */
2908EAPI void evas_font_path_append (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2909
2910/**
2911 * Prepends a font path to the list of font paths used by the given evas.
2912 * @param e The given evas.
2913 * @param path The new font path.
2914 * @ingroup Evas_Font_Path_Group
2915 */
2916EAPI void evas_font_path_prepend (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2917
2918/**
2919 * Retrieves the list of font paths used by the given evas.
2920 * @param e The given evas.
2921 * @return The list of font paths used.
2922 * @ingroup Evas_Font_Path_Group
2923 */
2924EAPI const Eina_List *evas_font_path_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2925
2926/**
2927 * @defgroup Evas_Object_Group Generic Object Functions
2928 *
2929 * Functions that manipulate generic Evas objects.
2930 *
2931 * All Evas displaying units are Evas objects. One handles them all by
2932 * means of the handle ::Evas_Object. Besides Evas treats their
2933 * objects equally, they have @b types, which define their specific
2934 * behavior (and individual API).
2935 *
2936 * Evas comes with a set of built-in object types:
2937 * - rectangle,
2938 * - line,
2939 * - polygon,
2940 * - text,
2941 * - textblock and
2942 * - image.
2943 *
2944 * These functions apply to @b any Evas object, whichever type that
2945 * may have.
2946 *
2947 * @note The built-in types which are most used are rectangles, text
2948 * and images. In fact, with these ones one can create 2D interfaces
2949 * of arbitrary complexity and EFL makes it easy.
2950 */
2951
2952/**
2953 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
2954 *
2955 * Almost every evas object created will have some generic function used to
2956 * manipulate it. That's because there are a number of basic actions to be done
2957 * to objects that are irrespective of the object's type, things like:
2958 * @li Showing/Hiding
2959 * @li Setting(and getting) geometry
2960 * @li Bring up or down a layer
2961 * @li Color management
2962 * @li Handling focus
2963 * @li Clipping
2964 * @li Reference counting
2965 *
2966 * All of this issues are handled through the functions here grouped. Examples
2967 * of these function can be seen in @ref Example_Evas_Object_Manipulation(which
2968 * deals with the most common ones) and in @ref Example_Evas_Stacking(which
2969 * deals with stacking functions).
2970 *
2971 * @ingroup Evas_Object_Group
2972 */
2973
2974/**
2975 * @addtogroup Evas_Object_Group_Basic
2976 * @{
2977 */
2978
2979/**
2980 * Clip one object to another.
2981 *
2982 * @param obj The object to be clipped
2983 * @param clip The object to clip @p obj by
2984 *
2985 * This function will clip the object @p obj to the area occupied by
2986 * the object @p clip. This means the object @p obj will only be
2987 * visible within the area occupied by the clipping object (@p clip).
2988 *
2989 * The color of the object being clipped will be multiplied by the
2990 * color of the clipping one, so the resulting color for the former
2991 * will be <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color
2992 * element (red, green, blue and alpha).
2993 *
2994 * Clipping is recursive, so clipping objects may be clipped by
2995 * others, and their color will in term be multiplied. You may @b not
2996 * set up circular clipping lists (i.e. object 1 clips object 2, which
2997 * clips object 1): the behavior of Evas is undefined in this case.
2998 *
2999 * Objects which do not clip others are visible in the canvas as
3000 * normal; <b>those that clip one or more objects become invisible
3001 * themselves</b>, only affecting what they clip. If an object ceases
3002 * to have other objects being clipped by it, it will become visible
3003 * again.
3004 *
3005 * The visibility of an object affects the objects that are clipped by
3006 * it, so if the object clipping others is not shown (as in
3007 * evas_object_show()), the objects clipped by it will not be shown
3008 * either.
3009 *
3010 * If @p obj was being clipped by another object when this function is
3011 * called, it gets implicitly removed from the old clipper's domain
3012 * and is made now to be clipped by its new clipper.
3013 *
3014 * The following figure illustrates some clipping in Evas:
3015 *
3016 * @image html clipping.png
3017 * @image rtf clipping.png
3018 * @image latex clipping.eps
3019 *
3020 * @note At the moment the <b>only objects that can validly be used to
3021 * clip other objects are rectangle objects</b>. All other object
3022 * types are invalid and the result of using them is undefined. The
3023 * clip object @p clip must be a valid object, but can also be @c
3024 * NULL, in which case the effect of this function is the same as
3025 * calling evas_object_clip_unset() on the @p obj object.
3026 *
3027 * Example:
3028 * @dontinclude evas-object-manipulation.c
3029 * @skip solid white clipper (note that it's the default color for a
3030 * @until evas_object_show(d.clipper);
3031 *
3032 * See the full @ref Example_Evas_Object_Manipulation "example".
3033 */
3034EAPI void evas_object_clip_set (Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2);
3035
3036/**
3037 * Get the object clipping @p obj (if any).
3038 *
3039 * @param obj The object to get the clipper from
3040 *
3041 * This function returns the object clipping @p obj. If @p obj is
3042 * not being clipped at all, @c NULL is returned. The object @p obj
3043 * must be a valid ::Evas_Object.
3044 *
3045 * See also evas_object_clip_set(), evas_object_clip_unset() and
3046 * evas_object_clipees_get().
3047 *
3048 * Example:
3049 * @dontinclude evas-object-manipulation.c
3050 * @skip if (evas_object_clip_get(d.img) == d.clipper)
3051 * @until return
3052 *
3053 * See the full @ref Example_Evas_Object_Manipulation "example".
3054 */
3055EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3056
3057/**
3058 * Disable/cease clipping on a clipped @p obj object.
3059 *
3060 * @param obj The object to cease clipping on
3061 *
3062 * This function disables clipping for the object @p obj, if it was
3063 * already clipped, i.e., its visibility and color get detached from
3064 * the previous clipper. If it wasn't, this has no effect. The object
3065 * @p obj must be a valid ::Evas_Object.
3066 *
3067 * See also evas_object_clip_set() (for an example),
3068 * evas_object_clipees_get() and evas_object_clip_get().
3069 *
3070 */
3071EAPI void evas_object_clip_unset (Evas_Object *obj);
3072
3073/**
3074 * Return a list of objects currently clipped by @p obj.
3075 *
3076 * @param obj The object to get a list of clippees from
3077 * @return a list of objects being clipped by @p obj
3078 *
3079 * This returns the internal list handle that contains all objects
3080 * clipped by the object @p obj. If none are clipped by it, the call
3081 * returns @c NULL. This list is only valid until the clip list is
3082 * changed and should be fetched again with another call to
3083 * evas_object_clipees_get() if any objects being clipped by this
3084 * object are unclipped, clipped by a new object, deleted or get the
3085 * clipper deleted. These operations will invalidate the list
3086 * returned, so it should not be used anymore after that point. Any
3087 * use of the list after this may have undefined results, possibly
3088 * leading to crashes. The object @p obj must be a valid
3089 * ::Evas_Object.
3090 *
3091 * See also evas_object_clip_set(), evas_object_clip_unset() and
3092 * evas_object_clip_get().
3093 *
3094 * Example:
3095 * @code
3096 * extern Evas_Object *obj;
3097 * Evas_Object *clipper;
3098 *
3099 * clipper = evas_object_clip_get(obj);
3100 * if (clipper)
3101 * {
3102 * Eina_List *clippees, *l;
3103 * Evas_Object *obj_tmp;
3104 *
3105 * clippees = evas_object_clipees_get(clipper);
3106 * printf("Clipper clips %i objects\n", eina_list_count(clippees));
3107 * EINA_LIST_FOREACH(clippees, l, obj_tmp)
3108 * evas_object_show(obj_tmp);
3109 * }
3110 * @endcode
3111 */
3112EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3113
3114
3115/**
3116 * Sets or unsets a given object as the currently focused one on its
3117 * canvas.
3118 *
3119 * @param obj The object to be focused or unfocused.
3120 * @param focus @c EINA_TRUE, to set it as focused or @c EINA_FALSE,
3121 * to take away the focus from it.
3122 *
3123 * Changing focus only affects where (key) input events go. There can
3124 * be only one object focused at any time. If @p focus is @c
3125 * EINA_TRUE, @p obj will be set as the currently focused object and
3126 * it will receive all keyboard events that are not exclusive key
3127 * grabs on other objects.
3128 *
3129 * Example:
3130 * @dontinclude evas-events.c
3131 * @skip evas_object_focus_set
3132 * @until evas_object_focus_set
3133 *
3134 * See the full example @ref Example_Evas_Events "here".
3135 *
3136 * @see evas_object_focus_get
3137 * @see evas_focus_get
3138 * @see evas_object_key_grab
3139 * @see evas_object_key_ungrab
3140 */
3141EAPI void evas_object_focus_set (Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
3142
3143/**
3144 * Retrieve whether an object has the focus.
3145 *
3146 * @param obj The object to retrieve focus information from.
3147 * @return @c EINA_TRUE if the object has the focus, @c EINA_FALSE
3148 * otherwise.
3149 *
3150 * If the passed object is the currently focused one, @c EINA_TRUE is
3151 * returned. @c EINA_FALSE is returned, otherwise.
3152 *
3153 * Example:
3154 * @dontinclude evas-events.c
3155 * @skip And again
3156 * @until something is bad
3157 *
3158 * See the full example @ref Example_Evas_Events "here".
3159 *
3160 * @see evas_object_focus_set
3161 * @see evas_focus_get
3162 * @see evas_object_key_grab
3163 * @see evas_object_key_ungrab
3164 */
3165EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3166
3167
3168/**
3169 * Sets the layer of the its canvas that the given object will be part
3170 * of.
3171 *
3172 * @param obj The given Evas object.
3173 * @param l The number of the layer to place the object on.
3174 * Must be between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
3175 *
3176 * If you don't use this function, you'll be dealing with an @b unique
3177 * layer of objects, the default one. Additional layers are handy when
3178 * you don't want a set of objects to interfere with another set with
3179 * regard to @b stacking. Two layers are completely disjoint in that
3180 * matter.
3181 *
3182 * This is a low-level function, which you'd be using when something
3183 * should be always on top, for example.
3184 *
3185 * @warning Be careful, it doesn't make sense to change the layer of
3186 * smart objects' children. Smart objects have a layer of their own,
3187 * which should contain all their children objects.
3188 *
3189 * @see evas_object_layer_get()
3190 */
3191EAPI void evas_object_layer_set (Evas_Object *obj, short l) EINA_ARG_NONNULL(1);
3192
3193/**
3194 * Retrieves the layer of its canvas that the given object is part of.
3195 *
3196 * @param obj The given Evas object to query layer from
3197 * @return Number of the its layer
3198 *
3199 * @see evas_object_layer_set()
3200 */
3201EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3202
3203
3204/**
3205 * Sets the name of the given Evas object to the given name.
3206 *
3207 * @param obj The given object.
3208 * @param name The given name.
3209 *
3210 * There might be occasions where one would like to name his/her
3211 * objects.
3212 *
3213 * Example:
3214 * @dontinclude evas-events.c
3215 * @skip d.bg = evas_object_rectangle_add(d.canvas);
3216 * @until evas_object_name_set(d.bg, "our dear rectangle");
3217 *
3218 * See the full @ref Example_Evas_Events "example".
3219 */
3220EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
3221
3222/**
3223 * Retrieves the name of the given Evas object.
3224 *
3225 * @param obj The given object.
3226 * @return The name of the object or @c NULL, if no name has been given
3227 * to it.
3228 *
3229 * Example:
3230 * @dontinclude evas-events.c
3231 * @skip fprintf(stdout, "An object got focused: %s\n",
3232 * @until evas_focus_get
3233 *
3234 * See the full @ref Example_Evas_Events "example".
3235 */
3236EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3237
3238
3239/**
3240 * Increments object reference count to defer its deletion.
3241 *
3242 * @param obj The given Evas object to reference
3243 *
3244 * This increments the reference count of an object, which if greater
3245 * than 0 will defer deletion by evas_object_del() until all
3246 * references are released back (counter back to 0). References cannot
3247 * go below 0 and unreferencing past that will result in the reference
3248 * count being limited to 0. References are limited to <c>2^32 - 1</c>
3249 * for an object. Referencing it more than this will result in it
3250 * being limited to this value.
3251 *
3252 * @see evas_object_unref()
3253 * @see evas_object_del()
3254 *
3255 * @note This is a <b>very simple<b> reference counting mechanism! For
3256 * instance, Evas is not ready to check for pending references on a
3257 * canvas deletion, or things like that. This is useful on scenarios
3258 * where, inside a code block, callbacks exist which would possibly
3259 * delete an object we are operating on afterwards. Then, one would
3260 * evas_object_ref() it on the beginning of the block and
3261 * evas_object_unref() it on the end. It would then be deleted at this
3262 * point, if it should be.
3263 *
3264 * Example:
3265 * @code
3266 * evas_object_ref(obj);
3267 *
3268 * // action here...
3269 * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
3270 * // more action here...
3271 * evas_object_unref(obj);
3272 * @endcode
3273 *
3274 * @ingroup Evas_Object_Group_Basic
3275 * @since 1.1.0
3276 */
3277EAPI void evas_object_ref (Evas_Object *obj);
3278
3279/**
3280 * Decrements object reference count.
3281 *
3282 * @param obj The given Evas object to unreference
3283 *
3284 * This decrements the reference count of an object. If the object has
3285 * had evas_object_del() called on it while references were more than
3286 * 0, it will be deleted at the time this function is called and puts
3287 * the counter back to 0. See evas_object_ref() for more information.
3288 *
3289 * @see evas_object_ref() (for an example)
3290 * @see evas_object_del()
3291 *
3292 * @ingroup Evas_Object_Group_Basic
3293 * @since 1.1.0
3294 */
3295EAPI void evas_object_unref (Evas_Object *obj);
3296
3297
3298/**
3299 * Marks the given Evas object for deletion (when Evas will free its
3300 * memory).
3301 *
3302 * @param obj The given Evas object.
3303 *
3304 * This call will mark @p obj for deletion, which will take place
3305 * whenever it has no more references to it (see evas_object_ref() and
3306 * evas_object_unref()).
3307 *
3308 * At actual deletion time, which may or may not be just after this
3309 * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks will
3310 * be called. If the object currently had the focus, its
3311 * ::EVAS_CALLBACK_FOCUS_OUT callback will also be called.
3312 *
3313 * @see evas_object_ref()
3314 * @see evas_object_unref()
3315 *
3316 * @ingroup Evas_Object_Group_Basic
3317 */
3318EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
3319
3320/**
3321 * Move the given Evas object to the given location inside its
3322 * canvas' viewport.
3323 *
3324 * @param obj The given Evas object.
3325 * @param x X position to move the object to, in canvas units.
3326 * @param y Y position to move the object to, in canvas units.
3327 *
3328 * Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback
3329 * will be called.
3330 *
3331 * @note Naturally, newly created objects are placed at the canvas'
3332 * origin: <code>0, 0</code>.
3333 *
3334 * Example:
3335 * @dontinclude evas-object-manipulation.c
3336 * @skip evas_object_image_border_set(d.clipper_border, 3, 3, 3, 3);
3337 * @until evas_object_show
3338 *
3339 * See the full @ref Example_Evas_Object_Manipulation "example".
3340 *
3341 * @ingroup Evas_Object_Group_Basic
3342 */
3343EAPI void evas_object_move (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
3344
3345/**
3346 * Changes the size of the given Evas object.
3347 *
3348 * @param obj The given Evas object.
3349 * @param w The new width of the Evas object.
3350 * @param h The new height of the Evas object.
3351 *
3352 * Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback
3353 * will be called.
3354 *
3355 * @note Newly created objects have zeroed dimensions. Then, you most
3356 * probably want to use evas_object_resize() on them after they are
3357 * created.
3358 *
3359 * @note Be aware that resizing an object changes its drawing area,
3360 * but that does imply the object is rescaled! For instance, images
3361 * are filled inside their drawing area using the specifications of
3362 * evas_object_image_fill_set(). Thus to scale the image to match
3363 * exactly your drawing area, you need to change the
3364 * evas_object_image_fill_set() as well.
3365 *
3366 * @note This is more evident in images, but text, textblock, lines
3367 * and polygons will behave similarly. Check their specific APIs to
3368 * know how to achieve your desired behavior. Consider the following
3369 * example:
3370 *
3371 * @code
3372 * // rescale image to fill exactly its area without tiling:
3373 * evas_object_resize(img, w, h);
3374 * evas_object_image_fill_set(img, 0, 0, w, h);
3375 * @endcode
3376 *
3377 * @ingroup Evas_Object_Group_Basic
3378 */
3379EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
3380
3381/**
3382 * Retrieves the position and (rectangular) size of the given Evas
3383 * object.
3384 *
3385 * @param obj The given Evas object.
3386 * @param x Pointer to an integer in which to store the X coordinate
3387 * of the object.
3388 * @param y Pointer to an integer in which to store the Y coordinate
3389 * of the object.
3390 * @param w Pointer to an integer in which to store the width of the
3391 * object.
3392 * @param h Pointer to an integer in which to store the height of the
3393 * object.
3394 *
3395 * The position, naturally, will be relative to the top left corner of
3396 * the canvas' viewport.
3397 *
3398 * @note Use @c NULL pointers on the geometry components you're not
3399 * interested in: they'll be ignored by the function.
3400 *
3401 * Example:
3402 * @dontinclude evas-events.c
3403 * @skip int w, h, cw, ch;
3404 * @until return
3405 *
3406 * See the full @ref Example_Evas_Events "example".
3407 *
3408 * @ingroup Evas_Object_Group_Basic
3409 */
3410EAPI 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);
3411
3412
3413/**
3414 * Makes the given Evas object visible.
3415 *
3416 * @param obj The given Evas object.
3417 *
3418 * Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW
3419 * callback will be called.
3420 *
3421 * @see evas_object_hide() for more on object visibility.
3422 * @see evas_object_visible_get()
3423 *
3424 * @ingroup Evas_Object_Group_Basic
3425 */
3426EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1);
3427
3428/**
3429 * Makes the given Evas object invisible.
3430 *
3431 * @param obj The given Evas object.
3432 *
3433 * Hidden objects, besides not being shown at all in your canvas,
3434 * won't be checked for changes on the canvas rendering
3435 * process. Furthermore, they will not catch input events. Thus, they
3436 * are much ligher (in processing needs) than an object that is
3437 * invisible due to indirect causes, such as being clipped or out of
3438 * the canvas' viewport.
3439 *
3440 * Besides becoming hidden, @p obj object's ::EVAS_CALLBACK_SHOW
3441 * callback will be called.
3442 *
3443 * @note All objects are created in the hidden state! If you want them
3444 * shown, use evas_object_show() after their creation.
3445 *
3446 * @see evas_object_show()
3447 * @see evas_object_visible_get()
3448 *
3449 * Example:
3450 * @dontinclude evas-object-manipulation.c
3451 * @skip if (evas_object_visible_get(d.clipper))
3452 * @until return
3453 *
3454 * See the full @ref Example_Evas_Object_Manipulation "example".
3455 *
3456 * @ingroup Evas_Object_Group_Basic
3457 */
3458EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1);
3459
3460/**
3461 * Retrieves whether or not the given Evas object is visible.
3462 *
3463 * @param obj The given Evas object.
3464 * @return @c EINA_TRUE if the object is visible, @c EINA_FALSE
3465 * otherwise.
3466 *
3467 * This retrieves an object's visibility as the one enforced by
3468 * evas_object_show() and evas_object_hide().
3469 *
3470 * @note The value returned isn't, by any means, influenced by
3471 * clippers covering @obj, it being out of its canvas' viewport or
3472 * stacked below other object.
3473 *
3474 * @see evas_object_show()
3475 * @see evas_object_hide() (for an example)
3476 *
3477 * @ingroup Evas_Object_Group_Basic
3478 */
3479EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3480
3481
3482/**
3483 * Sets the general/main color of the given Evas object to the given
3484 * one.
3485 *
3486 * @param obj The given Evas object.
3487 * @param r The red component of the given color.
3488 * @param g The green component of the given color.
3489 * @param b The blue component of the given color.
3490 * @param a The alpha component of the given color.
3491 *
3492 * @see evas_object_color_get() (for an example)
3493 * @note These color values are expected to be premultiplied by @p a.
3494 *
3495 * @ingroup Evas_Object_Group_Basic
3496 */
3497EAPI void evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
3498
3499/**
3500 * Retrieves the general/main color of the given Evas object.
3501 *
3502 * @param obj The given Evas object to retrieve color from.
3503 * @param r Pointer to an integer in which to store the red component
3504 * of the color.
3505 * @param g Pointer to an integer in which to store the green
3506 * component of the color.
3507 * @param b Pointer to an integer in which to store the blue component
3508 * of the color.
3509 * @param a Pointer to an integer in which to store the alpha
3510 * component of the color.
3511 *
3512 * Retrieves the “main” color's RGB component (and alpha channel)
3513 * values, <b>which range from 0 to 255</b>. For the alpha channel,
3514 * which defines the object's transparency level, 0 means totally
3515 * transparent, while 255 means opaque. These color values are
3516 * premultiplied by the alpha value.
3517 *
3518 * Usually you’ll use this attribute for text and rectangle objects,
3519 * where the “main” color is their unique one. If set for objects
3520 * which themselves have colors, like the images one, those colors get
3521 * modulated by this one.
3522 *
3523 * @note All newly created Evas rectangles get the default color
3524 * values of <code>255 255 255 255</code> (opaque white).
3525 *
3526 * @note Use @c NULL pointers on the components you're not interested
3527 * in: they'll be ignored by the function.
3528 *
3529 * Example:
3530 * @dontinclude evas-object-manipulation.c
3531 * @skip int alpha, r, g, b;
3532 * @until return
3533 *
3534 * See the full @ref Example_Evas_Object_Manipulation "example".
3535 *
3536 * @ingroup Evas_Object_Group_Basic
3537 */
3538EAPI void evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
3539
3540
3541/**
3542 * Retrieves the Evas canvas that the given object lives on.
3543 *
3544 * @param obj The given Evas object.
3545 * @return A pointer to the canvas where the object is on.
3546 *
3547 * This function is most useful at code contexts where you need to
3548 * operate on the canvas but have only the object pointer.
3549 *
3550 * @ingroup Evas_Object_Group_Basic
3551 */
3552EAPI Evas *evas_object_evas_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3553
3554/**
3555 * Retrieves the type of the given Evas object.
3556 *
3557 * @param obj The given object.
3558 * @return The type of the object.
3559 *
3560 * For Evas' builtin types, the return strings will be one of:
3561 * - <c>"rectangle"</c>,
3562 * - <c>"line"</c>,
3563 * - <c>"polygon"</c>,
3564 * - <c>"text"</c>,
3565 * - <c>"textblock"</c> and
3566 * - <c>"image"</c>.
3567 *
3568 * For Evas smart objects (see @ref Evas_Smart_Group), the name of the
3569 * smart class itself is returned on this call. For the built-in smart
3570 * objects, these names are:
3571 * - <c>"EvasObjectSmartClipped"</c>, for the clipped smart object
3572 * - <c>"Evas_Object_Box"</c>, for the box object and
3573 * - <c>"Evas_Object_Table"</c>, for the table object.
3574 *
3575 * Example:
3576 * @dontinclude evas-object-manipulation.c
3577 * @skip d.img = evas_object_image_filled_add(d.canvas);
3578 * @until border on the
3579 *
3580 * See the full @ref Example_Evas_Object_Manipulation "example".
3581 */
3582EAPI const char *evas_object_type_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3583
3584/**
3585 * Raise @p obj to the top of its layer.
3586 *
3587 * @param obj the object to raise
3588 *
3589 * @p obj will, then, be the highest one in the layer it belongs
3590 * to. Object on other layers won't get touched.
3591 *
3592 * @see evas_object_stack_above()
3593 * @see evas_object_stack_below()
3594 * @see evas_object_lower()
3595 */
3596EAPI void evas_object_raise (Evas_Object *obj) EINA_ARG_NONNULL(1);
3597
3598/**
3599 * Lower @p obj to the bottom of its layer.
3600 *
3601 * @param obj the object to lower
3602 *
3603 * @p obj will, then, be the lowest one in the layer it belongs
3604 * to. Objects on other layers won't get touched.
3605 *
3606 * @see evas_object_stack_above()
3607 * @see evas_object_stack_below()
3608 * @see evas_object_raise()
3609 */
3610EAPI void evas_object_lower (Evas_Object *obj) EINA_ARG_NONNULL(1);
3611
3612/**
3613 * Stack @p obj immediately above @p above
3614 *
3615 * @param obj the object to stack
3616 * @param above the object above which to stack
3617 *
3618 * Objects, in a given canvas, are stacked in the order they get added
3619 * to it. This means that, if they overlap, the highest ones will
3620 * cover the lowest ones, in that order. This function is a way to
3621 * change the stacking order for the objects.
3622 *
3623 * This function is intended to be used with <b>objects belonging to
3624 * the same layer</b> in a given canvas, otherwise it will fail (and
3625 * accomplish nothing).
3626 *
3627 * If you have smart objects on your canvas and @p obj is a member of
3628 * one of them, then @p above must also be a member of the same
3629 * smart object.
3630 *
3631 * Similarly, if @p obj is not a member of a smart object, @p above
3632 * must not be either.
3633 *
3634 * @see evas_object_layer_get()
3635 * @see evas_object_layer_set()
3636 * @see evas_object_stack_below()
3637 */
3638EAPI void evas_object_stack_above (Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2);
3639
3640/**
3641 * Stack @p obj immediately below @p below
3642 *
3643 * @param obj the object to stack
3644 * @param below the object below which to stack
3645 *
3646 * Objects, in a given canvas, are stacked in the order they get added
3647 * to it. This means that, if they overlap, the highest ones will
3648 * cover the lowest ones, in that order. This function is a way to
3649 * change the stacking order for the objects.
3650 *
3651 * This function is intended to be used with <b>objects belonging to
3652 * the same layer</b> in a given canvas, otherwise it will fail (and
3653 * accomplish nothing).
3654 *
3655 * If you have smart objects on your canvas and @p obj is a member of
3656 * one of them, then @p below must also be a member of the same
3657 * smart object.
3658 *
3659 * Similarly, if @p obj is not a member of a smart object, @p below
3660 * must not be either.
3661 *
3662 * @see evas_object_layer_get()
3663 * @see evas_object_layer_set()
3664 * @see evas_object_stack_below()
3665 */
3666EAPI void evas_object_stack_below (Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2);
3667
3668/**
3669 * Get the Evas object stacked right above @p obj
3670 *
3671 * @param obj an #Evas_Object
3672 * @return the #Evas_Object directly above @p obj, if any, or @c NULL,
3673 * if none
3674 *
3675 * This function will traverse layers in its search, if there are
3676 * objects on layers above the one @p obj is placed at.
3677 *
3678 * @see evas_object_layer_get()
3679 * @see evas_object_layer_set()
3680 * @see evas_object_below_get()
3681 *
3682 */
3683EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3684
3685/**
3686 * Get the Evas object stacked right below @p obj
3687 *
3688 * @param obj an #Evas_Object
3689 * @return the #Evas_Object directly below @p obj, if any, or @c NULL,
3690 * if none
3691 *
3692 * This function will traverse layers in its search, if there are
3693 * objects on layers below the one @p obj is placed at.
3694 *
3695 * @see evas_object_layer_get()
3696 * @see evas_object_layer_set()
3697 * @see evas_object_below_get()
3698 */
3699EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3700
3701/**
3702 * @}
3703 */
3704
3705/**
3706 * @defgroup Evas_Object_Group_Events Object Events
3707 *
3708 * Objects generate events when they are moved, resized, when their
3709 * visibility change, when they are deleted and so on. These methods
3710 * allow one to be notified about and to handle such events.
3711 *
3712 * Objects also generate events on input (keyboard and mouse), if they
3713 * accept them (are visible, focused, etc).
3714 *
3715 * For each of those events, Evas provides a way for one to register
3716 * callback functions to be issued just after they happen.
3717 *
3718 * The following figure illustrates some Evas (event) callbacks:
3719 *
3720 * @image html evas-callbacks.png
3721 * @image rtf evas-callbacks.png
3722 * @image latex evas-callbacks.eps
3723 *
3724 * Thees events have their values in the #Evas_Callback_Type
3725 * enumeration, which has also ones happening on the canvas level (se
3726 * #Evas_Canvas_Events).
3727 *
3728 * Examples on this group of functions can be found @ref
3729 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
3730 *
3731 * @ingroup Evas_Object_Group
3732 */
3733
3734/**
3735 * @addtogroup Evas_Object_Group_Events
3736 * @{
3737 */
3738
3739/**
3740 * Add (register) a callback function to a given Evas object event.
3741 *
3742 * @param obj Object to attach a callback to
3743 * @param type The type of event that will trigger the callback
3744 * @param func The function to be called when the event is triggered
3745 * @param data The data pointer to be passed to @p func
3746 *
3747 * This function adds a function callback to an object when the event
3748 * of type @p type occurs on object @p obj. The function is @p func.
3749 *
3750 * In the event of a memory allocation error during addition of the
3751 * callback to the object, evas_alloc_error() should be used to
3752 * determine the nature of the error, if any, and the program should
3753 * sensibly try and recover.
3754 *
3755 * A callback function must have the ::Evas_Object_Event_Cb prototype
3756 * definition. The first parameter (@p data) in this definition will
3757 * have the same value passed to evas_object_event_callback_add() as
3758 * the @p data parameter, at runtime. The second parameter @p e is the
3759 * canvas pointer on which the event occurred. The third parameter is
3760 * a pointer to the object on which event occurred. Finally, the
3761 * fourth parameter @p event_info is a pointer to a data structure
3762 * that may or may not be passed to the callback, depending on the
3763 * event type that triggered the callback. This is so because some
3764 * events don't carry extra context with them, but others do.
3765 *
3766 * The event type @p type to trigger the function may be one of
3767 * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT,
3768 * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP,
3769 * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL,
3770 * #EVAS_CALLBACK_MULTI_DOWN, #EVAS_CALLBACK_MULTI_UP,
3771 * #EVAS_CALLBACK_MULTI_MOVE, #EVAS_CALLBACK_FREE,
3772 * #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP,
3773 * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT,
3774 * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE,
3775 * #EVAS_CALLBACK_RESIZE, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL,
3776 * #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS,
3777 * #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED.
3778 *
3779 * This determines the kind of event that will trigger the callback.
3780 * What follows is a list explaining better the nature of each type of
3781 * event, along with their associated @p event_info pointers:
3782 *
3783 * - #EVAS_CALLBACK_MOUSE_IN: @p event_info is a pointer to an
3784 * #Evas_Event_Mouse_In struct\n\n
3785 * This event is triggered when the mouse pointer enters the area
3786 * (not shaded by other objects) of the object @p obj. This may
3787 * occur by the mouse pointer being moved by
3788 * evas_event_feed_mouse_move() calls, or by the object being shown,
3789 * raised, moved, resized, or other objects being moved out of the
3790 * way, hidden or lowered, whatever may cause the mouse pointer to
3791 * get on top of @p obj, having been on top of another object
3792 * previously.
3793 *
3794 * - #EVAS_CALLBACK_MOUSE_OUT: @p event_info is a pointer to an
3795 * #Evas_Event_Mouse_Out struct\n\n
3796 * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is,
3797 * but it occurs when the mouse pointer exits an object's area. Note
3798 * that no mouse out events will be reported if the mouse pointer is
3799 * implicitly grabbed to an object (mouse buttons are down, having
3800 * been pressed while the pointer was over that object). In these
3801 * cases, mouse out events will be reported once all buttons are
3802 * released, if the mouse pointer has left the object's area. The
3803 * indirect ways of taking off the mouse pointer from an object,
3804 * like cited above, for #EVAS_CALLBACK_MOUSE_IN, also apply here,
3805 * naturally.
3806 *
3807 * - #EVAS_CALLBACK_MOUSE_DOWN: @p event_info is a pointer to an
3808 * #Evas_Event_Mouse_Down struct\n\n
3809 * This event is triggered by a mouse button being pressed while the
3810 * mouse pointer is over an object. If the pointer mode for Evas is
3811 * #EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this
3812 * object to <b>passively grab the mouse</b> until all mouse buttons
3813 * have been released: all future mouse events will be reported to
3814 * only this object until no buttons are down. That includes mouse
3815 * move events, mouse in and mouse out events, and further button
3816 * presses. When all buttons are released, event propagation will
3817 * occur as normal (see #Evas_Object_Pointer_Mode).
3818 *
3819 * - #EVAS_CALLBACK_MOUSE_UP: @p event_info is a pointer to an
3820 * #Evas_Event_Mouse_Up struct\n\n
3821 * This event is triggered by a mouse button being released while
3822 * the mouse pointer is over an object's area (or when passively
3823 * grabbed to an object).
3824 *
3825 * - #EVAS_CALLBACK_MOUSE_MOVE: @p event_info is a pointer to an
3826 * #Evas_Event_Mouse_Move struct\n\n
3827 * This event is triggered by the mouse pointer being moved while
3828 * over an object's area (or while passively grabbed to an object).
3829 *
3830 * - #EVAS_CALLBACK_MOUSE_WHEEL: @p event_info is a pointer to an
3831 * #Evas_Event_Mouse_Wheel struct\n\n
3832 * This event is triggered by the mouse wheel being rolled while the
3833 * mouse pointer is over an object (or passively grabbed to an
3834 * object).
3835 *
3836 * - #EVAS_CALLBACK_MULTI_DOWN: @p event_info is a pointer to an
3837 * #Evas_Event_Multi_Down struct
3838 *
3839 * - #EVAS_CALLBACK_MULTI_UP: @p event_info is a pointer to an
3840 * #Evas_Event_Multi_Up struct
3841 *
3842 * - #EVAS_CALLBACK_MULTI_MOVE: @p event_info is a pointer to an
3843 * #Evas_Event_Multi_Move struct
3844 *
3845 * - #EVAS_CALLBACK_FREE: @p event_info is @c NULL \n\n
3846 * This event is triggered just before Evas is about to free all
3847 * memory used by an object and remove all references to it. This is
3848 * useful for programs to use if they attached data to an object and
3849 * want to free it when the object is deleted. The object is still
3850 * valid when this callback is called, but after it returns, there
3851 * is no guarantee on the object's validity.
3852 *
3853 * - #EVAS_CALLBACK_KEY_DOWN: @p event_info is a pointer to an
3854 * #Evas_Event_Key_Down struct\n\n
3855 * This callback is called when a key is pressed and the focus is on
3856 * the object, or a key has been grabbed to a particular object
3857 * which wants to intercept the key press regardless of what object
3858 * has the focus.
3859 *
3860 * - #EVAS_CALLBACK_KEY_UP: @p event_info is a pointer to an
3861 * #Evas_Event_Key_Up struct \n\n
3862 * This callback is called when a key is released and the focus is
3863 * on the object, or a key has been grabbed to a particular object
3864 * which wants to intercept the key release regardless of what
3865 * object has the focus.
3866 *
3867 * - #EVAS_CALLBACK_FOCUS_IN: @p event_info is @c NULL \n\n
3868 * This event is called when an object gains the focus. When it is
3869 * called the object has already gained the focus.
3870 *
3871 * - #EVAS_CALLBACK_FOCUS_OUT: @p event_info is @c NULL \n\n
3872 * This event is triggered when an object loses the focus. When it
3873 * is called the object has already lost the focus.
3874 *
3875 * - #EVAS_CALLBACK_SHOW: @p event_info is @c NULL \n\n
3876 * This event is triggered by the object being shown by
3877 * evas_object_show().
3878 *
3879 * - #EVAS_CALLBACK_HIDE: @p event_info is @c NULL \n\n
3880 * This event is triggered by an object being hidden by
3881 * evas_object_hide().
3882 *
3883 * - #EVAS_CALLBACK_MOVE: @p event_info is @c NULL \n\n
3884 * This event is triggered by an object being
3885 * moved. evas_object_move() can trigger this, as can any
3886 * object-specific manipulations that would mean the object's origin
3887 * could move.
3888 *
3889 * - #EVAS_CALLBACK_RESIZE: @p event_info is @c NULL \n\n
3890 * This event is triggered by an object being resized. Resizes can
3891 * be triggered by evas_object_resize() or by any object-specific
3892 * calls that may cause the object to resize.
3893 *
3894 * - #EVAS_CALLBACK_RESTACK: @p event_info is @c NULL \n\n
3895 * This event is triggered by an object being re-stacked. Stacking
3896 * changes can be triggered by
3897 * evas_object_stack_below()/evas_object_stack_above() and others.
3898 *
3899 * - #EVAS_CALLBACK_DEL: @p event_info is @c NULL.
3900 *
3901 * - #EVAS_CALLBACK_HOLD: @p event_info is a pointer to an
3902 * #Evas_Event_Hold struct
3903 *
3904 * - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @p event_info is @c NULL.
3905 *
3906 * - #EVAS_CALLBACK_IMAGE_PRELOADED: @p event_info is @c NULL.
3907 *
3908 * - #EVAS_CALLBACK_IMAGE_UNLOADED: @p event_info is @c NULL.
3909 *
3910 * @note Be careful not to add the same callback multiple times, if
3911 * that's not what you want, because Evas won't check if a callback
3912 * existed before exactly as the one being registered (and thus, call
3913 * it more than once on the event, in this case). This would make
3914 * sense if you passed different functions and/or callback data, only.
3915 *
3916 * Example:
3917 * @dontinclude evas-events.c
3918 * @skip evas_object_event_callback_add(
3919 * @until }
3920 *
3921 * See the full example @ref Example_Evas_Events "here".
3922 *
3923 */
3924 EAPI 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);
3925
3926/**
3927 * Add (register) a callback function to a given Evas object event with a
3928 * non-default priority set. Except for the priority field, it's exactly the
3929 * same as @ref evas_object_event_callback_add
3930 *
3931 * @param obj Object to attach a callback to
3932 * @param type The type of event that will trigger the callback
3933 * @param priority The priority of the callback, lower values called first.
3934 * @param func The function to be called when the event is triggered
3935 * @param data The data pointer to be passed to @p func
3936 *
3937 * @see evas_object_event_callback_add
3938 * @since 1.1.0
3939 */
3940EAPI 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);
3941
3942/**
3943 * Delete a callback function from an object
3944 *
3945 * @param obj Object to remove a callback from
3946 * @param type The type of event that was triggering the callback
3947 * @param func The function that was to be called when the event was triggered
3948 * @return The data pointer that was to be passed to the callback
3949 *
3950 * This function removes the most recently added callback from the
3951 * object @p obj which was triggered by the event type @p type and was
3952 * calling the function @p func when triggered. If the removal is
3953 * successful it will also return the data pointer that was passed to
3954 * evas_object_event_callback_add() when the callback was added to the
3955 * object. If not successful NULL will be returned.
3956 *
3957 * Example:
3958 * @code
3959 * extern Evas_Object *object;
3960 * void *my_data;
3961 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3962 *
3963 * my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
3964 * @endcode
3965 */
3966EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3);
3967
3968/**
3969 * Delete (unregister) a callback function registered to a given
3970 * Evas object event.
3971 *
3972 * @param obj Object to remove a callback from
3973 * @param type The type of event that was triggering the callback
3974 * @param func The function that was to be called when the event was
3975 * triggered
3976 * @param data The data pointer that was to be passed to the callback
3977 * @return The data pointer that was to be passed to the callback
3978 *
3979 * This function removes the most recently added callback from the
3980 * object @p obj, which was triggered by the event type @p type and was
3981 * calling the function @p func with data @p data, when triggered. If
3982 * the removal is successful it will also return the data pointer that
3983 * was passed to evas_object_event_callback_add() (that will be the
3984 * same as the parameter) when the callback was added to the
3985 * object. In errors, @c NULL will be returned.
3986 *
3987 * @note For deletion of Evas object events callbacks filtering by
3988 * just type and function pointer, user
3989 * evas_object_event_callback_del().
3990 *
3991 * Example:
3992 * @code
3993 * extern Evas_Object *object;
3994 * void *my_data;
3995 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3996 *
3997 * my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
3998 * @endcode
3999 */
4000EAPI 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);
4001
4002
4003/**
4004 * Set whether an Evas object is to pass (ignore) events.
4005 *
4006 * @param obj the Evas object to operate on
4007 * @param pass whether @p obj is to pass events (@c EINA_TRUE) or not
4008 * (@c EINA_FALSE)
4009 *
4010 * If @p pass is @c EINA_TRUE, it will make events on @p obj to be @b
4011 * ignored. They will be triggered on the @b next lower object (that
4012 * is not set to pass events), instead (see evas_object_below_get()).
4013 *
4014 * If @p pass is @c EINA_FALSE, events will be processed on that
4015 * object as normal.
4016 *
4017 * @see evas_object_pass_events_get() for an example
4018 * @see evas_object_repeat_events_set()
4019 * @see evas_object_propagate_events_set()
4020 * @see evas_object_freeze_events_set()
4021 */
4022EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1);
4023
4024/**
4025 * Determine whether an object is set to pass (ignore) events.
4026 *
4027 * @param obj the Evas object to get information from.
4028 * @return pass whether @p obj is set to pass events (@c EINA_TRUE) or not
4029 * (@c EINA_FALSE)
4030 *
4031 * Example:
4032 * @dontinclude evas-stacking.c
4033 * @skip if (strcmp(ev->keyname, "p") == 0)
4034 * @until }
4035 *
4036 * See the full @ref Example_Evas_Stacking "example".
4037 *
4038 * @see evas_object_pass_events_set()
4039 * @see evas_object_repeat_events_get()
4040 * @see evas_object_propagate_events_get()
4041 * @see evas_object_freeze_events_get()
4042 */
4043EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4044
4045/**
4046 * Set whether an Evas object is to repeat events.
4047 *
4048 * @param obj the Evas object to operate on
4049 * @param repeat whether @p obj is to repeat events (@c EINA_TRUE) or not
4050 * (@c EINA_FALSE)
4051 *
4052 * If @p repeat is @c EINA_TRUE, it will make events on @p obj to also
4053 * be repeated for the @b next lower object in the objects' stack (see
4054 * see evas_object_below_get()).
4055 *
4056 * If @p repeat is @c EINA_FALSE, events occurring on @p obj will be
4057 * processed only on it.
4058 *
4059 * Example:
4060 * @dontinclude evas-stacking.c
4061 * @skip if (strcmp(ev->keyname, "r") == 0)
4062 * @until }
4063 *
4064 * See the full @ref Example_Evas_Stacking "example".
4065 *
4066 * @see evas_object_repeat_events_get()
4067 * @see evas_object_pass_events_set()
4068 * @see evas_object_propagate_events_set()
4069 * @see evas_object_freeze_events_set()
4070 */
4071EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
4072
4073/**
4074 * Determine whether an object is set to repeat events.
4075 *
4076 * @param obj the given Evas object pointer
4077 * @retrieve whether @p obj is set to repeat events (@c EINA_TRUE)
4078 * or not (@c EINA_FALSE)
4079 *
4080 * @see evas_object_repeat_events_set() for an example
4081 * @see evas_object_pass_events_get()
4082 * @see evas_object_propagate_events_get()
4083 * @see evas_object_freeze_events_get()
4084 */
4085EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4086
4087/**
4088 * Set whether events on a smart object's member should get propagated
4089 * up to its parent.
4090 *
4091 * @param obj the smart object's child to operate on
4092 * @param prop whether to propagate events (@c EINA_TRUE) or not (@c
4093 * EINA_FALSE)
4094 *
4095 * This function has @b no effect if @p obj is not a member of a smart
4096 * object.
4097 *
4098 * If @p prop is @c EINA_TRUE, events occurring on this object will be
4099 * propagated on to the smart object of which @p obj is a member. If
4100 * @p prop is @c EINA_FALSE, events occurring on this object will @b
4101 * not be propagated on to the smart object of which @p obj is a
4102 * member. The default value is @c EINA_TRUE.
4103 *
4104 * @see evas_object_propagate_events_get()
4105 * @see evas_object_repeat_events_set()
4106 * @see evas_object_pass_events_set()
4107 * @see evas_object_freeze_events_set()
4108 */
4109EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1);
4110
4111/**
4112 * Retrieve whether an Evas object is set to propagate events.
4113 *
4114 * @param obj the given Evas object pointer
4115 * @return whether @p obj is set to propagate events (@c EINA_TRUE)
4116 * or not (@c EINA_FALSE)
4117 *
4118 * @see evas_object_propagate_events_set()
4119 * @see evas_object_repeat_events_get()
4120 * @see evas_object_pass_events_get()
4121 * @see evas_object_freeze_events_get()
4122 */
4123EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4124
4125/**
4126 * Set whether an Evas object is to freeze (discard) events.
4127 *
4128 * @param obj the Evas object to operate on
4129 * @param pass whether @p obj is to freeze events (@c EINA_TRUE) or not
4130 * (@c EINA_FALSE)
4131 *
4132 * If @p freeze is @c EINA_TRUE, it will make events on @p obj to be @b
4133 * discarded. Unlike evas_object_pass_events_set(), events will not be
4134 * passed to @b next lower object. This API can be used for blocking
4135 * events while @p obj is on transiting.
4136 *
4137 * If @p freeze is @c EINA_FALSE, events will be processed on that
4138 * object as normal.
4139 *
4140 * @see evas_object_freeze_events_get()
4141 * @see evas_object_pass_events_set()
4142 * @see evas_object_repeat_events_set()
4143 * @see evas_object_propagate_events_set()
4144 * @since 1.1.0
4145 */
4146EAPI void evas_object_freeze_events_set(Evas_Object *obj, Eina_Bool freeze) EINA_ARG_NONNULL(1);
4147
4148/**
4149 * Determine whether an object is set to freeze (discard) events.
4150 *
4151 * @param obj the Evas object to get information from.
4152 * @return freeze whether @p obj is set to freeze events (@c EINA_TRUE) or
4153 * not (@c EINA_FALSE)
4154 *
4155 * @see evas_object_freeze_events_set()
4156 * @see evas_object_pass_events_get()
4157 * @see evas_object_repeat_events_get()
4158 * @see evas_object_propagate_events_get()
4159 * @since 1.1.0
4160 */
4161EAPI Eina_Bool evas_object_freeze_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4162
4163/**
4164 * @}
4165 */
4166
4167/**
4168 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspective, 3D...)
4169 *
4170 * Evas allows different transformations to be applied to all kinds of
4171 * objects. These are applied by means of UV mapping.
4172 *
4173 * With UV mapping, one maps points in the source object to a 3D space
4174 * positioning at target. This allows rotation, perspective, scale and
4175 * lots of other effects, depending on the map that is used.
4176 *
4177 * Each map point may carry a multiplier color. If properly
4178 * calculated, these can do shading effects on the object, producing
4179 * 3D effects.
4180 *
4181 * As usual, Evas provides both the raw and easy to use methods. The
4182 * raw methods allow developer to create its maps somewhere else,
4183 * maybe load them from some file format. The easy to use methods,
4184 * calculate the points given some high-level parameters, such as
4185 * rotation angle, ambient light and so on.
4186 *
4187 * @note applying mapping will reduce performance, so use with
4188 * care. The impact on performance depends on engine in
4189 * use. Software is quite optimized, but not as fast as OpenGL.
4190 *
4191 * @section sec-map-points Map points
4192 * @subsection subsec-rotation Rotation
4193 *
4194 * A map consists of a set of points, currently only four are supported. Each
4195 * of these points contains a set of canvas coordinates @c x and @c y that
4196 * can be used to alter the geometry of the mapped object, and a @c z
4197 * coordinate that indicates the depth of that point. This last coordinate
4198 * does not normally affect the map, but it's used by several of the utility
4199 * functions to calculate the right position of the point given other
4200 * parameters.
4201 *
4202 * The coordinates for each point are set with evas_map_point_coord_set().
4203 * The following image shows a map set to match the geometry of an existing
4204 * object.
4205 *
4206 * @image html map-set-map-points-1.png
4207 * @image rtf map-set-map-points-1.png
4208 * @image latex map-set-map-points-1.eps
4209 *
4210 * This is a common practice, so there are a few functions that help make it
4211 * easier.
4212 *
4213 * evas_map_util_points_populate_from_geometry() sets the coordinates of each
4214 * point in the given map to match the rectangle defined by the function
4215 * parameters.
4216 *
4217 * evas_map_util_points_populate_from_object() and
4218 * evas_map_util_points_populate_from_object_full() both take an object and
4219 * set the map points to match its geometry. The difference between the two
4220 * is that the first function sets the @c z value of all points to 0, while
4221 * the latter receives the value to set in said coordinate as a parameter.
4222 *
4223 * The following lines of code all produce the same result as in the image
4224 * above.
4225 * @code
4226 * evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
4227 * // Assuming o is our original object
4228 * evas_object_move(o, 100, 100);
4229 * evas_object_resize(o, 200, 200);
4230 * evas_map_util_points_populate_from_object(m, o);
4231 * evas_map_util_points_populate_from_object_full(m, o, 0);
4232 * @endcode
4233 *
4234 * Several effects can be applied to an object by simply setting each point
4235 * of the map to the right coordinates. For example, a simulated perspective
4236 * could be achieve as follows.
4237 *
4238 * @image html map-set-map-points-2.png
4239 * @image rtf map-set-map-points-2.png
4240 * @image latex map-set-map-points-2.eps
4241 *
4242 * As said before, the @c z coordinate is unused here so when setting points
4243 * by hand, its value is of no importance.
4244 *
4245 * @image html map-set-map-points-3.png
4246 * @image rtf map-set-map-points-3.png
4247 * @image latex map-set-map-points-3.eps
4248 *
4249 * In all three cases above, setting the map to be used by the object is the
4250 * same.
4251 * @code
4252 * evas_object_map_set(o, m);
4253 * evas_object_map_enable_set(o, EINA_TRUE);
4254 * @endcode
4255 *
4256 * Doing things this way, however, is a lot of work that can be avoided by
4257 * using the provided utility functions, as described in the next section.
4258 *
4259 * @section map-utils Utility functions
4260 *
4261 * Utility functions take an already set up map and alter it to produce a
4262 * specific effect. For example, to rotate an object around its own center
4263 * you would need to take the rotation angle, the coordinates of each corner
4264 * of the object and do all the math to get the new set of coordinates that
4265 * need to tbe set in the map.
4266 *
4267 * Or you can use this code:
4268 * @code
4269 * evas_object_geometry_get(o, &x, &y, &w, &h);
4270 * m = evas_map_new(4);
4271 * evas_map_util_points_populate_from_object(m, o);
4272 * evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
4273 * evas_object_map_set(o, m);
4274 * evas_object_map_enable_set(o, EINA_TRUE);
4275 * evas_map_free(m);
4276 * @endcode
4277 *
4278 * Which will rotate the object around its center point in a 45 degree angle
4279 * in the clockwise direction, taking it from this
4280 *
4281 * @image html map-rotation-2d-1.png
4282 * @image rtf map-rotation-2d-1.png
4283 * @image latex map-rotation-2d-1.eps
4284 *
4285 * to this
4286 *
4287 * @image html map-rotation-2d-2.png
4288 * @image rtf map-rotation-2d-2.png
4289 * @image latex map-rotation-2d-2.eps
4290 *
4291 * Objects may be rotated around any other point just by setting the last two
4292 * paramaters of the evas_map_util_rotate() function to the right values. A
4293 * circle of roughly the diameter of the object overlaid on each image shows
4294 * where the center of rotation is set for each example.
4295 *
4296 * For example, this code
4297 * @code
4298 * evas_object_geometry_get(o, &x, &y, &w, &h);
4299 * m = evas_map_new(4);
4300 * evas_map_util_points_populate_from_object(m, o);
4301 * evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
4302 * evas_object_map_set(o, m);
4303 * evas_object_map_enable_set(o, EINA_TRUE);
4304 * evas_map_free(m);
4305 * @endcode
4306 *
4307 * produces something like
4308 *
4309 * @image html map-rotation-2d-3.png
4310 * @image rtf map-rotation-2d-3.png
4311 * @image latex map-rotation-2d-3.eps
4312 *
4313 * And the following
4314 * @code
4315 * evas_output_size_get(evas, &w, &h);
4316 * m = evas_map_new(4);
4317 * evas_map_util_points_populate_from_object(m, o);
4318 * evas_map_util_rotate(m, 45, w, h);
4319 * evas_object_map_set(o, m);
4320 * evas_object_map_enable_set(o, EINA_TRUE);
4321 * evas_map_free(m);
4322 * @endcode
4323 *
4324 * rotates the object around the center of the window
4325 *
4326 * @image html map-rotation-2d-4.png
4327 * @image rtf map-rotation-2d-4.png
4328 * @image latex map-rotation-2d-4.eps
4329 *
4330 * @subsection subsec-3d 3D Maps
4331 *
4332 * Maps can also be used to achieve the effect of 3-dimensionality. When doing
4333 * this, the @c z coordinate of each point counts, with higher values meaning
4334 * the point is further into the screen, and smaller values (negative, usually)
4335 * meaning the point is closwer towards the user.
4336 *
4337 * Thinking in 3D also introduces the concept of back-face of an object. An
4338 * object is said to be facing the user when all its points are placed in a
4339 * clockwise fashion. The next image shows this, with each point showing the
4340 * with which is identified within the map.
4341 *
4342 * @image html map-point-order-face.png
4343 * @image rtf map-point-order-face.png
4344 * @image latex map-point-order-face.eps
4345 *
4346 * Rotating this map around the @c Y axis would leave the order of the points
4347 * in a counter-clockwise fashion, as seen in the following image.
4348 *
4349 * @image html map-point-order-back.png
4350 * @image rtf map-point-order-back.png
4351 * @image latex map-point-order-back.eps
4352 *
4353 * This way we can say that we are looking at the back face of the object.
4354 * This will have stronger implications later when we talk about lighting.
4355 *
4356 * To know if a map is facing towards the user or not it's enough to use
4357 * the evas_map_util_clockwise_get() function, but this is normally done
4358 * after all the other operations are applied on the map.
4359 *
4360 * @subsection subsec-3d-rot 3D rotation and perspective
4361 *
4362 * Much like evas_map_util_rotate(), there's the function
4363 * evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
4364 * to an object. As in its 2D counterpart, the rotation can be applied around
4365 * any point in the canvas, this time with a @c z coordinate too. The rotation
4366 * can also be around any of the 3 axis.
4367 *
4368 * Starting from this simple setup
4369 *
4370 * @image html map-3d-basic-1.png
4371 * @image rtf map-3d-basic-1.png
4372 * @image latex map-3d-basic-1.eps
4373 *
4374 * and setting maps so that the blue square to rotate on all axis around a
4375 * sphere that uses the object as its center, and the red square to rotate
4376 * around the @c Y axis, we get the following. A simple overlay over the image
4377 * shows the original geometry of each object and the axis around which they
4378 * are being rotated, with the @c Z one not appearing due to being orthogonal
4379 * to the screen.
4380 *
4381 * @image html map-3d-basic-2.png
4382 * @image rtf map-3d-basic-2.png
4383 * @image latex map-3d-basic-2.eps
4384 *
4385 * which doesn't look very real. This can be helped by adding perspective
4386 * to the transformation, which can be simply done by calling
4387 * evas_map_util_3d_perspective() on the map after its position has been set.
4388 * The result in this case, making the vanishing point the center of each
4389 * object:
4390 *
4391 * @image html map-3d-basic-3.png
4392 * @image rtf map-3d-basic-3.png
4393 * @image latex map-3d-basic-3.eps
4394 *
4395 * @section sec-color Color and lighting
4396 *
4397 * Each point in a map can be set to a color, which will be multiplied with
4398 * the objects own color and linearly interpolated in between adjacent points.
4399 * This is done with evas_map_point_color_set() for each point of the map,
4400 * or evas_map_util_points_color_set() to set every point to the same color.
4401 *
4402 * When using 3D effects, colors can be used to improve the looks of them by
4403 * simulating a light source. The evas_map_util_3d_lighting() function makes
4404 * this task easier by taking the coordinates of the light source and its
4405 * color, along with the color of the ambient light. Evas then sets the color
4406 * of each point based on the distance to the light source, the angle with
4407 * which the object is facing the light and the ambient light. Here, the
4408 * orientation of each point as explained before, becomes more important.
4409 * If the map is defined counter-clockwise, the object will be facing away
4410 * from the user and thus become obscured, since no light would be reflecting
4411 * from it.
4412 *
4413 * @image html map-light.png
4414 * @image rtf map-light.png
4415 * @image latex map-light.eps
4416 * @note Object facing the light source
4417 *
4418 * @image html map-light2.png
4419 * @image rtf map-light2.png
4420 * @image latex map-light2.eps
4421 * @note Same object facing away from the user
4422 *
4423 * @section Image mapping
4424 *
4425 * @image html map-uv-mapping-1.png
4426 * @image rtf map-uv-mapping-1.png
4427 * @image latex map-uv-mapping-1.eps
4428 *
4429 * Images need some special handling when mapped. Evas can easily take care
4430 * of objects and do almost anything with them, but it's completely oblivious
4431 * to the content of images, so each point in the map needs to be told to what
4432 * pixel in the source image it belongs. Failing to do may sometimes result
4433 * in the expected behavior, or it may look like a partial work.
4434 *
4435 * The next image illustrates one possibility of a map being set to an image
4436 * object, without setting the right UV mapping for each point. The objects
4437 * themselves are mapped properly to their new geometry, but the image content
4438 * may not be displayed correctly within the mapped object.
4439 *
4440 * @image html map-uv-mapping-2.png
4441 * @image rtf map-uv-mapping-2.png
4442 * @image latex map-uv-mapping-2.eps
4443 *
4444 * Once Evas knows how to handle the source image within the map, it will
4445 * transform it as needed. This is done with evas_map_point_image_uv_set(),
4446 * which tells the map to which pixel in image it maps.
4447 *
4448 * To match our example images to the maps above all we need is the size of
4449 * each image, which can always be found with evas_object_image_size_get().
4450 *
4451 * @code
4452 * evas_map_point_image_uv_set(m, 0, 0, 0);
4453 * evas_map_point_image_uv_set(m, 1, 150, 0);
4454 * evas_map_point_image_uv_set(m, 2, 150, 200);
4455 * evas_map_point_image_uv_set(m, 3, 0, 200);
4456 * evas_object_map_set(o, m);
4457 * evas_object_map_enable_set(o, EINA_TRUE);
4458 *
4459 * evas_map_point_image_uv_set(m, 0, 0, 0);
4460 * evas_map_point_image_uv_set(m, 1, 120, 0);
4461 * evas_map_point_image_uv_set(m, 2, 120, 160);
4462 * evas_map_point_image_uv_set(m, 3, 0, 160);
4463 * evas_object_map_set(o2, m);
4464 * evas_object_map_enable_set(o2, EINA_TRUE);
4465 * @endcode
4466 *
4467 * To get
4468 *
4469 * @image html map-uv-mapping-3.png
4470 * @image rtf map-uv-mapping-3.png
4471 * @image latex map-uv-mapping-3.eps
4472 *
4473 * Maps can also be set to use part of an image only, or even map them inverted,
4474 * and combined with evas_object_image_source_set() it can be used to achieve
4475 * more interesting results.
4476 *
4477 * @code
4478 * evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
4479 * evas_map_point_image_uv_set(m, 0, 0, h);
4480 * evas_map_point_image_uv_set(m, 1, w, h);
4481 * evas_map_point_image_uv_set(m, 2, w, h / 3);
4482 * evas_map_point_image_uv_set(m, 3, 0, h / 3);
4483 * evas_object_map_set(o, m);
4484 * evas_object_map_enable_set(o, EINA_TRUE);
4485 * @endcode
4486 *
4487 * @image html map-uv-mapping-4.png
4488 * @image rtf map-uv-mapping-4.png
4489 * @image latex map-uv-mapping-4.eps
4490 *
4491 * Examples:
4492 * @li @ref Example_Evas_Map_Overview
4493 *
4494 * @ingroup Evas_Object_Group
4495 *
4496 * @{
4497 */
4498
4499/**
4500 * Enable or disable the map that is set.
4501 *
4502 * Enable or disable the use of map for the object @p obj.
4503 * On enable, the object geometry will be saved, and the new geometry will
4504 * change (position and size) to reflect the map geometry set.
4505 *
4506 * If the object doesn't have a map set (with evas_object_map_set()), the
4507 * initial geometry will be undefined. It is advised to always set a map
4508 * to the object first, and then call this function to enable its use.
4509 *
4510 * @param obj object to enable the map on
4511 * @param enabled enabled state
4512 */
4513EAPI void evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled);
4514
4515/**
4516 * Get the map enabled state
4517 *
4518 * This returns the currently enabled state of the map on the object indicated.
4519 * The default map enable state is off. You can enable and disable it with
4520 * evas_object_map_enable_set().
4521 *
4522 * @param obj object to get the map enabled state from
4523 * @return the map enabled state
4524 */
4525EAPI Eina_Bool evas_object_map_enable_get (const Evas_Object *obj);
4526
4527/**
4528 * Set the map source object
4529 *
4530 * This sets the object from which the map is taken - can be any object that
4531 * has map enabled on it.
4532 *
4533 * Currently not implemented. for future use.
4534 *
4535 * @param obj object to set the map source of
4536 * @param src the source object from which the map is taken
4537 */
4538EAPI void evas_object_map_source_set (Evas_Object *obj, Evas_Object *src);
4539
4540/**
4541 * Get the map source object
4542 *
4543 * @param obj object to set the map source of
4544 * @return the object set as the source
4545 *
4546 * @see evas_object_map_source_set()
4547 */
4548EAPI Evas_Object *evas_object_map_source_get (const Evas_Object *obj);
4549
4550/**
4551 * Set current object transformation map.
4552 *
4553 * This sets the map on a given object. It is copied from the @p map pointer,
4554 * so there is no need to keep the @p map object if you don't need it anymore.
4555 *
4556 * A map is a set of 4 points which have canvas x, y coordinates per point,
4557 * with an optional z point value as a hint for perspective correction, if it
4558 * is available. As well each point has u and v coordinates. These are like
4559 * "texture coordinates" in OpenGL in that they define a point in the source
4560 * image that is mapped to that map vertex/point. The u corresponds to the x
4561 * coordinate of this mapped point and v, the y coordinate. Note that these
4562 * coordinates describe a bounding region to sample. If you have a 200x100
4563 * source image and want to display it at 200x100 with proper pixel
4564 * precision, then do:
4565 *
4566 * @code
4567 * Evas_Map *m = evas_map_new(4);
4568 * evas_map_point_coord_set(m, 0, 0, 0, 0);
4569 * evas_map_point_coord_set(m, 1, 200, 0, 0);
4570 * evas_map_point_coord_set(m, 2, 200, 100, 0);
4571 * evas_map_point_coord_set(m, 3, 0, 100, 0);
4572 * evas_map_point_image_uv_set(m, 0, 0, 0);
4573 * evas_map_point_image_uv_set(m, 1, 200, 0);
4574 * evas_map_point_image_uv_set(m, 2, 200, 100);
4575 * evas_map_point_image_uv_set(m, 3, 0, 100);
4576 * evas_object_map_set(obj, m);
4577 * evas_map_free(m);
4578 * @endcode
4579 *
4580 * Note that the map points a uv coordinates match the image geometry. If
4581 * the @p map parameter is NULL, the stored map will be freed and geometry
4582 * prior to enabling/setting a map will be restored.
4583 *
4584 * @param obj object to change transformation map
4585 * @param map new map to use
4586 *
4587 * @see evas_map_new()
4588 */
4589EAPI void evas_object_map_set (Evas_Object *obj, const Evas_Map *map);
4590
4591/**
4592 * Get current object transformation map.
4593 *
4594 * This returns the current internal map set on the indicated object. It is
4595 * intended for read-only access and is only valid as long as the object is
4596 * not deleted or the map on the object is not changed. If you wish to modify
4597 * the map and set it back do the following:
4598 *
4599 * @code
4600 * const Evas_Map *m = evas_object_map_get(obj);
4601 * Evas_Map *m2 = evas_map_dup(m);
4602 * evas_map_util_rotate(m2, 30.0, 0, 0);
4603 * evas_object_map_set(obj);
4604 * evas_map_free(m2);
4605 * @endcode
4606 *
4607 * @param obj object to query transformation map.
4608 * @return map reference to map in use. This is an internal data structure, so
4609 * do not modify it.
4610 *
4611 * @see evas_object_map_set()
4612 */
4613EAPI const Evas_Map *evas_object_map_get (const Evas_Object *obj);
4614
4615
4616/**
4617 * Populate source and destination map points to match exactly object.
4618 *
4619 * Usually one initialize map of an object to match it's original
4620 * position and size, then transform these with evas_map_util_*
4621 * functions, such as evas_map_util_rotate() or
4622 * evas_map_util_3d_rotate(). The original set is done by this
4623 * function, avoiding code duplication all around.
4624 *
4625 * @param m map to change all 4 points (must be of size 4).
4626 * @param obj object to use unmapped geometry to populate map coordinates.
4627 * @param z Point Z Coordinate hint (pre-perspective transform). This value
4628 * will be used for all four points.
4629 *
4630 * @see evas_map_util_points_populate_from_object()
4631 * @see evas_map_point_coord_set()
4632 * @see evas_map_point_image_uv_set()
4633 */
4634EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
4635
4636/**
4637 * Populate source and destination map points to match exactly object.
4638 *
4639 * Usually one initialize map of an object to match it's original
4640 * position and size, then transform these with evas_map_util_*
4641 * functions, such as evas_map_util_rotate() or
4642 * evas_map_util_3d_rotate(). The original set is done by this
4643 * function, avoiding code duplication all around.
4644 *
4645 * Z Point coordinate is assumed as 0 (zero).
4646 *
4647 * @param m map to change all 4 points (must be of size 4).
4648 * @param obj object to use unmapped geometry to populate map coordinates.
4649 *
4650 * @see evas_map_util_points_populate_from_object_full()
4651 * @see evas_map_util_points_populate_from_geometry()
4652 * @see evas_map_point_coord_set()
4653 * @see evas_map_point_image_uv_set()
4654 */
4655EAPI void evas_map_util_points_populate_from_object (Evas_Map *m, const Evas_Object *obj);
4656
4657/**
4658 * Populate source and destination map points to match given geometry.
4659 *
4660 * Similar to evas_map_util_points_populate_from_object_full(), this
4661 * call takes raw values instead of querying object's unmapped
4662 * geometry. The given width will be used to calculate destination
4663 * points (evas_map_point_coord_set()) and set the image uv
4664 * (evas_map_point_image_uv_set()).
4665 *
4666 * @param m map to change all 4 points (must be of size 4).
4667 * @param x Point X Coordinate
4668 * @param y Point Y Coordinate
4669 * @param w width to use to calculate second and third points.
4670 * @param h height to use to calculate third and fourth points.
4671 * @param z Point Z Coordinate hint (pre-perspective transform). This value
4672 * will be used for all four points.
4673 *
4674 * @see evas_map_util_points_populate_from_object()
4675 * @see evas_map_point_coord_set()
4676 * @see evas_map_point_image_uv_set()
4677 */
4678EAPI void evas_map_util_points_populate_from_geometry (Evas_Map *m, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Evas_Coord z);
4679
4680/**
4681 * Set color of all points to given color.
4682 *
4683 * This call is useful to reuse maps after they had 3d lightning or
4684 * any other colorization applied before.
4685 *
4686 * @param m map to change the color of.
4687 * @param r red (0 - 255)
4688 * @param g green (0 - 255)
4689 * @param b blue (0 - 255)
4690 * @param a alpha (0 - 255)
4691 *
4692 * @see evas_map_point_color_set()
4693 */
4694EAPI void evas_map_util_points_color_set (Evas_Map *m, int r, int g, int b, int a);
4695
4696/**
4697 * Change the map to apply the given rotation.
4698 *
4699 * This rotates the indicated map's coordinates around the center coordinate
4700 * given by @p cx and @p cy as the rotation center. The points will have their
4701 * X and Y coordinates rotated clockwise by @p degrees degrees (360.0 is a
4702 * full rotation). Negative values for degrees will rotate counter-clockwise
4703 * by that amount. All coordinates are canvas global coordinates.
4704 *
4705 * @param m map to change.
4706 * @param degrees amount of degrees from 0.0 to 360.0 to rotate.
4707 * @param cx rotation's center horizontal position.
4708 * @param cy rotation's center vertical position.
4709 *
4710 * @see evas_map_point_coord_set()
4711 * @see evas_map_util_zoom()
4712 */
4713EAPI void evas_map_util_rotate (Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
4714
4715/**
4716 * Change the map to apply the given zooming.
4717 *
4718 * Like evas_map_util_rotate(), this zooms the points of the map from a center
4719 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
4720 * parameters specify how much to zoom in the X and Y direction respectively.
4721 * A value of 1.0 means "don't zoom". 2.0 means "double the size". 0.5 is
4722 * "half the size" etc. All coordinates are canvas global coordinates.
4723 *
4724 * @param m map to change.
4725 * @param zoomx horizontal zoom to use.
4726 * @param zoomy vertical zoom to use.
4727 * @param cx zooming center horizontal position.
4728 * @param cy zooming center vertical position.
4729 *
4730 * @see evas_map_point_coord_set()
4731 * @see evas_map_util_rotate()
4732 */
4733EAPI void evas_map_util_zoom (Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
4734
4735/**
4736 * Rotate the map around 3 axes in 3D
4737 *
4738 * This will rotate not just around the "Z" axis as in evas_map_util_rotate()
4739 * (which is a convenience call for those only wanting 2D). This will rotate
4740 * around the X, Y and Z axes. The Z axis points "into" the screen with low
4741 * values at the screen and higher values further away. The X axis runs from
4742 * left to right on the screen and the Y axis from top to bottom. Like with
4743 * evas_map_util_rotate() you provide a center point to rotate around (in 3D).
4744 *
4745 * @param m map to change.
4746 * @param dx amount of degrees from 0.0 to 360.0 to rotate around X axis.
4747 * @param dy amount of degrees from 0.0 to 360.0 to rotate around Y axis.
4748 * @param dz amount of degrees from 0.0 to 360.0 to rotate around Z axis.
4749 * @param cx rotation's center horizontal position.
4750 * @param cy rotation's center vertical position.
4751 * @param cz rotation's center vertical position.
4752 */
4753EAPI void evas_map_util_3d_rotate (Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz);
4754
4755/**
4756 * Perform lighting calculations on the given Map
4757 *
4758 * This is used to apply lighting calculations (from a single light source)
4759 * to a given map. The R, G and B values of each vertex will be modified to
4760 * reflect the lighting based on the lixth point coordinates, the light
4761 * color and the ambient color, and at what angle the map is facing the
4762 * light source. A surface should have its points be declared in a
4763 * clockwise fashion if the face is "facing" towards you (as opposed to
4764 * away from you) as faces have a "logical" side for lighting.
4765 *
4766 * @image html map-light3.png
4767 * @image rtf map-light3.png
4768 * @image latex map-light3.eps
4769 * @note Grey object, no lighting used
4770 *
4771 * @image html map-light4.png
4772 * @image rtf map-light4.png
4773 * @image latex map-light4.eps
4774 * @note Lights out! Every color set to 0
4775 *
4776 * @image html map-light5.png
4777 * @image rtf map-light5.png
4778 * @image latex map-light5.eps
4779 * @note Ambient light to full black, red light coming from close at the
4780 * bottom-left vertex
4781 *
4782 * @image html map-light6.png
4783 * @image rtf map-light6.png
4784 * @image latex map-light6.eps
4785 * @note Same light as before, but not the light is set to 0 and ambient light
4786 * is cyan
4787 *
4788 * @image html map-light7.png
4789 * @image rtf map-light7.png
4790 * @image latex map-light7.eps
4791 * @note Both lights are on
4792 *
4793 * @image html map-light8.png
4794 * @image rtf map-light8.png
4795 * @image latex map-light8.eps
4796 * @note Both lights again, but this time both are the same color.
4797 *
4798 * @param m map to change.
4799 * @param lx X coordinate in space of light point
4800 * @param ly Y coordinate in space of light point
4801 * @param lz Z coordinate in space of light point
4802 * @param lr light red value (0 - 255)
4803 * @param lg light green value (0 - 255)
4804 * @param lb light blue value (0 - 255)
4805 * @param ar ambient color red value (0 - 255)
4806 * @param ag ambient color green value (0 - 255)
4807 * @param ab ambient color blue value (0 - 255)
4808 */
4809EAPI void evas_map_util_3d_lighting (Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab);
4810
4811/**
4812 * Apply a perspective transform to the map
4813 *
4814 * This applies a given perspective (3D) to the map coordinates. X, Y and Z
4815 * values are used. The px and py points specify the "infinite distance" point
4816 * in the 3D conversion (where all lines converge to like when artists draw
4817 * 3D by hand). The @p z0 value specifies the z value at which there is a 1:1
4818 * mapping between spatial coordinates and screen coordinates. Any points
4819 * on this z value will not have their X and Y values modified in the transform.
4820 * Those further away (Z value higher) will shrink into the distance, and
4821 * those less than this value will expand and become bigger. The @p foc value
4822 * determines the "focal length" of the camera. This is in reality the distance
4823 * between the camera lens plane itself (at or closer than this rendering
4824 * results are undefined) and the "z0" z value. This allows for some "depth"
4825 * control and @p foc must be greater than 0.
4826 *
4827 * @param m map to change.
4828 * @param px The perspective distance X coordinate
4829 * @param py The perspective distance Y coordinate
4830 * @param z0 The "0" z plane value
4831 * @param foc The focal distance
4832 */
4833EAPI void evas_map_util_3d_perspective (Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
4834
4835/**
4836 * Get the clockwise state of a map
4837 *
4838 * This determines if the output points (X and Y. Z is not used) are
4839 * clockwise or anti-clockwise. This can be used for "back-face culling". This
4840 * is where you hide objects that "face away" from you. In this case objects
4841 * that are not clockwise.
4842 *
4843 * @param m map to query.
4844 * @return 1 if clockwise, 0 otherwise
4845 */
4846EAPI Eina_Bool evas_map_util_clockwise_get (Evas_Map *m);
4847
4848
4849/**
4850 * Create map of transformation points to be later used with an Evas object.
4851 *
4852 * This creates a set of points (currently only 4 is supported. no other
4853 * number for @p count will work). That is empty and ready to be modified
4854 * with evas_map calls.
4855 *
4856 * @param count number of points in the map.
4857 * @return a newly allocated map or @c NULL on errors.
4858 *
4859 * @see evas_map_free()
4860 * @see evas_map_dup()
4861 * @see evas_map_point_coord_set()
4862 * @see evas_map_point_image_uv_set()
4863 * @see evas_map_util_points_populate_from_object_full()
4864 * @see evas_map_util_points_populate_from_object()
4865 *
4866 * @see evas_object_map_set()
4867 */
4868EAPI Evas_Map *evas_map_new (int count);
4869
4870/**
4871 * Set the smoothing for map rendering
4872 *
4873 * This sets smoothing for map rendering. If the object is a type that has
4874 * its own smoothing settings, then both the smooth settings for this object
4875 * and the map must be turned off. By default smooth maps are enabled.
4876 *
4877 * @param m map to modify. Must not be NULL.
4878 * @param enabled enable or disable smooth map rendering
4879 */
4880EAPI void evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled);
4881
4882/**
4883 * get the smoothing for map rendering
4884 *
4885 * This gets smoothing for map rendering.
4886 *
4887 * @param m map to get the smooth from. Must not be NULL.
4888 */
4889EAPI Eina_Bool evas_map_smooth_get (const Evas_Map *m);
4890
4891/**
4892 * Set the alpha flag for map rendering
4893 *
4894 * This sets alpha flag for map rendering. If the object is a type that has
4895 * its own alpha settings, then this will take precedence. Only image objects
4896 * have this currently.
4897 * Setting this off stops alpha blending of the map area, and is
4898 * useful if you know the object and/or all sub-objects is 100% solid.
4899 *
4900 * @param m map to modify. Must not be NULL.
4901 * @param enabled enable or disable alpha map rendering
4902 */
4903EAPI void evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled);
4904
4905/**
4906 * get the alpha flag for map rendering
4907 *
4908 * This gets the alpha flag for map rendering.
4909 *
4910 * @param m map to get the alpha from. Must not be NULL.
4911 */
4912EAPI Eina_Bool evas_map_alpha_get (const Evas_Map *m);
4913
4914/**
4915 * Copy a previously allocated map.
4916 *
4917 * This makes a duplicate of the @p m object and returns it.
4918 *
4919 * @param m map to copy. Must not be NULL.
4920 * @return newly allocated map with the same count and contents as @p m.
4921 */
4922EAPI Evas_Map *evas_map_dup (const Evas_Map *m);
4923
4924/**
4925 * Free a previously allocated map.
4926 *
4927 * This frees a givem map @p m and all memory associated with it. You must NOT
4928 * free a map returned by evas_object_map_get() as this is internal.
4929 *
4930 * @param m map to free.
4931 */
4932EAPI void evas_map_free (Evas_Map *m);
4933
4934/**
4935 * Get a maps size.
4936 *
4937 * Returns the number of points in a map. Should be at least 4.
4938 *
4939 * @param m map to get size.
4940 * @return -1 on error, points otherwise.
4941 */
4942EAPI int evas_map_count_get (const Evas_Map *m) EINA_CONST;
4943
4944/**
4945 * Change the map point's coordinate.
4946 *
4947 * This sets the fixed point's coordinate in the map. Note that points
4948 * describe the outline of a quadrangle and are ordered either clockwise
4949 * or anti-clock-wise. It is suggested to keep your quadrangles concave and
4950 * non-complex, though these polygon modes may work, they may not render
4951 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
4952 * 2 and 3, and 3 and 0 to describe the edges of the quadrangle.
4953 *
4954 * The X and Y and Z coordinates are in canvas units. Z is optional and may
4955 * or may not be honored in drawing. Z is a hint and does not affect the
4956 * X and Y rendered coordinates. It may be used for calculating fills with
4957 * perspective correct rendering.
4958 *
4959 * Remember all coordinates are canvas global ones like with move and resize
4960 * in evas.
4961 *
4962 * @param m map to change point. Must not be @c NULL.
4963 * @param idx index of point to change. Must be smaller than map size.
4964 * @param x Point X Coordinate
4965 * @param y Point Y Coordinate
4966 * @param z Point Z Coordinate hint (pre-perspective transform)
4967 *
4968 * @see evas_map_util_rotate()
4969 * @see evas_map_util_zoom()
4970 * @see evas_map_util_points_populate_from_object_full()
4971 * @see evas_map_util_points_populate_from_object()
4972 */
4973EAPI void evas_map_point_coord_set (Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
4974
4975/**
4976 * Get the map point's coordinate.
4977 *
4978 * This returns the coordinates of the given point in the map.
4979 *
4980 * @param m map to query point.
4981 * @param idx index of point to query. Must be smaller than map size.
4982 * @param x where to return the X coordinate.
4983 * @param y where to return the Y coordinate.
4984 * @param z where to return the Z coordinate.
4985 */
4986EAPI void evas_map_point_coord_get (const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
4987
4988/**
4989 * Change the map point's U and V texture source point
4990 *
4991 * This sets the U and V coordinates for the point. This determines which
4992 * coordinate in the source image is mapped to the given point, much like
4993 * OpenGL and textures. Notes that these points do select the pixel, but
4994 * are double floating point values to allow for accuracy and sub-pixel
4995 * selection.
4996 *
4997 * @param m map to change the point of.
4998 * @param idx index of point to change. Must be smaller than map size.
4999 * @param u the X coordinate within the image/texture source
5000 * @param v the Y coordinate within the image/texture source
5001 *
5002 * @see evas_map_point_coord_set()
5003 * @see evas_object_map_set()
5004 * @see evas_map_util_points_populate_from_object_full()
5005 * @see evas_map_util_points_populate_from_object()
5006 */
5007EAPI void evas_map_point_image_uv_set (Evas_Map *m, int idx, double u, double v);
5008
5009/**
5010 * Get the map point's U and V texture source points
5011 *
5012 * This returns the texture points set by evas_map_point_image_uv_set().
5013 *
5014 * @param m map to query point.
5015 * @param idx index of point to query. Must be smaller than map size.
5016 * @param u where to write the X coordinate within the image/texture source
5017 * @param v where to write the Y coordinate within the image/texture source
5018 */
5019EAPI void evas_map_point_image_uv_get (const Evas_Map *m, int idx, double *u, double *v);
5020
5021/**
5022 * Set the color of a vertex in the map
5023 *
5024 * This sets the color of the vertex in the map. Colors will be linearly
5025 * interpolated between vertex points through the map. Color will multiply
5026 * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
5027 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
5028 * have no affect on modifying the texture pixels.
5029 *
5030 * @param m map to change the color of.
5031 * @param idx index of point to change. Must be smaller than map size.
5032 * @param r red (0 - 255)
5033 * @param g green (0 - 255)
5034 * @param b blue (0 - 255)
5035 * @param a alpha (0 - 255)
5036 *
5037 * @see evas_map_util_points_color_set()
5038 * @see evas_map_point_coord_set()
5039 * @see evas_object_map_set()
5040 */
5041EAPI void evas_map_point_color_set (Evas_Map *m, int idx, int r, int g, int b, int a);
5042
5043/**
5044 * Get the color set on a vertex in the map
5045 *
5046 * This gets the color set by evas_map_point_color_set() on the given vertex
5047 * of the map.
5048 *
5049 * @param m map to get the color of the vertex from.
5050 * @param idx index of point get. Must be smaller than map size.
5051 * @param r pointer to red return
5052 * @param g pointer to green return
5053 * @param b pointer to blue return
5054 * @param a pointer to alpha return (0 - 255)
5055 *
5056 * @see evas_map_point_coord_set()
5057 * @see evas_object_map_set()
5058 */
5059EAPI void evas_map_point_color_get (const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
5060/**
5061 * @}
5062 */
5063
5064/**
5065 * @defgroup Evas_Object_Group_Size_Hints Size Hints
5066 *
5067 * Objects may carry hints, so that another object that acts as a
5068 * manager (see @ref Evas_Smart_Object_Group) may know how to properly
5069 * position and resize its subordinate objects. The Size Hints provide
5070 * a common interface that is recommended as the protocol for such
5071 * information.
5072 *
5073 * For example, box objects use alignment hints to align its
5074 * lines/columns inside its container, padding hints to set the
5075 * padding between each individual child, etc.
5076 *
5077 * Examples on their usage:
5078 * - @ref Example_Evas_Size_Hints "evas-hints.c"
5079 * - @ref Example_Evas_Aspect_Hints "evas-aspect-hints.c"
5080 *
5081 * @ingroup Evas_Object_Group
5082 */
5083
5084/**
5085 * @addtogroup Evas_Object_Group_Size_Hints
5086 * @{
5087 */
5088
5089/**
5090 * Retrieves the hints for an object's minimum size.
5091 *
5092 * @param obj The given Evas object to query hints from.
5093 * @param w Pointer to an integer in which to store the minimum width.
5094 * @param h Pointer to an integer in which to store the minimum height.
5095 *
5096 * These are hints on the minimim sizes @p obj should have. This is
5097 * not a size enforcement in any way, it's just a hint that should be
5098 * used whenever appropriate.
5099 *
5100 * @note Use @c NULL pointers on the hint components you're not
5101 * interested in: they'll be ignored by the function.
5102 *
5103 * @see evas_object_size_hint_min_set() for an example
5104 */
5105EAPI void evas_object_size_hint_min_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
5106
5107/**
5108 * Sets the hints for an object's minimum size.
5109 *
5110 * @param obj The given Evas object to query hints from.
5111 * @param w Integer to use as the minimum width hint.
5112 * @param h Integer to use as the minimum height hint.
5113 *
5114 * This is not a size enforcement in any way, it's just a hint that
5115 * should be used whenever appropriate.
5116 *
5117 * Values @c 0 will be treated as unset hint components, when queried
5118 * by managers.
5119 *
5120 * Example:
5121 * @dontinclude evas-hints.c
5122 * @skip evas_object_size_hint_min_set
5123 * @until return
5124 *
5125 * In this example the minimum size hints change the behavior of an
5126 * Evas box when layouting its children. See the full @ref
5127 * Example_Evas_Size_Hints "example".
5128 *
5129 * @see evas_object_size_hint_min_get()
5130 */
5131EAPI void evas_object_size_hint_min_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
5132
5133/**
5134 * Retrieves the hints for an object's maximum size.
5135 *
5136 * @param obj The given Evas object to query hints from.
5137 * @param w Pointer to an integer in which to store the maximum width.
5138 * @param h Pointer to an integer in which to store the maximum height.
5139 *
5140 * These are hints on the maximum sizes @p obj should have. This is
5141 * not a size enforcement in any way, it's just a hint that should be
5142 * used whenever appropriate.
5143 *
5144 * @note Use @c NULL pointers on the hint components you're not
5145 * interested in: they'll be ignored by the function.
5146 *
5147 * @see evas_object_size_hint_max_set()
5148 */
5149EAPI void evas_object_size_hint_max_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
5150
5151/**
5152 * Sets the hints for an object's maximum size.
5153 *
5154 * @param obj The given Evas object to query hints from.
5155 * @param w Integer to use as the maximum width hint.
5156 * @param h Integer to use as the maximum height hint.
5157 *
5158 * This is not a size enforcement in any way, it's just a hint that
5159 * should be used whenever appropriate.
5160 *
5161 * Values @c -1 will be treated as unset hint components, when queried
5162 * by managers.
5163 *
5164 * Example:
5165 * @dontinclude evas-hints.c
5166 * @skip evas_object_size_hint_max_set
5167 * @until return
5168 *
5169 * In this example the maximum size hints change the behavior of an
5170 * Evas box when layouting its children. See the full @ref
5171 * Example_Evas_Size_Hints "example".
5172 *
5173 * @see evas_object_size_hint_max_get()
5174 */
5175EAPI void evas_object_size_hint_max_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
5176
5177/**
5178 * Retrieves the hints for an object's optimum size.
5179 *
5180 * @param obj The given Evas object to query hints from.
5181 * @param w Pointer to an integer in which to store the requested width.
5182 * @param h Pointer to an integer in which to store the requested height.
5183 *
5184 * These are hints on the optimum sizes @p obj should have. This is
5185 * not a size enforcement in any way, it's just a hint that should be
5186 * used whenever appropriate.
5187 *
5188 * @note Use @c NULL pointers on the hint components you're not
5189 * interested in: they'll be ignored by the function.
5190 *
5191 * @see evas_object_size_hint_request_set()
5192 */
5193EAPI void evas_object_size_hint_request_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
5194
5195/**
5196 * Sets the hints for an object's optimum size.
5197 *
5198 * @param obj The given Evas object to query hints from.
5199 * @param w Integer to use as the preferred width hint.
5200 * @param h Integer to use as the preferred height hint.
5201 *
5202 * This is not a size enforcement in any way, it's just a hint that
5203 * should be used whenever appropriate.
5204 *
5205 * Values @c 0 will be treated as unset hint components, when queried
5206 * by managers.
5207 *
5208 * @see evas_object_size_hint_request_get()
5209 */
5210EAPI void evas_object_size_hint_request_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
5211
5212/**
5213 * Retrieves the hints for an object's aspect ratio.
5214 *
5215 * @param obj The given Evas object to query hints from.
5216 * @param aspect Returns the policy/type of aspect ratio applied to @p obj.
5217 * @param w Pointer to an integer in which to store the aspect's width
5218 * ratio term.
5219 * @param h Pointer to an integer in which to store the aspect's
5220 * height ratio term.
5221 *
5222 * The different aspect ratio policies are documented in the
5223 * #Evas_Aspect_Control type. A container respecting these size hints
5224 * would @b resize its children accordingly to those policies.
5225 *
5226 * For any policy, if any of the given aspect ratio terms are @c 0,
5227 * the object's container should ignore the aspect and scale @p obj to
5228 * occupy the whole available area. If they are both positive
5229 * integers, that proportion will be respected, under each scaling
5230 * policy.
5231 *
5232 * These images illustrate some of the #Evas_Aspect_Control policies:
5233 *
5234 * @image html any-policy.png
5235 * @image rtf any-policy.png
5236 * @image latex any-policy.eps
5237 *
5238 * @image html aspect-control-none-neither.png
5239 * @image rtf aspect-control-none-neither.png
5240 * @image latex aspect-control-none-neither.eps
5241 *
5242 * @image html aspect-control-both.png
5243 * @image rtf aspect-control-both.png
5244 * @image latex aspect-control-both.eps
5245 *
5246 * @image html aspect-control-horizontal.png
5247 * @image rtf aspect-control-horizontal.png
5248 * @image latex aspect-control-horizontal.eps
5249 *
5250 * This is not a size enforcement in any way, it's just a hint that
5251 * should be used whenever appropriate.
5252 *
5253 * @note Use @c NULL pointers on the hint components you're not
5254 * interested in: they'll be ignored by the function.
5255 *
5256 * Example:
5257 * @dontinclude evas-aspect-hints.c
5258 * @skip if (strcmp(ev->keyname, "c") == 0)
5259 * @until }
5260 *
5261 * See the full @ref Example_Evas_Aspect_Hints "example".
5262 *
5263 * @see evas_object_size_hint_aspect_set()
5264 */
5265EAPI 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);
5266
5267/**
5268 * Sets the hints for an object's aspect ratio.
5269 *
5270 * @param obj The given Evas object to query hints from.
5271 * @param aspect The policy/type of aspect ratio to apply to @p obj.
5272 * @param w Integer to use as aspect width ratio term.
5273 * @param h Integer to use as aspect height ratio term.
5274 *
5275 * This is not a size enforcement in any way, it's just a hint that should
5276 * be used whenever appropriate.
5277 *
5278 * If any of the given aspect ratio terms are @c 0,
5279 * the object's container will ignore the aspect and scale @p obj to
5280 * occupy the whole available area, for any given policy.
5281 *
5282 * @see evas_object_size_hint_aspect_get() for more information.
5283 */
5284EAPI void evas_object_size_hint_aspect_set (Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
5285
5286/**
5287 * Retrieves the hints for on object's alignment.
5288 *
5289 * @param obj The given Evas object to query hints from.
5290 * @param x Pointer to a double in which to store the horizontal
5291 * alignment hint.
5292 * @param y Pointer to a double in which to store the vertical
5293 * alignment hint.
5294 *
5295 * This is not a size enforcement in any way, it's just a hint that
5296 * should be used whenever appropriate.
5297 *
5298 * @note Use @c NULL pointers on the hint components you're not
5299 * interested in: they'll be ignored by the function.
5300 *
5301 * @see evas_object_size_hint_align_set() for more information
5302 */
5303EAPI void evas_object_size_hint_align_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
5304
5305/**
5306 * Sets the hints for an object's alignment.
5307 *
5308 * @param obj The given Evas object to query hints from.
5309 * @param x Double, ranging from @c 0.0 to @c 1.0 or with the
5310 * special value #EVAS_HINT_FILL, to use as horizontal alignment hint.
5311 * @param y Double, ranging from @c 0.0 to @c 1.0 or with the
5312 * special value #EVAS_HINT_FILL, to use as vertical alignment hint.
5313 *
5314 * These are hints on how to align an object <b>inside the boundaries
5315 * of a container/manager</b>. Accepted values are in the @c 0.0 to @c
5316 * 1.0 range, with the special value #EVAS_HINT_FILL used to specify
5317 * "justify" or "fill" by some users. In this case, maximum size hints
5318 * should be enforced with higher priority, if they are set. Also, any
5319 * padding hint set on objects should add up to the alignment space on
5320 * the final scene composition.
5321 *
5322 * See documentation of possible users: in Evas, they are the @ref
5323 * Evas_Object_Box "box" and @ref Evas_Object_Table "table" smart
5324 * objects.
5325 *
5326 * For the horizontal component, @c 0.0 means to the left, @c 1.0
5327 * means to the right. Analogously, for the vertical component, @c 0.0
5328 * to the top, @c 1.0 means to the bottom.
5329 *
5330 * See the following figure:
5331 *
5332 * @image html alignment-hints.png
5333 * @image rtf alignment-hints.png
5334 * @image latex alignment-hints.eps
5335 *
5336 * This is not a size enforcement in any way, it's just a hint that
5337 * should be used whenever appropriate.
5338 *
5339 * Example:
5340 * @dontinclude evas-hints.c
5341 * @skip evas_object_size_hint_align_set
5342 * @until return
5343 *
5344 * In this example the alignment hints change the behavior of an Evas
5345 * box when layouting its children. See the full @ref
5346 * Example_Evas_Size_Hints "example".
5347 *
5348 * @see evas_object_size_hint_align_get()
5349 * @see evas_object_size_hint_max_set()
5350 * @see evas_object_size_hint_padding_set()
5351 */
5352EAPI void evas_object_size_hint_align_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
5353
5354/**
5355 * Retrieves the hints for an object's weight.
5356 *
5357 * @param obj The given Evas object to query hints from.
5358 * @param x Pointer to a double in which to store the horizontal weight.
5359 * @param y Pointer to a double in which to store the vertical weight.
5360 *
5361 * Accepted values are zero or positive values. Some users might use
5362 * this hint as a boolean, but some might consider it as a @b
5363 * proportion, see documentation of possible users, which in Evas are
5364 * the @ref Evas_Object_Box "box" and @ref Evas_Object_Table "table"
5365 * smart objects.
5366 *
5367 * This is not a size enforcement in any way, it's just a hint that
5368 * should be used whenever appropriate.
5369 *
5370 * @note Use @c NULL pointers on the hint components you're not
5371 * interested in: they'll be ignored by the function.
5372 *
5373 * @see evas_object_size_hint_weight_set() for an example
5374 */
5375EAPI void evas_object_size_hint_weight_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
5376
5377/**
5378 * Sets the hints for an object's weight.
5379 *
5380 * @param obj The given Evas object to query hints from.
5381 * @param x Nonnegative double value to use as horizontal weight hint.
5382 * @param y Nonnegative double value to use as vertical weight hint.
5383 *
5384 * This is not a size enforcement in any way, it's just a hint that
5385 * should be used whenever appropriate.
5386 *
5387 * This is a hint on how a container object should @b resize a given
5388 * child within its area. Containers may adhere to the simpler logic
5389 * of just expanding the child object's dimensions to fit its own (see
5390 * the #EVAS_HINT_EXPAND helper weight macro) or the complete one of
5391 * taking each child's weight hint as real @b weights to how much of
5392 * its size to allocate for them in each axis. A container is supposed
5393 * to, after @b normalizing the weights of its children (with weight
5394 * hints), distribute the space it has to layout them by those factors
5395 * -- most weighted children get larger in this process than the least
5396 * ones.
5397 *
5398 * Example:
5399 * @dontinclude evas-hints.c
5400 * @skip evas_object_size_hint_weight_set
5401 * @until return
5402 *
5403 * In this example the weight hints change the behavior of an Evas box
5404 * when layouting its children. See the full @ref
5405 * Example_Evas_Size_Hints "example".
5406 *
5407 * @see evas_object_size_hint_weight_get() for more information
5408 */
5409EAPI void evas_object_size_hint_weight_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
5410
5411/**
5412 * Retrieves the hints for an object's padding space.
5413 *
5414 * @param obj The given Evas object to query hints from.
5415 * @param l Pointer to an integer in which to store left padding.
5416 * @param r Pointer to an integer in which to store right padding.
5417 * @param t Pointer to an integer in which to store top padding.
5418 * @param b Pointer to an integer in which to store bottom padding.
5419 *
5420 * Padding is extra space an object takes on each of its delimiting
5421 * rectangle sides, in canvas units. This space will be rendered
5422 * transparent, naturally, as in the following figure:
5423 *
5424 * @image html padding-hints.png
5425 * @image rtf padding-hints.png
5426 * @image latex padding-hints.eps
5427 *
5428 * This is not a size enforcement in any way, it's just a hint that
5429 * should be used whenever appropriate.
5430 *
5431 * @note Use @c NULL pointers on the hint components you're not
5432 * interested in: they'll be ignored by the function.
5433 *
5434 * Example:
5435 * @dontinclude evas-hints.c
5436 * @skip evas_object_size_hint_padding_set
5437 * @until return
5438 *
5439 * In this example the padding hints change the behavior of an Evas box
5440 * when layouting its children. See the full @ref
5441 * Example_Evas_Size_Hints "example".
5442 *
5443 * @see evas_object_size_hint_padding_set()
5444 */
5445EAPI 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);
5446
5447/**
5448 * Sets the hints for an object's padding space.
5449 *
5450 * @param obj The given Evas object to query hints from.
5451 * @param l Integer to specify left padding.
5452 * @param r Integer to specify right padding.
5453 * @param t Integer to specify top padding.
5454 * @param b Integer to specify bottom padding.
5455 *
5456 * This is not a size enforcement in any way, it's just a hint that
5457 * should be used whenever appropriate.
5458 *
5459 * @see evas_object_size_hint_padding_get() for more information
5460 */
5461EAPI 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);
5462
5463/**
5464 * @}
5465 */
5466
5467/**
5468 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
5469 *
5470 * Miscellaneous functions that also apply to any object, but are less
5471 * used or not implemented by all objects.
5472 *
5473 * Examples on this group of functions can be found @ref
5474 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
5475 *
5476 * @ingroup Evas_Object_Group
5477 */
5478
5479/**
5480 * @addtogroup Evas_Object_Group_Extras
5481 * @{
5482 */
5483
5484/**
5485 * Set an attached data pointer to an object with a given string key.
5486 *
5487 * @param obj The object to attach the data pointer to
5488 * @param key The string key for the data to access it
5489 * @param data The pointer to the data to be attached
5490 *
5491 * This attaches the pointer @p data to the object @p obj, given the
5492 * access string @p key. This pointer will stay "hooked" to the object
5493 * until a new pointer with the same string key is attached with
5494 * evas_object_data_set() or it is deleted with
5495 * evas_object_data_del(). On deletion of the object @p obj, the
5496 * pointers will not be accessible from the object anymore.
5497 *
5498 * You can find the pointer attached under a string key using
5499 * evas_object_data_get(). It is the job of the calling application to
5500 * free any data pointed to by @p data when it is no longer required.
5501 *
5502 * If @p data is @c NULL, the old value stored at @p key will be
5503 * removed but no new value will be stored. This is synonymous with
5504 * calling evas_object_data_del() with @p obj and @p key.
5505 *
5506 * @note This function is very handy when you have data associated
5507 * specifically to an Evas object, being of use only when dealing with
5508 * it. Than you don't have the burden to a pointer to it elsewhere,
5509 * using this family of functions.
5510 *
5511 * Example:
5512 *
5513 * @code
5514 * int *my_data;
5515 * extern Evas_Object *obj;
5516 *
5517 * my_data = malloc(500);
5518 * evas_object_data_set(obj, "name_of_data", my_data);
5519 * printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data"));
5520 * @endcode
5521 */
5522EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2);
5523
5524/**
5525 * Return an attached data pointer on an Evas object by its given
5526 * string key.
5527 *
5528 * @param obj The object to which the data was attached
5529 * @param key The string key the data was stored under
5530 * @return The data pointer stored, or @c NULL if none was stored
5531 *
5532 * This function will return the data pointer attached to the object
5533 * @p obj, stored using the string key @p key. If the object is valid
5534 * and a data pointer was stored under the given key, that pointer
5535 * will be returned. If this is not the case, @c NULL will be
5536 * returned, signifying an invalid object or a non-existent key. It is
5537 * possible that a @c NULL pointer was stored given that key, but this
5538 * situation is non-sensical and thus can be considered an error as
5539 * well. @c NULL pointers are never stored as this is the return value
5540 * if an error occurs.
5541 *
5542 * Example:
5543 *
5544 * @code
5545 * int *my_data;
5546 * extern Evas_Object *obj;
5547 *
5548 * my_data = evas_object_data_get(obj, "name_of_my_data");
5549 * if (my_data) printf("Data stored was %p\n", my_data);
5550 * else printf("No data was stored on the object\n");
5551 * @endcode
5552 */
5553EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
5554
5555/**
5556 * Delete an attached data pointer from an object.
5557 *
5558 * @param obj The object to delete the data pointer from
5559 * @param key The string key the data was stored under
5560 * @return The original data pointer stored at @p key on @p obj
5561 *
5562 * This will remove the stored data pointer from @p obj stored under
5563 * @p key and return this same pointer, if actually there was data
5564 * there, or @c NULL, if nothing was stored under that key.
5565 *
5566 * Example:
5567 *
5568 * @code
5569 * int *my_data;
5570 * extern Evas_Object *obj;
5571 *
5572 * my_data = evas_object_data_del(obj, "name_of_my_data");
5573 * @endcode
5574 */
5575EAPI void *evas_object_data_del (Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
5576
5577
5578/**
5579 * Set pointer behavior.
5580 *
5581 * @param obj
5582 * @param setting desired behavior.
5583 *
5584 * This function has direct effect on event callbacks related to
5585 * mouse.
5586 *
5587 * If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse
5588 * is down at this object, events will be restricted to it as source,
5589 * mouse moves, for example, will be emitted even if outside this
5590 * object area.
5591 *
5592 * If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will
5593 * be emitted just when inside this object area.
5594 *
5595 * The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB.
5596 *
5597 * @ingroup Evas_Object_Group_Extras
5598 */
5599EAPI void evas_object_pointer_mode_set (Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1);
5600
5601/**
5602 * Determine how pointer will behave.
5603 * @param obj
5604 * @return pointer behavior.
5605 * @ingroup Evas_Object_Group_Extras
5606 */
5607EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5608
5609
5610/**
5611 * Sets whether or not the given Evas object is to be drawn anti-aliased.
5612 *
5613 * @param obj The given Evas object.
5614 * @param anti_alias 1 if the object is to be anti_aliased, 0 otherwise.
5615 * @ingroup Evas_Object_Group_Extras
5616 */
5617EAPI void evas_object_anti_alias_set (Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1);
5618
5619/**
5620 * Retrieves whether or not the given Evas object is to be drawn anti_aliased.
5621 * @param obj The given Evas object.
5622 * @return @c 1 if the object is to be anti_aliased. @c 0 otherwise.
5623 * @ingroup Evas_Object_Group_Extras
5624 */
5625EAPI Eina_Bool evas_object_anti_alias_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5626
5627
5628/**
5629 * Sets the scaling factor for an Evas object. Does not affect all
5630 * objects.
5631 *
5632 * @param obj The given Evas object.
5633 * @param scale The scaling factor. <c>1.0</c> means no scaling,
5634 * default size.
5635 *
5636 * This will multiply the object's dimension by the given factor, thus
5637 * altering its geometry (width and height). Useful when you want
5638 * scalable UI elements, possibly at run time.
5639 *
5640 * @note Only text and textblock objects have scaling change
5641 * handlers. Other objects won't change visually on this call.
5642 *
5643 * @see evas_object_scale_get()
5644 *
5645 * @ingroup Evas_Object_Group_Extras
5646 */
5647EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
5648
5649/**
5650 * Retrieves the scaling factor for the given Evas object.
5651 *
5652 * @param obj The given Evas object.
5653 * @return The scaling factor.
5654 *
5655 * @ingroup Evas_Object_Group_Extras
5656 *
5657 * @see evas_object_scale_set()
5658 */
5659EAPI double evas_object_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5660
5661
5662/**
5663 * Sets the render_op to be used for rendering the Evas object.
5664 * @param obj The given Evas object.
5665 * @param render_op one of the Evas_Render_Op values.
5666 * @ingroup Evas_Object_Group_Extras
5667 */
5668EAPI void evas_object_render_op_set (Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1);
5669
5670/**
5671 * Retrieves the current value of the operation used for rendering the Evas object.
5672 * @param obj The given Evas object.
5673 * @return one of the enumerated values in Evas_Render_Op.
5674 * @ingroup Evas_Object_Group_Extras
5675 */
5676EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5677
5678/**
5679 * Set whether to use precise (usually expensive) point collision
5680 * detection for a given Evas object.
5681 *
5682 * @param obj The given object.
5683 * @param precise whether to use precise point collision detection or
5684 * not The default value is false.
5685 *
5686 * Use this function to make Evas treat objects' transparent areas as
5687 * @b not belonging to it with regard to mouse pointer events. By
5688 * default, all of the object's boundary rectangle will be taken in
5689 * account for them.
5690 *
5691 * @warning By using precise point collision detection you'll be
5692 * making Evas more resource intensive.
5693 *
5694 * Example code follows.
5695 * @dontinclude evas-events.c
5696 * @skip if (strcmp(ev->keyname, "p") == 0)
5697 * @until }
5698 *
5699 * See the full example @ref Example_Evas_Events "here".
5700 *
5701 * @see evas_object_precise_is_inside_get()
5702 * @ingroup Evas_Object_Group_Extras
5703 */
5704 EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1);
5705
5706/**
5707 * Determine whether an object is set to use precise point collision
5708 * detection.
5709 *
5710 * @param obj The given object.
5711 * @return whether @p obj is set to use precise point collision
5712 * detection or not The default value is false.
5713 *
5714 * @see evas_object_precise_is_inside_set() for an example
5715 *
5716 * @ingroup Evas_Object_Group_Extras
5717 */
5718 EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5719
5720/**
5721 * Set a hint flag on the given Evas object that it's used as a "static
5722 * clipper".
5723 *
5724 * @param obj The given object.
5725 * @param is_static_clip @c EINA_TRUE if it's to be used as a static
5726 * clipper, @c EINA_FALSE otherwise
5727 *
5728 * This is a hint to Evas that this object is used as a big static
5729 * clipper and shouldn't be moved with children and otherwise
5730 * considered specially. The default value for new objects is @c
5731 * EINA_FALSE.
5732 *
5733 * @see evas_object_static_clip_get()
5734 *
5735 * @ingroup Evas_Object_Group_Extras
5736 */
5737 EAPI void evas_object_static_clip_set (Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1);
5738
5739/**
5740 * Get the "static clipper" hint flag for a given Evas object.
5741 *
5742 * @param obj The given object.
5743 * @returrn @c EINA_TRUE if it's set as a static clipper, @c
5744 * EINA_FALSE otherwise
5745 *
5746 * @see evas_object_static_clip_set() for more details
5747 *
5748 * @ingroup Evas_Object_Group_Extras
5749 */
5750 EAPI Eina_Bool evas_object_static_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5751
5752/**
5753 * @}
5754 */
5755
5756/**
5757 * @defgroup Evas_Object_Group_Find Finding Objects
5758 *
5759 * Functions that allows finding objects by their position, name or
5760 * other properties.
5761 *
5762 * @ingroup Evas_Object_Group
5763 */
5764
5765/**
5766 * @addtogroup Evas_Object_Group_Find
5767 * @{
5768 */
5769
5770/**
5771 * Retrieve the object that currently has focus.
5772 *
5773 * @param e The Evas canvas to query for focused object on.
5774 * @return The object that has focus or @c NULL if there is not one.
5775 *
5776 * Evas can have (at most) one of its objects focused at a time.
5777 * Focused objects will be the ones having <b>key events</b> delivered
5778 * to, which the programmer can act upon by means of
5779 * evas_object_event_callback_add() usage.
5780 *
5781 * @note Most users wouldn't be dealing directly with Evas' focused
5782 * objects. Instead, they would be using a higher level library for
5783 * that (like a toolkit, as Elementary) to handle focus and who's
5784 * receiving input for them.
5785 *
5786 * This call returns the object that currently has focus on the canvas
5787 * @p e or @c NULL, if none.
5788 *
5789 * @see evas_object_focus_set
5790 * @see evas_object_focus_get
5791 * @see evas_object_key_grab
5792 * @see evas_object_key_ungrab
5793 *
5794 * Example:
5795 * @dontinclude evas-events.c
5796 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
5797 * @until evas_object_focus_set(d.bg, EINA_TRUE);
5798 * @dontinclude evas-events.c
5799 * @skip called when our rectangle gets focus
5800 * @until }
5801 *
5802 * In this example the @c event_info is exactly a pointer to that
5803 * focused rectangle. See the full @ref Example_Evas_Events "example".
5804 *
5805 * @ingroup Evas_Object_Group_Find
5806 */
5807EAPI Evas_Object *evas_focus_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5808
5809/**
5810 * Retrieves the object on the given evas with the given name.
5811 * @param e The given evas.
5812 * @param name The given name.
5813 * @return If successful, the Evas object with the given name. Otherwise,
5814 * @c NULL.
5815 *
5816 * This looks for the evas object given a name by evas_object_name_set(). If
5817 * the name is not unique canvas-wide, then which one of the many objects
5818 * with that name is returned is undefined, so only use this if you can ensure
5819 * the object name is unique.
5820 *
5821 * @ingroup Evas_Object_Group_Find
5822 */
5823EAPI Evas_Object *evas_object_name_find (const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5824
5825/**
5826 * Retrieves the object from children of the given object with the given name.
5827 * @param obj The parent (smart) object whose children to search.
5828 * @param name The given name.
5829 * @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.).
5830 * @return If successful, the Evas object with the given name. Otherwise,
5831 * @c NULL.
5832 *
5833 * This looks for the evas object given a name by evas_object_name_set(), but
5834 * it ONLY looks at the children of the object *p obj, and will only recurse
5835 * into those children if @p recurse is greater than 0. If the name is not
5836 * unique within immediate children (or the whole child tree) then it is not
5837 * defined which child object will be returned. If @p recurse is set to -1 then
5838 * it will recurse without limit.
5839 *
5840 * @since 1.2
5841 *
5842 * @ingroup Evas_Object_Group_Find
5843 */
5844EAPI Evas_Object *evas_object_name_child_find (const Evas_Object *obj, const char *name, int recurse) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5845
5846/**
5847 * Retrieve the Evas object stacked at the top of a given position in
5848 * a canvas
5849 *
5850 * @param e A handle to the canvas.
5851 * @param x The horizontal coordinate of the position
5852 * @param y The vertical coordinate of the position
5853 * @param include_pass_events_objects Boolean flag to include or not
5854 * objects which pass events in this calculation
5855 * @param include_hidden_objects Boolean flag to include or not hidden
5856 * objects in this calculation
5857 * @return The Evas object that is over all other objects at the given
5858 * position.
5859 *
5860 * This function will traverse all the layers of the given canvas,
5861 * from top to bottom, querying for objects with areas covering the
5862 * given position. The user can remove from from the query
5863 * objects which are hidden and/or which are set to pass events.
5864 *
5865 * @warning This function will @b skip objects parented by smart
5866 * objects, acting only on the ones at the "top level", with regard to
5867 * object parenting.
5868 */
5869EAPI 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);
5870
5871/**
5872 * Retrieve the Evas object stacked at the top at the position of the
5873 * mouse cursor, over a given canvas
5874 *
5875 * @param e A handle to the canvas.
5876 * @return The Evas object that is over all other objects at the mouse
5877 * pointer's position
5878 *
5879 * This function will traverse all the layers of the given canvas,
5880 * from top to bottom, querying for objects with areas covering the
5881 * mouse pointer's position, over @p e.
5882 *
5883 * @warning This function will @b skip objects parented by smart
5884 * objects, acting only on the ones at the "top level", with regard to
5885 * object parenting.
5886 */
5887EAPI Evas_Object *evas_object_top_at_pointer_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5888
5889/**
5890 * Retrieve the Evas object stacked at the top of a given rectangular
5891 * region in a canvas
5892 *
5893 * @param e A handle to the canvas.
5894 * @param x The top left corner's horizontal coordinate for the
5895 * rectangular region
5896 * @param y The top left corner's vertical coordinate for the
5897 * rectangular region
5898 * @param w The width of the rectangular region
5899 * @param h The height of the rectangular region
5900 * @param include_pass_events_objects Boolean flag to include or not
5901 * objects which pass events in this calculation
5902 * @param include_hidden_objects Boolean flag to include or not hidden
5903 * objects in this calculation
5904 * @return The Evas object that is over all other objects at the given
5905 * rectangular region.
5906 *
5907 * This function will traverse all the layers of the given canvas,
5908 * from top to bottom, querying for objects with areas overlapping
5909 * with the given rectangular region inside @p e. The user can remove
5910 * from the query objects which are hidden and/or which are set to
5911 * pass events.
5912 *
5913 * @warning This function will @b skip objects parented by smart
5914 * objects, acting only on the ones at the "top level", with regard to
5915 * object parenting.
5916 */
5917EAPI 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);
5918
5919/**
5920 * Retrieve a list of Evas objects lying over a given position in
5921 * a canvas
5922 *
5923 * @param e A handle to the canvas.
5924 * @param x The horizontal coordinate of the position
5925 * @param y The vertical coordinate of the position
5926 * @param include_pass_events_objects Boolean flag to include or not
5927 * objects which pass events in this calculation
5928 * @param include_hidden_objects Boolean flag to include or not hidden
5929 * objects in this calculation
5930 * @return The list of Evas objects that are over the given position
5931 * in @p e
5932 *
5933 * This function will traverse all the layers of the given canvas,
5934 * from top to bottom, querying for objects with areas covering the
5935 * given position. The user can remove from from the query
5936 * objects which are hidden and/or which are set to pass events.
5937 *
5938 * @warning This function will @b skip objects parented by smart
5939 * objects, acting only on the ones at the "top level", with regard to
5940 * object parenting.
5941 */
5942EAPI 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);
5943 EAPI 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);
5944
5945/**
5946 * Get the lowest (stacked) Evas object on the canvas @p
5947 *
5948 * @param e a valid canvas pointer
5949 * @return a pointer to the lowest object on it, if any, or @c NULL,
5950 * otherwise
5951 *
5952 * This function will take all populated layers in the canvas into
5953 * account, getting the lowest object for the lowest layer, naturally.
5954 *
5955 * @see evas_object_layer_get()
5956 * @see evas_object_layer_set()
5957 * @see evas_object_below_get()
5958 * @see evas_object_above_get()
5959 *
5960 * @warning This function will @b skip objects parented by smart
5961 * objects, acting only on the ones at the "top level", with regard to
5962 * object parenting.
5963 */
5964EAPI Evas_Object *evas_object_bottom_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5965
5966/**
5967 * Get the highest (stacked) Evas object on the canvas @p
5968 *
5969 * @param e a valid canvas pointer
5970 * @return a pointer to the highest object on it, if any, or @c NULL,
5971 * otherwise
5972 *
5973 * This function will take all populated layers in the canvas into
5974 * account, getting the highest object for the highest layer,
5975 * naturally.
5976 *
5977 * @see evas_object_layer_get()
5978 * @see evas_object_layer_set()
5979 * @see evas_object_below_get()
5980 * @see evas_object_above_get()
5981 *
5982 * @warning This function will @b skip objects parented by smart
5983 * objects, acting only on the ones at the "top level", with regard to
5984 * object parenting.
5985 */
5986EAPI Evas_Object *evas_object_top_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5987
5988/**
5989 * @}
5990 */
5991
5992/**
5993 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
5994 *
5995 * Evas provides a way to intercept method calls. The interceptor
5996 * callback may opt to completely deny the call, or may check and
5997 * change the parameters before continuing. The continuation of an
5998 * intercepted call is done by calling the intercepted call again,
5999 * from inside the interceptor callback.
6000 *
6001 * @ingroup Evas_Object_Group
6002 */
6003
6004/**
6005 * @addtogroup Evas_Object_Group_Interceptors
6006 * @{
6007 */
6008
6009typedef void (*Evas_Object_Intercept_Show_Cb) (void *data, Evas_Object *obj);
6010typedef void (*Evas_Object_Intercept_Hide_Cb) (void *data, Evas_Object *obj);
6011typedef void (*Evas_Object_Intercept_Move_Cb) (void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
6012typedef void (*Evas_Object_Intercept_Resize_Cb) (void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
6013typedef void (*Evas_Object_Intercept_Raise_Cb) (void *data, Evas_Object *obj);
6014typedef void (*Evas_Object_Intercept_Lower_Cb) (void *data, Evas_Object *obj);
6015typedef void (*Evas_Object_Intercept_Stack_Above_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
6016typedef void (*Evas_Object_Intercept_Stack_Below_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
6017typedef void (*Evas_Object_Intercept_Layer_Set_Cb) (void *data, Evas_Object *obj, int l);
6018typedef void (*Evas_Object_Intercept_Color_Set_Cb) (void *data, Evas_Object *obj, int r, int g, int b, int a);
6019typedef void (*Evas_Object_Intercept_Clip_Set_Cb) (void *data, Evas_Object *obj, Evas_Object *clip);
6020typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *obj);
6021
6022/**
6023 * Set the callback function that intercepts a show event of a object.
6024 *
6025 * @param obj The given canvas object pointer.
6026 * @param func The given function to be the callback function.
6027 * @param data The data passed to the callback function.
6028 *
6029 * This function sets a callback function to intercepts a show event
6030 * of a canvas object.
6031 *
6032 * @see evas_object_intercept_show_callback_del().
6033 *
6034 */
6035EAPI void evas_object_intercept_show_callback_add (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
6036
6037/**
6038 * Unset the callback function that intercepts a show event of a
6039 * object.
6040 *
6041 * @param obj The given canvas object pointer.
6042 * @param func The given callback function.
6043 *
6044 * This function sets a callback function to intercepts a show event
6045 * of a canvas object.
6046 *
6047 * @see evas_object_intercept_show_callback_add().
6048 *
6049 */
6050EAPI void *evas_object_intercept_show_callback_del (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2);
6051
6052/**
6053 * Set the callback function that intercepts a hide event of a object.
6054 *
6055 * @param obj The given canvas object pointer.
6056 * @param func The given function to be the callback function.
6057 * @param data The data passed to the callback function.
6058 *
6059 * This function sets a callback function to intercepts a hide event
6060 * of a canvas object.
6061 *
6062 * @see evas_object_intercept_hide_callback_del().
6063 *
6064 */
6065EAPI void evas_object_intercept_hide_callback_add (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
6066
6067/**
6068 * Unset the callback function that intercepts a hide event of a
6069 * object.
6070 *
6071 * @param obj The given canvas object pointer.
6072 * @param func The given callback function.
6073 *
6074 * This function sets a callback function to intercepts a hide event
6075 * of a canvas object.
6076 *
6077 * @see evas_object_intercept_hide_callback_add().
6078 *
6079 */
6080EAPI void *evas_object_intercept_hide_callback_del (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2);
6081
6082/**
6083 * Set the callback function that intercepts a move event of a object.
6084 *
6085 * @param obj The given canvas object pointer.
6086 * @param func The given function to be the callback function.
6087 * @param data The data passed to the callback function.
6088 *
6089 * This function sets a callback function to intercepts a move event
6090 * of a canvas object.
6091 *
6092 * @see evas_object_intercept_move_callback_del().
6093 *
6094 */
6095EAPI void evas_object_intercept_move_callback_add (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
6096
6097/**
6098 * Unset the callback function that intercepts a move event of a
6099 * object.
6100 *
6101 * @param obj The given canvas object pointer.
6102 * @param func The given callback function.
6103 *
6104 * This function sets a callback function to intercepts a move event
6105 * of a canvas object.
6106 *
6107 * @see evas_object_intercept_move_callback_add().
6108 *
6109 */
6110EAPI void *evas_object_intercept_move_callback_del (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2);
6111
6112 EAPI void evas_object_intercept_resize_callback_add (Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
6113 EAPI void *evas_object_intercept_resize_callback_del (Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2);
6114 EAPI void evas_object_intercept_raise_callback_add (Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
6115 EAPI void *evas_object_intercept_raise_callback_del (Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2);
6116 EAPI void evas_object_intercept_lower_callback_add (Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
6117 EAPI void *evas_object_intercept_lower_callback_del (Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2);
6118 EAPI 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);
6119 EAPI void *evas_object_intercept_stack_above_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2);
6120 EAPI 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);
6121 EAPI void *evas_object_intercept_stack_below_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2);
6122 EAPI 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);
6123 EAPI void *evas_object_intercept_layer_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2);
6124 EAPI 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);
6125 EAPI void *evas_object_intercept_color_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2);
6126 EAPI 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);
6127 EAPI void *evas_object_intercept_clip_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2);
6128 EAPI 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);
6129 EAPI void *evas_object_intercept_clip_unset_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2);
6130
6131/**
6132 * @}
6133 */
6134
6135/**
6136 * @defgroup Evas_Object_Specific Specific Object Functions
6137 *
6138 * Functions that work on specific objects.
6139 *
6140 */
6141
6142/**
6143 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
6144 *
6145 * @brief Function to create evas rectangle objects.
6146 *
6147 * There is only one function to deal with rectangle objects, this may make this
6148 * function seem useless given there are no functions to manipulate the created
6149 * rectangle, however the rectangle is actually very useful and should be
6150 * manipulated using the generic @ref Evas_Object_Group "evas object functions".
6151 *
6152 * The evas rectangle server a number of key functions when working on evas
6153 * programs:
6154 * @li Background
6155 * @li Debugging
6156 * @li Clipper
6157 *
6158 * @section Background
6159 *
6160 * One extremely common requirement of evas programs is to have a solid color
6161 * background, this can be accomplished with the following very simple code:
6162 * @code
6163 * Evas_Object *bg = evas_object_rectangle_add(evas_canvas);
6164 * //Here we set the rectangles red, green, blue and opacity levels
6165 * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
6166 * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
6167 * evas_object_show(bg);
6168 * @endcode
6169 *
6170 * This however will have issues if the @c evas_canvas is resized, however most
6171 * windows are created using ecore evas and that has a solution to using the
6172 * rectangle as a background:
6173 * @code
6174 * Evas_Object *bg = evas_object_rectangle_add(ecore_evas_get(ee));
6175 * //Here we set the rectangles red, green, blue and opacity levels
6176 * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
6177 * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
6178 * evas_object_show(bg);
6179 * ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE);
6180 * @endcode
6181 * So this gives us a white background to our window that will be resized
6182 * together with it.
6183 *
6184 * @section Debugging
6185 *
6186 * Debugging is a major part of any programmers task and when debugging visual
6187 * issues with evas programs the rectangle is an extremely useful tool. The
6188 * rectangle's simplicity means that it's easier to pinpoint issues with it than
6189 * with more complex objects. Therefore a common technique to use when writing
6190 * an evas program and not getting the desired visual result is to replace the
6191 * misbehaving object for a solid color rectangle and seeing how it interacts
6192 * with the other elements, this often allows us to notice clipping, parenting
6193 * or positioning issues. Once the issues have been identified and corrected the
6194 * rectangle can be replaced for the original part and in all likelihood any
6195 * remaining issues will be specific to that object's type.
6196 *
6197 * @section clipping Clipping
6198 *
6199 * Clipping serves two main functions:
6200 * @li Limiting visibility(i.e. hiding portions of an object).
6201 * @li Applying a layer of color to an object.
6202 *
6203 * @subsection hiding Limiting visibility
6204 *
6205 * It is often necessary to show only parts of an object, while it may be
6206 * possible to create an object that corresponds only to the part that must be
6207 * shown(and it isn't always possible) it's usually easier to use a a clipper. A
6208 * clipper is a rectangle that defines what's visible and what is not. The way
6209 * to do this is to create a solid white rectangle(which is the default, no need
6210 * to call evas_object_color_set()) and give it a position and size of what
6211 * should be visible. The following code exemplifies showing the center half of
6212 * @c my_evas_object:
6213 * @code
6214 * Evas_Object *clipper = evas_object_rectangle_add(evas_canvas);
6215 * evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4);
6216 * evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2);
6217 * evas_object_clip_set(my_evas_object, clipper);
6218 * evas_object_show(clipper);
6219 * @endcode
6220 *
6221 * @subsection color Layer of color
6222 *
6223 * In the @ref clipping section we used a solid white clipper, which produced no
6224 * change in the color of the clipped object, it just hid what was outside the
6225 * clippers area. It is however sometimes desirable to change the of color an
6226 * object, this can be accomplished using a clipper that has a non-white color.
6227 * Clippers with color work by multiplying the colors of clipped object. The
6228 * following code will show how to remove all the red from an object:
6229 * @code
6230 * Evas_Object *clipper = evas_object_rectangle_add(evas);
6231 * evas_object_move(clipper, my_evas_object_x, my_evas_object_y);
6232 * evas_object_resize(clipper, my_evas_object_width, my_evas_object_height);
6233 * evas_object_color_set(clipper, 0, 255, 255, 255);
6234 * evas_object_clip_set(obj, clipper);
6235 * evas_object_show(clipper);
6236 * @endcode
6237 *
6238 * For an example that more fully exercise the use of an evas object rectangle
6239 * see @ref Example_Evas_Object_Manipulation.
6240 *
6241 * @ingroup Evas_Object_Specific
6242 */
6243
6244/**
6245 * Adds a rectangle to the given evas.
6246 * @param e The given evas.
6247 * @return The new rectangle object.
6248 *
6249 * @ingroup Evas_Object_Rectangle
6250 */
6251EAPI Evas_Object *evas_object_rectangle_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6252
6253/**
6254 * @defgroup Evas_Object_Image Image Object Functions
6255 *
6256 * Here are grouped together functions used to create and manipulate
6257 * image objects. They are available to whichever occasion one needs
6258 * complex imagery on a GUI that could not be achieved by the other
6259 * Evas' primitive object types, or to make image manipulations.
6260 *
6261 * Evas will support whichever image file types it was compiled with
6262 * support to (its image loaders) -- check your software packager for
6263 * that information and see
6264 * evas_object_image_extension_can_load_get().
6265 *
6266 * @section Evas_Object_Image_Basics Image object basics
6267 *
6268 * The most common use of image objects -- to display an image on the
6269 * canvas -- is achieved by a common function triplet:
6270 * @code
6271 * img = evas_object_image_add(canvas);
6272 * evas_object_image_file_set(img, "path/to/img", NULL);
6273 * evas_object_image_fill_set(img, 0, 0, w, h);
6274 * @endcode
6275 * The first function, naturally, is creating the image object. Then,
6276 * one must set an source file on it, so that it knows where to fetch
6277 * image data from. Next, one must set <b>how to fill the image
6278 * object's area</b> with that given pixel data. One could use just a
6279 * sub-region of the original image or even have it tiled repeatedly
6280 * on the image object. For the common case of having the whole source
6281 * image to be displayed on the image object, stretched to the
6282 * destination's size, there's also a function helper, to be used
6283 * instead of evas_object_image_fill_set():
6284 * @code
6285 * evas_object_image_filled_set(img, EINA_TRUE);
6286 * @endcode
6287 * See those functions' documentation for more details.
6288 *
6289 * @section Evas_Object_Image_Scale Scale and resizing
6290 *
6291 * Resizing of image objects will scale their respective source images
6292 * to their areas, if they are set to "fill" the object's area
6293 * (evas_object_image_filled_set()). If the user wants any control on
6294 * the aspect ratio of an image for different sizes, he/she has to
6295 * take care of that themselves. There are functions to make images to
6296 * get loaded scaled (up or down) in memory, already, if the user is
6297 * going to use them at pre-determined sizes and wants to save
6298 * computations.
6299 *
6300 * Evas has even a scale cache, which will take care of caching scaled
6301 * versions of images with more often usage/hits. Finally, one can
6302 * have images being rescaled @b smoothly by Evas (more
6303 * computationally expensive) or not.
6304 *
6305 * @section Evas_Object_Image_Performance Performance hints
6306 *
6307 * When dealing with image objects, there are some tricks to boost the
6308 * performance of your application, if it does intense image loading
6309 * and/or manipulations, as in animations on a UI.
6310 *
6311 * @subsection Evas_Object_Image_Load Load hints
6312 *
6313 * In image viewer applications, for example, the user will be looking
6314 * at a given image, at full size, and will desire that the navigation
6315 * to the adjacent images on his/her album be fluid and fast. Thus,
6316 * while displaying a given image, the program can be on the
6317 * background loading the next and previous images already, so that
6318 * displaying them on the sequence is just a matter of repainting the
6319 * screen (and not decoding image data).
6320 *
6321 * Evas addresses this issue with <b>image pre-loading</b>. The code
6322 * for the situation above would be something like the following:
6323 * @code
6324 * prev = evas_object_image_filled_add(canvas);
6325 * evas_object_image_file_set(prev, "/path/to/prev", NULL);
6326 * evas_object_image_preload(prev, EINA_TRUE);
6327 *
6328 * next = evas_object_image_filled_add(canvas);
6329 * evas_object_image_file_set(next, "/path/to/next", NULL);
6330 * evas_object_image_preload(next, EINA_TRUE);
6331 * @endcode
6332 *
6333 * If you're loading images which are too big, consider setting
6334 * previously it's loading size to something smaller, in case you
6335 * won't expose them in real size. It may speed up the loading
6336 * considerably:
6337 * @code
6338 * //to load a scaled down version of the image in memory, if that's
6339 * //the size you'll be displaying it anyway
6340 * evas_object_image_load_scale_down_set(img, zoom);
6341 *
6342 * //optional: if you know you'll be showing a sub-set of the image's
6343 * //pixels, you can avoid loading the complementary data
6344 * evas_object_image_load_region_set(img, x, y, w, h);
6345 * @endcode
6346 * Refer to Elementary's Photocam widget for a high level (smart)
6347 * object which does lots of loading speed-ups for you.
6348 *
6349 * @subsection Evas_Object_Image_Animation Animation hints
6350 *
6351 * If you want to animate image objects on a UI (what you'd get by
6352 * concomitant usage of other libraries, like Ecore and Edje), there
6353 * are also some tips on how to boost the performance of your
6354 * application. If the animation involves resizing of an image (thus,
6355 * re-scaling), you'd better turn off smooth scaling on it @b during
6356 * the animation, turning it back on afterwards, for less
6357 * computations. Also, in this case you'd better flag the image object
6358 * in question not to cache scaled versions of it:
6359 * @code
6360 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC);
6361 *
6362 * // resizing takes place in between
6363 *
6364 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC);
6365 * @endcode
6366 *
6367 * Finally, movement of opaque images through the canvas is less
6368 * expensive than of translucid ones, because of blending
6369 * computations.
6370 *
6371 * @section Evas_Object_Image_Borders Borders
6372 *
6373 * Evas provides facilities for one to specify an image's region to be
6374 * treated specially -- as "borders". This will make those regions be
6375 * treated specially on resizing scales, by keeping their aspect. This
6376 * makes setting frames around other objects on UIs easy.
6377 * See the following figures for a visual explanation:\n
6378 * @htmlonly
6379 * <img src="image-borders.png" style="max-width: 100%;" />
6380 * <a href="image-borders.png">Full-size</a>
6381 * @endhtmlonly
6382 * @image rtf image-borders.png
6383 * @image latex image-borders.eps width=\textwidth
6384 * @htmlonly
6385 * <img src="border-effect.png" style="max-width: 100%;" />
6386 * <a href="border-effect.png">Full-size</a>
6387 * @endhtmlonly
6388 * @image rtf border-effect.png
6389 * @image latex border-effect.eps width=\textwidth
6390 *
6391 * @section Evas_Object_Image_Manipulation Manipulating pixels
6392 *
6393 * Evas image objects can be used to manipulate raw pixels in many
6394 * ways. The meaning of the data in the pixel arrays will depend on
6395 * the image's color space, be warned (see next section). You can set
6396 * your own data as an image's pixel data, fetch an image's pixel data
6397 * for saving/altering, convert images between different color spaces
6398 * and even advanced operations like setting a native surface as image
6399 * objects' data.
6400 *
6401 * @section Evas_Object_Image_Color_Spaces Color spaces
6402 *
6403 * Image objects may return or accept "image data" in multiple
6404 * formats. This is based on the color space of an object. Here is a
6405 * rundown on formats:
6406 *
6407 * - #EVAS_COLORSPACE_ARGB8888:
6408 * .
6409 * This pixel format is a linear block of pixels, starting at the
6410 * top-left row by row until the bottom right of the image or pixel
6411 * region. All pixels are 32-bit unsigned int's with the high-byte
6412 * being alpha and the low byte being blue in the format ARGB. Alpha
6413 * may or may not be used by evas depending on the alpha flag of the
6414 * image, but if not used, should be set to 0xff anyway.
6415 * \n\n
6416 * This colorspace uses premultiplied alpha. That means that R, G
6417 * and B cannot exceed A in value. The conversion from
6418 * non-premultiplied colorspace is:
6419 * \n\n
6420 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
6421 * \n\n
6422 * So 50% transparent blue will be: 0x80000080. This will not be
6423 * "dark" - just 50% transparent. Values are 0 == black, 255 ==
6424 * solid or full red, green or blue.
6425 *
6426 * - #EVAS_COLORSPACE_YCBCR422P601_PL:
6427 * .
6428 * This is a pointer-list indirected set of YUV (YCbCr) pixel
6429 * data. This means that the data returned or set is not actual
6430 * pixel data, but pointers TO lines of pixel data. The list of
6431 * pointers will first be N rows of pointers to the Y plane -
6432 * pointing to the first pixel at the start of each row in the Y
6433 * plane. N is the height of the image data in pixels. Each pixel in
6434 * the Y, U and V planes is 1 byte exactly, packed. The next N / 2
6435 * pointers will point to rows in the U plane, and the next N / 2
6436 * pointers will point to the V plane rows. U and V planes are half
6437 * the horizontal and vertical resolution of the Y plane.
6438 * \n\n
6439 * Row order is top to bottom and row pixels are stored left to
6440 * right.
6441 * \n\n
6442 * There is a limitation that these images MUST be a multiple of 2
6443 * pixels in size horizontally or vertically. This is due to the U
6444 * and V planes being half resolution. Also note that this assumes
6445 * the itu601 YUV colorspace specification. This is defined for
6446 * standard television and mpeg streams. HDTV may use the itu709
6447 * specification.
6448 * \n\n
6449 * Values are 0 to 255, indicating full or no signal in that plane
6450 * respectively.
6451 *
6452 * - #EVAS_COLORSPACE_YCBCR422P709_PL:
6453 * .
6454 * Not implemented yet.
6455 *
6456 * - #EVAS_COLORSPACE_RGB565_A5P:
6457 * .
6458 * In the process of being implemented in 1 engine only. This may
6459 * change.
6460 * \n\n
6461 * This is a pointer to image data for 16-bit half-word pixel data
6462 * in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue),
6463 * with the high-byte containing red and the low byte containing
6464 * blue, per pixel. This data is packed row by row from the top-left
6465 * to the bottom right.
6466 * \n\n
6467 * If the image has an alpha channel enabled there will be an extra
6468 * alpha plane after the color pixel plane. If not, then this data
6469 * will not exist and should not be accessed in any way. This plane
6470 * is a set of pixels with 1 byte per pixel defining the alpha
6471 * values of all pixels in the image from the top-left to the bottom
6472 * right of the image, row by row. Even though the values of the
6473 * alpha pixels can be 0 to 255, only values 0 through to 32 are
6474 * used, 32 being solid and 0 being transparent.
6475 * \n\n
6476 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
6477 * with 0 being black and 31 or 63 being full red, green or blue
6478 * respectively. This colorspace is also pre-multiplied like
6479 * EVAS_COLORSPACE_ARGB8888 so:
6480 * \n\n
6481 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
6482 *
6483 * - #EVAS_COLORSPACE_GRY8:
6484 * .
6485 * The image is just a alpha mask (8 bit's per pixel). This is used
6486 * for alpha masking.
6487 *
6488 * Some examples on this group of functions can be found @ref
6489 * Example_Evas_Images "here".
6490 *
6491 * @ingroup Evas_Object_Specific
6492 */
6493
6494/**
6495 * @addtogroup Evas_Object_Image
6496 * @{
6497 */
6498
6499typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o);
6500
6501
6502/**
6503 * Creates a new image object on the given Evas @p e canvas.
6504 *
6505 * @param e The given canvas.
6506 * @return The created image object handle.
6507 *
6508 * @note If you intend to @b display an image somehow in a GUI,
6509 * besides binding it to a real image file/source (with
6510 * evas_object_image_file_set(), for example), you'll have to tell
6511 * this image object how to fill its space with the pixels it can get
6512 * from the source. See evas_object_image_filled_add(), for a helper
6513 * on the common case of scaling up an image source to the whole area
6514 * of the image object.
6515 *
6516 * @see evas_object_image_fill_set()
6517 *
6518 * Example:
6519 * @code
6520 * img = evas_object_image_add(canvas);
6521 * evas_object_image_file_set(img, "/path/to/img", NULL);
6522 * @endcode
6523 */
6524EAPI Evas_Object *evas_object_image_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6525
6526/**
6527 * Creates a new image object that @b automatically scales its bound
6528 * image to the object's area, on both axis.
6529 *
6530 * @param e The given canvas.
6531 * @return The created image object handle.
6532 *
6533 * This is a helper function around evas_object_image_add() and
6534 * evas_object_image_filled_set(). It has the same effect of applying
6535 * those functions in sequence, which is a very common use case.
6536 *
6537 * @note Whenever this object gets resized, the bound image will be
6538 * rescaled, too.
6539 *
6540 * @see evas_object_image_add()
6541 * @see evas_object_image_filled_set()
6542 * @see evas_object_image_fill_set()
6543 */
6544EAPI Evas_Object *evas_object_image_filled_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6545
6546
6547/**
6548 * Sets the data for an image from memory to be loaded
6549 *
6550 * This is the same as evas_object_image_file_set() but the file to be loaded
6551 * may exist at an address in memory (the data for the file, not the filename
6552 * itself). The @p data at the address is copied and stored for future use, so
6553 * no @p data needs to be kept after this call is made. It will be managed and
6554 * freed for you when no longer needed. The @p size is limited to 2 gigabytes
6555 * in size, and must be greater than 0. A NULL @p data pointer is also invalid.
6556 * Set the filename to NULL to reset to empty state and have the image file
6557 * data freed from memory using evas_object_image_file_set().
6558 *
6559 * The @p format is optional (pass NULL if you don't need/use it). It is used
6560 * to help Evas guess better which loader to use for the data. It may simply
6561 * be the "extension" of the file as it would normally be on disk such as
6562 * "jpg" or "png" or "gif" etc.
6563 *
6564 * @param obj The given image object.
6565 * @param data The image file data address
6566 * @param size The size of the image file data in bytes
6567 * @param format The format of the file (optional), or @c NULL if not needed
6568 * @param key The image key in file, or @c NULL.
6569 */
6570EAPI void evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2);
6571
6572/**
6573 * Set the source file from where an image object must fetch the real
6574 * image data (it may be an Eet file, besides pure image ones).
6575 *
6576 * @param obj The given image object.
6577 * @param file The image file path.
6578 * @param key The image key in @p file (if its an Eet one), or @c
6579 * NULL, otherwise.
6580 *
6581 * If the file supports multiple data stored in it (as Eet files do),
6582 * you can specify the key to be used as the index of the image in
6583 * this file.
6584 *
6585 * Example:
6586 * @code
6587 * img = evas_object_image_add(canvas);
6588 * evas_object_image_file_set(img, "/path/to/img", NULL);
6589 * err = evas_object_image_load_error_get(img);
6590 * if (err != EVAS_LOAD_ERROR_NONE)
6591 * {
6592 * fprintf(stderr, "could not load image '%s'. error string is \"%s\"\n",
6593 * valid_path, evas_load_error_str(err));
6594 * }
6595 * else
6596 * {
6597 * evas_object_image_fill_set(img, 0, 0, w, h);
6598 * evas_object_resize(img, w, h);
6599 * evas_object_show(img);
6600 * }
6601 * @endcode
6602 */
6603EAPI void evas_object_image_file_set (Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
6604
6605/**
6606 * Retrieve the source file from where an image object is to fetch the
6607 * real image data (it may be an Eet file, besides pure image ones).
6608 *
6609 * @param obj The given image object.
6610 * @param file Location to store the image file path.
6611 * @param key Location to store the image key (if @p file is an Eet
6612 * one).
6613 *
6614 * You must @b not modify the strings on the returned pointers.
6615 *
6616 * @note Use @c NULL pointers on the file components you're not
6617 * interested in: they'll be ignored by the function.
6618 */
6619EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2);
6620
6621/**
6622 * Set the dimensions for an image object's border, a region which @b
6623 * won't ever be scaled together with its center.
6624 *
6625 * @param obj The given image object.
6626 * @param l The border's left width.
6627 * @param r The border's right width.
6628 * @param t The border's top width.
6629 * @param b The border's bottom width.
6630 *
6631 * When Evas is rendering, an image source may be scaled to fit the
6632 * size of its image object. This function sets an area from the
6633 * borders of the image inwards which is @b not to be scaled. This
6634 * function is useful for making frames and for widget theming, where,
6635 * for example, buttons may be of varying sizes, but their border size
6636 * must remain constant.
6637 *
6638 * The units used for @p l, @p r, @p t and @p b are canvas units.
6639 *
6640 * @note The border region itself @b may be scaled by the
6641 * evas_object_image_border_scale_set() function.
6642 *
6643 * @note By default, image objects have no borders set, i. e. @c l, @c
6644 * r, @c t and @c b start as @c 0.
6645 *
6646 * See the following figures for visual explanation:\n
6647 * @htmlonly
6648 * <img src="image-borders.png" style="max-width: 100%;" />
6649 * <a href="image-borders.png">Full-size</a>
6650 * @endhtmlonly
6651 * @image rtf image-borders.png
6652 * @image latex image-borders.eps width=\textwidth
6653 * @htmlonly
6654 * <img src="border-effect.png" style="max-width: 100%;" />
6655 * <a href="border-effect.png">Full-size</a>
6656 * @endhtmlonly
6657 * @image rtf border-effect.png
6658 * @image latex border-effect.eps width=\textwidth
6659 *
6660 * @see evas_object_image_border_get()
6661 * @see evas_object_image_border_center_fill_set()
6662 */
6663EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1);
6664
6665/**
6666 * Retrieve the dimensions for an image object's border, a region
6667 * which @b won't ever be scaled together with its center.
6668 *
6669 * @param obj The given image object.
6670 * @param l Location to store the border's left width in.
6671 * @param r Location to store the border's right width in.
6672 * @param t Location to store the border's top width in.
6673 * @param b Location to store the border's bottom width in.
6674 *
6675 * @note Use @c NULL pointers on the border components you're not
6676 * interested in: they'll be ignored by the function.
6677 *
6678 * See @ref evas_object_image_border_set() for more details.
6679 */
6680EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
6681
6682/**
6683 * Sets @b how the center part of the given image object (not the
6684 * borders) should be drawn when Evas is rendering it.
6685 *
6686 * @param obj The given image object.
6687 * @param fill Fill mode of the center region of @p obj (a value in
6688 * #Evas_Border_Fill_Mode).
6689 *
6690 * This function sets how the center part of the image object's source
6691 * image is to be drawn, which must be one of the values in
6692 * #Evas_Border_Fill_Mode. By center we mean the complementary part of
6693 * that defined by evas_object_image_border_set(). This one is very
6694 * useful for making frames and decorations. You would most probably
6695 * also be using a filled image (as in evas_object_image_filled_set())
6696 * to use as a frame.
6697 *
6698 * @see evas_object_image_border_center_fill_get()
6699 */
6700EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1);
6701
6702/**
6703 * Retrieves @b how the center part of the given image object (not the
6704 * borders) is to be drawn when Evas is rendering it.
6705 *
6706 * @param obj The given image object.
6707 * @return fill Fill mode of the center region of @p obj (a value in
6708 * #Evas_Border_Fill_Mode).
6709 *
6710 * See @ref evas_object_image_fill_set() for more details.
6711 */
6712EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6713
6714/**
6715 * Set whether the image object's fill property should track the
6716 * object's size.
6717 *
6718 * @param obj The given image object.
6719 * @param setting @c EINA_TRUE, to make the fill property follow
6720 * object size or @c EINA_FALSE, otherwise
6721 *
6722 * If @p setting is @c EINA_TRUE, then every evas_object_resize() will
6723 * @b automatically trigger a call to evas_object_image_fill_set()
6724 * with the that new size (and @c 0, @c 0 as source image's origin),
6725 * so the bound image will fill the whole object's area.
6726 *
6727 * @see evas_object_image_filled_add()
6728 * @see evas_object_image_fill_get()
6729 */
6730EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
6731
6732/**
6733 * Retrieve whether the image object's fill property should track the
6734 * object's size.
6735 *
6736 * @param obj The given image object.
6737 * @return @c EINA_TRUE if it is tracking, @c EINA_FALSE, if not (and
6738 * evas_object_fill_set() must be called manually).
6739 *
6740 * @see evas_object_image_filled_set() for more information
6741 */
6742EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6743
6744/**
6745 * Sets the scaling factor (multiplier) for the borders of an image
6746 * object.
6747 *
6748 * @param obj The given image object.
6749 * @param scale The scale factor (default is @c 1.0 - i.e. no scaling)
6750 *
6751 * @see evas_object_image_border_set()
6752 * @see evas_object_image_border_scale_get()
6753 */
6754EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale);
6755
6756/**
6757 * Retrieves the scaling factor (multiplier) for the borders of an
6758 * image object.
6759 *
6760 * @param obj The given image object.
6761 * @return The scale factor set for its borders
6762 *
6763 * @see evas_object_image_border_set()
6764 * @see evas_object_image_border_scale_set()
6765 */
6766EAPI double evas_object_image_border_scale_get (const Evas_Object *obj);
6767
6768/**
6769 * Set how to fill an image object's drawing rectangle given the
6770 * (real) image bound to it.
6771 *
6772 * @param obj The given image object to operate on.
6773 * @param x The x coordinate (from the top left corner of the bound
6774 * image) to start drawing from.
6775 * @param y The y coordinate (from the top left corner of the bound
6776 * image) to start drawing from.
6777 * @param w The width the bound image will be displayed at.
6778 * @param h The height the bound image will be displayed at.
6779 *
6780 * Note that if @p w or @p h are smaller than the dimensions of
6781 * @p obj, the displayed image will be @b tiled around the object's
6782 * area. To have only one copy of the bound image drawn, @p x and @p y
6783 * must be 0 and @p w and @p h need to be the exact width and height
6784 * of the image object itself, respectively.
6785 *
6786 * See the following image to better understand the effects of this
6787 * call. On this diagram, both image object and original image source
6788 * have @c a x @c a dimensions and the image itself is a circle, with
6789 * empty space around it:
6790 *
6791 * @image html image-fill.png
6792 * @image rtf image-fill.png
6793 * @image latex image-fill.eps
6794 *
6795 * @warning The default values for the fill parameters are @p x = 0,
6796 * @p y = 0, @p w = 0 and @p h = 0. Thus, if you're not using the
6797 * evas_object_image_filled_add() helper and want your image
6798 * displayed, you'll have to set valid values with this function on
6799 * your object.
6800 *
6801 * @note evas_object_image_filled_set() is a helper function which
6802 * will @b override the values set here automatically, for you, in a
6803 * given way.
6804 */
6805EAPI void evas_object_image_fill_set (Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
6806
6807/**
6808 * Retrieve how an image object is to fill its drawing rectangle,
6809 * given the (real) image bound to it.
6810 *
6811 * @param obj The given image object.
6812 * @param x Location to store the x coordinate (from the top left
6813 * corner of the bound image) to start drawing from.
6814 * @param y Location to store the y coordinate (from the top left
6815 * corner of the bound image) to start drawing from.
6816 * @param w Location to store the width the bound image is to be
6817 * displayed at.
6818 * @param h Location to store the height the bound image is to be
6819 * displayed at.
6820 *
6821 * @note Use @c NULL pointers on the fill components you're not
6822 * interested in: they'll be ignored by the function.
6823 *
6824 * See @ref evas_object_image_fill_set() for more details.
6825 */
6826EAPI void evas_object_image_fill_get (const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
6827
6828/**
6829 * Sets the tiling mode for the given evas image object's fill.
6830 * @param obj The given evas image object.
6831 * @param spread One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT,
6832 * EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.
6833 */
6834EAPI void evas_object_image_fill_spread_set (Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1);
6835
6836/**
6837 * Retrieves the spread (tiling mode) for the given image object's
6838 * fill.
6839 *
6840 * @param obj The given evas image object.
6841 * @return The current spread mode of the image object.
6842 */
6843EAPI Evas_Fill_Spread evas_object_image_fill_spread_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6844
6845/**
6846 * Sets the size of the given image object.
6847 *
6848 * @param obj The given image object.
6849 * @param w The new width of the image.
6850 * @param h The new height of the image.
6851 *
6852 * This function will scale down or crop the image so that it is
6853 * treated as if it were at the given size. If the size given is
6854 * smaller than the image, it will be cropped. If the size given is
6855 * larger, then the image will be treated as if it were in the upper
6856 * left hand corner of a larger image that is otherwise transparent.
6857 */
6858EAPI void evas_object_image_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
6859
6860/**
6861 * Retrieves the size of the given image object.
6862 *
6863 * @param obj The given image object.
6864 * @param w Location to store the width of the image in, or @c NULL.
6865 * @param h Location to store the height of the image in, or @c NULL.
6866 *
6867 * See @ref evas_object_image_size_set() for more details.
6868 */
6869EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
6870
6871/**
6872 * Retrieves the row stride of the given image object.
6873 *
6874 * @param obj The given image object.
6875 * @return The stride of the image (<b>in bytes</b>).
6876 *
6877 * The row stride is the number of bytes between the start of a row
6878 * and the start of the next row for image data.
6879 */
6880EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6881
6882/**
6883 * Retrieves a number representing any error that occurred during the
6884 * last loading of the given image object's source image.
6885 *
6886 * @param obj The given image object.
6887 * @return A value giving the last error that occurred. It should be
6888 * one of the #Evas_Load_Error values. #EVAS_LOAD_ERROR_NONE
6889 * is returned if there was no error.
6890 */
6891EAPI Evas_Load_Error evas_object_image_load_error_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6892
6893/**
6894 * Sets the raw image data of the given image object.
6895 *
6896 * @param obj The given image object.
6897 * @param data The raw data, or @c NULL.
6898 *
6899 * Note that the raw data must be of the same size (see
6900 * evas_object_image_size_set(), which has to be called @b before this
6901 * one) and colorspace (see evas_object_image_colorspace_set()) of the
6902 * image. If data is @c NULL, the current image data will be
6903 * freed. Naturally, if one does not set an image object's data
6904 * manually, it will still have one, allocated by Evas.
6905 *
6906 * @see evas_object_image_data_get()
6907 */
6908EAPI void evas_object_image_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
6909
6910/**
6911 * Get a pointer to the raw image data of the given image object.
6912 *
6913 * @param obj The given image object.
6914 * @param for_writing Whether the data being retrieved will be
6915 * modified (@c EINA_TRUE) or not (@c EINA_FALSE).
6916 * @return The raw image data.
6917 *
6918 * This function returns a pointer to an image object's internal pixel
6919 * buffer, for reading only or read/write. If you request it for
6920 * writing, the image will be marked dirty so that it gets redrawn at
6921 * the next update.
6922 *
6923 * Each time you call this function on an image object, its data
6924 * buffer will have an internal reference counter
6925 * incremented. Decrement it back by using
6926 * evas_object_image_data_set(). This is specially important for the
6927 * directfb Evas engine.
6928 *
6929 * This is best suited for when you want to modify an existing image,
6930 * without changing its dimensions.
6931 *
6932 * @note The contents' format returned by it depend on the color
6933 * space of the given image object.
6934 *
6935 * @note You may want to use evas_object_image_data_update_add() to
6936 * inform data changes, if you did any.
6937 *
6938 * @see evas_object_image_data_set()
6939 */
6940EAPI void *evas_object_image_data_get (const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6941
6942/**
6943 * Converts the raw image data of the given image object to the
6944 * specified colorspace.
6945 *
6946 * Note that this function does not modify the raw image data. If the
6947 * requested colorspace is the same as the image colorspace nothing is
6948 * done and NULL is returned. You should use
6949 * evas_object_image_colorspace_get() to check the current image
6950 * colorspace.
6951 *
6952 * See @ref evas_object_image_colorspace_get.
6953 *
6954 * @param obj The given image object.
6955 * @param to_cspace The colorspace to which the image raw data will be converted.
6956 * @return data A newly allocated data in the format specified by to_cspace.
6957 */
6958EAPI void *evas_object_image_data_convert (Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6959
6960/**
6961 * Replaces the raw image data of the given image object.
6962 *
6963 * @param obj The given image object.
6964 * @param data The raw data to replace.
6965 *
6966 * This function lets the application replace an image object's
6967 * internal pixel buffer with an user-allocated one. For best results,
6968 * you should generally first call evas_object_image_size_set() with
6969 * the width and height for the new buffer.
6970 *
6971 * This call is best suited for when you will be using image data with
6972 * different dimensions than the existing image data, if any. If you
6973 * only need to modify the existing image in some fashion, then using
6974 * evas_object_image_data_get() is probably what you are after.
6975 *
6976 * Note that the caller is responsible for freeing the buffer when
6977 * finished with it, as user-set image data will not be automatically
6978 * freed when the image object is deleted.
6979 *
6980 * See @ref evas_object_image_data_get() for more details.
6981 *
6982 */
6983EAPI void evas_object_image_data_copy_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
6984
6985/**
6986 * Mark a sub-region of the given image object to be redrawn.
6987 *
6988 * @param obj The given image object.
6989 * @param x X-offset of the region to be updated.
6990 * @param y Y-offset of the region to be updated.
6991 * @param w Width of the region to be updated.
6992 * @param h Height of the region to be updated.
6993 *
6994 * This function schedules a particular rectangular region of an image
6995 * object to be updated (redrawn) at the next rendering cycle.
6996 */
6997EAPI void evas_object_image_data_update_add (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
6998
6999/**
7000 * Enable or disable alpha channel usage on the given image object.
7001 *
7002 * @param obj The given image object.
7003 * @param has_alpha Whether to use alpha channel (@c EINA_TRUE) data
7004 * or not (@c EINA_FALSE).
7005 *
7006 * This function sets a flag on an image object indicating whether or
7007 * not to use alpha channel data. A value of @c EINA_TRUE makes it use
7008 * alpha channel data, and @c EINA_FALSE makes it ignore that
7009 * data. Note that this has nothing to do with an object's color as
7010 * manipulated by evas_object_color_set().
7011 *
7012 * @see evas_object_image_alpha_get()
7013 */
7014EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1);
7015
7016/**
7017 * Retrieve whether alpha channel data is being used on the given
7018 * image object.
7019 *
7020 * @param obj The given image object.
7021 * @return Whether the alpha channel data is being used (@c EINA_TRUE)
7022 * or not (@c EINA_FALSE).
7023 *
7024 * This function returns @c EINA_TRUE if the image object's alpha
7025 * channel is being used, or @c EINA_FALSE otherwise.
7026 *
7027 * See @ref evas_object_image_alpha_set() for more details.
7028 */
7029EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7030
7031/**
7032 * Sets whether to use high-quality image scaling algorithm on the
7033 * given image object.
7034 *
7035 * @param obj The given image object.
7036 * @param smooth_scale Whether to use smooth scale or not.
7037 *
7038 * When enabled, a higher quality image scaling algorithm is used when
7039 * scaling images to sizes other than the source image's original
7040 * one. This gives better results but is more computationally
7041 * expensive.
7042 *
7043 * @note Image objects get created originally with smooth scaling @b
7044 * on.
7045 *
7046 * @see evas_object_image_smooth_scale_get()
7047 */
7048EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1);
7049
7050/**
7051 * Retrieves whether the given image object is using high-quality
7052 * image scaling algorithm.
7053 *
7054 * @param obj The given image object.
7055 * @return Whether smooth scale is being used.
7056 *
7057 * See @ref evas_object_image_smooth_scale_set() for more details.
7058 */
7059EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7060
7061/**
7062 * Preload an image object's image data in the background
7063 *
7064 * @param obj The given image object.
7065 * @param cancel @c EINA_FALSE will add it the preloading work queue,
7066 * @c EINA_TRUE will remove it (if it was issued before).
7067 *
7068 * This function requests the preload of the data image in the
7069 * background. The work is queued before being processed (because
7070 * there might be other pending requests of this type).
7071 *
7072 * Whenever the image data gets loaded, Evas will call
7073 * #EVAS_CALLBACK_IMAGE_PRELOADED registered callbacks on @p obj (what
7074 * may be immediately, if the data was already preloaded before).
7075 *
7076 * Use @c EINA_TRUE for @p cancel on scenarios where you don't need
7077 * the image data preloaded anymore.
7078 *
7079 * @note Any evas_object_show() call after evas_object_image_preload()
7080 * will make the latter to be @b cancelled, with the loading process
7081 * now taking place @b synchronously (and, thus, blocking the return
7082 * of the former until the image is loaded). It is highly advisable,
7083 * then, that the user preload an image with it being @b hidden, just
7084 * to be shown on the #EVAS_CALLBACK_IMAGE_PRELOADED event's callback.
7085 */
7086EAPI void evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1);
7087
7088/**
7089 * Reload an image object's image data.
7090 *
7091 * @param obj The given image object pointer.
7092 *
7093 * This function reloads the image data bound to image object @p obj.
7094 */
7095EAPI void evas_object_image_reload (Evas_Object *obj) EINA_ARG_NONNULL(1);
7096
7097/**
7098 * Save the given image object's contents to an (image) file.
7099 *
7100 * @param obj The given image object.
7101 * @param file The filename to be used to save the image (extension
7102 * obligatory).
7103 * @param key The image key in the file (if an Eet one), or @c NULL,
7104 * otherwise.
7105 * @param flags String containing the flags to be used (@c NULL for
7106 * none).
7107 *
7108 * The extension suffix on @p file will determine which <b>saver
7109 * module</b> Evas is to use when saving, thus the final file's
7110 * format. If the file supports multiple data stored in it (Eet ones),
7111 * you can specify the key to be used as the index of the image in it.
7112 *
7113 * You can specify some flags when saving the image. Currently
7114 * acceptable flags are @c quality and @c compress. Eg.: @c
7115 * "quality=100 compress=9"
7116 */
7117EAPI Eina_Bool evas_object_image_save (const Evas_Object *obj, const char *file, const char *key, const char *flags) EINA_ARG_NONNULL(1, 2);
7118
7119/**
7120 * Import pixels from given source to a given canvas image object.
7121 *
7122 * @param obj The given canvas object.
7123 * @param pixels The pixel's source to be imported.
7124 *
7125 * This function imports pixels from a given source to a given canvas image.
7126 *
7127 */
7128EAPI Eina_Bool evas_object_image_pixels_import (Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2);
7129
7130/**
7131 * Set the callback function to get pixels from a canvas' image.
7132 *
7133 * @param obj The given canvas pointer.
7134 * @param func The callback function.
7135 * @param data The data pointer to be passed to @a func.
7136 *
7137 * This functions sets a function to be the callback function that get
7138 * pixes from a image of the canvas.
7139 *
7140 */
7141EAPI void evas_object_image_pixels_get_callback_set(Evas_Object *obj, Evas_Object_Image_Pixels_Get_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
7142
7143/**
7144 * Mark whether the given image object is dirty (needs to be redrawn).
7145 *
7146 * @param obj The given image object.
7147 * @param dirty Whether the image is dirty.
7148 */
7149EAPI void evas_object_image_pixels_dirty_set (Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1);
7150
7151/**
7152 * Retrieves whether the given image object is dirty (needs to be redrawn).
7153 *
7154 * @param obj The given image object.
7155 * @return Whether the image is dirty.
7156 */
7157EAPI Eina_Bool evas_object_image_pixels_dirty_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7158
7159/**
7160 * Set the DPI resolution of an image object's source image.
7161 *
7162 * @param obj The given canvas pointer.
7163 * @param dpi The new DPI resolution.
7164 *
7165 * This function sets the DPI resolution of a given loaded canvas
7166 * image. Most useful for the SVG image loader.
7167 *
7168 * @see evas_object_image_load_dpi_get()
7169 */
7170EAPI void evas_object_image_load_dpi_set (Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1);
7171
7172/**
7173 * Get the DPI resolution of a loaded image object in the canvas.
7174 *
7175 * @param obj The given canvas pointer.
7176 * @return The DPI resolution of the given canvas image.
7177 *
7178 * This function returns the DPI resolution of the given canvas image.
7179 *
7180 * @see evas_object_image_load_dpi_set() for more details
7181 */
7182EAPI double evas_object_image_load_dpi_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7183
7184/**
7185 * Set the size of a given image object's source image, when loading
7186 * it.
7187 *
7188 * @param obj The given canvas object.
7189 * @param w The new width of the image's load size.
7190 * @param h The new height of the image's load size.
7191 *
7192 * This function sets a new (loading) size for the given canvas
7193 * image.
7194 *
7195 * @see evas_object_image_load_size_get()
7196 */
7197EAPI void evas_object_image_load_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
7198
7199/**
7200 * Get the size of a given image object's source image, when loading
7201 * it.
7202 *
7203 * @param obj The given image object.
7204 * @param w Where to store the new width of the image's load size.
7205 * @param h Where to store the new height of the image's load size.
7206 *
7207 * @note Use @c NULL pointers on the size components you're not
7208 * interested in: they'll be ignored by the function.
7209 *
7210 * @see evas_object_image_load_size_set() for more details
7211 */
7212EAPI void evas_object_image_load_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
7213
7214/**
7215 * Set the scale down factor of a given image object's source image,
7216 * when loading it.
7217 *
7218 * @param obj The given image object pointer.
7219 * @param scale_down The scale down factor.
7220 *
7221 * This function sets the scale down factor of a given canvas
7222 * image. Most useful for the SVG image loader.
7223 *
7224 * @see evas_object_image_load_scale_down_get()
7225 */
7226EAPI void evas_object_image_load_scale_down_set (Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1);
7227
7228/**
7229 * get the scale down factor of a given image object's source image,
7230 * when loading it.
7231 *
7232 * @param obj The given image object pointer.
7233 *
7234 * @see evas_object_image_load_scale_down_set() for more details
7235 */
7236EAPI int evas_object_image_load_scale_down_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7237
7238/**
7239 * Inform a given image object to load a selective region of its
7240 * source image.
7241 *
7242 * @param obj The given image object pointer.
7243 * @param x X-offset of the region to be loaded.
7244 * @param y Y-offset of the region to be loaded.
7245 * @param w Width of the region to be loaded.
7246 * @param h Height of the region to be loaded.
7247 *
7248 * This function is useful when one is not showing all of an image's
7249 * area on its image object.
7250 *
7251 * @note The image loader for the image format in question has to
7252 * support selective region loading in order to this function to take
7253 * effect.
7254 *
7255 * @see evas_object_image_load_region_get()
7256 */
7257EAPI void evas_object_image_load_region_set (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
7258
7259/**
7260 * Retrieve the coordinates of a given image object's selective
7261 * (source image) load region.
7262 *
7263 * @param obj The given image object pointer.
7264 * @param x Where to store the X-offset of the region to be loaded.
7265 * @param y Where to store the Y-offset of the region to be loaded.
7266 * @param w Where to store the width of the region to be loaded.
7267 * @param h Where to store the height of the region to be loaded.
7268 *
7269 * @note Use @c NULL pointers on the coordinates you're not interested
7270 * in: they'll be ignored by the function.
7271 *
7272 * @see evas_object_image_load_region_get()
7273 */
7274EAPI void evas_object_image_load_region_get (const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
7275
7276/**
7277 * Define if the orientation information in the image file should be honored.
7278 *
7279 * @param obj The given image object pointer.
7280 * @param enable @p EINA_TRUE means that it should honor the orientation information
7281 * @since 1.1
7282 */
7283EAPI void evas_object_image_load_orientation_set (Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
7284
7285/**
7286 * Get if the orientation information in the image file should be honored.
7287 *
7288 * @param obj The given image object pointer.
7289 * @since 1.1
7290 */
7291EAPI Eina_Bool evas_object_image_load_orientation_get (const Evas_Object *obj) EINA_ARG_NONNULL(1);
7292
7293/**
7294 * Set the colorspace of a given image of the canvas.
7295 *
7296 * @param obj The given image object pointer.
7297 * @param cspace The new color space.
7298 *
7299 * This function sets the colorspace of given canvas image.
7300 *
7301 */
7302EAPI void evas_object_image_colorspace_set (Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1);
7303
7304/**
7305 * Get the colorspace of a given image of the canvas.
7306 *
7307 * @param obj The given image object pointer.
7308 * @return The colorspace of the image.
7309 *
7310 * This function returns the colorspace of given canvas image.
7311 *
7312 */
7313EAPI Evas_Colorspace evas_object_image_colorspace_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7314
7315/**
7316 * Get the support state of a given image
7317 *
7318 * @param obj The given image object pointer
7319 * @return The region support state
7320 * @since 1.2.0
7321 *
7322 * This function returns the state of the region support of given image
7323 */
7324EAPI Eina_Bool evas_object_image_region_support_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7325
7326/**
7327 * Set the native surface of a given image of the canvas
7328 *
7329 * @param obj The given canvas pointer.
7330 * @param surf The new native surface.
7331 *
7332 * This function sets a native surface of a given canvas image.
7333 *
7334 */
7335EAPI void evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2);
7336
7337/**
7338 * Get the native surface of a given image of the canvas
7339 *
7340 * @param obj The given canvas pointer.
7341 * @return The native surface of the given canvas image.
7342 *
7343 * This function returns the native surface of a given canvas image.
7344 *
7345 */
7346EAPI Evas_Native_Surface *evas_object_image_native_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7347
7348/**
7349 * Set the video surface linked to a given image of the canvas
7350 *
7351 * @param obj The given canvas pointer.
7352 * @param surf The new video surface.
7353 * @since 1.1.0
7354 *
7355 * This function link a video surface to a given canvas image.
7356 *
7357 */
7358EAPI void evas_object_image_video_surface_set (Evas_Object *obj, Evas_Video_Surface *surf) EINA_ARG_NONNULL(1);
7359
7360/**
7361 * Get the video surface linekd to a given image of the canvas
7362 *
7363 * @param obj The given canvas pointer.
7364 * @return The video surface of the given canvas image.
7365 * @since 1.1.0
7366 *
7367 * This function returns the video surface linked to a given canvas image.
7368 *
7369 */
7370EAPI const Evas_Video_Surface *evas_object_image_video_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7371
7372/**
7373 * Set the scale hint of a given image of the canvas.
7374 *
7375 * @param obj The given image object pointer.
7376 * @param hint The scale hint, a value in
7377 * #Evas_Image_Scale_Hint.
7378 *
7379 * This function sets the scale hint value of the given image object
7380 * in the canvas, which will affect how Evas is to cache scaled
7381 * versions of its original source image.
7382 *
7383 * @see evas_object_image_scale_hint_get()
7384 */
7385EAPI void evas_object_image_scale_hint_set (Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1);
7386
7387/**
7388 * Get the scale hint of a given image of the canvas.
7389 *
7390 * @param obj The given image object pointer.
7391 * @return The scale hint value set on @p obj, a value in
7392 * #Evas_Image_Scale_Hint.
7393 *
7394 * This function returns the scale hint value of the given image
7395 * object of the canvas.
7396 *
7397 * @see evas_object_image_scale_hint_set() for more details.
7398 */
7399EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7400
7401/**
7402 * Set the content hint setting of a given image object of the canvas.
7403 *
7404 * @param obj The given canvas pointer.
7405 * @param hint The content hint value, one of the
7406 * #Evas_Image_Content_Hint ones.
7407 *
7408 * This function sets the content hint value of the given image of the
7409 * canvas. For example, if you're on the GL engine and your driver
7410 * implementation supports it, setting this hint to
7411 * #EVAS_IMAGE_CONTENT_HINT_DYNAMIC will make it need @b zero copies
7412 * at texture upload time, which is an "expensive" operation.
7413 *
7414 * @see evas_object_image_content_hint_get()
7415 */
7416EAPI void evas_object_image_content_hint_set (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1);
7417
7418/**
7419 * Get the content hint setting of a given image object of the canvas.
7420 *
7421 * @param obj The given canvas pointer.
7422 * @return hint The content hint value set on it, one of the
7423 * #Evas_Image_Content_Hint ones (#EVAS_IMAGE_CONTENT_HINT_NONE means
7424 * an error).
7425 *
7426 * This function returns the content hint value of the given image of
7427 * the canvas.
7428 *
7429 * @see evas_object_image_content_hint_set()
7430 */
7431EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7432
7433
7434/**
7435 * Enable an image to be used as an alpha mask.
7436 *
7437 * This will set any flags, and discard any excess image data not used as an
7438 * alpha mask.
7439 *
7440 * Note there is little point in using a image as alpha mask unless it has an
7441 * alpha channel.
7442 *
7443 * @param obj Object to use as an alpha mask.
7444 * @param ismask Use image as alphamask, must be true.
7445 */
7446EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1);
7447
7448/**
7449 * Set the source object on an image object to used as a @b proxy.
7450 *
7451 * @param obj Proxy (image) object.
7452 * @param src Source object to use for the proxy.
7453 * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
7454 *
7455 * If an image object is set to behave as a @b proxy, it will mirror
7456 * the rendering contents of a given @b source object in its drawing
7457 * region, without affecting that source in any way. The source must
7458 * be another valid Evas object. Other effects may be applied to the
7459 * proxy, such as a map (see evas_object_map_set()) to create a
7460 * reflection of the original object (for example).
7461 *
7462 * Any existing source object on @p obj will be removed after this
7463 * call. Setting @p src to @c NULL clears the proxy object (not in
7464 * "proxy state" anymore).
7465 *
7466 * @warning You cannot set a proxy as another proxy's source.
7467 *
7468 * @see evas_object_image_source_get()
7469 * @see evas_object_image_source_unset()
7470 */
7471EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1);
7472
7473/**
7474 * Get the current source object of an image object.
7475 *
7476 * @param obj Image object
7477 * @return Source object (if any), or @c NULL, if not in "proxy mode"
7478 * (or on errors).
7479 *
7480 * @see evas_object_image_source_set() for more details
7481 */
7482EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1);
7483
7484/**
7485 * Clear the source object on a proxy image object.
7486 *
7487 * @param obj Image object to clear source of.
7488 * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
7489 *
7490 * This is equivalent to calling evas_object_image_source_set() with a
7491 * @c NULL source.
7492 */
7493EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1);
7494
7495/**
7496 * Check if a file extension may be supported by @ref Evas_Object_Image.
7497 *
7498 * @param file The file to check
7499 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
7500 * @since 1.1.0
7501 *
7502 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
7503 *
7504 * This functions is threadsafe.
7505 */
7506EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
7507
7508/**
7509 * Check if a file extension may be supported by @ref Evas_Object_Image.
7510 *
7511 * @param file The file to check, it should be an Eina_Stringshare.
7512 * @return EINA_TRUE if we may be able to open it, EINA_FALSE if it's unlikely.
7513 * @since 1.1.0
7514 *
7515 * This functions is threadsafe.
7516 */
7517EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
7518
7519/**
7520 * Check if an image object can be animated (have multiple frames)
7521 *
7522 * @param obj Image object
7523 * @return whether obj support animation
7524 *
7525 * This returns if the image file of an image object is capable of animation
7526 * such as an animated gif file might. This is only useful to be called once
7527 * the image object file has been set.
7528 *
7529 * Example:
7530 * @code
7531 * extern Evas_Object *obj;
7532 *
7533 * if (evas_object_image_animated_get(obj))
7534 * {
7535 * int frame_count;
7536 * int loop_count;
7537 * Evas_Image_Animated_Loop_Hint loop_type;
7538 * double duration;
7539 *
7540 * frame_count = evas_object_image_animated_frame_count_get(obj);
7541 * printf("This image has %d frames\n",frame_count);
7542 *
7543 * duration = evas_object_image_animated_frame_duration_get(obj,1,0);
7544 * printf("Frame 1's duration is %f. You had better set object's frame to 2 after this duration using timer\n");
7545 *
7546 * loop_count = evas_object_image_animated_loop_count_get(obj);
7547 * printf("loop count is %d. You had better run loop %d times\n",loop_count,loop_count);
7548 *
7549 * loop_type = evas_object_image_animated_loop_type_get(obj);
7550 * if (loop_type == EVAS_IMAGE_ANIMATED_HINT_LOOP)
7551 * printf("You had better set frame like 1->2->3->1->2->3...\n");
7552 * else if (loop_type == EVAS_IMAGE_ANIMATED_HINT_PINGPONG)
7553 * printf("You had better set frame like 1->2->3->2->1->2...\n");
7554 * else
7555 * printf("Unknown loop type\n");
7556 *
7557 * evas_object_image_animated_frame_set(obj,1);
7558 * printf("You set image object's frame to 1. You can see frame 1\n");
7559 * }
7560 * @endcode
7561 *
7562 * @see evas_object_image_animated_get()
7563 * @see evas_object_image_animated_frame_count_get()
7564 * @see evas_object_image_animated_loop_type_get()
7565 * @see evas_object_image_animated_loop_count_get()
7566 * @see evas_object_image_animated_frame_duration_get()
7567 * @see evas_object_image_animated_frame_set()
7568 * @since 1.1.0
7569 */
7570EAPI Eina_Bool evas_object_image_animated_get(const Evas_Object *obj);
7571
7572/**
7573 * Get the total number of frames of the image object.
7574 *
7575 * @param obj Image object
7576 * @return The number of frames
7577 *
7578 * This returns total number of frames the image object supports (if animated)
7579 *
7580 * @see evas_object_image_animated_get()
7581 * @see evas_object_image_animated_frame_count_get()
7582 * @see evas_object_image_animated_loop_type_get()
7583 * @see evas_object_image_animated_loop_count_get()
7584 * @see evas_object_image_animated_frame_duration_get()
7585 * @see evas_object_image_animated_frame_set()
7586 * @since 1.1.0
7587 */
7588EAPI int evas_object_image_animated_frame_count_get(const Evas_Object *obj);
7589
7590/**
7591 * Get the kind of looping the image object does.
7592 *
7593 * @param obj Image object
7594 * @return Loop type of the image object
7595 *
7596 * This returns the kind of looping the image object wants to do.
7597 *
7598 * If it returns EVAS_IMAGE_ANIMATED_HINT_LOOP, you should display frames in a sequence like:
7599 * 1->2->3->1->2->3->1...
7600 * If it returns EVAS_IMAGE_ANIMATED_HINT_PINGPONG, it is better to
7601 * display frames in a sequence like: 1->2->3->2->1->2->3->1...
7602 *
7603 * The default type is EVAS_IMAGE_ANIMATED_HINT_LOOP.
7604 *
7605 * @see evas_object_image_animated_get()
7606 * @see evas_object_image_animated_frame_count_get()
7607 * @see evas_object_image_animated_loop_type_get()
7608 * @see evas_object_image_animated_loop_count_get()
7609 * @see evas_object_image_animated_frame_duration_get()
7610 * @see evas_object_image_animated_frame_set()
7611 * @since 1.1.0
7612 */
7613EAPI Evas_Image_Animated_Loop_Hint evas_object_image_animated_loop_type_get(const Evas_Object *obj);
7614
7615/**
7616 * Get the number times the animation of the object loops.
7617 *
7618 * @param obj Image object
7619 * @return The number of loop of an animated image object
7620 *
7621 * This returns loop count of image. The loop count is the number of times
7622 * the animation will play fully from first to last frame until the animation
7623 * should stop (at the final frame).
7624 *
7625 * If 0 is returned, then looping should happen indefinitely (no limit to
7626 * the number of times it loops).
7627 *
7628 * @see evas_object_image_animated_get()
7629 * @see evas_object_image_animated_frame_count_get()
7630 * @see evas_object_image_animated_loop_type_get()
7631 * @see evas_object_image_animated_loop_count_get()
7632 * @see evas_object_image_animated_frame_duration_get()
7633 * @see evas_object_image_animated_frame_set()
7634 * @since 1.1.0
7635 */
7636EAPI int evas_object_image_animated_loop_count_get(const Evas_Object *obj);
7637
7638/**
7639 * Get the duration of a sequence of frames.
7640 *
7641 * @param obj Image object
7642 * @param start_frame The first frame
7643 * @param fram_num Number of frames in the sequence
7644 *
7645 * This returns total duration that the specified sequence of frames should
7646 * take in seconds.
7647 *
7648 * If you set start_frame to 1 and frame_num 0, you get frame 1's duration
7649 * If you set start_frame to 1 and frame_num 1, you get frame 1's duration +
7650 * frame2's duration
7651 *
7652 * @see evas_object_image_animated_get()
7653 * @see evas_object_image_animated_frame_count_get()
7654 * @see evas_object_image_animated_loop_type_get()
7655 * @see evas_object_image_animated_loop_count_get()
7656 * @see evas_object_image_animated_frame_duration_get()
7657 * @see evas_object_image_animated_frame_set()
7658 * @since 1.1.0
7659 */
7660EAPI double evas_object_image_animated_frame_duration_get(const Evas_Object *obj, int start_frame, int fram_num);
7661
7662/**
7663 * Set the frame to current frame of an image object
7664 *
7665 * @param obj The given image object.
7666 * @param frame_num The index of current frame
7667 *
7668 * This set image object's current frame to frame_num with 1 being the first
7669 * frame.
7670 *
7671 * @see evas_object_image_animated_get()
7672 * @see evas_object_image_animated_frame_count_get()
7673 * @see evas_object_image_animated_loop_type_get()
7674 * @see evas_object_image_animated_loop_count_get()
7675 * @see evas_object_image_animated_frame_duration_get()
7676 * @see evas_object_image_animated_frame_set()
7677 * @since 1.1.0
7678 */
7679EAPI void evas_object_image_animated_frame_set(Evas_Object *obj, int frame_num);
7680/**
7681 * @}
7682 */
7683
7684/**
7685 * @defgroup Evas_Object_Text Text Object Functions
7686 *
7687 * Functions that operate on single line, single style text objects.
7688 *
7689 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
7690 *
7691 * See some @ref Example_Evas_Text "examples" on this group of functions.
7692 *
7693 * @ingroup Evas_Object_Specific
7694 */
7695
7696/**
7697 * @addtogroup Evas_Object_Text
7698 * @{
7699 */
7700
7701/* basic styles (4 bits allocated use 0->10 now, 5 left) */
7702#define EVAS_TEXT_STYLE_MASK_BASIC 0xf
7703
7704/**
7705 * Text style type creation macro. Use style types on the 's'
7706 * arguments, being 'x' your style variable.
7707 */
7708#define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
7709 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
7710
7711#define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
7712
7713/**
7714 * Text style type creation macro. This one will impose shadow
7715 * directions on the style type variable -- use the @c
7716 * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* values on 's', incrementally.
7717 */
7718#define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
7719 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
7720
7721 typedef enum _Evas_Text_Style_Type
7722 {
7723 EVAS_TEXT_STYLE_PLAIN, /**< plain, standard text */
7724 EVAS_TEXT_STYLE_SHADOW, /**< text with shadow underneath */
7725 EVAS_TEXT_STYLE_OUTLINE, /**< text with an outline */
7726 EVAS_TEXT_STYLE_SOFT_OUTLINE, /**< text with a soft outline */
7727 EVAS_TEXT_STYLE_GLOW, /**< text with a glow effect */
7728 EVAS_TEXT_STYLE_OUTLINE_SHADOW, /**< text with both outline and shadow effects */
7729 EVAS_TEXT_STYLE_FAR_SHADOW, /**< text with (far) shadow underneath */
7730 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW, /**< text with outline and soft shadow effects combined */
7731 EVAS_TEXT_STYLE_SOFT_SHADOW, /**< text with (soft) shadow underneath */
7732 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW, /**< text with (far soft) shadow underneath */
7733
7734 /* OR these to modify shadow direction (3 bits needed) */
7735 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< shadow growing to bottom right */
7736 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< shadow growing to the bottom */
7737 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< shadow growing to bottom left */
7738 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< shadow growing to the left */
7739 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< shadow growing to top left */
7740 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< shadow growing to the top */
7741 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< shadow growing to top right */
7742 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< shadow growing to the right */
7743 } Evas_Text_Style_Type; /**< Types of styles to be applied on text objects. The @c EVAS_TEXT_STYLE_SHADOW_DIRECTION_* ones are to be ORed together with others imposing shadow, to change shadow's direction */
7744
7745/**
7746 * Creates a new text object on the provided canvas.
7747 *
7748 * @param e The canvas to create the text object on.
7749 * @return @c NULL on error, a pointer to a new text object on
7750 * success.
7751 *
7752 * Text objects are for simple, single line text elements. If you want
7753 * more elaborated text blocks, see @ref Evas_Object_Textblock.
7754 *
7755 * @see evas_object_text_font_source_set()
7756 * @see evas_object_text_font_set()
7757 * @see evas_object_text_text_set()
7758 */
7759EAPI Evas_Object *evas_object_text_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7760
7761/**
7762 * Set the font (source) file to be used on a given text object.
7763 *
7764 * @param obj The text object to set font for.
7765 * @param font The font file's path.
7766 *
7767 * This function allows the font file to be explicitly set for a given
7768 * text object, overriding system lookup, which will first occur in
7769 * the given file's contents.
7770 *
7771 * @see evas_object_text_font_get()
7772 */
7773EAPI void evas_object_text_font_source_set (Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1);
7774
7775/**
7776 * Get the font file's path which is being used on a given text
7777 * object.
7778 *
7779 * @param obj The text object to set font for.
7780 * @param font The font file's path.
7781 *
7782 * @see evas_object_text_font_get() for more details
7783 */
7784EAPI const char *evas_object_text_font_source_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7785
7786/**
7787 * Set the font family and size on a given text object.
7788 *
7789 * @param obj The text object to set font for.
7790 * @param font The font (family) name.
7791 * @param size The font size, in points.
7792 *
7793 * This function allows the font name and size of a text object to be
7794 * set. The @p font string has to follow fontconfig's convention on
7795 * naming fonts, as it's the underlying library used to query system
7796 * fonts by Evas (see the @c fc-list command's output, on your system,
7797 * to get an idea).
7798 *
7799 * @see evas_object_text_font_get()
7800 * @see evas_object_text_font_source_set()
7801 */
7802 EAPI void evas_object_text_font_set (Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1);
7803
7804/**
7805 * Retrieve the font family and size in use on a given text object.
7806 *
7807 * @param obj The evas text object to query for font information.
7808 * @param font A pointer to the location to store the font name in.
7809 * @param size A pointer to the location to store the font size in.
7810 *
7811 * This function allows the font name and size of a text object to be
7812 * queried. Be aware that the font name string is still owned by Evas
7813 * and should @b not have free() called on it by the caller of the
7814 * function.
7815 *
7816 * @see evas_object_text_font_set()
7817 */
7818EAPI void evas_object_text_font_get (const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1);
7819
7820/**
7821 * Sets the text string to be displayed by the given text object.
7822 *
7823 * @param obj The text object to set text string on.
7824 * @param text Text string to display on it.
7825 *
7826 * @see evas_object_text_text_get()
7827 */
7828EAPI void evas_object_text_text_set (Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
7829
7830/**
7831 * Retrieves the text string currently being displayed by the given
7832 * text object.
7833 *
7834 * @param obj The given text object.
7835 * @return The text string currently being displayed on it.
7836 *
7837 * @note Do not free() the return value.
7838 *
7839 * @see evas_object_text_text_set()
7840 */
7841EAPI const char *evas_object_text_text_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7842
7843/**
7844 * @brief Sets the BiDi delimiters used in the textblock.
7845 *
7846 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
7847 * is useful for example in recipients fields of e-mail clients where bidi
7848 * oddities can occur when mixing rtl and ltr.
7849 *
7850 * @param obj The given text object.
7851 * @param delim A null terminated string of delimiters, e.g ",|".
7852 * @since 1.1.0
7853 */
7854EAPI void evas_object_text_bidi_delimiters_set(Evas_Object *obj, const char *delim);
7855
7856/**
7857 * @brief Gets the BiDi delimiters used in the textblock.
7858 *
7859 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
7860 * is useful for example in recipients fields of e-mail clients where bidi
7861 * oddities can occur when mixing rtl and ltr.
7862 *
7863 * @param obj The given text object.
7864 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
7865 * @since 1.1.0
7866 */
7867EAPI const char *evas_object_text_bidi_delimiters_get(const Evas_Object *obj);
7868
7869 EAPI Evas_Coord evas_object_text_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7870 EAPI Evas_Coord evas_object_text_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7871 EAPI Evas_Coord evas_object_text_max_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7872 EAPI Evas_Coord evas_object_text_max_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7873 EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7874 EAPI Evas_Coord evas_object_text_vert_advance_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7875 EAPI Evas_Coord evas_object_text_inset_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7876
7877/**
7878 * Retrieve position and dimension information of a character within a text @c Evas_Object.
7879 *
7880 * This function is used to obtain the X, Y, width and height of a the character
7881 * located at @p pos within the @c Evas_Object @p obj. @p obj must be a text object
7882 * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx,
7883 * @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to that
7884 * parameter.
7885 *
7886 * @param obj The text object to retrieve position information for.
7887 * @param pos The character position to request co-ordinates for.
7888 * @param cx A pointer to an @c Evas_Coord to store the X value in (can be NULL).
7889 * @param cy A pointer to an @c Evas_Coord to store the Y value in (can be NULL).
7890 * @param cw A pointer to an @c Evas_Coord to store the Width value in (can be NULL).
7891 * @param ch A pointer to an @c Evas_Coord to store the Height value in (can be NULL).
7892 *
7893 * @returns EINA_FALSE on success, EINA_TRUE on error.
7894 */
7895EAPI Eina_Bool evas_object_text_char_pos_get (const Evas_Object *obj, int pos, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
7896 EAPI int evas_object_text_char_coords_get (const Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
7897
7898/**
7899 * Returns the logical position of the last char in the text
7900 * up to the pos given. this is NOT the position of the last char
7901 * because of the possibility of RTL in the text.
7902 */
7903EAPI int evas_object_text_last_up_to_pos (const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
7904
7905/**
7906 * Retrieves the style on use on the given text object.
7907 *
7908 * @param obj the given text object to set style on.
7909 * @return the style type in use.
7910 *
7911 * @see evas_object_text_style_set() for more details.
7912 */
7913EAPI Evas_Text_Style_Type evas_object_text_style_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7914
7915/**
7916 * Sets the style to apply on the given text object.
7917 *
7918 * @param obj the given text object to set style on.
7919 * @param type a style type.
7920 *
7921 * Text object styles are one of the values in
7922 * #Evas_Text_Style_Type. Some of those values are combinations of
7923 * more than one style, and some account for the direction of the
7924 * rendering of shadow effects.
7925 *
7926 * @note One may use the helper macros #EVAS_TEXT_STYLE_BASIC_SET and
7927 * #EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET to assemble a style value.
7928 *
7929 * The following figure illustrates the text styles:
7930 *
7931 * @image html text-styles.png
7932 * @image rtf text-styles.png
7933 * @image latex text-styles.eps
7934 *
7935 * @see evas_object_text_style_get()
7936 * @see evas_object_text_shadow_color_set()
7937 * @see evas_object_text_outline_color_set()
7938 * @see evas_object_text_glow_color_set()
7939 * @see evas_object_text_glow2_color_set()
7940 */
7941EAPI void evas_object_text_style_set (Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1);
7942
7943/**
7944 * Sets the shadow color for the given text object.
7945 *
7946 * @param obj The given Evas text object.
7947 * @param r The red component of the given color.
7948 * @param g The green component of the given color.
7949 * @param b The blue component of the given color.
7950 * @param a The alpha component of the given color.
7951 *
7952 * Shadow effects, which are fading colors decorating the text
7953 * underneath it, will just be shown if the object is set to one of
7954 * the following styles:
7955 *
7956 * - #EVAS_TEXT_STYLE_SHADOW
7957 * - #EVAS_TEXT_STYLE_OUTLINE_SHADOW
7958 * - #EVAS_TEXT_STYLE_FAR_SHADOW
7959 * - #EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW
7960 * - #EVAS_TEXT_STYLE_SOFT_SHADOW
7961 * - #EVAS_TEXT_STYLE_FAR_SOFT_SHADOW
7962 *
7963 * One can also change the direction where the shadow grows to, with
7964 * evas_object_text_style_set().
7965 *
7966 * @see evas_object_text_shadow_color_get()
7967 */
7968EAPI void evas_object_text_shadow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
7969
7970/**
7971 * Retrieves the shadow color for the given text object.
7972 *
7973 * @param obj The given Evas text object.
7974 * @param r Pointer to variable to hold the red component of the given
7975 * color.
7976 * @param g Pointer to variable to hold the green component of the
7977 * given color.
7978 * @param b Pointer to variable to hold the blue component of the
7979 * given color.
7980 * @param a Pointer to variable to hold the alpha component of the
7981 * given color.
7982 *
7983 * @note Use @c NULL pointers on the color components you're not
7984 * interested in: they'll be ignored by the function.
7985 *
7986 * @see evas_object_text_shadow_color_set() for more details.
7987 */
7988EAPI void evas_object_text_shadow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
7989
7990/**
7991 * Sets the glow color for the given text object.
7992 *
7993 * @param obj The given Evas text object.
7994 * @param r The red component of the given color.
7995 * @param g The green component of the given color.
7996 * @param b The blue component of the given color.
7997 * @param a The alpha component of the given color.
7998 *
7999 * Glow effects, which are glowing colors decorating the text's
8000 * surroundings, will just be shown if the object is set to the
8001 * #EVAS_TEXT_STYLE_GLOW style.
8002 *
8003 * @note Glow effects are placed from a short distance of the text
8004 * itself, but no touching it. For glowing effects right on the
8005 * borders of the glyphs, see 'glow 2' effects
8006 * (evas_object_text_glow2_color_set()).
8007 *
8008 * @see evas_object_text_glow_color_get()
8009 */
8010EAPI void evas_object_text_glow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
8011
8012/**
8013 * Retrieves the glow color for the given text object.
8014 *
8015 * @param obj The given Evas text object.
8016 * @param r Pointer to variable to hold the red component of the given
8017 * color.
8018 * @param g Pointer to variable to hold the green component of the
8019 * given color.
8020 * @param b Pointer to variable to hold the blue component of the
8021 * given color.
8022 * @param a Pointer to variable to hold the alpha component of the
8023 * given color.
8024 *
8025 * @note Use @c NULL pointers on the color components you're not
8026 * interested in: they'll be ignored by the function.
8027 *
8028 * @see evas_object_text_glow_color_set() for more details.
8029 */
8030EAPI void evas_object_text_glow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
8031
8032/**
8033 * Sets the 'glow 2' color for the given text object.
8034 *
8035 * @param obj The given Evas text object.
8036 * @param r The red component of the given color.
8037 * @param g The green component of the given color.
8038 * @param b The blue component of the given color.
8039 * @param a The alpha component of the given color.
8040 *
8041 * 'Glow 2' effects, which are glowing colors decorating the text's
8042 * (immediate) surroundings, will just be shown if the object is set
8043 * to the #EVAS_TEXT_STYLE_GLOW style. See also
8044 * evas_object_text_glow_color_set().
8045 *
8046 * @see evas_object_text_glow2_color_get()
8047 */
8048EAPI void evas_object_text_glow2_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
8049
8050/**
8051 * Retrieves the 'glow 2' color for the given text object.
8052 *
8053 * @param obj The given Evas text object.
8054 * @param r Pointer to variable to hold the red component of the given
8055 * color.
8056 * @param g Pointer to variable to hold the green component of the
8057 * given color.
8058 * @param b Pointer to variable to hold the blue component of the
8059 * given color.
8060 * @param a Pointer to variable to hold the alpha component of the
8061 * given color.
8062 *
8063 * @note Use @c NULL pointers on the color components you're not
8064 * interested in: they'll be ignored by the function.
8065 *
8066 * @see evas_object_text_glow2_color_set() for more details.
8067 */
8068EAPI void evas_object_text_glow2_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
8069
8070/**
8071 * Sets the outline color for the given text object.
8072 *
8073 * @param obj The given Evas text object.
8074 * @param r The red component of the given color.
8075 * @param g The green component of the given color.
8076 * @param b The blue component of the given color.
8077 * @param a The alpha component of the given color.
8078 *
8079 * Outline effects (colored lines around text glyphs) will just be
8080 * shown if the object is set to one of the following styles:
8081 * - #EVAS_TEXT_STYLE_OUTLINE
8082 * - #EVAS_TEXT_STYLE_SOFT_OUTLINE
8083 * - #EVAS_TEXT_STYLE_OUTLINE_SHADOW
8084 * - #EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW
8085 *
8086 * @see evas_object_text_outline_color_get()
8087 */
8088EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
8089
8090/**
8091 * Retrieves the outline color for the given text object.
8092 *
8093 * @param obj The given Evas text object.
8094 * @param r Pointer to variable to hold the red component of the given
8095 * color.
8096 * @param g Pointer to variable to hold the green component of the
8097 * given color.
8098 * @param b Pointer to variable to hold the blue component of the
8099 * given color.
8100 * @param a Pointer to variable to hold the alpha component of the
8101 * given color.
8102 *
8103 * @note Use @c NULL pointers on the color components you're not
8104 * interested in: they'll be ignored by the function.
8105 *
8106 * @see evas_object_text_outline_color_set() for more details.
8107 */
8108EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
8109
8110/**
8111 * Gets the text style pad of a text object.
8112 *
8113 * @param obj The given text object.
8114 * @param l The left pad (or @c NULL).
8115 * @param r The right pad (or @c NULL).
8116 * @param t The top pad (or @c NULL).
8117 * @param b The bottom pad (or @c NULL).
8118 *
8119 */
8120EAPI void evas_object_text_style_pad_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
8121
8122/**
8123 * Retrieves the direction of the text currently being displayed in the
8124 * text object.
8125 * @param obj The given evas text object.
8126 * @return the direction of the text
8127 */
8128EAPI Evas_BiDi_Direction evas_object_text_direction_get (const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
8129
8130/**
8131 * @}
8132 */
8133
8134/**
8135 * @defgroup Evas_Object_Textblock Textblock Object Functions
8136 *
8137 * Functions used to create and manipulate textblock objects. Unlike
8138 * @ref Evas_Object_Text, these handle complex text, doing multiple
8139 * styles and multiline text based on HTML-like tags. Of these extra
8140 * features will be heavier on memory and processing cost.
8141 *
8142 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
8143 *
8144 * This part explains about the textblock object's API and proper usage.
8145 * If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal.
8146 * The main user of the textblock object is the edje entry object in Edje, so
8147 * that's a good place to learn from, but I think this document is more than
8148 * enough, if it's not, please contact me and I'll update it.
8149 *
8150 * @subsection textblock_intro Introduction
8151 * The textblock objects is, as implied, an object that can show big chunks of
8152 * text. Textblock supports many features including: Text formatting, automatic
8153 * and manual text alignment, embedding items (for example icons) and more.
8154 * Textblock has three important parts, the text paragraphs, the format nodes
8155 * and the cursors.
8156 *
8157 * You can use markup to format text, for example: "<font_size=50>Big!</font_size>".
8158 * You can also put more than one style directive in one tag:
8159 * "<font_size=50 color=#F00>Big and Red!</font_size>".
8160 * Please notice that we used "</font_size>" although the format also included
8161 * color, this is because the first format determines the matching closing tag's
8162 * name. You can also use anonymous tags, like: "<font_size=30>Big</>" which
8163 * just pop any type of format, but it's advised to use the named alternatives
8164 * instead.
8165 *
8166 * @subsection textblock_cursors Textblock Object Cursors
8167 * A textblock Cursor @ref Evas_Textblock_Cursor is data type that represents
8168 * a position in a textblock. Each cursor contains information about the
8169 * paragraph it points to, the position in that paragraph and the object itself.
8170 * Cursors register to textblock objects upon creation, this means that once
8171 * you created a cursor, it belongs to a specific obj and you can't for example
8172 * copy a cursor "into" a cursor of a different object. Registered cursors
8173 * also have the added benefit of updating automatically upon textblock changes,
8174 * this means that if you have a cursor pointing to a specific character, it'll
8175 * still point to it even after you change the whole object completely (as long
8176 * as the char was not deleted), this is not possible without updating, because
8177 * as mentioned, each cursor holds a character position. There are many
8178 * functions that handle cursors, just check out the evas_textblock_cursor*
8179 * functions. For creation and deletion of cursors check out:
8180 * @see evas_object_textblock_cursor_new()
8181 * @see evas_textblock_cursor_free()
8182 * @note Cursors are generally the correct way to handle text in the textblock object, and there are enough functions to do everything you need with them (no need to get big chunks of text and processing them yourself).
8183 *
8184 * @subsection textblock_paragraphs Textblock Object Paragraphs
8185 * The textblock object is made out of text splitted to paragraphs (delimited
8186 * by the paragraph separation character). Each paragraph has many (or none)
8187 * format nodes associated with it which are responsible for the formatting
8188 * of that paragraph.
8189 *
8190 * @subsection textblock_format_nodes Textblock Object Format Nodes
8191 * As explained in @ref textblock_paragraphs each one of the format nodes
8192 * is associated with a paragraph.
8193 * There are two types of format nodes, visible and invisible:
8194 * Visible: formats that a cursor can point to, i.e formats that
8195 * occupy space, for example: newlines, tabs, items and etc. Some visible items
8196 * are made of two parts, in this case, only the opening tag is visible.
8197 * A closing tag (i.e a </tag> tag) should NEVER be visible.
8198 * Invisible: formats that don't occupy space, for example: bold and underline.
8199 * Being able to access format nodes is very important for some uses. For
8200 * example, edje uses the "<a>" format to create links in the text (and pop
8201 * popups above them when clicked). For the textblock object a is just a
8202 * formatting instruction (how to color the text), but edje utilizes the access
8203 * to the format nodes to make it do more.
8204 * For more information, take a look at all the evas_textblock_node_format_*
8205 * functions.
8206 * The translation of "<tag>" tags to actual format is done according to the
8207 * tags defined in the style, see @ref evas_textblock_style_set
8208 *
8209 * @subsection textblock_special_formats Special Formats
8210 * Textblock supports various format directives that can be used either in
8211 * markup, or by calling @ref evas_object_textblock_format_append or
8212 * @ref evas_object_textblock_format_prepend. In addition to the mentioned
8213 * format directives, textblock allows creating additional format directives
8214 * using "tags" that can be set in the style see @ref evas_textblock_style_set .
8215 *
8216 * Textblock supports the following formats:
8217 * @li font - Font description in fontconfig like format, e.g: "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
8218 * @li font_weight - Overrides the weight defined in "font". E.g: "font_weight=Bold" is the same as "font=:style=Bold". Supported weights: "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack".
8219 * @li font_style - Overrides the style defined in "font". E.g: "font_style=Italic" is the same as "font=:style=Italic". Supported styles: "normal", "oblique", and "italic".
8220 * @li font_width - Overrides the width defined in "font". E.g: "font_width=Condensed" is the same as "font=:style=Condensed". Supported widths: "normal", "ultracondensed", "extracondensed", "condensed", "semicondensed", "semiexpanded", "expanded", "extraexpanded", and "ultraexpanded".
8221 * @li lang - Overrides the language defined in "font". E.g: "lang=he" is the same as "font=:lang=he".
8222 * @li font_fallbacks - A comma delimited list of fonts to try if finding the main font fails.
8223 * @li font_size - The font size in points.
8224 * @li font_source - The source of the font, e.g an eet file.
8225 * @li color - Text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8226 * @li underline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8227 * @li underline2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8228 * @li outline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8229 * @li shadow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8230 * @li glow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8231 * @li glow2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8232 * @li backing_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8233 * @li strikethrough_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8234 * @li align - Either "auto" (meaning according to text direction), "left", "right", "center", "middle", a value between 0.0 and 1.0, or a value between 0% to 100%.
8235 * @li valign - Either "top", "bottom", "middle", "center", "baseline", "base", a value between 0.0 and 1.0, or a value between 0% to 100%.
8236 * @li wrap - "word", "char", "mixed", or "none".
8237 * @li left_margin - Either "reset", or a pixel value indicating the margin.
8238 * @li right_margin - Either "reset", or a pixel value indicating the margin.
8239 * @li underline - "on", "off", "single", or "double".
8240 * @li strikethrough - "on" or "off"
8241 * @li backing - "on" or "off"
8242 * @li style - Either "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow", or "far_soft_shadow".
8243 * @li tabstops - Pixel value for tab width.
8244 * @li linesize - Force a line size in pixels.
8245 * @li linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
8246 * @li linegap - Force a line gap in pixels.
8247 * @li linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
8248 * @li item - Creates an empty space that should be filled by an upper layer. Use "size", "abssize", or "relsize". To define the items size, and an optional: vsize=full/ascent to define the item's position in the line.
8249 * @li linefill - Either a float value or percentage indicating how much to fill the line.
8250 * @li ellipsis - Value between 0.0-1.0 to indicate the type of ellipsis, or -1.0 to indicate ellipsis isn't wanted.
8251 * @li password - "on" or "off". This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off.
8252 *
8253 *
8254 * @todo put here some usage examples
8255 *
8256 * @ingroup Evas_Object_Specific
8257 *
8258 * @{
8259 */
8260
8261 typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
8262 typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
8263 /**
8264 * @typedef Evas_Object_Textblock_Node_Format
8265 * A format node.
8266 */
8267 typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
8268 typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
8269
8270 struct _Evas_Textblock_Rectangle
8271 {
8272 Evas_Coord x, y, w, h;
8273 };
8274
8275 typedef enum _Evas_Textblock_Text_Type
8276 {
8277 EVAS_TEXTBLOCK_TEXT_RAW,
8278 EVAS_TEXTBLOCK_TEXT_PLAIN,
8279 EVAS_TEXTBLOCK_TEXT_MARKUP
8280 } Evas_Textblock_Text_Type;
8281
8282 typedef enum _Evas_Textblock_Cursor_Type
8283 {
8284 EVAS_TEXTBLOCK_CURSOR_UNDER,
8285 EVAS_TEXTBLOCK_CURSOR_BEFORE
8286 } Evas_Textblock_Cursor_Type;
8287
8288
8289/**
8290 * Adds a textblock to the given evas.
8291 * @param e The given evas.
8292 * @return The new textblock object.
8293 */
8294EAPI Evas_Object *evas_object_textblock_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8295
8296
8297/**
8298 * Returns the unescaped version of escape.
8299 * @param escape the string to be escaped
8300 * @return the unescaped version of escape
8301 */
8302EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8303
8304/**
8305 * Returns the escaped version of the string.
8306 * @param string to escape
8307 * @param len_ret the len of the part of the string that was used.
8308 * @return the escaped string.
8309 */
8310EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8311
8312/**
8313 * Return the unescaped version of the string between start and end.
8314 *
8315 * @param escape_start the start of the string.
8316 * @param escape_end the end of the string.
8317 * @return the unescaped version of the range
8318 */
8319EAPI const char *evas_textblock_escape_string_range_get(const char *escape_start, const char *escape_end) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
8320
8321/**
8322 * Return the plain version of the markup.
8323 *
8324 * Works as if you set the markup to a textblock and then retrieve the plain
8325 * version of the text. i.e: <br> and <\n> will be replaced with \n, &...; with
8326 * the actual char and etc.
8327 *
8328 * @param obj the textblock object to work with. (if NULL, tries the default)
8329 * @param text the markup text (if NULL, return NULL)
8330 * @return an allocated plain text version of the markup
8331 * @since 1.2.0
8332 */
8333EAPI char *evas_textblock_text_markup_to_utf8(const Evas_Object *obj, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
8334
8335/**
8336 * Return the markup version of the plain text.
8337 *
8338 * Replaces \n -> <br/> \t -> <tab/> and etc. Generally needed before you pass
8339 * plain text to be set in a textblock.
8340 *
8341 * @param obj the textblock object to work with (if NULL, it just does the
8342 * default behaviour, i.e with no extra object information).
8343 * @param text the markup text (if NULL, return NULL)
8344 * @return an allocated plain text version of the markup
8345 * @since 1.2.0
8346 */
8347EAPI char *evas_textblock_text_utf8_to_markup(const Evas_Object *obj, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
8348
8349/**
8350 * Creates a new textblock style.
8351 * @return The new textblock style.
8352 */
8353EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
8354
8355/**
8356 * Destroys a textblock style.
8357 * @param ts The textblock style to free.
8358 */
8359EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
8360
8361/**
8362 * Sets the style ts to the style passed as text by text.
8363 * Expected a string consisting of many (or none) tag='format' pairs.
8364 *
8365 * @param ts the style to set.
8366 * @param text the text to parse - NOT NULL.
8367 * @return Returns no value.
8368 */
8369EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
8370
8371/**
8372 * Return the text of the style ts.
8373 * @param ts the style to get it's text.
8374 * @return the text of the style or null on error.
8375 */
8376EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8377
8378
8379/**
8380 * Set the objects style to ts.
8381 * @param obj the Evas object to set the style to.
8382 * @param ts the style to set.
8383 * @return Returns no value.
8384 */
8385EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
8386
8387/**
8388 * Return the style of an object.
8389 * @param obj the object to get the style from.
8390 * @return the style of the object.
8391 */
8392EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8393
8394/**
8395 * Push ts to the top of the user style stack.
8396 *
8397 * FIXME: API is solid but currently only supports 1 style in the stack.
8398 *
8399 * The user style overrides the corresponding elements of the regular style.
8400 * This is the proper way to do theme overrides in code.
8401 * @param obj the Evas object to set the style to.
8402 * @param ts the style to set.
8403 * @return Returns no value.
8404 * @see evas_object_textblock_style_set
8405 * @since 1.2.0
8406 */
8407EAPI void evas_object_textblock_style_user_push(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
8408
8409/**
8410 * Del the from the top of the user style stack.
8411 *
8412 * @param obj the object to get the style from.
8413 * @see evas_object_textblock_style_get
8414 * @since 1.2.0
8415 */
8416EAPI void evas_object_textblock_style_user_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
8417
8418/**
8419 * Get (don't remove) the style at the top of the user style stack.
8420 *
8421 * @param obj the object to get the style from.
8422 * @return the style of the object.
8423 * @see evas_object_textblock_style_get
8424 * @since 1.2.0
8425 */
8426EAPI const Evas_Textblock_Style *evas_object_textblock_style_user_peek(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8427
8428/**
8429 * @brief Set the "replacement character" to use for the given textblock object.
8430 *
8431 * @param obj The given textblock object.
8432 * @param ch The charset name.
8433 */
8434EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1);
8435
8436/**
8437 * @brief Get the "replacement character" for given textblock object. Returns
8438 * NULL if no replacement character is in use.
8439 *
8440 * @param obj The given textblock object
8441 * @return replacement character or @c NULL
8442 */
8443EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8444
8445/**
8446 * @brief Sets the vertical alignment of text within the textblock object
8447 * as a whole.
8448 *
8449 * Normally alignment is 0.0 (top of object). Values given should be
8450 * between 0.0 and 1.0 (1.0 bottom of object, 0.5 being vertically centered
8451 * etc.).
8452 *
8453 * @param obj The given textblock object.
8454 * @param align A value between 0.0 and 1.0
8455 * @since 1.1.0
8456 */
8457EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align);
8458
8459/**
8460 * @brief Gets the vertical alignment of a textblock
8461 *
8462 * @param obj The given textblock object.
8463 * @return The alignment set for the object
8464 * @since 1.1.0
8465 */
8466EAPI double evas_object_textblock_valign_get(const Evas_Object *obj);
8467
8468/**
8469 * @brief Sets the BiDi delimiters used in the textblock.
8470 *
8471 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
8472 * is useful for example in recipients fields of e-mail clients where bidi
8473 * oddities can occur when mixing rtl and ltr.
8474 *
8475 * @param obj The given textblock object.
8476 * @param delim A null terminated string of delimiters, e.g ",|".
8477 * @since 1.1.0
8478 */
8479EAPI void evas_object_textblock_bidi_delimiters_set(Evas_Object *obj, const char *delim);
8480
8481/**
8482 * @brief Gets the BiDi delimiters used in the textblock.
8483 *
8484 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
8485 * is useful for example in recipients fields of e-mail clients where bidi
8486 * oddities can occur when mixing rtl and ltr.
8487 *
8488 * @param obj The given textblock object.
8489 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
8490 * @since 1.1.0
8491 */
8492EAPI const char *evas_object_textblock_bidi_delimiters_get(const Evas_Object *obj);
8493
8494/**
8495 * @brief Sets newline mode. When true, newline character will behave
8496 * as a paragraph separator.
8497 *
8498 * @param obj The given textblock object.
8499 * @param mode EINA_TRUE for legacy mode, EINA_FALSE otherwise.
8500 * @since 1.1.0
8501 */
8502EAPI void evas_object_textblock_legacy_newline_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1);
8503
8504/**
8505 * @brief Gets newline mode. When true, newline character behaves
8506 * as a paragraph separator.
8507 *
8508 * @param obj The given textblock object.
8509 * @return EINA_TRUE if in legacy mode, EINA_FALSE otherwise.
8510 * @since 1.1.0
8511 */
8512EAPI Eina_Bool evas_object_textblock_legacy_newline_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8513
8514
8515/**
8516 * Sets the tetxblock's text to the markup text.
8517 *
8518 * @note assumes text does not include the unicode object replacement char (0xFFFC)
8519 *
8520 * @param obj the textblock object.
8521 * @param text the markup text to use.
8522 * @return Return no value.
8523 */
8524EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
8525
8526/**
8527 * Prepends markup to the cursor cur.
8528 *
8529 * @note assumes text does not include the unicode object replacement char (0xFFFC)
8530 *
8531 * @param cur the cursor to prepend to.
8532 * @param text the markup text to prepend.
8533 * @return Return no value.
8534 */
8535EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
8536
8537/**
8538 * Return the markup of the object.
8539 *
8540 * @param obj the Evas object.
8541 * @return the markup text of the object.
8542 */
8543EAPI const char *evas_object_textblock_text_markup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
8544
8545
8546/**
8547 * Return the object's main cursor.
8548 *
8549 * @param obj the object.
8550 * @return the obj's main cursor.
8551 */
8552EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8553
8554/**
8555 * Create a new cursor, associate it to the obj and init it to point
8556 * to the start of the textblock. Association to the object means the cursor
8557 * will be updated when the object will change.
8558 *
8559 * @note if you need speed and you know what you are doing, it's slightly faster to just allocate the cursor yourself and not associate it. (only people developing the actual object, and not users of the object).
8560 *
8561 * @param obj the object to associate to.
8562 * @return the new cursor.
8563 */
8564EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8565
8566
8567/**
8568 * Free the cursor and unassociate it from the object.
8569 * @note do not use it to free unassociated cursors.
8570 *
8571 * @param cur the cursor to free.
8572 * @return Returns no value.
8573 */
8574EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8575
8576
8577/**
8578 * Sets the cursor to the start of the first text node.
8579 *
8580 * @param cur the cursor to update.
8581 * @return Returns no value.
8582 */
8583EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8584
8585/**
8586 * sets the cursor to the end of the last text node.
8587 *
8588 * @param cur the cursor to set.
8589 * @return Returns no value.
8590 */
8591EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8592
8593/**
8594 * Advances to the start of the next text node
8595 *
8596 * @param cur the cursor to update
8597 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
8598 */
8599EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8600
8601/**
8602 * Advances to the end of the previous text node
8603 *
8604 * @param cur the cursor to update
8605 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
8606 */
8607EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8608
8609/**
8610 * Returns the
8611 *
8612 * @param obj The evas, must not be NULL.
8613 * @param anchor the anchor name to get
8614 * @return Returns the list format node corresponding to the anchor, may be null if there are none.
8615 */
8616EAPI const Eina_List *evas_textblock_node_format_list_get(const Evas_Object *obj, const char *anchor) EINA_ARG_NONNULL(1, 2);
8617
8618/**
8619 * Returns the first format node.
8620 *
8621 * @param obj The evas, must not be NULL.
8622 * @return Returns the first format node, may be null if there are none.
8623 */
8624EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
8625
8626/**
8627 * Returns the last format node.
8628 *
8629 * @param obj The evas textblock, must not be NULL.
8630 * @return Returns the first format node, may be null if there are none.
8631 */
8632EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
8633
8634/**
8635 * Returns the next format node (after n)
8636 *
8637 * @param n the current format node - not null.
8638 * @return Returns the next format node, may be null.
8639 */
8640EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
8641
8642/**
8643 * Returns the prev format node (after n)
8644 *
8645 * @param n the current format node - not null.
8646 * @return Returns the prev format node, may be null.
8647 */
8648EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
8649
8650/**
8651 * Remove a format node and it's match. i.e, removes a <tag> </tag> pair.
8652 * Assumes the node is the first part of <tag> i.e, this won't work if
8653 * n is a closing tag.
8654 *
8655 * @param obj the Evas object of the textblock - not null.
8656 * @param n the current format node - not null.
8657 */
8658EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
8659
8660/**
8661 * Sets the cursor to point to the place where format points to.
8662 *
8663 * @param cur the cursor to update.
8664 * @param n the format node to update according.
8665 * @deprecated duplicate of evas_textblock_cursor_at_format_set
8666 */
8667EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
8668
8669/**
8670 * Return the format node at the position pointed by cur.
8671 *
8672 * @param cur the position to look at.
8673 * @return the format node if found, NULL otherwise.
8674 * @see evas_textblock_cursor_format_is_visible_get()
8675 */
8676EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8677
8678/**
8679 * Get the text format representation of the format node.
8680 *
8681 * @param fmt the format node.
8682 * @return the textual format of the format node.
8683 */
8684EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fnode) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8685
8686/**
8687 * Set the cursor to point to the position of fmt.
8688 *
8689 * @param cur the cursor to update
8690 * @param fmt the format to update according to.
8691 */
8692EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
8693
8694/**
8695 * Check if the current cursor position is a visible format. This way is more
8696 * efficient than evas_textblock_cursor_format_get() to check for the existence
8697 * of a visible format.
8698 *
8699 * @param cur the cursor to look at.
8700 * @return #EINA_TRUE if the cursor points to a visible format, #EINA_FALSE otherwise.
8701 * @see evas_textblock_cursor_format_get()
8702 */
8703EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8704
8705/**
8706 * Advances to the next format node
8707 *
8708 * @param cur the cursor to be updated.
8709 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8710 */
8711EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8712
8713/**
8714 * Advances to the previous format node.
8715 *
8716 * @param cur the cursor to update.
8717 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8718 */
8719EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8720
8721/**
8722 * Returns true if the cursor points to a format.
8723 *
8724 * @param cur the cursor to check.
8725 * @return Returns #EINA_TRUE if a cursor points to a format #EINA_FALSE otherwise.
8726 */
8727EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8728
8729/**
8730 * Advances 1 char forward.
8731 *
8732 * @param cur the cursor to advance.
8733 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8734 */
8735EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8736
8737/**
8738 * Advances 1 char backward.
8739 *
8740 * @param cur the cursor to advance.
8741 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8742 */
8743EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8744
8745/**
8746 * Moves the cursor to the start of the word under the cursor.
8747 *
8748 * @param cur the cursor to move.
8749 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8750 * @since 1.2.0
8751 */
8752EAPI Eina_Bool evas_textblock_cursor_word_start(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8753
8754/**
8755 * Moves the cursor to the end of the word under the cursor.
8756 *
8757 * @param cur the cursor to move.
8758 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8759 * @since 1.2.0
8760 */
8761EAPI Eina_Bool evas_textblock_cursor_word_end(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8762
8763/**
8764 * Go to the first char in the node the cursor is pointing on.
8765 *
8766 * @param cur the cursor to update.
8767 * @return Returns no value.
8768 */
8769EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8770
8771/**
8772 * Go to the last char in a text node.
8773 *
8774 * @param cur the cursor to update.
8775 * @return Returns no value.
8776 */
8777EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8778
8779/**
8780 * Go to the start of the current line
8781 *
8782 * @param cur the cursor to update.
8783 * @return Returns no value.
8784 */
8785EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8786
8787/**
8788 * Go to the end of the current line.
8789 *
8790 * @param cur the cursor to update.
8791 * @return Returns no value.
8792 */
8793EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8794
8795/**
8796 * Return the current cursor pos.
8797 *
8798 * @param cur the cursor to take the position from.
8799 * @return the position or -1 on error
8800 */
8801EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8802
8803/**
8804 * Set the cursor pos.
8805 *
8806 * @param cur the cursor to be set.
8807 * @param pos the pos to set.
8808 */
8809EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
8810
8811/**
8812 * Go to the start of the line passed
8813 *
8814 * @param cur cursor to update.
8815 * @param line numer to set.
8816 * @return #EINA_TRUE on success, #EINA_FALSE on error.
8817 */
8818EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
8819
8820/**
8821 * Compare two cursors.
8822 *
8823 * @param cur1 the first cursor.
8824 * @param cur2 the second cursor.
8825 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
8826 */
8827EAPI int evas_textblock_cursor_compare(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
8828
8829/**
8830 * Make cur_dest point to the same place as cur. Does not work if they don't
8831 * point to the same object.
8832 *
8833 * @param cur the source cursor.
8834 * @param cur_dest destination cursor.
8835 * @return Returns no value.
8836 */
8837EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
8838
8839
8840/**
8841 * Adds text to the current cursor position and set the cursor to *before*
8842 * the start of the text just added.
8843 *
8844 * @param cur the cursor to where to add text at.
8845 * @param _text the text to add.
8846 * @return Returns the len of the text added.
8847 * @see evas_textblock_cursor_text_prepend()
8848 */
8849EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
8850
8851/**
8852 * Adds text to the current cursor position and set the cursor to *after*
8853 * the start of the text just added.
8854 *
8855 * @param cur the cursor to where to add text at.
8856 * @param _text the text to add.
8857 * @return Returns the len of the text added.
8858 * @see evas_textblock_cursor_text_append()
8859 */
8860EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
8861
8862
8863/**
8864 * Adds format to the current cursor position. If the format being added is a
8865 * visible format, add it *before* the cursor position, otherwise, add it after.
8866 * This behavior is because visible formats are like characters and invisible
8867 * should be stacked in a way that the last one is added last.
8868 *
8869 * This function works with native formats, that means that style defined
8870 * tags like <br> won't work here. For those kind of things use markup prepend.
8871 *
8872 * @param cur the cursor to where to add format at.
8873 * @param format the format to add.
8874 * @return Returns true if a visible format was added, false otherwise.
8875 * @see evas_textblock_cursor_format_prepend()
8876 */
8877
8878/**
8879 * Check if the current cursor position points to the terminating null of the
8880 * last paragraph. (shouldn't be allowed to point to the terminating null of
8881 * any previous paragraph anyway.
8882 *
8883 * @param cur the cursor to look at.
8884 * @return #EINA_TRUE if the cursor points to the terminating null, #EINA_FALSE otherwise.
8885 */
8886EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
8887
8888/**
8889 * Adds format to the current cursor position. If the format being added is a
8890 * visible format, add it *before* the cursor position, otherwise, add it after.
8891 * This behavior is because visible formats are like characters and invisible
8892 * should be stacked in a way that the last one is added last.
8893 * If the format is visible the cursor is advanced after it.
8894 *
8895 * This function works with native formats, that means that style defined
8896 * tags like <br> won't work here. For those kind of things use markup prepend.
8897 *
8898 * @param cur the cursor to where to add format at.
8899 * @param format the format to add.
8900 * @return Returns true if a visible format was added, false otherwise.
8901 * @see evas_textblock_cursor_format_prepend()
8902 */
8903EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
8904
8905/**
8906 * Delete the character at the location of the cursor. If there's a format
8907 * pointing to this position, delete it as well.
8908 *
8909 * @param cur the cursor pointing to the current location.
8910 * @return Returns no value.
8911 */
8912EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8913
8914/**
8915 * Delete the range between cur1 and cur2.
8916 *
8917 * @param cur1 one side of the range.
8918 * @param cur2 the second side of the range
8919 * @return Returns no value.
8920 */
8921EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
8922
8923
8924/**
8925 * Return the text of the paragraph cur points to - returns the text in markup..
8926 *
8927 * @param cur the cursor pointing to the paragraph.
8928 * @return the text on success, NULL otherwise.
8929 */
8930EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8931
8932/**
8933 * Return the length of the paragraph, cheaper the eina_unicode_strlen()
8934 *
8935 * @param cur the position of the paragraph.
8936 * @return the length of the paragraph on success, -1 otehrwise.
8937 */
8938EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8939
8940/**
8941 * Return the currently visible range.
8942 *
8943 * @param start the start of the range.
8944 * @param end the end of the range.
8945 * @return EINA_TRUE on success. EINA_FALSE otherwise.
8946 * @since 1.1.0
8947 */
8948EAPI Eina_Bool evas_textblock_cursor_visible_range_get(Evas_Textblock_Cursor *start, Evas_Textblock_Cursor *end) EINA_ARG_NONNULL(1, 2);
8949
8950/**
8951 * Return the format nodes in the range between cur1 and cur2.
8952 *
8953 * @param cur1 one side of the range.
8954 * @param cur2 the other side of the range
8955 * @return the foramt nodes in the range. You have to free it.
8956 * @since 1.1.0
8957 */
8958EAPI Eina_List * evas_textblock_cursor_range_formats_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
8959
8960/**
8961 * Return the text in the range between cur1 and cur2
8962 *
8963 * @param cur1 one side of the range.
8964 * @param cur2 the other side of the range
8965 * @param format The form on which to return the text. Markup - in textblock markup. Plain - UTF8.
8966 * @return the text in the range
8967 * @see elm_entry_markup_to_utf8()
8968 */
8969EAPI char *evas_textblock_cursor_range_text_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2, Evas_Textblock_Text_Type format) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
8970
8971/**
8972 * Return the content of the cursor.
8973 *
8974 * Free the returned string pointer when done (if it is not NULL).
8975 *
8976 * @param cur the cursor
8977 * @return the text in the range, terminated by a nul byte (may be utf8).
8978 */
8979EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8980
8981
8982/**
8983 * Returns the geometry of the cursor. Depends on the type of cursor requested.
8984 * This should be used instead of char_geometry_get because there are weird
8985 * special cases with BiDi text.
8986 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
8987 * get, except for the case of the last char of a line which depends on the
8988 * paragraph direction.
8989 *
8990 * in '|' cursor mode (i.e a line between two chars) it is very variable.
8991 * For example consider the following visual string:
8992 * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
8993 * a '|' between the c and the C.
8994 *
8995 * @param cur the cursor.
8996 * @param cx the x of the cursor
8997 * @param cy the y of the cursor
8998 * @param cw the width of the cursor
8999 * @param ch the height of the cursor
9000 * @param dir the direction of the cursor, can be NULL.
9001 * @param ctype the type of the cursor.
9002 * @return line number of the char on success, -1 on error.
9003 */
9004EAPI int evas_textblock_cursor_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch, Evas_BiDi_Direction *dir, Evas_Textblock_Cursor_Type ctype) EINA_ARG_NONNULL(1);
9005
9006/**
9007 * Returns the geometry of the char at cur.
9008 *
9009 * @param cur the position of the char.
9010 * @param cx the x of the char.
9011 * @param cy the y of the char.
9012 * @param cw the w of the char.
9013 * @param ch the h of the char.
9014 * @return line number of the char on success, -1 on error.
9015 */
9016EAPI int evas_textblock_cursor_char_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
9017
9018/**
9019 * Returns the geometry of the pen at cur.
9020 *
9021 * @param cur the position of the char.
9022 * @param cpen_x the pen_x of the char.
9023 * @param cy the y of the char.
9024 * @param cadv the adv of the char.
9025 * @param ch the h of the char.
9026 * @return line number of the char on success, -1 on error.
9027 */
9028EAPI int evas_textblock_cursor_pen_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cpen_x, Evas_Coord *cy, Evas_Coord *cadv, Evas_Coord *ch) EINA_ARG_NONNULL(1);
9029
9030/**
9031 * Returns the geometry of the line at cur.
9032 *
9033 * @param cur the position of the line.
9034 * @param cx the x of the line.
9035 * @param cy the y of the line.
9036 * @param cw the width of the line.
9037 * @param ch the height of the line.
9038 * @return line number of the line on success, -1 on error.
9039 */
9040EAPI int evas_textblock_cursor_line_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
9041
9042/**
9043 * Set the position of the cursor according to the X and Y coordinates.
9044 *
9045 * @param cur the cursor to set.
9046 * @param x coord to set by.
9047 * @param y coord to set by.
9048 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
9049 */
9050EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
9051
9052/**
9053 * Set the cursor position according to the y coord.
9054 *
9055 * @param cur the cur to be set.
9056 * @param y the coord to set by.
9057 * @return the line number found, -1 on error.
9058 */
9059EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
9060
9061/**
9062 * Get the geometry of a range.
9063 *
9064 * @param cur1 one side of the range.
9065 * @param cur2 other side of the range.
9066 * @return a list of Rectangles representing the geometry of the range.
9067 */
9068EAPI Eina_List *evas_textblock_cursor_range_geometry_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
9069 EAPI Eina_Bool evas_textblock_cursor_format_item_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
9070
9071
9072/**
9073 * Checks if the cursor points to the end of the line.
9074 *
9075 * @param cur the cursor to check.
9076 * @return #EINA_TRUE if true, #EINA_FALSE otherwise.
9077 */
9078EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
9079
9080
9081/**
9082 * Get the geometry of a line number.
9083 *
9084 * @param obj the object.
9085 * @param line the line number.
9086 * @param cx x coord of the line.
9087 * @param cy y coord of the line.
9088 * @param cw w coord of the line.
9089 * @param ch h coord of the line.
9090 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
9091 */
9092EAPI Eina_Bool evas_object_textblock_line_number_geometry_get(const Evas_Object *obj, int line, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
9093
9094/**
9095 * Clear the textblock object.
9096 * @note Does *NOT* free the Evas object itself.
9097 *
9098 * @param obj the object to clear.
9099 * @return nothing.
9100 */
9101EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
9102
9103/**
9104 * Get the formatted width and height. This calculates the actual size after restricting
9105 * the textblock to the current size of the object.
9106 * The main difference between this and @ref evas_object_textblock_size_native_get
9107 * is that the "native" function does not wrapping into account
9108 * it just calculates the real width of the object if it was placed on an
9109 * infinite canvas, while this function gives the size after wrapping
9110 * according to the size restrictions of the object.
9111 *
9112 * For example for a textblock containing the text: "You shall not pass!"
9113 * with no margins or padding and assuming a monospace font and a size of
9114 * 7x10 char widths (for simplicity) has a native size of 19x1
9115 * and a formatted size of 5x4.
9116 *
9117 *
9118 * @param obj the Evas object.
9119 * @param w[out] the width of the object.
9120 * @param h[out] the height of the object
9121 * @return Returns no value.
9122 * @see evas_object_textblock_size_native_get
9123 */
9124EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
9125
9126/**
9127 * Get the native width and height. This calculates the actual size without taking account
9128 * the current size of the object.
9129 * The main difference between this and @ref evas_object_textblock_size_formatted_get
9130 * is that the "native" function does not take wrapping into account
9131 * it just calculates the real width of the object if it was placed on an
9132 * infinite canvas, while the "formatted" function gives the size after
9133 * wrapping text according to the size restrictions of the object.
9134 *
9135 * For example for a textblock containing the text: "You shall not pass!"
9136 * with no margins or padding and assuming a monospace font and a size of
9137 * 7x10 char widths (for simplicity) has a native size of 19x1
9138 * and a formatted size of 5x4.
9139 *
9140 * @param obj the Evas object of the textblock
9141 * @param w[out] the width returned
9142 * @param h[out] the height returned
9143 * @return Returns no value.
9144 */
9145EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
9146 EAPI void evas_object_textblock_style_insets_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) EINA_ARG_NONNULL(1);
9147/**
9148 * @}
9149 */
9150
9151/**
9152 * @defgroup Evas_Line_Group Line Object Functions
9153 *
9154 * Functions used to deal with evas line objects.
9155 *
9156 * @ingroup Evas_Object_Specific
9157 *
9158 * @{
9159 */
9160
9161/**
9162 * Adds a new evas line object to the given evas.
9163 * @param e The given evas.
9164 * @return The new evas line object.
9165 */
9166EAPI Evas_Object *evas_object_line_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
9167
9168/**
9169 * Sets the coordinates of the end points of the given evas line object.
9170 * @param obj The given evas line object.
9171 * @param x1 The X coordinate of the first point.
9172 * @param y1 The Y coordinate of the first point.
9173 * @param x2 The X coordinate of the second point.
9174 * @param y2 The Y coordinate of the second point.
9175 */
9176EAPI void evas_object_line_xy_set (Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2);
9177
9178/**
9179 * Retrieves the coordinates of the end points of the given evas line object.
9180 * @param obj The given line object.
9181 * @param x1 Pointer to an integer in which to store the X coordinate of the
9182 * first end point.
9183 * @param y1 Pointer to an integer in which to store the Y coordinate of the
9184 * first end point.
9185 * @param x2 Pointer to an integer in which to store the X coordinate of the
9186 * second end point.
9187 * @param y2 Pointer to an integer in which to store the Y coordinate of the
9188 * second end point.
9189 */
9190EAPI void evas_object_line_xy_get (const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2);
9191/**
9192 * @}
9193 */
9194
9195/**
9196 * @defgroup Evas_Object_Polygon Polygon Object Functions
9197 *
9198 * Functions that operate on evas polygon objects.
9199 *
9200 * Hint: as evas does not provide ellipse, smooth paths or circle, one
9201 * can calculate points and convert these to a polygon.
9202 *
9203 * @ingroup Evas_Object_Specific
9204 *
9205 * @{
9206 */
9207
9208/**
9209 * Adds a new evas polygon object to the given evas.
9210 * @param e The given evas.
9211 * @return A new evas polygon object.
9212 */
9213EAPI Evas_Object *evas_object_polygon_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
9214
9215/**
9216 * Adds the given point to the given evas polygon object.
9217 * @param obj The given evas polygon object.
9218 * @param x The X coordinate of the given point.
9219 * @param y The Y coordinate of the given point.
9220 * @ingroup Evas_Polygon_Group
9221 */
9222EAPI void evas_object_polygon_point_add (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
9223
9224/**
9225 * Removes all of the points from the given evas polygon object.
9226 * @param obj The given polygon object.
9227 */
9228EAPI void evas_object_polygon_points_clear (Evas_Object *obj) EINA_ARG_NONNULL(1);
9229/**
9230 * @}
9231 */
9232
9233/* @since 1.2.0 */
9234EAPI void evas_object_is_frame_object_set(Evas_Object *obj, Eina_Bool is_frame);
9235
9236/* @since 1.2.0 */
9237EAPI Eina_Bool evas_object_is_frame_object_get(Evas_Object *obj);
9238
9239/**
9240 * @defgroup Evas_Smart_Group Smart Functions
9241 *
9242 * Functions that deal with #Evas_Smart structs, creating definition
9243 * (classes) of objects that will have customized behavior for methods
9244 * like evas_object_move(), evas_object_resize(),
9245 * evas_object_clip_set() and others.
9246 *
9247 * These objects will accept the generic methods defined in @ref
9248 * Evas_Object_Group and the extensions defined in @ref
9249 * Evas_Smart_Object_Group. There are a couple of existent smart
9250 * objects in Evas itself (see @ref Evas_Object_Box, @ref
9251 * Evas_Object_Table and @ref Evas_Smart_Object_Clipped).
9252 *
9253 * See also some @ref Example_Evas_Smart_Objects "examples" of this
9254 * group of functions.
9255 */
9256
9257/**
9258 * @addtogroup Evas_Smart_Group
9259 * @{
9260 */
9261
9262/**
9263 * @def EVAS_SMART_CLASS_VERSION
9264 *
9265 * The version you have to put into the version field in the
9266 * #Evas_Smart_Class struct. Used to safeguard from binaries with old
9267 * smart object intefaces running with newer ones.
9268 *
9269 * @ingroup Evas_Smart_Group
9270 */
9271#define EVAS_SMART_CLASS_VERSION 4
9272/**
9273 * @struct _Evas_Smart_Class
9274 *
9275 * A smart object's @b base class definition
9276 *
9277 * @ingroup Evas_Smart_Group
9278 */
9279struct _Evas_Smart_Class
9280{
9281 const char *name; /**< the name string of the class */
9282 int version;
9283 void (*add) (Evas_Object *o); /**< code to be run when adding object to a canvas */
9284 void (*del) (Evas_Object *o); /**< code to be run when removing object to a canvas */
9285 void (*move) (Evas_Object *o, Evas_Coord x, Evas_Coord y); /**< code to be run when moving object on a canvas */
9286 void (*resize) (Evas_Object *o, Evas_Coord w, Evas_Coord h); /**< code to be run when resizing object on a canvas */
9287 void (*show) (Evas_Object *o); /**< code to be run when showing object on a canvas */
9288 void (*hide) (Evas_Object *o); /**< code to be run when hiding object on a canvas */
9289 void (*color_set) (Evas_Object *o, int r, int g, int b, int a); /**< code to be run when setting color of object on a canvas */
9290 void (*clip_set) (Evas_Object *o, Evas_Object *clip); /**< code to be run when setting clipper of object on a canvas */
9291 void (*clip_unset) (Evas_Object *o); /**< code to be run when unsetting clipper of object on a canvas */
9292 void (*calculate) (Evas_Object *o); /**< code to be run when object has rendering updates on a canvas */
9293 void (*member_add) (Evas_Object *o, Evas_Object *child); /**< code to be run when child member is added to object */
9294 void (*member_del) (Evas_Object *o, Evas_Object *child); /**< code to be run when child member is removed from object */
9295
9296 const Evas_Smart_Class *parent; /**< this class inherits from this parent */
9297 const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, @c NULL terminated */
9298 void *interfaces; /**< to be used in a future near you */
9299 const void *data;
9300};
9301
9302/**
9303 * @struct _Evas_Smart_Cb_Description
9304 *
9305 * Describes a callback issued by a smart object
9306 * (evas_object_smart_callback_call()), as defined in its smart object
9307 * class. This is particularly useful to explain to end users and
9308 * their code (i.e., introspection) what the parameter @c event_info
9309 * will point to.
9310 *
9311 * @ingroup Evas_Smart_Group
9312 */
9313struct _Evas_Smart_Cb_Description
9314{
9315 const char *name; /**< callback name ("changed", for example) */
9316
9317 /**
9318 * @brief Hint on the type of @c event_info parameter's contents on
9319 * a #Evas_Smart_Cb callback.
9320 *
9321 * The type string uses the pattern similar to
9322 * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures,
9323 * but extended to optionally include variable names within
9324 * brackets preceding types. Example:
9325 *
9326 * @li Structure with two integers:
9327 * @c "(ii)"
9328 *
9329 * @li Structure called 'x' with two integers named 'a' and 'b':
9330 * @c "[x]([a]i[b]i)"
9331 *
9332 * @li Array of integers:
9333 * @c "ai"
9334 *
9335 * @li Array called 'x' of struct with two integers:
9336 * @c "[x]a(ii)"
9337 *
9338 * @note This type string is used as a hint and is @b not validated
9339 * or enforced in any way. Implementors should make the best
9340 * use of it to help bindings, documentation and other users
9341 * of introspection features.
9342 */
9343 const char *type;
9344};
9345
9346/**
9347 * @def EVAS_SMART_CLASS_INIT_NULL
9348 * Initializer to zero a whole Evas_Smart_Class structure.
9349 *
9350 * @see EVAS_SMART_CLASS_INIT_VERSION
9351 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
9352 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9353 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9354 * @ingroup Evas_Smart_Group
9355 */
9356#define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
9357
9358/**
9359 * @def EVAS_SMART_CLASS_INIT_VERSION
9360 * Initializer to zero a whole Evas_Smart_Class structure and set version.
9361 *
9362 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
9363 * latest EVAS_SMART_CLASS_VERSION.
9364 *
9365 * @see EVAS_SMART_CLASS_INIT_NULL
9366 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
9367 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9368 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9369 * @ingroup Evas_Smart_Group
9370 */
9371#define EVAS_SMART_CLASS_INIT_VERSION {NULL, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
9372
9373/**
9374 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
9375 * Initializer to zero a whole Evas_Smart_Class structure and set name
9376 * and version.
9377 *
9378 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
9379 * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
9380 *
9381 * It will keep a reference to name field as a "const char *", that is,
9382 * name must be available while the structure is used (hint: static or global!)
9383 * and will not be modified.
9384 *
9385 * @see EVAS_SMART_CLASS_INIT_NULL
9386 * @see EVAS_SMART_CLASS_INIT_VERSION
9387 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9388 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9389 * @ingroup Evas_Smart_Group
9390 */
9391#define EVAS_SMART_CLASS_INIT_NAME_VERSION(name) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
9392
9393/**
9394 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9395 * Initializer to zero a whole Evas_Smart_Class structure and set name,
9396 * version and parent class.
9397 *
9398 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
9399 * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
9400 * parent class.
9401 *
9402 * It will keep a reference to name field as a "const char *", that is,
9403 * name must be available while the structure is used (hint: static or global!)
9404 * and will not be modified. Similarly, parent reference will be kept.
9405 *
9406 * @see EVAS_SMART_CLASS_INIT_NULL
9407 * @see EVAS_SMART_CLASS_INIT_VERSION
9408 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
9409 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9410 * @ingroup Evas_Smart_Group
9411 */
9412#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT(name, parent) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, NULL, NULL}
9413
9414/**
9415 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9416 * Initializer to zero a whole Evas_Smart_Class structure and set name,
9417 * version, parent class and callbacks definition.
9418 *
9419 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
9420 * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
9421 * class and callbacks at this level.
9422 *
9423 * It will keep a reference to name field as a "const char *", that is,
9424 * name must be available while the structure is used (hint: static or global!)
9425 * and will not be modified. Similarly, parent and callbacks reference
9426 * will be kept.
9427 *
9428 * @see EVAS_SMART_CLASS_INIT_NULL
9429 * @see EVAS_SMART_CLASS_INIT_VERSION
9430 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
9431 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9432 * @ingroup Evas_Smart_Group
9433 */
9434#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS(name, parent, callbacks) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, callbacks, NULL}
9435
9436/**
9437 * @def EVAS_SMART_SUBCLASS_NEW
9438 *
9439 * Convenience macro to subclass a given Evas smart class.
9440 *
9441 * @param smart_name The name used for the smart class. e.g:
9442 * @c "Evas_Object_Box".
9443 * @param prefix Prefix used for all variables and functions defined
9444 * and referenced by this macro.
9445 * @param api_type Type of the structure used as API for the smart
9446 * class. Either #Evas_Smart_Class or something derived from it.
9447 * @param parent_type Type of the parent class API.
9448 * @param parent_func Function that gets the parent class. e.g:
9449 * evas_object_box_smart_class_get().
9450 * @param cb_desc Array of callback descriptions for this smart class.
9451 *
9452 * This macro saves some typing when writing a smart class derived
9453 * from another one. In order to work, the user @b must provide some
9454 * functions adhering to the following guidelines:
9455 * - @<prefix@>_smart_set_user(): the @b internal @c _smart_set
9456 * function (defined by this macro) will call this one, provided by
9457 * the user, after inheriting everything from the parent, which
9458 * should <b>take care of setting the right member functions for
9459 * the class</b>, both overrides and extensions, if any.
9460 * - If this new class should be subclassable as well, a @b public @c
9461 * _smart_set() function is desirable to fill in the class used as
9462 * parent by the children. It's up to the user to provide this
9463 * interface, which will most likely call @<prefix@>_smart_set() to
9464 * get the job done.
9465 *
9466 * After the macro's usage, the following will be defined for use:
9467 * - @<prefix@>_parent_sc: A pointer to the @b parent smart
9468 * class. When calling parent functions from overloaded ones, use
9469 * this global variable.
9470 * - @<prefix@>_smart_class_new(): this function returns the
9471 * #Evas_Smart needed to create smart objects with this class,
9472 * which should be passed to evas_object_smart_add().
9473 *
9474 * @warning @p smart_name has to be a pointer to a globally available
9475 * string! The smart class created here will just have a pointer set
9476 * to that, and all object instances will depend on it for smart class
9477 * name lookup.
9478 *
9479 * @ingroup Evas_Smart_Group
9480 */
9481#define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
9482 static const parent_type * prefix##_parent_sc = NULL; \
9483 static void prefix##_smart_set_user(api_type *api); \
9484 static void prefix##_smart_set(api_type *api) \
9485 { \
9486 Evas_Smart_Class *sc; \
9487 if (!(sc = (Evas_Smart_Class *)api)) \
9488 return; \
9489 if (!prefix##_parent_sc) \
9490 prefix##_parent_sc = parent_func(); \
9491 evas_smart_class_inherit(sc, prefix##_parent_sc); \
9492 prefix##_smart_set_user(api); \
9493 } \
9494 static Evas_Smart * prefix##_smart_class_new(void) \
9495 { \
9496 static Evas_Smart *smart = NULL; \
9497 static api_type api; \
9498 if (!smart) \
9499 { \
9500 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
9501 memset(&api, 0, sizeof(api_type)); \
9502 sc->version = EVAS_SMART_CLASS_VERSION; \
9503 sc->name = smart_name; \
9504 sc->callbacks = cb_desc; \
9505 prefix##_smart_set(&api); \
9506 smart = evas_smart_class_new(sc); \
9507 } \
9508 return smart; \
9509 }
9510
9511/**
9512 * @def EVAS_SMART_DATA_ALLOC
9513 *
9514 * Convenience macro to allocate smart data only if needed.
9515 *
9516 * When writing a subclassable smart object, the @c .add() function
9517 * will need to check if the smart private data was already allocated
9518 * by some child object or not. This macro makes it easier to do it.
9519 *
9520 * @note This is an idiom used when one calls the parent's @c. add()
9521 * after the specialized code. Naturally, the parent's base smart data
9522 * has to be contemplated as the specialized one's first member, for
9523 * things to work.
9524 *
9525 * @param o Evas object passed to the @c .add() function
9526 * @param priv_type The type of the data to allocate
9527 *
9528 * @ingroup Evas_Smart_Group
9529 */
9530#define EVAS_SMART_DATA_ALLOC(o, priv_type) \
9531 priv_type *priv; \
9532 priv = evas_object_smart_data_get(o); \
9533 if (!priv) { \
9534 priv = (priv_type *)calloc(1, sizeof(priv_type)); \
9535 if (!priv) return; \
9536 evas_object_smart_data_set(o, priv); \
9537 }
9538
9539
9540/**
9541 * Free an #Evas_Smart struct
9542 *
9543 * @param s the #Evas_Smart struct to free
9544 *
9545 * @warning If this smart handle was created using
9546 * evas_smart_class_new(), the associated #Evas_Smart_Class will not
9547 * be freed.
9548 *
9549 * @note If you're using the #EVAS_SMART_SUBCLASS_NEW schema to create your
9550 * smart object, note that an #Evas_Smart handle will be shared amongst all
9551 * instances of the given smart class, through a static variable.
9552 * Evas will internally count references on #Evas_Smart handles and free them
9553 * when they are not referenced anymore. Thus, this function is of no use
9554 * for Evas users, most probably.
9555 */
9556EAPI void evas_smart_free (Evas_Smart *s) EINA_ARG_NONNULL(1);
9557
9558/**
9559 * Creates a new #Evas_Smart from a given #Evas_Smart_Class struct
9560 *
9561 * @param sc the smart class definition
9562 * @return a new #Evas_Smart pointer
9563 *
9564 * #Evas_Smart handles are necessary to create new @b instances of
9565 * smart objects belonging to the class described by @p sc. That
9566 * handle will contain, besides the smart class interface definition,
9567 * all its smart callbacks infrastructure set, too.
9568 *
9569 * @note If you are willing to subclass a given smart class to
9570 * construct yours, consider using the #EVAS_SMART_SUBCLASS_NEW macro,
9571 * which will make use of this function automatically for you.
9572 */
9573EAPI Evas_Smart *evas_smart_class_new (const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
9574
9575/**
9576 * Get the #Evas_Smart_Class handle of an #Evas_Smart struct
9577 *
9578 * @param s a valid #Evas_Smart pointer
9579 * @return the #Evas_Smart_Class in it
9580 */
9581EAPI const Evas_Smart_Class *evas_smart_class_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
9582
9583
9584/**
9585 * @brief Get the data pointer set on an #Evas_Smart struct
9586 *
9587 * @param s a valid #Evas_Smart handle
9588 *
9589 * This data pointer is set as the data field in the #Evas_Smart_Class
9590 * passed in to evas_smart_class_new().
9591 */
9592EAPI void *evas_smart_data_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
9593
9594/**
9595 * Get the smart callbacks known by this #Evas_Smart handle's smart
9596 * class hierarchy.
9597 *
9598 * @param s A valid #Evas_Smart handle.
9599 * @param[out] count Returns the number of elements in the returned
9600 * array.
9601 * @return The array with callback descriptions known by this smart
9602 * class, with its size returned in @a count parameter. It
9603 * should not be modified in any way. If no callbacks are
9604 * known, @c NULL is returned. The array is sorted by event
9605 * names and elements refer to the original values given to
9606 * evas_smart_class_new()'s #Evas_Smart_Class::callbacks
9607 * (pointer to them).
9608 *
9609 * This is likely different from
9610 * evas_object_smart_callbacks_descriptions_get() as it will contain
9611 * the callbacks of @b all this class hierarchy sorted, while the
9612 * direct smart class member refers only to that specific class and
9613 * should not include parent's.
9614 *
9615 * If no callbacks are known, this function returns @c NULL.
9616 *
9617 * The array elements and thus their contents will be @b references to
9618 * original values given to evas_smart_class_new() as
9619 * Evas_Smart_Class::callbacks.
9620 *
9621 * The array is sorted by Evas_Smart_Cb_Description::name. The last
9622 * array element is a @c NULL pointer and is not accounted for in @a
9623 * count. Loop iterations can check any of these size indicators.
9624 *
9625 * @note objects may provide per-instance callbacks, use
9626 * evas_object_smart_callbacks_descriptions_get() to get those
9627 * as well.
9628 * @see evas_object_smart_callbacks_descriptions_get()
9629 */
9630EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
9631
9632
9633/**
9634 * Find a callback description for the callback named @a name.
9635 *
9636 * @param s The #Evas_Smart where to search for class registered smart
9637 * event callbacks.
9638 * @param name Name of the desired callback, which must @b not be @c
9639 * NULL. The search has a special case for @a name being the
9640 * same pointer as registered with #Evas_Smart_Cb_Description.
9641 * One can use it to avoid excessive use of strcmp().
9642 * @return A reference to the description if found, or @c NULL, otherwise
9643 *
9644 * @see evas_smart_callbacks_descriptions_get()
9645 */
9646EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2);
9647
9648
9649/**
9650 * Sets one class to inherit from the other.
9651 *
9652 * Copy all function pointers, set @c parent to @a parent_sc and copy
9653 * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
9654 * using @a parent_sc_size as reference.
9655 *
9656 * This is recommended instead of a single memcpy() since it will take
9657 * care to not modify @a sc name, version, callbacks and possible
9658 * other members.
9659 *
9660 * @param sc child class.
9661 * @param parent_sc parent class, will provide attributes.
9662 * @param parent_sc_size size of parent_sc structure, child should be at least
9663 * this size. Everything after @c Evas_Smart_Class size is copied
9664 * using regular memcpy().
9665 */
9666EAPI Eina_Bool evas_smart_class_inherit_full (Evas_Smart_Class *sc, const Evas_Smart_Class *parent_sc, unsigned int parent_sc_size) EINA_ARG_NONNULL(1, 2);
9667
9668/**
9669 * Get the number of users of the smart instance
9670 *
9671 * @param s The Evas_Smart to get the usage count of
9672 * @return The number of uses of the smart instance
9673 *
9674 * This function tells you how many more uses of the smart instance are in
9675 * existence. This should be used before freeing/clearing any of the
9676 * Evas_Smart_Class that was used to create the smart instance. The smart
9677 * instance will refer to data in the Evas_Smart_Class used to create it and
9678 * thus you cannot remove the original data until all users of it are gone.
9679 * When the usage count goes to 0, you can evas_smart_free() the smart
9680 * instance @p s and remove from memory any of the Evas_Smart_Class that
9681 * was used to create the smart instance, if you desire. Removing it from
9682 * memory without doing this will cause problems (crashes, undefined
9683 * behavior etc. etc.), so either never remove the original
9684 * Evas_Smart_Class data from memory (have it be a constant structure and
9685 * data), or use this API call and be very careful.
9686 */
9687EAPI int evas_smart_usage_get(const Evas_Smart *s);
9688
9689 /**
9690 * @def evas_smart_class_inherit
9691 * Easy to use version of evas_smart_class_inherit_full().
9692 *
9693 * This version will use sizeof(parent_sc), copying everything.
9694 *
9695 * @param sc child class, will have methods copied from @a parent_sc
9696 * @param parent_sc parent class, will provide contents to be copied.
9697 * @return 1 on success, 0 on failure.
9698 * @ingroup Evas_Smart_Group
9699 */
9700#define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, (Evas_Smart_Class *)parent_sc, sizeof(*parent_sc))
9701
9702/**
9703 * @}
9704 */
9705
9706/**
9707 * @defgroup Evas_Smart_Object_Group Smart Object Functions
9708 *
9709 * Functions dealing with Evas smart objects (instances).
9710 *
9711 * Smart objects are groupings of primitive Evas objects that behave
9712 * as a cohesive group. For instance, a file manager icon may be a
9713 * smart object composed of an image object, a text label and two
9714 * rectangles that appear behind the image and text when the icon is
9715 * selected. As a smart object, the normal Evas object API could be
9716 * used on the icon object.
9717 *
9718 * Besides that, generally smart objects implement a <b>specific
9719 * API</b>, so that users interact with its own custom features. The
9720 * API takes form of explicit exported functions one may call and
9721 * <b>smart callbacks</b>.
9722 *
9723 * @section Evas_Smart_Object_Group_Callbacks Smart events and callbacks
9724 *
9725 * Smart objects can elect events (smart events, from now on) occurring
9726 * inside of them to be reported back to their users via callback
9727 * functions (smart callbacks). This way, you can extend Evas' own
9728 * object events. They are defined by an <b>event string</b>, which
9729 * identifies them uniquely. There's also a function prototype
9730 * definition for the callback functions: #Evas_Smart_Cb.
9731 *
9732 * When defining an #Evas_Smart_Class, smart object implementors are
9733 * strongly encouraged to properly set the Evas_Smart_Class::callbacks
9734 * callbacks description array, so that the users of the smart object
9735 * can have introspection on its events API <b>at run time</b>.
9736 *
9737 * See some @ref Example_Evas_Smart_Objects "examples" of this group
9738 * of functions.
9739 *
9740 * @see @ref Evas_Smart_Group for class definitions.
9741 */
9742
9743/**
9744 * @addtogroup Evas_Smart_Object_Group
9745 * @{
9746 */
9747
9748/**
9749 * Instantiates a new smart object described by @p s.
9750 *
9751 * @param e the canvas on which to add the object
9752 * @param s the #Evas_Smart describing the smart object
9753 * @return a new #Evas_Object handle
9754 *
9755 * This is the function one should use when defining the public
9756 * function @b adding an instance of the new smart object to a given
9757 * canvas. It will take care of setting all of its internals to work
9758 * as they should, if the user set things properly, as seem on the
9759 * #EVAS_SMART_SUBCLASS_NEW, for example.
9760 *
9761 * @ingroup Evas_Smart_Object_Group
9762 */
9763EAPI Evas_Object *evas_object_smart_add (Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC;
9764
9765/**
9766 * Set an Evas object as a member of a given smart object.
9767 *
9768 * @param obj The member object
9769 * @param smart_obj The smart object
9770 *
9771 * Members will automatically be stacked and layered together with the
9772 * smart object. The various stacking functions will operate on
9773 * members relative to the other members instead of the entire canvas,
9774 * since they now live on an exclusive layer (see
9775 * evas_object_stack_above(), for more details).
9776 *
9777 * Any @p smart_obj object's specific implementation of the @c
9778 * member_add() smart function will take place too, naturally.
9779 *
9780 * @see evas_object_smart_member_del()
9781 * @see evas_object_smart_members_get()
9782 *
9783 * @ingroup Evas_Smart_Object_Group
9784 */
9785EAPI void evas_object_smart_member_add (Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2);
9786
9787/**
9788 * Removes a member object from a given smart object.
9789 *
9790 * @param obj the member object
9791 * @ingroup Evas_Smart_Object_Group
9792 *
9793 * This removes a member object from a smart object, if it was added
9794 * to any. The object will still be on the canvas, but no longer
9795 * associated with whichever smart object it was associated with.
9796 *
9797 * @see evas_object_smart_member_add() for more details
9798 * @see evas_object_smart_members_get()
9799 */
9800EAPI void evas_object_smart_member_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
9801
9802/**
9803 * Retrieves the list of the member objects of a given Evas smart
9804 * object
9805 *
9806 * @param obj the smart object to get members from
9807 * @return Returns the list of the member objects of @p obj.
9808 *
9809 * The returned list should be freed with @c eina_list_free() when you
9810 * no longer need it.
9811 *
9812 * @see evas_object_smart_member_add()
9813 * @see evas_object_smart_member_del()
9814*/
9815EAPI Eina_List *evas_object_smart_members_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
9816
9817/**
9818 * Gets the parent smart object of a given Evas object, if it has one.
9819 *
9820 * @param obj the Evas object you want to get the parent smart object
9821 * from
9822 * @return Returns the parent smart object of @a obj or @c NULL, if @a
9823 * obj is not a smart member of any
9824 *
9825 * @ingroup Evas_Smart_Object_Group
9826 */
9827EAPI Evas_Object *evas_object_smart_parent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
9828
9829/**
9830 * Checks whether a given smart object or any of its smart object
9831 * parents is of a given smart class.
9832 *
9833 * @param obj An Evas smart object to check the type of
9834 * @param type The @b name (type) of the smart class to check for
9835 * @return @c EINA_TRUE, if @a obj or any of its parents is of type @a
9836 * type, @c EINA_FALSE otherwise
9837 *
9838 * If @p obj is not a smart object, this call will fail
9839 * immediately. Otherwise, make sure evas_smart_class_inherit() or its
9840 * sibling functions were used correctly when creating the smart
9841 * object's class, so it has a valid @b parent smart class pointer
9842 * set.
9843 *
9844 * The checks use smart classes names and <b>string
9845 * comparison</b>. There is a version of this same check using
9846 * <b>pointer comparison</b>, since a smart class' name is a single
9847 * string in Evas.
9848 *
9849 * @see evas_object_smart_type_check_ptr()
9850 * @see #EVAS_SMART_SUBCLASS_NEW
9851 *
9852 * @ingroup Evas_Smart_Object_Group
9853 */
9854EAPI Eina_Bool evas_object_smart_type_check (const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
9855
9856/**
9857 * Checks whether a given smart object or any of its smart object
9858 * parents is of a given smart class, <b>using pointer comparison</b>.
9859 *
9860 * @param obj An Evas smart object to check the type of
9861 * @param type The type (name string) to check for. Must be the name
9862 * @return @c EINA_TRUE, if @a obj or any of its parents is of type @a
9863 * type, @c EINA_FALSE otherwise
9864 *
9865 * @see evas_object_smart_type_check() for more details
9866 *
9867 * @ingroup Evas_Smart_Object_Group
9868 */
9869EAPI Eina_Bool evas_object_smart_type_check_ptr (const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
9870
9871/**
9872 * Get the #Evas_Smart from which @p obj smart object was created.
9873 *
9874 * @param obj a smart object
9875 * @return the #Evas_Smart handle or @c NULL, on errors
9876 *
9877 * @ingroup Evas_Smart_Object_Group
9878 */
9879EAPI Evas_Smart *evas_object_smart_smart_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
9880
9881/**
9882 * Retrieve user data stored on a given smart object.
9883 *
9884 * @param obj The smart object's handle
9885 * @return A pointer to data stored using
9886 * evas_object_smart_data_set(), or @c NULL, if none has been
9887 * set.
9888 *
9889 * @see evas_object_smart_data_set()
9890 *
9891 * @ingroup Evas_Smart_Object_Group
9892 */
9893EAPI void *evas_object_smart_data_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
9894
9895/**
9896 * Store a pointer to user data for a given smart object.
9897 *
9898 * @param obj The smart object's handle
9899 * @param data A pointer to user data
9900 *
9901 * This data is stored @b independently of the one set by
9902 * evas_object_data_set(), naturally.
9903 *
9904 * @see evas_object_smart_data_get()
9905 *
9906 * @ingroup Evas_Smart_Object_Group
9907 */
9908EAPI void evas_object_smart_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
9909
9910/**
9911 * Add (register) a callback function to the smart event specified by
9912 * @p event on the smart object @p obj.
9913 *
9914 * @param obj a smart object
9915 * @param event the event's name string
9916 * @param func the callback function
9917 * @param data user data to be passed to the callback function
9918 *
9919 * Smart callbacks look very similar to Evas callbacks, but are
9920 * implemented as smart object's custom ones.
9921 *
9922 * This function adds a function callback to an smart object when the
9923 * event named @p event occurs in it. The function is @p func.
9924 *
9925 * In the event of a memory allocation error during addition of the
9926 * callback to the object, evas_alloc_error() should be used to
9927 * determine the nature of the error, if any, and the program should
9928 * sensibly try and recover.
9929 *
9930 * A smart callback function must have the ::Evas_Smart_Cb prototype
9931 * definition. The first parameter (@p data) in this definition will
9932 * have the same value passed to evas_object_smart_callback_add() as
9933 * the @p data parameter, at runtime. The second parameter @p obj is a
9934 * handle to the object on which the event occurred. The third
9935 * parameter, @p event_info, is a pointer to data which is totally
9936 * dependent on the smart object's implementation and semantic for the
9937 * given event.
9938 *
9939 * There is an infrastructure for introspection on smart objects'
9940 * events (see evas_smart_callbacks_descriptions_get()), but no
9941 * internal smart objects on Evas implement them yet.
9942 *
9943 * @see @ref Evas_Smart_Object_Group_Callbacks for more details.
9944 *
9945 * @see evas_object_smart_callback_del()
9946 * @ingroup Evas_Smart_Object_Group
9947 */
9948EAPI void evas_object_smart_callback_add (Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1, 2, 3);
9949
9950/**
9951 * Add (register) a callback function to the smart event specified by
9952 * @p event on the smart object @p obj. Except for the priority field,
9953 * it's exactly the same as @ref evas_object_smart_callback_add
9954 *
9955 * @param obj a smart object
9956 * @param event the event's name string
9957 * @param priority The priority of the callback, lower values called first.
9958 * @param func the callback function
9959 * @param data user data to be passed to the callback function
9960 *
9961 * @see evas_object_smart_callback_add
9962 * @since 1.1.0
9963 * @ingroup Evas_Smart_Object_Group
9964 */
9965EAPI void evas_object_smart_callback_priority_add(Evas_Object *obj, const char *event, Evas_Callback_Priority priority, Evas_Smart_Cb func, const void *data);
9966
9967/**
9968 * Delete (unregister) a callback function from the smart event
9969 * specified by @p event on the smart object @p obj.
9970 *
9971 * @param obj a smart object
9972 * @param event the event's name string
9973 * @param func the callback function
9974 * @return the data pointer
9975 *
9976 * This function removes <b>the first</b> added smart callback on the
9977 * object @p obj matching the event name @p event and the registered
9978 * function pointer @p func. If the removal is successful it will also
9979 * return the data pointer that was passed to
9980 * evas_object_smart_callback_add() (that will be the same as the
9981 * parameter) when the callback(s) was(were) added to the canvas. If
9982 * not successful @c NULL will be returned.
9983 *
9984 * @see evas_object_smart_callback_add() for more details.
9985 *
9986 * @ingroup Evas_Smart_Object_Group
9987 */
9988EAPI void *evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3);
9989
9990/**
9991 * Delete (unregister) a callback function from the smart event
9992 * specified by @p event on the smart object @p obj.
9993 *
9994 * @param obj a smart object
9995 * @param event the event's name string
9996 * @param func the callback function
9997 * @param data the data pointer that was passed to the callback
9998 * @return the data pointer
9999 *
10000 * This function removes <b>the first</b> added smart callback on the
10001 * object @p obj matching the event name @p event, the registered
10002 * function pointer @p func and the callback data pointer @p data. If
10003 * the removal is successful it will also return the data pointer that
10004 * was passed to evas_object_smart_callback_add() (that will be the same
10005 * as the parameter) when the callback(s) was(were) added to the canvas.
10006 * If not successful @c NULL will be returned. A common use would be to
10007 * remove an exact match of a callback
10008 *
10009 * @see evas_object_smart_callback_add() for more details.
10010 * @since 1.2.0
10011 * @ingroup Evas_Smart_Object_Group
10012 *
10013 * @note To delete all smart event callbacks which match @p type and @p func,
10014 * use evas_object_smart_callback_del().
10015 */
10016EAPI void *evas_object_smart_callback_del_full(Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1, 2, 3);
10017
10018/**
10019 * Call a given smart callback on the smart object @p obj.
10020 *
10021 * @param obj the smart object
10022 * @param event the event's name string
10023 * @param event_info pointer to an event specific struct or information to
10024 * pass to the callback functions registered on this smart event
10025 *
10026 * This should be called @b internally, from the smart object's own
10027 * code, when some specific event has occurred and the implementor
10028 * wants is to pertain to the object's events API (see @ref
10029 * Evas_Smart_Object_Group_Callbacks). The documentation for the smart
10030 * object should include a list of possible events and what type of @p
10031 * event_info to expect for each of them. Also, when defining an
10032 * #Evas_Smart_Class, smart object implementors are strongly
10033 * encouraged to properly set the Evas_Smart_Class::callbacks
10034 * callbacks description array, so that the users of the smart object
10035 * can have introspection on its events API <b>at run time</b>.
10036 *
10037 * @ingroup Evas_Smart_Object_Group
10038 */
10039EAPI void evas_object_smart_callback_call (Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2);
10040
10041
10042/**
10043 * Set an smart object @b instance's smart callbacks descriptions.
10044 *
10045 * @param obj A smart object
10046 * @param descriptions @c NULL terminated array with
10047 * #Evas_Smart_Cb_Description descriptions. Array elements won't be
10048 * modified at run time, but references to them and their contents
10049 * will be made, so this array should be kept alive during the whole
10050 * object's lifetime.
10051 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
10052 *
10053 * These descriptions are hints to be used by introspection and are
10054 * not enforced in any way.
10055 *
10056 * It will not be checked if instance callbacks descriptions have the
10057 * same name as respective possibly registered in the smart object
10058 * @b class. Both are kept in different arrays and users of
10059 * evas_object_smart_callbacks_descriptions_get() should handle this
10060 * case as they wish.
10061 *
10062 * @note Becase @p descriptions must be @c NULL terminated, and
10063 * because a @c NULL name makes little sense, too,
10064 * Evas_Smart_Cb_Description::name must @b not be @c NULL.
10065 *
10066 * @note While instance callbacks descriptions are possible, they are
10067 * @b not recommended. Use @b class callbacks descriptions
10068 * instead as they make you smart object user's life simpler and
10069 * will use less memory, as descriptions and arrays will be
10070 * shared among all instances.
10071 *
10072 * @ingroup Evas_Smart_Object_Group
10073 */
10074EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1);
10075
10076/**
10077 * Retrieve an smart object's know smart callback descriptions (both
10078 * instance and class ones).
10079 *
10080 * @param obj The smart object to get callback descriptions from.
10081 * @param class_descriptions Where to store class callbacks
10082 * descriptions array, if any is known. If no descriptions are
10083 * known, @c NULL is returned
10084 * @param class_count Returns how many class callbacks descriptions
10085 * are known.
10086 * @param instance_descriptions Where to store instance callbacks
10087 * descriptions array, if any is known. If no descriptions are
10088 * known, @c NULL is returned.
10089 * @param instance_count Returns how many instance callbacks
10090 * descriptions are known.
10091 *
10092 * This call searches for registered callback descriptions for both
10093 * instance and class of the given smart object. These arrays will be
10094 * sorted by Evas_Smart_Cb_Description::name and also @c NULL
10095 * terminated, so both @a class_count and @a instance_count can be
10096 * ignored, if the caller wishes so. The terminator @c NULL is not
10097 * counted in these values.
10098 *
10099 * @note If just class descriptions are of interest, try
10100 * evas_smart_callbacks_descriptions_get() instead.
10101 *
10102 * @note Use @c NULL pointers on the descriptions/counters you're not
10103 * interested in: they'll be ignored by the function.
10104 *
10105 * @see evas_smart_callbacks_descriptions_get()
10106 *
10107 * @ingroup Evas_Smart_Object_Group
10108 */
10109EAPI void evas_object_smart_callbacks_descriptions_get(const Evas_Object *obj, const Evas_Smart_Cb_Description ***class_descriptions, unsigned int *class_count, const Evas_Smart_Cb_Description ***instance_descriptions, unsigned int *instance_count) EINA_ARG_NONNULL(1);
10110
10111/**
10112 * Find callback description for callback called @a name.
10113 *
10114 * @param obj the smart object.
10115 * @param name name of desired callback, must @b not be @c NULL. The
10116 * search have a special case for @a name being the same
10117 * pointer as registered with Evas_Smart_Cb_Description, one
10118 * can use it to avoid excessive use of strcmp().
10119 * @param class_description pointer to return class description or @c
10120 * NULL if not found. If parameter is @c NULL, no search will
10121 * be done on class descriptions.
10122 * @param instance_description pointer to return instance description
10123 * or @c NULL if not found. If parameter is @c NULL, no search
10124 * will be done on instance descriptions.
10125 * @return reference to description if found, @c NULL if not found.
10126 */
10127EAPI void evas_object_smart_callback_description_find(const Evas_Object *obj, const char *name, const Evas_Smart_Cb_Description **class_description, const Evas_Smart_Cb_Description **instance_description) EINA_ARG_NONNULL(1, 2);
10128
10129
10130/**
10131 * Mark smart object as changed, dirty.
10132 *
10133 * @param obj The given Evas smart object
10134 *
10135 * This will flag the given object as needing recalculation,
10136 * forcefully. As an effect, on the next rendering cycle it's @b
10137 * calculate() (see #Evas_Smart_Class) smart function will be called.
10138 *
10139 * @see evas_object_smart_need_recalculate_set().
10140 * @see evas_object_smart_calculate().
10141 *
10142 * @ingroup Evas_Smart_Object_Group
10143 */
10144EAPI void evas_object_smart_changed (Evas_Object *obj) EINA_ARG_NONNULL(1);
10145
10146/**
10147 * Set or unset the flag signalling that a given smart object needs to
10148 * get recalculated.
10149 *
10150 * @param obj the smart object
10151 * @param value whether one wants to set (@c EINA_TRUE) or to unset
10152 * (@c EINA_FALSE) the flag.
10153 *
10154 * If this flag is set, then the @c calculate() smart function of @p
10155 * obj will be called, if one is provided, during rendering phase of
10156 * Evas (see evas_render()), after which this flag will be
10157 * automatically unset.
10158 *
10159 * If that smart function is not provided for the given object, this
10160 * flag will be left unchanged.
10161 *
10162 * @note just setting this flag will not make the canvas' whole scene
10163 * dirty, by itself, and evas_render() will have no effect. To
10164 * force that, use evas_object_smart_changed(), that will also
10165 * automatically call this function automatically, with @c
10166 * EINA_TRUE as parameter.
10167 *
10168 * @see evas_object_smart_need_recalculate_get()
10169 * @see evas_object_smart_calculate()
10170 * @see evas_smart_objects_calculate()
10171 *
10172 * @ingroup Evas_Smart_Object_Group
10173 */
10174EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
10175
10176/**
10177 * Get the value of the flag signalling that a given smart object needs to
10178 * get recalculated.
10179 *
10180 * @param obj the smart object
10181 * @return if flag is set or not.
10182 *
10183 * @note this flag will be unset during the rendering phase, when the
10184 * @c calculate() smart function is called, if one is provided.
10185 * If it's not provided, then the flag will be left unchanged
10186 * after the rendering phase.
10187 *
10188 * @see evas_object_smart_need_recalculate_set(), for more details
10189 *
10190 * @ingroup Evas_Smart_Object_Group
10191 */
10192EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
10193
10194/**
10195 * Call the @b calculate() smart function immediately on a given smart
10196 * object.
10197 *
10198 * @param obj the smart object's handle
10199 *
10200 * This will force immediate calculations (see #Evas_Smart_Class)
10201 * needed for renderization of this object and, besides, unset the
10202 * flag on it telling it needs recalculation for the next rendering
10203 * phase.
10204 *
10205 * @see evas_object_smart_need_recalculate_set()
10206 *
10207 * @ingroup Evas_Smart_Object_Group
10208 */
10209EAPI void evas_object_smart_calculate (Evas_Object *obj) EINA_ARG_NONNULL(1);
10210
10211/**
10212 * Call user-provided @c calculate() smart functions and unset the
10213 * flag signalling that the object needs to get recalculated to @b all
10214 * smart objects in the canvas.
10215 *
10216 * @param e The canvas to calculate all smart objects in
10217 *
10218 * @see evas_object_smart_need_recalculate_set()
10219 *
10220 * @ingroup Evas_Smart_Object_Group
10221 */
10222EAPI void evas_smart_objects_calculate (Evas *e);
10223
10224/**
10225 * This gets the internal counter that counts the number of smart calculations
10226 *
10227 * @param e The canvas to get the calculate counter from
10228 *
10229 * Whenever evas performs smart object calculations on the whole canvas
10230 * it increments a counter by 1. This is the smart object calculate counter
10231 * that this function returns the value of. It starts at the value of 0 and
10232 * will increase (and eventually wrap around to negative values and so on) by
10233 * 1 every time objects are calculated. You can use this counter to ensure
10234 * you don't re-do calculations withint the same calculation generation/run
10235 * if the calculations maybe cause self-feeding effects.
10236 *
10237 * @ingroup Evas_Smart_Object_Group
10238 * @since 1.1
10239 */
10240EAPI int evas_smart_objects_calculate_count_get (const Evas *e);
10241
10242/**
10243 * Moves all children objects of a given smart object relative to a
10244 * given offset.
10245 *
10246 * @param obj the smart object.
10247 * @param dx horizontal offset (delta).
10248 * @param dy vertical offset (delta).
10249 *
10250 * This will make each of @p obj object's children to move, from where
10251 * they before, with those delta values (offsets) on both directions.
10252 *
10253 * @note This is most useful on custom smart @c move() functions.
10254 *
10255 * @note Clipped smart objects already make use of this function on
10256 * their @c move() smart function definition.
10257 */
10258EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1);
10259
10260/**
10261 * @}
10262 */
10263
10264/**
10265 * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
10266 *
10267 * Clipped smart object is a base to construct other smart objects
10268 * based on the concept of having an internal clipper that is applied
10269 * to all children objects. This clipper will control the visibility,
10270 * clipping and color of sibling objects (remember that the clipping
10271 * is recursive, and clipper color modulates the color of its
10272 * clippees). By default, this base will also move children relatively
10273 * to the parent, and delete them when parent is deleted. In other
10274 * words, it is the base for simple object grouping.
10275 *
10276 * See some @ref Example_Evas_Smart_Objects "examples" of this group
10277 * of functions.
10278 *
10279 * @see evas_object_smart_clipped_smart_set()
10280 *
10281 * @ingroup Evas_Smart_Object_Group
10282 */
10283
10284/**
10285 * @addtogroup Evas_Smart_Object_Clipped
10286 * @{
10287 */
10288
10289/**
10290 * Every subclass should provide this at the beginning of their own
10291 * data set with evas_object_smart_data_set().
10292 */
10293 typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
10294 struct _Evas_Object_Smart_Clipped_Data
10295 {
10296 Evas_Object *clipper;
10297 Evas *evas;
10298 };
10299
10300
10301/**
10302 * Get the clipper object for the given clipped smart object.
10303 *
10304 * @param obj the clipped smart object to retrieve associated clipper
10305 * from.
10306 * @return the clipper object.
10307 *
10308 * Use this function if you want to change any of this clipper's
10309 * properties, like colors.
10310 *
10311 * @see evas_object_smart_clipped_smart_add()
10312 */
10313EAPI Evas_Object *evas_object_smart_clipped_clipper_get (Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
10314
10315/**
10316 * Set a given smart class' callbacks so it implements the <b>clipped smart
10317 * object"</b>'s interface.
10318 *
10319 * @param sc The smart class handle to operate on
10320 *
10321 * This call will assign all the required methods of the @p sc
10322 * #Evas_Smart_Class instance to the implementations set for clipped
10323 * smart objects. If one wants to "subclass" it, call this function
10324 * and then override desired values. If one wants to call any original
10325 * method, save it somewhere. Example:
10326 *
10327 * @code
10328 * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
10329 *
10330 * static void my_class_smart_add(Evas_Object *o)
10331 * {
10332 * parent_sc.add(o);
10333 * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
10334 * 255, 0, 0, 255);
10335 * }
10336 *
10337 * Evas_Smart_Class *my_class_new(void)
10338 * {
10339 * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
10340 * if (!parent_sc.name)
10341 * {
10342 * evas_object_smart_clipped_smart_set(&sc);
10343 * parent_sc = sc;
10344 * sc.add = my_class_smart_add;
10345 * }
10346 * return &sc;
10347 * }
10348 * @endcode
10349 *
10350 * Default behavior for each of #Evas_Smart_Class functions on a
10351 * clipped smart object are:
10352 * - @c add: creates a hidden clipper with "infinite" size, to clip
10353 * any incoming members;
10354 * - @c del: delete all children objects;
10355 * - @c move: move all objects relative relatively;
10356 * - @c resize: <b>not defined</b>;
10357 * - @c show: if there are children objects, show clipper;
10358 * - @c hide: hides clipper;
10359 * - @c color_set: set the color of clipper;
10360 * - @c clip_set: set clipper of clipper;
10361 * - @c clip_unset: unset the clipper of clipper;
10362 *
10363 * @note There are other means of assigning parent smart classes to
10364 * child ones, like the #EVAS_SMART_SUBCLASS_NEW macro or the
10365 * evas_smart_class_inherit_full() function.
10366 */
10367EAPI void evas_object_smart_clipped_smart_set (Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
10368
10369/**
10370 * Get a pointer to the <b>clipped smart object's</b> class, to use
10371 * for proper inheritance
10372 *
10373 * @see #Evas_Smart_Object_Clipped for more information on this smart
10374 * class
10375 */
10376EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get (void) EINA_CONST;
10377
10378/**
10379 * @}
10380 */
10381
10382/**
10383 * @defgroup Evas_Object_Box Box Smart Object
10384 *
10385 * A box is a convenience smart object that packs children inside it
10386 * in @b sequence, using a layouting function specified by the
10387 * user. There are a couple of pre-made layouting functions <b>built-in
10388 * in Evas</b>, all of them using children size hints to define their
10389 * size and alignment inside their cell space.
10390 *
10391 * Examples on this smart object's usage:
10392 * - @ref Example_Evas_Box
10393 * - @ref Example_Evas_Size_Hints
10394 *
10395 * @see @ref Evas_Object_Group_Size_Hints
10396 *
10397 * @ingroup Evas_Smart_Object_Group
10398 */
10399
10400/**
10401 * @addtogroup Evas_Object_Box
10402 * @{
10403 */
10404
10405/**
10406 * @typedef Evas_Object_Box_Api
10407 *
10408 * Smart class extension, providing extra box object requirements.
10409 *
10410 * @ingroup Evas_Object_Box
10411 */
10412 typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
10413
10414/**
10415 * @typedef Evas_Object_Box_Data
10416 *
10417 * Smart object instance data, providing box object requirements.
10418 *
10419 * @ingroup Evas_Object_Box
10420 */
10421 typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
10422
10423/**
10424 * @typedef Evas_Object_Box_Option
10425 *
10426 * The base structure for a box option. Box options are a way of
10427 * extending box items properties, which will be taken into account
10428 * for layouting decisions. The box layouting functions provided by
10429 * Evas will only rely on objects' canonical size hints to layout
10430 * them, so the basic box option has @b no (custom) property set.
10431 *
10432 * Users creating their own layouts, but not depending on extra child
10433 * items' properties, would be fine just using
10434 * evas_object_box_layout_set(). But if one desires a layout depending
10435 * on extra child properties, he/she has to @b subclass the box smart
10436 * object. Thus, by using evas_object_box_smart_class_get() and
10437 * evas_object_box_smart_set(), the @c option_new() and @c
10438 * option_free() smart class functions should be properly
10439 * redefined/extended.
10440 *
10441 * Object properties are bound to an integer identifier and must have
10442 * a name string. Their values are open to any data. See the API on
10443 * option properties for more details.
10444 *
10445 * @ingroup Evas_Object_Box
10446 */
10447 typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
10448
10449/**
10450 * @typedef Evas_Object_Box_Layout
10451 *
10452 * Function signature for an Evas box object layouting routine. By
10453 * @a o it will be passed the box object in question, by @a priv it will
10454 * be passed the box's internal data and, by @a user_data, it will be
10455 * passed any custom data one could have set to a given box layouting
10456 * function, with evas_object_box_layout_set().
10457 *
10458 * @ingroup Evas_Object_Box
10459 */
10460 typedef void (*Evas_Object_Box_Layout) (Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
10461
10462/**
10463 * @def EVAS_OBJECT_BOX_API_VERSION
10464 *
10465 * Current version for Evas box object smart class, a value which goes
10466 * to _Evas_Object_Box_Api::version.
10467 *
10468 * @ingroup Evas_Object_Box
10469 */
10470#define EVAS_OBJECT_BOX_API_VERSION 1
10471
10472/**
10473 * @struct _Evas_Object_Box_Api
10474 *
10475 * This structure should be used by any smart class inheriting from
10476 * the box's one, to provide custom box behavior which could not be
10477 * achieved only by providing a layout function, with
10478 * evas_object_box_layout_set().
10479 *
10480 * @extends Evas_Smart_Class
10481 * @ingroup Evas_Object_Box
10482 */
10483 struct _Evas_Object_Box_Api
10484 {
10485 Evas_Smart_Class base; /**< Base smart class struct, need for all smart objects */
10486 int version; /**< Version of this smart class definition */
10487 Evas_Object_Box_Option *(*append) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child); /**< Smart function to append child elements in boxes */
10488 Evas_Object_Box_Option *(*prepend) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child); /**< Smart function to prepend child elements in boxes */
10489 Evas_Object_Box_Option *(*insert_before) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, const Evas_Object *reference); /**< Smart function to insert a child element before another in boxes */
10490 Evas_Object_Box_Option *(*insert_after) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, const Evas_Object *reference); /**< Smart function to insert a child element after another in boxes */
10491 Evas_Object_Box_Option *(*insert_at) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, unsigned int pos); /**< Smart function to insert a child element at a given position on boxes */
10492 Evas_Object *(*remove) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child); /**< Smart function to remove a child element from boxes */
10493 Evas_Object *(*remove_at) (Evas_Object *o, Evas_Object_Box_Data *priv, unsigned int pos); /**< Smart function to remove a child element from boxes, by its position */
10494 Eina_Bool (*property_set) (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args); /**< Smart function to set a custom property on a box child */
10495 Eina_Bool (*property_get) (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args); /**< Smart function to retrieve a custom property from a box child */
10496 const char *(*property_name_get)(Evas_Object *o, int property); /**< Smart function to get the name of a custom property of box children */
10497 int (*property_id_get) (Evas_Object *o, const char *name); /**< Smart function to get the numerical ID of a custom property of box children */
10498 Evas_Object_Box_Option *(*option_new) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child); /**< Smart function to create a new box option struct */
10499 void (*option_free) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt); /**< Smart function to delete a box option struct */
10500 };
10501
10502/**
10503 * @def EVAS_OBJECT_BOX_API_INIT
10504 *
10505 * Initializer for a whole #Evas_Object_Box_Api structure, with
10506 * @c NULL values on its specific fields.
10507 *
10508 * @param smart_class_init initializer to use for the "base" field
10509 * (#Evas_Smart_Class).
10510 *
10511 * @see EVAS_SMART_CLASS_INIT_NULL
10512 * @see EVAS_SMART_CLASS_INIT_VERSION
10513 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
10514 * @see EVAS_OBJECT_BOX_API_INIT_NULL
10515 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
10516 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
10517 * @ingroup Evas_Object_Box
10518 */
10519#define EVAS_OBJECT_BOX_API_INIT(smart_class_init) {smart_class_init, EVAS_OBJECT_BOX_API_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
10520
10521/**
10522 * @def EVAS_OBJECT_BOX_API_INIT_NULL
10523 *
10524 * Initializer to zero out a whole #Evas_Object_Box_Api structure.
10525 *
10526 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
10527 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
10528 * @see EVAS_OBJECT_BOX_API_INIT
10529 * @ingroup Evas_Object_Box
10530 */
10531#define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
10532
10533/**
10534 * @def EVAS_OBJECT_BOX_API_INIT_VERSION
10535 *
10536 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
10537 * set a specific version on it.
10538 *
10539 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will set
10540 * the version field of #Evas_Smart_Class (base field) to the latest
10541 * #EVAS_SMART_CLASS_VERSION.
10542 *
10543 * @see EVAS_OBJECT_BOX_API_INIT_NULL
10544 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
10545 * @see EVAS_OBJECT_BOX_API_INIT
10546 * @ingroup Evas_Object_Box
10547 */
10548#define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
10549
10550/**
10551 * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
10552 *
10553 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
10554 * set its name and version.
10555 *
10556 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will also
10557 * set the version field of #Evas_Smart_Class (base field) to the
10558 * latest #EVAS_SMART_CLASS_VERSION and name it to the specific value.
10559 *
10560 * It will keep a reference to the name field as a <c>"const char *"</c>,
10561 * i.e., the name must be available while the structure is
10562 * used (hint: static or global variable!) and must not be modified.
10563 *
10564 * @see EVAS_OBJECT_BOX_API_INIT_NULL
10565 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
10566 * @see EVAS_OBJECT_BOX_API_INIT
10567 * @ingroup Evas_Object_Box
10568 */
10569#define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
10570
10571/**
10572 * @struct _Evas_Object_Box_Data
10573 *
10574 * This structure augments clipped smart object's instance data,
10575 * providing extra members required by generic box implementation. If
10576 * a subclass inherits from #Evas_Object_Box_Api, then it may augment
10577 * #Evas_Object_Box_Data to fit its own needs.
10578 *
10579 * @extends Evas_Object_Smart_Clipped_Data
10580 * @ingroup Evas_Object_Box
10581 */
10582 struct _Evas_Object_Box_Data
10583 {
10584 Evas_Object_Smart_Clipped_Data base;
10585 const Evas_Object_Box_Api *api;
10586 struct {
10587 double h, v;
10588 } align;
10589 struct {
10590 Evas_Coord h, v;
10591 } pad;
10592 Eina_List *children;
10593 struct {
10594 Evas_Object_Box_Layout cb;
10595 void *data;
10596 void (*free_data)(void *data);
10597 } layout;
10598 Eina_Bool layouting : 1;
10599 Eina_Bool children_changed : 1;
10600 };
10601
10602 struct _Evas_Object_Box_Option
10603 {
10604 Evas_Object *obj; /**< Pointer to the box child object, itself */
10605 Eina_Bool max_reached:1;
10606 Eina_Bool min_reached:1;
10607 Evas_Coord alloc_size;
10608 }; /**< #Evas_Object_Box_Option struct fields */
10609
10610/**
10611 * Set the default box @a api struct (Evas_Object_Box_Api)
10612 * with the default values. May be used to extend that API.
10613 *
10614 * @param api The box API struct to set back, most probably with
10615 * overridden fields (on class extensions scenarios)
10616 */
10617EAPI void evas_object_box_smart_set (Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
10618
10619/**
10620 * Get the Evas box smart class, for inheritance purposes.
10621 *
10622 * @return the (canonical) Evas box smart class.
10623 *
10624 * The returned value is @b not to be modified, just use it as your
10625 * parent class.
10626 */
10627EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get (void) EINA_CONST;
10628
10629/**
10630 * Set a new layouting function to a given box object
10631 *
10632 * @param o The box object to operate on.
10633 * @param cb The new layout function to set on @p o.
10634 * @param data Data pointer to be passed to @p cb.
10635 * @param free_data Function to free @p data, if need be.
10636 *
10637 * A box layout function affects how a box object displays child
10638 * elements within its area. The list of pre-defined box layouts
10639 * available in Evas is:
10640 * - evas_object_box_layout_horizontal()
10641 * - evas_object_box_layout_vertical()
10642 * - evas_object_box_layout_homogeneous_horizontal()
10643 * - evas_object_box_layout_homogeneous_vertical()
10644 * - evas_object_box_layout_homogeneous_max_size_horizontal()
10645 * - evas_object_box_layout_homogeneous_max_size_vertical()
10646 * - evas_object_box_layout_flow_horizontal()
10647 * - evas_object_box_layout_flow_vertical()
10648 * - evas_object_box_layout_stack()
10649 *
10650 * Refer to each of their documentation texts for details on them.
10651 *
10652 * @note A box layouting function will be triggered by the @c
10653 * 'calculate' smart callback of the box's smart class.
10654 */
10655EAPI void evas_object_box_layout_set (Evas_Object *o, Evas_Object_Box_Layout cb, const void *data, void (*free_data)(void *data)) EINA_ARG_NONNULL(1, 2);
10656
10657/**
10658 * Add a new box object on the provided canvas.
10659 *
10660 * @param evas The canvas to create the box object on.
10661 * @return @c NULL on error, a pointer to a new box object on
10662 * success.
10663 *
10664 * After instantiation, if a box object hasn't its layout function
10665 * set, via evas_object_box_layout_set(), it will have it by default
10666 * set to evas_object_box_layout_horizontal(). The remaining
10667 * properties of the box must be set/retrieved via
10668 * <c>evas_object_box_{h,v}_{align,padding}_{get,set)()</c>.
10669 */
10670EAPI Evas_Object *evas_object_box_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
10671
10672/**
10673 * Add a new box as a @b child of a given smart object.
10674 *
10675 * @param parent The parent smart object to put the new box in.
10676 * @return @c NULL on error, a pointer to a new box object on
10677 * success.
10678 *
10679 * This is a helper function that has the same effect of putting a new
10680 * box object into @p parent by use of evas_object_smart_member_add().
10681 *
10682 * @see evas_object_box_add()
10683 */
10684EAPI Evas_Object *evas_object_box_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
10685
10686/**
10687 * Layout function which sets the box @a o to a (basic) horizontal box
10688 *
10689 * @param o The box object in question
10690 * @param priv The smart data of the @p o
10691 * @param data The data pointer passed on
10692 * evas_object_box_layout_set(), if any
10693 *
10694 * In this layout, the box object's overall behavior is controlled by
10695 * its padding/alignment properties, which are set by the
10696 * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
10697 * functions. The size hints of the elements in the box -- set by the
10698 * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
10699 * -- also control the way this function works.
10700 *
10701 * \par Box's properties:
10702 * @c align_h controls the horizontal alignment of the child objects
10703 * relative to the containing box. When set to @c 0.0, children are
10704 * aligned to the left. A value of @c 1.0 makes them aligned to the
10705 * right border. Values in between align them proportionally. Note
10706 * that if the size required by the children, which is given by their
10707 * widths and the @c padding_h property of the box, is bigger than the
10708 * their container's width, the children will be displayed out of the
10709 * box's bounds. A negative value of @c align_h makes the box to
10710 * @b justify its children. The padding between them, in this case, is
10711 * corrected so that the leftmost one touches the left border and the
10712 * rightmost one touches the right border (even if they must
10713 * overlap). The @c align_v and @c padding_v properties of the box
10714 * @b don't contribute to its behaviour when this layout is chosen.
10715 *
10716 * \par Child element's properties:
10717 * @c align_x does @b not influence the box's behavior. @c padding_l
10718 * and @c padding_r sum up to the container's horizontal padding
10719 * between elements. The child's @c padding_t, @c padding_b and
10720 * @c align_y properties apply for padding/alignment relative to the
10721 * overall height of the box. Finally, there is the @c weight_x
10722 * property, which, if set to a non-zero value, tells the container
10723 * that the child width is @b not pre-defined. If the container can't
10724 * accommodate all its children, it sets the widths of the ones
10725 * <b>with weights</b> to sizes as small as they can all fit into
10726 * it. If the size required by the children is less than the
10727 * available, the box increases its childrens' (which have weights)
10728 * widths as to fit the remaining space. The @c weight_x property,
10729 * besides telling the element is resizable, gives a @b weight for the
10730 * resizing process. The parent box will try to distribute (or take
10731 * off) widths accordingly to the @b normalized list of weigths: most
10732 * weighted children remain/get larger in this process than the least
10733 * ones. @c weight_y does not influence the layout.
10734 *
10735 * If one desires that, besides having weights, child elements must be
10736 * resized bounded to a minimum or maximum size, those size hints must
10737 * be set, by the <c>evas_object_size_hint_{min,max}_set()</c>
10738 * functions.
10739 */
10740EAPI void evas_object_box_layout_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10741
10742/**
10743 * Layout function which sets the box @a o to a (basic) vertical box
10744 *
10745 * This function behaves analogously to
10746 * evas_object_box_layout_horizontal(). The description of its
10747 * behaviour can be derived from that function's documentation.
10748 */
10749EAPI void evas_object_box_layout_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10750
10751/**
10752 * Layout function which sets the box @a o to a @b homogeneous
10753 * vertical box
10754 *
10755 * This function behaves analogously to
10756 * evas_object_box_layout_homogeneous_horizontal(). The description
10757 * of its behaviour can be derived from that function's documentation.
10758 */
10759EAPI void evas_object_box_layout_homogeneous_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10760
10761/**
10762 * Layout function which sets the box @a o to a @b homogeneous
10763 * horizontal box
10764 *
10765 * @param o The box object in question
10766 * @param priv The smart data of the @p o
10767 * @param data The data pointer passed on
10768 * evas_object_box_layout_set(), if any
10769 *
10770 * In a homogeneous horizontal box, its width is divided @b equally
10771 * between the contained objects. The box's overall behavior is
10772 * controlled by its padding/alignment properties, which are set by
10773 * the <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
10774 * functions. The size hints the elements in the box -- set by the
10775 * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
10776 * -- also control the way this function works.
10777 *
10778 * \par Box's properties:
10779 * @c align_h has no influence on the box for this layout.
10780 * @c padding_h tells the box to draw empty spaces of that size, in
10781 * pixels, between the (equal) child objects's cells. The @c align_v
10782 * and @c padding_v properties of the box don't contribute to its
10783 * behaviour when this layout is chosen.
10784 *
10785 * \par Child element's properties:
10786 * @c padding_l and @c padding_r sum up to the required width of the
10787 * child element. The @c align_x property tells the relative position
10788 * of this overall child width in its allocated cell (@r 0.0 to
10789 * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to
10790 * @c align_x makes the box try to resize this child element to the exact
10791 * width of its cell (respecting the minimum and maximum size hints on
10792 * the child's width and accounting for its horizontal padding
10793 * hints). The child's @c padding_t, @c padding_b and @c align_y
10794 * properties apply for padding/alignment relative to the overall
10795 * height of the box. A value of @c -1.0 to @c align_y makes the box
10796 * try to resize this child element to the exact height of its parent
10797 * (respecting the maximum size hint on the child's height).
10798 */
10799EAPI void evas_object_box_layout_homogeneous_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10800
10801/**
10802 * Layout function which sets the box @a o to a <b>maximum size,
10803 * homogeneous</b> horizontal box
10804 *
10805 * @param o The box object in question
10806 * @param priv The smart data of the @p o
10807 * @param data The data pointer passed on
10808 * evas_object_box_layout_set(), if any
10809 *
10810 * In a maximum size, homogeneous horizontal box, besides having cells
10811 * of <b>equal size</b> reserved for the child objects, this size will
10812 * be defined by the size of the @b largest child in the box (in
10813 * width). The box's overall behavior is controlled by its properties,
10814 * which are set by the
10815 * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
10816 * functions. The size hints of the elements in the box -- set by the
10817 * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
10818 * -- also control the way this function works.
10819 *
10820 * \par Box's properties:
10821 * @c padding_h tells the box to draw empty spaces of that size, in
10822 * pixels, between the child objects's cells. @c align_h controls the
10823 * horizontal alignment of the child objects, relative to the
10824 * containing box. When set to @c 0.0, children are aligned to the
10825 * left. A value of @c 1.0 lets them aligned to the right
10826 * border. Values in between align them proportionally. A negative
10827 * value of @c align_h makes the box to @b justify its children
10828 * cells. The padding between them, in this case, is corrected so that
10829 * the leftmost one touches the left border and the rightmost one
10830 * touches the right border (even if they must overlap). The
10831 * @c align_v and @c padding_v properties of the box don't contribute to
10832 * its behaviour when this layout is chosen.
10833 *
10834 * \par Child element's properties:
10835 * @c padding_l and @c padding_r sum up to the required width of the
10836 * child element. The @c align_x property tells the relative position
10837 * of this overall child width in its allocated cell (@c 0.0 to
10838 * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to
10839 * @c align_x makes the box try to resize this child element to the exact
10840 * width of its cell (respecting the minimum and maximum size hints on
10841 * the child's width and accounting for its horizontal padding
10842 * hints). The child's @c padding_t, @c padding_b and @c align_y
10843 * properties apply for padding/alignment relative to the overall
10844 * height of the box. A value of @c -1.0 to @c align_y makes the box
10845 * try to resize this child element to the exact height of its parent
10846 * (respecting the max hint on the child's height).
10847 */
10848EAPI void evas_object_box_layout_homogeneous_max_size_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10849
10850/**
10851 * Layout function which sets the box @a o to a <b>maximum size,
10852 * homogeneous</b> vertical box
10853 *
10854 * This function behaves analogously to
10855 * evas_object_box_layout_homogeneous_max_size_horizontal(). The
10856 * description of its behaviour can be derived from that function's
10857 * documentation.
10858 */
10859EAPI void evas_object_box_layout_homogeneous_max_size_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10860
10861/**
10862 * Layout function which sets the box @a o to a @b flow horizontal
10863 * box.
10864 *
10865 * @param o The box object in question
10866 * @param priv The smart data of the @p o
10867 * @param data The data pointer passed on
10868 * evas_object_box_layout_set(), if any
10869 *
10870 * In a flow horizontal box, the box's child elements are placed in
10871 * @b rows (think of text as an analogy). A row has as much elements as
10872 * can fit into the box's width. The box's overall behavior is
10873 * controlled by its properties, which are set by the
10874 * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
10875 * functions. The size hints of the elements in the box -- set by the
10876 * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
10877 * -- also control the way this function works.
10878 *
10879 * \par Box's properties:
10880 * @c padding_h tells the box to draw empty spaces of that size, in
10881 * pixels, between the child objects's cells. @c align_h dictates the
10882 * horizontal alignment of the rows (@c 0.0 to left align them, @c 1.0
10883 * to right align). A value of @c -1.0 to @c align_h lets the rows
10884 * @b justified horizontally. @c align_v controls the vertical alignment
10885 * of the entire set of rows (@c 0.0 to top, @c 1.0 to bottom). A
10886 * value of @c -1.0 to @c align_v makes the box to @b justify the rows
10887 * vertically. The padding between them, in this case, is corrected so
10888 * that the first row touches the top border and the last one touches
10889 * the bottom border (even if they must overlap). @c padding_v has no
10890 * influence on the layout.
10891 *
10892 * \par Child element's properties:
10893 * @c padding_l and @c padding_r sum up to the required width of the
10894 * child element. The @c align_x property has no influence on the
10895 * layout. The child's @c padding_t and @c padding_b sum up to the
10896 * required height of the child element and is the only means (besides
10897 * row justifying) of setting space between rows. Note, however, that
10898 * @c align_y dictates positioning relative to the <b>largest
10899 * height</b> required by a child object in the actual row.
10900 */
10901EAPI void evas_object_box_layout_flow_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10902
10903/**
10904 * Layout function which sets the box @a o to a @b flow vertical box.
10905 *
10906 * This function behaves analogously to
10907 * evas_object_box_layout_flow_horizontal(). The description of its
10908 * behaviour can be derived from that function's documentation.
10909 */
10910EAPI void evas_object_box_layout_flow_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10911
10912/**
10913 * Layout function which sets the box @a o to a @b stacking box
10914 *
10915 * @param o The box object in question
10916 * @param priv The smart data of the @p o
10917 * @param data The data pointer passed on
10918 * evas_object_box_layout_set(), if any
10919 *
10920 * In a stacking box, all children will be given the same size -- the
10921 * box's own size -- and they will be stacked one above the other, so
10922 * that the first object in @p o's internal list of child elements
10923 * will be the bottommost in the stack.
10924 *
10925 * \par Box's properties:
10926 * No box properties are used.
10927 *
10928 * \par Child element's properties:
10929 * @c padding_l and @c padding_r sum up to the required width of the
10930 * child element. The @c align_x property tells the relative position
10931 * of this overall child width in its allocated cell (@c 0.0 to
10932 * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to @c
10933 * align_x makes the box try to resize this child element to the exact
10934 * width of its cell (respecting the min and max hints on the child's
10935 * width and accounting for its horizontal padding properties). The
10936 * same applies to the vertical axis.
10937 */
10938EAPI void evas_object_box_layout_stack (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10939
10940/**
10941 * Set the alignment of the whole bounding box of contents, for a
10942 * given box object.
10943 *
10944 * @param o The given box object to set alignment from
10945 * @param horizontal The horizontal alignment, in pixels
10946 * @param vertical the vertical alignment, in pixels
10947 *
10948 * This will influence how a box object is to align its bounding box
10949 * of contents within its own area. The values @b must be in the range
10950 * @c 0.0 - @c 1.0, or undefined behavior is expected. For horizontal
10951 * alignment, @c 0.0 means to the left, with @c 1.0 meaning to the
10952 * right. For vertical alignment, @c 0.0 means to the top, with @c 1.0
10953 * meaning to the bottom.
10954 *
10955 * @note The default values for both alignments is @c 0.5.
10956 *
10957 * @see evas_object_box_align_get()
10958 */
10959EAPI void evas_object_box_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
10960
10961/**
10962 * Get the alignment of the whole bounding box of contents, for a
10963 * given box object.
10964 *
10965 * @param o The given box object to get alignment from
10966 * @param horizontal Pointer to a variable where to store the
10967 * horizontal alignment
10968 * @param vertical Pointer to a variable where to store the vertical
10969 * alignment
10970 *
10971 * @see evas_object_box_align_set() for more information
10972 */
10973EAPI void evas_object_box_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
10974
10975/**
10976 * Set the (space) padding between cells set for a given box object.
10977 *
10978 * @param o The given box object to set padding from
10979 * @param horizontal The horizontal padding, in pixels
10980 * @param vertical the vertical padding, in pixels
10981 *
10982 * @note The default values for both padding components is @c 0.
10983 *
10984 * @see evas_object_box_padding_get()
10985 */
10986EAPI void evas_object_box_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
10987
10988/**
10989 * Get the (space) padding between cells set for a given box object.
10990 *
10991 * @param o The given box object to get padding from
10992 * @param horizontal Pointer to a variable where to store the
10993 * horizontal padding
10994 * @param vertical Pointer to a variable where to store the vertical
10995 * padding
10996 *
10997 * @see evas_object_box_padding_set()
10998 */
10999EAPI void evas_object_box_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
11000
11001/**
11002 * Append a new @a child object to the given box object @a o.
11003 *
11004 * @param o The given box object
11005 * @param child A child Evas object to be made a member of @p o
11006 * @return A box option bound to the recently added box item or @c
11007 * NULL, on errors
11008 *
11009 * On success, the @c "child,added" smart event will take place.
11010 *
11011 * @note The actual placing of the item relative to @p o's area will
11012 * depend on the layout set to it. For example, on horizontal layouts
11013 * an item in the end of the box's list of children will appear on its
11014 * right.
11015 *
11016 * @note This call will trigger the box's _Evas_Object_Box_Api::append
11017 * smart function.
11018 */
11019EAPI Evas_Object_Box_Option *evas_object_box_append (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
11020
11021/**
11022 * Prepend a new @a child object to the given box object @a o.
11023 *
11024 * @param o The given box object
11025 * @param child A child Evas object to be made a member of @p o
11026 * @return A box option bound to the recently added box item or @c
11027 * NULL, on errors
11028 *
11029 * On success, the @c "child,added" smart event will take place.
11030 *
11031 * @note The actual placing of the item relative to @p o's area will
11032 * depend on the layout set to it. For example, on horizontal layouts
11033 * an item in the beginning of the box's list of children will appear
11034 * on its left.
11035 *
11036 * @note This call will trigger the box's
11037 * _Evas_Object_Box_Api::prepend smart function.
11038 */
11039EAPI Evas_Object_Box_Option *evas_object_box_prepend (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
11040
11041/**
11042 * Insert a new @a child object <b>before another existing one</b>, in
11043 * a given box object @a o.
11044 *
11045 * @param o The given box object
11046 * @param child A child Evas object to be made a member of @p o
11047 * @param reference The child object to place this new one before
11048 * @return A box option bound to the recently added box item or @c
11049 * NULL, on errors
11050 *
11051 * On success, the @c "child,added" smart event will take place.
11052 *
11053 * @note This function will fail if @p reference is not a member of @p
11054 * o.
11055 *
11056 * @note The actual placing of the item relative to @p o's area will
11057 * depend on the layout set to it.
11058 *
11059 * @note This call will trigger the box's
11060 * _Evas_Object_Box_Api::insert_before smart function.
11061 */
11062EAPI Evas_Object_Box_Option *evas_object_box_insert_before (Evas_Object *o, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1, 2, 3);
11063
11064/**
11065 * Insert a new @a child object <b>after another existing one</b>, in
11066 * a given box object @a o.
11067 *
11068 * @param o The given box object
11069 * @param child A child Evas object to be made a member of @p o
11070 * @param reference The child object to place this new one after
11071 * @return A box option bound to the recently added box item or @c
11072 * NULL, on errors
11073 *
11074 * On success, the @c "child,added" smart event will take place.
11075 *
11076 * @note This function will fail if @p reference is not a member of @p
11077 * o.
11078 *
11079 * @note The actual placing of the item relative to @p o's area will
11080 * depend on the layout set to it.
11081 *
11082 * @note This call will trigger the box's
11083 * _Evas_Object_Box_Api::insert_after smart function.
11084 */
11085EAPI Evas_Object_Box_Option *evas_object_box_insert_after (Evas_Object *o, Evas_Object *child, const Evas_Object *referente) EINA_ARG_NONNULL(1, 2, 3);
11086
11087/**
11088 * Insert a new @a child object <b>at a given position</b>, in a given
11089 * box object @a o.
11090 *
11091 * @param o The given box object
11092 * @param child A child Evas object to be made a member of @p o
11093 * @param pos The numeric position (starting from @c 0) to place the
11094 * new child object at
11095 * @return A box option bound to the recently added box item or @c
11096 * NULL, on errors
11097 *
11098 * On success, the @c "child,added" smart event will take place.
11099 *
11100 * @note This function will fail if the given position is invalid,
11101 * given @p o's internal list of elements.
11102 *
11103 * @note The actual placing of the item relative to @p o's area will
11104 * depend on the layout set to it.
11105 *
11106 * @note This call will trigger the box's
11107 * _Evas_Object_Box_Api::insert_at smart function.
11108 */
11109EAPI Evas_Object_Box_Option *evas_object_box_insert_at (Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2);
11110
11111/**
11112 * Remove a given object from a box object, unparenting it again.
11113 *
11114 * @param o The box object to remove a child object from
11115 * @param child The handle to the child object to be removed
11116 * @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
11117 *
11118 * On removal, you'll get an unparented object again, just as it was
11119 * before you inserted it in the box. The
11120 * _Evas_Object_Box_Api::option_free box smart callback will be called
11121 * automatically for you and, also, the @c "child,removed" smart event
11122 * will take place.
11123 *
11124 * @note This call will trigger the box's _Evas_Object_Box_Api::remove
11125 * smart function.
11126 */
11127EAPI Eina_Bool evas_object_box_remove (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
11128
11129/**
11130 * Remove an object, <b>bound to a given position</b> in a box object,
11131 * unparenting it again.
11132 *
11133 * @param o The box object to remove a child object from
11134 * @param in The numeric position (starting from @c 0) of the child
11135 * object to be removed
11136 * @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
11137 *
11138 * On removal, you'll get an unparented object again, just as it was
11139 * before you inserted it in the box. The @c option_free() box smart
11140 * callback will be called automatically for you and, also, the
11141 * @c "child,removed" smart event will take place.
11142 *
11143 * @note This function will fail if the given position is invalid,
11144 * given @p o's internal list of elements.
11145 *
11146 * @note This call will trigger the box's
11147 * _Evas_Object_Box_Api::remove_at smart function.
11148 */
11149EAPI Eina_Bool evas_object_box_remove_at (Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1);
11150
11151/**
11152 * Remove @b all child objects from a box object, unparenting them
11153 * again.
11154 *
11155 * @param o The box object to remove a child object from
11156 * @param child The handle to the child object to be removed
11157 * @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
11158 *
11159 * This has the same effect of calling evas_object_box_remove() on
11160 * each of @p o's child objects, in sequence. If, and only if, all
11161 * those calls succeed, so does this one.
11162 */
11163EAPI Eina_Bool evas_object_box_remove_all (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
11164
11165/**
11166 * Get an iterator to walk the list of children of a given box object.
11167 *
11168 * @param o The box to retrieve an items iterator from
11169 * @return An iterator on @p o's child objects, on success, or @c NULL,
11170 * on errors
11171 *
11172 * @note Do @b not remove or delete objects while walking the list.
11173 */
11174EAPI Eina_Iterator *evas_object_box_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11175
11176/**
11177 * Get an accessor (a structure providing random items access) to the
11178 * list of children of a given box object.
11179 *
11180 * @param o The box to retrieve an items iterator from
11181 * @return An accessor on @p o's child objects, on success, or @c NULL,
11182 * on errors
11183 *
11184 * @note Do not remove or delete objects while walking the list.
11185 */
11186EAPI Eina_Accessor *evas_object_box_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11187
11188/**
11189 * Get the list of children objects in a given box object.
11190 *
11191 * @param o The box to retrieve an items list from
11192 * @return A list of @p o's child objects, on success, or @c NULL,
11193 * on errors (or if it has no child objects)
11194 *
11195 * The returned list should be freed with @c eina_list_free() when you
11196 * no longer need it.
11197 *
11198 * @note This is a duplicate of the list kept by the box internally.
11199 * It's up to the user to destroy it when it no longer needs it.
11200 * It's possible to remove objects from the box when walking
11201 * this list, but these removals won't be reflected on it.
11202 */
11203EAPI Eina_List *evas_object_box_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11204
11205/**
11206 * Get the name of the property of the child elements of the box @a o
11207 * which have @a id as identifier
11208 *
11209 * @param o The box to search child options from
11210 * @param id The numerical identifier of the option being searched, for
11211 * its name
11212 * @return The name of the given property or @c NULL, on errors.
11213 *
11214 * @note This call won't do anything for a canonical Evas box. Only
11215 * users which have @b subclassed it, setting custom box items options
11216 * (see #Evas_Object_Box_Option) on it, would benefit from this
11217 * function. They'd have to implement it and set it to be the
11218 * _Evas_Object_Box_Api::property_name_get smart class function of the
11219 * box, which is originally set to @c NULL.
11220 */
11221EAPI const char *evas_object_box_option_property_name_get (Evas_Object *o, int property) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
11222
11223/**
11224 * Get the numerical identifier of the property of the child elements
11225 * of the box @a o which have @a name as name string
11226 *
11227 * @param o The box to search child options from
11228 * @param name The name string of the option being searched, for
11229 * its ID
11230 * @return The numerical ID of the given property or @c -1, on
11231 * errors.
11232 *
11233 * @note This call won't do anything for a canonical Evas box. Only
11234 * users which have @b subclassed it, setting custom box items options
11235 * (see #Evas_Object_Box_Option) on it, would benefit from this
11236 * function. They'd have to implement it and set it to be the
11237 * _Evas_Object_Box_Api::property_id_get smart class function of the
11238 * box, which is originally set to @c NULL.
11239 */
11240EAPI int evas_object_box_option_property_id_get (Evas_Object *o, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
11241
11242/**
11243 * Set a property value (by its given numerical identifier), on a
11244 * given box child element
11245 *
11246 * @param o The box parenting the child element
11247 * @param opt The box option structure bound to the child box element
11248 * to set a property on
11249 * @param id The numerical ID of the given property
11250 * @param ... (List of) actual value(s) to be set for this
11251 * property. It (they) @b must be of the same type the user has
11252 * defined for it (them).
11253 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
11254 *
11255 * @note This call won't do anything for a canonical Evas box. Only
11256 * users which have @b subclassed it, setting custom box items options
11257 * (see #Evas_Object_Box_Option) on it, would benefit from this
11258 * function. They'd have to implement it and set it to be the
11259 * _Evas_Object_Box_Api::property_set smart class function of the box,
11260 * which is originally set to @c NULL.
11261 *
11262 * @note This function will internally create a variable argument
11263 * list, with the values passed after @p property, and call
11264 * evas_object_box_option_property_vset() with this list and the same
11265 * previous arguments.
11266 */
11267EAPI Eina_Bool evas_object_box_option_property_set (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
11268
11269/**
11270 * Set a property value (by its given numerical identifier), on a
11271 * given box child element -- by a variable argument list
11272 *
11273 * @param o The box parenting the child element
11274 * @param opt The box option structure bound to the child box element
11275 * to set a property on
11276 * @param id The numerical ID of the given property
11277 * @param va_list The variable argument list implementing the value to
11278 * be set for this property. It @b must be of the same type the user has
11279 * defined for it.
11280 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
11281 *
11282 * This is a variable argument list variant of the
11283 * evas_object_box_option_property_set(). See its documentation for
11284 * more details.
11285 */
11286EAPI Eina_Bool evas_object_box_option_property_vset (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) EINA_ARG_NONNULL(1, 2);
11287
11288/**
11289 * Get a property's value (by its given numerical identifier), on a
11290 * given box child element
11291 *
11292 * @param o The box parenting the child element
11293 * @param opt The box option structure bound to the child box element
11294 * to get a property from
11295 * @param id The numerical ID of the given property
11296 * @param ... (List of) pointer(s) where to store the value(s) set for
11297 * this property. It (they) @b must point to variable(s) of the same
11298 * type the user has defined for it (them).
11299 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
11300 *
11301 * @note This call won't do anything for a canonical Evas box. Only
11302 * users which have @b subclassed it, getting custom box items options
11303 * (see #Evas_Object_Box_Option) on it, would benefit from this
11304 * function. They'd have to implement it and get it to be the
11305 * _Evas_Object_Box_Api::property_get smart class function of the
11306 * box, which is originally get to @c NULL.
11307 *
11308 * @note This function will internally create a variable argument
11309 * list, with the values passed after @p property, and call
11310 * evas_object_box_option_property_vget() with this list and the same
11311 * previous arguments.
11312 */
11313EAPI Eina_Bool evas_object_box_option_property_get (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
11314
11315/**
11316 * Get a property's value (by its given numerical identifier), on a
11317 * given box child element -- by a variable argument list
11318 *
11319 * @param o The box parenting the child element
11320 * @param opt The box option structure bound to the child box element
11321 * to get a property from
11322 * @param id The numerical ID of the given property
11323 * @param va_list The variable argument list with pointers to where to
11324 * store the values of this property. They @b must point to variables
11325 * of the same type the user has defined for them.
11326 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
11327 *
11328 * This is a variable argument list variant of the
11329 * evas_object_box_option_property_get(). See its documentation for
11330 * more details.
11331 */
11332EAPI Eina_Bool evas_object_box_option_property_vget (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) EINA_ARG_NONNULL(1, 2);
11333
11334/**
11335 * @}
11336 */
11337
11338/**
11339 * @defgroup Evas_Object_Table Table Smart Object.
11340 *
11341 * Convenience smart object that packs children using a tabular
11342 * layout using children size hints to define their size and
11343 * alignment inside their cell space.
11344 *
11345 * @ref tutorial_table shows how to use this Evas_Object.
11346 *
11347 * @see @ref Evas_Object_Group_Size_Hints
11348 *
11349 * @ingroup Evas_Smart_Object_Group
11350 *
11351 * @{
11352 */
11353
11354/**
11355 * @brief Create a new table.
11356 *
11357 * @param evas Canvas in which table will be added.
11358 */
11359EAPI Evas_Object *evas_object_table_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11360
11361/**
11362 * @brief Create a table that is child of a given element @a parent.
11363 *
11364 * @see evas_object_table_add()
11365 */
11366EAPI Evas_Object *evas_object_table_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11367
11368/**
11369 * @brief Set how this table should layout children.
11370 *
11371 * @todo consider aspect hint and respect it.
11372 *
11373 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE
11374 * If table does not use homogeneous mode then columns and rows will
11375 * be calculated based on hints of individual cells. This operation
11376 * mode is more flexible, but more complex and heavy to calculate as
11377 * well. @b Weight properties are handled as a boolean expand. Negative
11378 * alignment will be considered as 0.5. This is the default.
11379 *
11380 * @todo @c EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE should balance weight.
11381 *
11382 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE
11383 * When homogeneous is relative to table the own table size is divided
11384 * equally among children, filling the whole table area. That is, if
11385 * table has @c WIDTH and @c COLUMNS, each cell will get <tt>WIDTH /
11386 * COLUMNS</tt> pixels. If children have minimum size that is larger
11387 * than this amount (including padding), then it will overflow and be
11388 * aligned respecting the alignment hint, possible overlapping sibling
11389 * cells. @b Weight hint is used as a boolean, if greater than zero it
11390 * will make the child expand in that axis, taking as much space as
11391 * possible (bounded to maximum size hint). Negative alignment will be
11392 * considered as 0.5.
11393 *
11394 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM
11395 * When homogeneous is relative to item it means the greatest minimum
11396 * cell size will be used. That is, if no element is set to expand,
11397 * the table will have its contents to a minimum size, the bounding
11398 * box of all these children will be aligned relatively to the table
11399 * object using evas_object_table_align_get(). If the table area is
11400 * too small to hold this minimum bounding box, then the objects will
11401 * keep their size and the bounding box will overflow the box area,
11402 * still respecting the alignment. @b Weight hint is used as a
11403 * boolean, if greater than zero it will make that cell expand in that
11404 * axis, toggling the <b>expand mode</b>, which makes the table behave
11405 * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the
11406 * bounding box will overflow and items will not overlap siblings. If
11407 * no minimum size is provided at all then the table will fallback to
11408 * expand mode as well.
11409 */
11410EAPI void evas_object_table_homogeneous_set (Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1);
11411
11412/**
11413 * Get the current layout homogeneous mode.
11414 *
11415 * @see evas_object_table_homogeneous_set()
11416 */
11417EAPI Evas_Object_Table_Homogeneous_Mode evas_object_table_homogeneous_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
11418
11419/**
11420 * Set padding between cells.
11421 */
11422EAPI void evas_object_table_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
11423
11424/**
11425 * Get padding between cells.
11426 */
11427EAPI void evas_object_table_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
11428
11429/**
11430 * Set the alignment of the whole bounding box of contents.
11431 */
11432EAPI void evas_object_table_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
11433
11434/**
11435 * Get alignment of the whole bounding box of contents.
11436 */
11437EAPI void evas_object_table_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
11438
11439/**
11440 * Sets the mirrored mode of the table. In mirrored mode the table items go
11441 * from right to left instead of left to right. That is, 1,1 is top right, not
11442 * top left.
11443 *
11444 * @param obj The table object.
11445 * @param mirrored the mirrored mode to set
11446 * @since 1.1.0
11447 */
11448EAPI void evas_object_table_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
11449
11450/**
11451 * Gets the mirrored mode of the table.
11452 *
11453 * @param obj The table object.
11454 * @return EINA_TRUE if it's a mirrored table, EINA_FALSE otherwise.
11455 * @since 1.1.0
11456 * @see evas_object_table_mirrored_set()
11457 */
11458EAPI Eina_Bool evas_object_table_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
11459
11460/**
11461 * Get packing location of a child of table
11462 *
11463 * @param o The given table object.
11464 * @param child The child object to add.
11465 * @param col pointer to store relative-horizontal position to place child.
11466 * @param row pointer to store relative-vertical position to place child.
11467 * @param colspan pointer to store how many relative-horizontal position to use for this child.
11468 * @param rowspan pointer to store how many relative-vertical position to use for this child.
11469 *
11470 * @return 1 on success, 0 on failure.
11471 * @since 1.1.0
11472 */
11473EAPI Eina_Bool evas_object_table_pack_get(Evas_Object *o, Evas_Object *child, unsigned short *col, unsigned short *row, unsigned short *colspan, unsigned short *rowspan);
11474
11475/**
11476 * Add a new child to a table object or set its current packing.
11477 *
11478 * @param o The given table object.
11479 * @param child The child object to add.
11480 * @param col relative-horizontal position to place child.
11481 * @param row relative-vertical position to place child.
11482 * @param colspan how many relative-horizontal position to use for this child.
11483 * @param rowspan how many relative-vertical position to use for this child.
11484 *
11485 * @return 1 on success, 0 on failure.
11486 */
11487EAPI Eina_Bool evas_object_table_pack (Evas_Object *o, Evas_Object *child, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan) EINA_ARG_NONNULL(1, 2);
11488
11489/**
11490 * Remove child from table.
11491 *
11492 * @note removing a child will immediately call a walk over children in order
11493 * to recalculate numbers of columns and rows. If you plan to remove
11494 * all children, use evas_object_table_clear() instead.
11495 *
11496 * @return 1 on success, 0 on failure.
11497 */
11498EAPI Eina_Bool evas_object_table_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
11499
11500/**
11501 * Faster way to remove all child objects from a table object.
11502 *
11503 * @param o The given table object.
11504 * @param clear if true, it will delete just removed children.
11505 */
11506EAPI void evas_object_table_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
11507
11508/**
11509 * Get the number of columns and rows this table takes.
11510 *
11511 * @note columns and rows are virtual entities, one can specify a table
11512 * with a single object that takes 4 columns and 5 rows. The only
11513 * difference for a single cell table is that paddings will be
11514 * accounted proportionally.
11515 */
11516EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1);
11517
11518/**
11519 * Get an iterator to walk the list of children for the table.
11520 *
11521 * @note Do not remove or delete objects while walking the list.
11522 */
11523EAPI Eina_Iterator *evas_object_table_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11524
11525/**
11526 * Get an accessor to get random access to the list of children for the table.
11527 *
11528 * @note Do not remove or delete objects while walking the list.
11529 */
11530EAPI Eina_Accessor *evas_object_table_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11531
11532/**
11533 * Get the list of children for the table.
11534 *
11535 * @note This is a duplicate of the list kept by the table internally.
11536 * It's up to the user to destroy it when it no longer needs it.
11537 * It's possible to remove objects from the table when walking this
11538 * list, but these removals won't be reflected on it.
11539 */
11540EAPI Eina_List *evas_object_table_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11541
11542/**
11543 * Get the child of the table at the given coordinates
11544 *
11545 * @note This does not take into account col/row spanning
11546 */
11547EAPI Evas_Object *evas_object_table_child_get (const Evas_Object *o, unsigned short col, unsigned short row) EINA_ARG_NONNULL(1);
11548/**
11549 * @}
11550 */
11551
11552/**
11553 * @defgroup Evas_Object_Grid Grid Smart Object.
11554 *
11555 * Convenience smart object that packs children under a regular grid
11556 * layout, using their virtual grid location and size to determine
11557 * children's positions inside the grid object's area.
11558 *
11559 * @ingroup Evas_Smart_Object_Group
11560 * @since 1.1.0
11561 */
11562
11563/**
11564 * @addtogroup Evas_Object_Grid
11565 * @{
11566 */
11567
11568/**
11569 * Create a new grid.
11570 *
11571 * It's set to a virtual size of 1x1 by default and add children with
11572 * evas_object_grid_pack().
11573 * @since 1.1.0
11574 */
11575EAPI Evas_Object *evas_object_grid_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11576
11577/**
11578 * Create a grid that is child of a given element @a parent.
11579 *
11580 * @see evas_object_grid_add()
11581 * @since 1.1.0
11582 */
11583EAPI Evas_Object *evas_object_grid_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11584
11585/**
11586 * Set the virtual resolution for the grid
11587 *
11588 * @param o The grid object to modify
11589 * @param w The virtual horizontal size (resolution) in integer units
11590 * @param h The virtual vertical size (resolution) in integer units
11591 * @since 1.1.0
11592 */
11593EAPI void evas_object_grid_size_set (Evas_Object *o, int w, int h) EINA_ARG_NONNULL(1);
11594
11595/**
11596 * Get the current virtual resolution
11597 *
11598 * @param o The grid object to query
11599 * @param w A pointer to an integer to store the virtual width
11600 * @param h A pointer to an integer to store the virtual height
11601 * @see evas_object_grid_size_set()
11602 * @since 1.1.0
11603 */
11604EAPI void evas_object_grid_size_get (const Evas_Object *o, int *w, int *h) EINA_ARG_NONNULL(1);
11605
11606/**
11607 * Sets the mirrored mode of the grid. In mirrored mode the grid items go
11608 * from right to left instead of left to right. That is, 0,0 is top right, not
11609 * to left.
11610 *
11611 * @param obj The grid object.
11612 * @param mirrored the mirrored mode to set
11613 * @since 1.1.0
11614 */
11615EAPI void evas_object_grid_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
11616
11617/**
11618 * Gets the mirrored mode of the grid.
11619 *
11620 * @param obj The grid object.
11621 * @return EINA_TRUE if it's a mirrored grid, EINA_FALSE otherwise.
11622 * @see evas_object_grid_mirrored_set()
11623 * @since 1.1.0
11624 */
11625EAPI Eina_Bool evas_object_grid_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
11626
11627/**
11628 * Add a new child to a grid object.
11629 *
11630 * @param o The given grid object.
11631 * @param child The child object to add.
11632 * @param x The virtual x coordinate of the child
11633 * @param y The virtual y coordinate of the child
11634 * @param w The virtual width of the child
11635 * @param h The virtual height of the child
11636 * @return 1 on success, 0 on failure.
11637 * @since 1.1.0
11638 */
11639EAPI Eina_Bool evas_object_grid_pack (Evas_Object *o, Evas_Object *child, int x, int y, int w, int h) EINA_ARG_NONNULL(1, 2);
11640
11641/**
11642 * Remove child from grid.
11643 *
11644 * @note removing a child will immediately call a walk over children in order
11645 * to recalculate numbers of columns and rows. If you plan to remove
11646 * all children, use evas_object_grid_clear() instead.
11647 *
11648 * @return 1 on success, 0 on failure.
11649 * @since 1.1.0
11650 */
11651EAPI Eina_Bool evas_object_grid_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
11652
11653/**
11654 * Faster way to remove all child objects from a grid object.
11655 *
11656 * @param o The given grid object.
11657 * @param clear if true, it will delete just removed children.
11658 * @since 1.1.0
11659 */
11660EAPI void evas_object_grid_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
11661
11662/**
11663 * Get the pack options for a grid child
11664 *
11665 * Get the pack x, y, width and height in virtual coordinates set by
11666 * evas_object_grid_pack()
11667 * @param o The grid object
11668 * @param child The grid child to query for coordinates
11669 * @param x The pointer to where the x coordinate will be returned
11670 * @param y The pointer to where the y coordinate will be returned
11671 * @param w The pointer to where the width will be returned
11672 * @param h The pointer to where the height will be returned
11673 * @return 1 on success, 0 on failure.
11674 * @since 1.1.0
11675 */
11676EAPI Eina_Bool evas_object_grid_pack_get (Evas_Object *o, Evas_Object *child, int *x, int *y, int *w, int *h);
11677
11678/**
11679 * Get an iterator to walk the list of children for the grid.
11680 *
11681 * @note Do not remove or delete objects while walking the list.
11682 * @since 1.1.0
11683 */
11684EAPI Eina_Iterator *evas_object_grid_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11685
11686/**
11687 * Get an accessor to get random access to the list of children for the grid.
11688 *
11689 * @note Do not remove or delete objects while walking the list.
11690 * @since 1.1.0
11691 */
11692EAPI Eina_Accessor *evas_object_grid_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11693
11694/**
11695 * Get the list of children for the grid.
11696 *
11697 * @note This is a duplicate of the list kept by the grid internally.
11698 * It's up to the user to destroy it when it no longer needs it.
11699 * It's possible to remove objects from the grid when walking this
11700 * list, but these removals won't be reflected on it.
11701 * @since 1.1.0
11702 */
11703EAPI Eina_List *evas_object_grid_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11704
11705/**
11706 * @}
11707 */
11708
11709/**
11710 * @defgroup Evas_Cserve Shared Image Cache Server
11711 *
11712 * Evas has an (optional) module which provides client-server
11713 * infrastructure to <b>share bitmaps across multiple processes</b>,
11714 * saving data and processing power.
11715 *
11716 * Be warned that it @b doesn't work when <b>threaded image
11717 * preloading</b> is enabled for Evas, though.
11718 */
11719 typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
11720 typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
11721 typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
11722 typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
11723
11724/**
11725 * Statistics about the server that shares cached bitmaps.
11726 * @ingroup Evas_Cserve
11727 */
11728 struct _Evas_Cserve_Stats
11729 {
11730 int saved_memory; /**< current amount of saved memory, in bytes */
11731 int wasted_memory; /**< current amount of wasted memory, in bytes */
11732 int saved_memory_peak; /**< peak amount of saved memory, in bytes */
11733 int wasted_memory_peak; /**< peak amount of wasted memory, in bytes */
11734 double saved_time_image_header_load; /**< time, in seconds, saved in header loads by sharing cached loads instead */
11735 double saved_time_image_data_load; /**< time, in seconds, saved in data loads by sharing cached loads instead */
11736 };
11737
11738/**
11739 * A handle of a cache of images shared by a server.
11740 * @ingroup Evas_Cserve
11741 */
11742 struct _Evas_Cserve_Image_Cache
11743 {
11744 struct {
11745 int mem_total;
11746 int count;
11747 } active, cached;
11748 Eina_List *images;
11749 };
11750
11751/**
11752 * A handle to an image shared by a server.
11753 * @ingroup Evas_Cserve
11754 */
11755 struct _Evas_Cserve_Image
11756 {
11757 const char *file, *key;
11758 int w, h;
11759 time_t file_mod_time;
11760 time_t file_checked_time;
11761 time_t cached_time;
11762 int refcount;
11763 int data_refcount;
11764 int memory_footprint;
11765 double head_load_time;
11766 double data_load_time;
11767 Eina_Bool alpha : 1;
11768 Eina_Bool data_loaded : 1;
11769 Eina_Bool active : 1;
11770 Eina_Bool dead : 1;
11771 Eina_Bool useless : 1;
11772 };
11773
11774/**
11775 * Configuration that controls the server that shares cached bitmaps.
11776 * @ingroup Evas_Cserve
11777 */
11778 struct _Evas_Cserve_Config
11779 {
11780 int cache_max_usage;
11781 int cache_item_timeout;
11782 int cache_item_timeout_check;
11783 };
11784
11785
11786/**
11787 * Retrieves if the system wants to share bitmaps using the server.
11788 * @return @c EINA_TRUE if it wants, @c EINA_FALSE otherwise.
11789 * @ingroup Evas_Cserve
11790 */
11791EAPI Eina_Bool evas_cserve_want_get (void) EINA_WARN_UNUSED_RESULT;
11792
11793/**
11794 * Retrieves if the system is connected to the server used to share
11795 * bitmaps.
11796 *
11797 * @return @c EINA_TRUE if it's connected, @c EINA_FALSE otherwise.
11798 * @ingroup Evas_Cserve
11799 */
11800EAPI Eina_Bool evas_cserve_connected_get (void) EINA_WARN_UNUSED_RESULT;
11801
11802/**
11803 * Retrieves statistics from a running bitmap sharing server.
11804 * @param stats pointer to structure to fill with statistics about the
11805 * bitmap cache server.
11806 *
11807 * @return @c EINA_TRUE if @p stats were filled with data,
11808 * @c EINA_FALSE otherwise (when @p stats is untouched)
11809 * @ingroup Evas_Cserve
11810 */
11811EAPI Eina_Bool evas_cserve_stats_get (Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
11812
11813/**
11814 * Completely discard/clean a given images cache, thus re-setting it.
11815 *
11816 * @param cache A handle to the given images cache.
11817 */
11818EAPI void evas_cserve_image_cache_contents_clean (Evas_Cserve_Image_Cache *cache);
11819
11820/**
11821 * Retrieves the current configuration of the Evas image caching
11822 * server.
11823 *
11824 * @param config where to store current image caching server's
11825 * configuration.
11826 *
11827 * @return @c EINA_TRUE if @p config was filled with data,
11828 * @c EINA_FALSE otherwise (when @p config is untouched)
11829 *
11830 * The fields of @p config will be altered to reflect the current
11831 * configuration's values.
11832 *
11833 * @see evas_cserve_config_set()
11834 *
11835 * @ingroup Evas_Cserve
11836 */
11837EAPI Eina_Bool evas_cserve_config_get (Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
11838
11839/**
11840 * Changes the configurations of the Evas image caching server.
11841 *
11842 * @param config A bitmap cache configuration handle with fields set
11843 * to desired configuration values.
11844 * @return @c EINA_TRUE if @p config was successfully applied,
11845 * @c EINA_FALSE otherwise.
11846 *
11847 * @see evas_cserve_config_get()
11848 *
11849 * @ingroup Evas_Cserve
11850 */
11851EAPI Eina_Bool evas_cserve_config_set (const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
11852
11853/**
11854 * Force the system to disconnect from the bitmap caching server.
11855 *
11856 * @ingroup Evas_Cserve
11857 */
11858EAPI void evas_cserve_disconnect (void);
11859
11860/**
11861 * @defgroup Evas_Utils General Utilities
11862 *
11863 * Some functions that are handy but are not specific of canvas or
11864 * objects.
11865 */
11866
11867/**
11868 * Converts the given Evas image load error code into a string
11869 * describing it in english.
11870 *
11871 * @param error the error code, a value in ::Evas_Load_Error.
11872 * @return Always returns a valid string. If the given @p error is not
11873 * supported, <code>"Unknown error"</code> is returned.
11874 *
11875 * Mostly evas_object_image_file_set() would be the function setting
11876 * that error value afterwards, but also evas_object_image_load(),
11877 * evas_object_image_save(), evas_object_image_data_get(),
11878 * evas_object_image_data_convert(), evas_object_image_pixels_import()
11879 * and evas_object_image_is_inside(). This function is meant to be
11880 * used in conjunction with evas_object_image_load_error_get(), as in:
11881 *
11882 * Example code:
11883 * @dontinclude evas-load-error-str.c
11884 * @skip img1 =
11885 * @until ecore_main_loop_begin(
11886 *
11887 * Here, being @c valid_path the path to a valid image and @c
11888 * bogus_path a path to a file which does not exist, the two outputs
11889 * of evas_load_error_str() would be (if no other errors occur):
11890 * <code>"No error on load"</code> and <code>"File (or file path) does
11891 * not exist"</code>, respectively. See the full @ref
11892 * Example_Evas_Images "example".
11893 *
11894 * @ingroup Evas_Utils
11895 */
11896EAPI const char *evas_load_error_str (Evas_Load_Error error);
11897
11898/* Evas utility routines for color space conversions */
11899/* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
11900/* rgb color space has r,g,b in the range 0 to 255 */
11901
11902/**
11903 * Convert a given color from HSV to RGB format.
11904 *
11905 * @param h The Hue component of the color.
11906 * @param s The Saturation component of the color.
11907 * @param v The Value component of the color.
11908 * @param r The Red component of the color.
11909 * @param g The Green component of the color.
11910 * @param b The Blue component of the color.
11911 *
11912 * This function converts a given color in HSV color format to RGB
11913 * color format.
11914 *
11915 * @ingroup Evas_Utils
11916 **/
11917EAPI void evas_color_hsv_to_rgb (float h, float s, float v, int *r, int *g, int *b);
11918
11919/**
11920 * Convert a given color from RGB to HSV format.
11921 *
11922 * @param r The Red component of the color.
11923 * @param g The Green component of the color.
11924 * @param b The Blue component of the color.
11925 * @param h The Hue component of the color.
11926 * @param s The Saturation component of the color.
11927 * @param v The Value component of the color.
11928 *
11929 * This function converts a given color in RGB color format to HSV
11930 * color format.
11931 *
11932 * @ingroup Evas_Utils
11933 **/
11934EAPI void evas_color_rgb_to_hsv (int r, int g, int b, float *h, float *s, float *v);
11935
11936/* argb color space has a,r,g,b in the range 0 to 255 */
11937
11938/**
11939 * Pre-multiplies a rgb triplet by an alpha factor.
11940 *
11941 * @param a The alpha factor.
11942 * @param r The Red component of the color.
11943 * @param g The Green component of the color.
11944 * @param b The Blue component of the color.
11945 *
11946 * This function pre-multiplies a given rgb triplet by an alpha
11947 * factor. Alpha factor is used to define transparency.
11948 *
11949 * @ingroup Evas_Utils
11950 **/
11951EAPI void evas_color_argb_premul (int a, int *r, int *g, int *b);
11952
11953/**
11954 * Undo pre-multiplication of a rgb triplet by an alpha factor.
11955 *
11956 * @param a The alpha factor.
11957 * @param r The Red component of the color.
11958 * @param g The Green component of the color.
11959 * @param b The Blue component of the color.
11960 *
11961 * This function undoes pre-multiplication a given rbg triplet by an
11962 * alpha factor. Alpha factor is used to define transparency.
11963 *
11964 * @see evas_color_argb_premul().
11965 *
11966 * @ingroup Evas_Utils
11967 **/
11968EAPI void evas_color_argb_unpremul (int a, int *r, int *g, int *b);
11969
11970
11971/**
11972 * Pre-multiplies data by an alpha factor.
11973 *
11974 * @param data The data value.
11975 * @param len The length value.
11976 *
11977 * This function pre-multiplies a given data by an alpha
11978 * factor. Alpha factor is used to define transparency.
11979 *
11980 * @ingroup Evas_Utils
11981 **/
11982EAPI void evas_data_argb_premul (unsigned int *data, unsigned int len);
11983
11984/**
11985 * Undo pre-multiplication data by an alpha factor.
11986 *
11987 * @param data The data value.
11988 * @param len The length value.
11989 *
11990 * This function undoes pre-multiplication of a given data by an alpha
11991 * factor. Alpha factor is used to define transparency.
11992 *
11993 * @ingroup Evas_Utils
11994 **/
11995EAPI void evas_data_argb_unpremul (unsigned int *data, unsigned int len);
11996
11997/* string and font handling */
11998
11999/**
12000 * Gets the next character in the string
12001 *
12002 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
12003 * this function will place in @p decoded the decoded code point at @p pos
12004 * and return the byte index for the next character in the string.
12005 *
12006 * The only boundary check done is that @p pos must be >= 0. Other than that,
12007 * no checks are performed, so passing an index value that's not within the
12008 * length of the string will result in undefined behavior.
12009 *
12010 * @param str The UTF-8 string
12011 * @param pos The byte index where to start
12012 * @param decoded Address where to store the decoded code point. Optional.
12013 *
12014 * @return The byte index of the next character
12015 *
12016 * @ingroup Evas_Utils
12017 */
12018EAPI int evas_string_char_next_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
12019
12020/**
12021 * Gets the previous character in the string
12022 *
12023 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
12024 * this function will place in @p decoded the decoded code point at @p pos
12025 * and return the byte index for the previous character in the string.
12026 *
12027 * The only boundary check done is that @p pos must be >= 1. Other than that,
12028 * no checks are performed, so passing an index value that's not within the
12029 * length of the string will result in undefined behavior.
12030 *
12031 * @param str The UTF-8 string
12032 * @param pos The byte index where to start
12033 * @param decoded Address where to store the decoded code point. Optional.
12034 *
12035 * @return The byte index of the previous character
12036 *
12037 * @ingroup Evas_Utils
12038 */
12039EAPI int evas_string_char_prev_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
12040
12041/**
12042 * Get the length in characters of the string.
12043 * @param str The string to get the length of.
12044 * @return The length in characters (not bytes)
12045 * @ingroup Evas_Utils
12046 */
12047EAPI int evas_string_char_len_get (const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
12048
12049/**
12050 * @defgroup Evas_Keys Key Input Functions
12051 *
12052 * Functions which feed key events to the canvas.
12053 *
12054 * As explained in @ref intro_not_evas, Evas is @b not aware of input
12055 * systems at all. Then, the user, if using it crudely (evas_new()),
12056 * will have to feed it with input events, so that it can react
12057 * somehow. If, however, the user creates a canvas by means of the
12058 * Ecore_Evas wrapper, it will automatically bind the chosen display
12059 * engine's input events to the canvas, for you.
12060 *
12061 * This group presents the functions dealing with the feeding of key
12062 * events to the canvas. On most of them, one has to reference a given
12063 * key by a name (<code>keyname</code> argument). Those are
12064 * <b>platform dependent</b> symbolic names for the keys. Sometimes
12065 * you'll get the right <code>keyname</code> by simply using an ASCII
12066 * value of the key name, but it won't be like that always.
12067 *
12068 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
12069 * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
12070 * to your display engine's documentation when using evas through an
12071 * Ecore helper wrapper when you need the <code>keyname</code>s.
12072 *
12073 * Example:
12074 * @dontinclude evas-events.c
12075 * @skip mods = evas_key_modifier_get(evas);
12076 * @until {
12077 *
12078 * All the other @c evas_key functions behave on the same manner. See
12079 * the full @ref Example_Evas_Events "example".
12080 *
12081 * @ingroup Evas_Canvas
12082 */
12083
12084/**
12085 * @addtogroup Evas_Keys
12086 * @{
12087 */
12088
12089/**
12090 * Returns a handle to the list of modifier keys registered in the
12091 * canvas @p e. This is required to check for which modifiers are set
12092 * at a given time with the evas_key_modifier_is_set() function.
12093 *
12094 * @param e The pointer to the Evas canvas
12095 *
12096 * @see evas_key_modifier_add
12097 * @see evas_key_modifier_del
12098 * @see evas_key_modifier_on
12099 * @see evas_key_modifier_off
12100 * @see evas_key_modifier_is_set
12101 *
12102 * @return An ::Evas_Modifier handle to query Evas' keys subsystem
12103 * with evas_key_modifier_is_set(), or @c NULL on error.
12104 */
12105EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
12106
12107/**
12108 * Returns a handle to the list of lock keys registered in the canvas
12109 * @p e. This is required to check for which locks are set at a given
12110 * time with the evas_key_lock_is_set() function.
12111 *
12112 * @param e The pointer to the Evas canvas
12113 *
12114 * @see evas_key_lock_add
12115 * @see evas_key_lock_del
12116 * @see evas_key_lock_on
12117 * @see evas_key_lock_off
12118 * @see evas_key_lock_is_set
12119 *
12120 * @return An ::Evas_Lock handle to query Evas' keys subsystem with
12121 * evas_key_lock_is_set(), or @c NULL on error.
12122 */
12123EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
12124
12125
12126/**
12127 * Checks the state of a given modifier key, at the time of the
12128 * call. If the modifier is set, such as shift being pressed, this
12129 * function returns @c Eina_True.
12130 *
12131 * @param m The current modifiers set, as returned by
12132 * evas_key_modifier_get().
12133 * @param keyname The name of the modifier key to check status for.
12134 *
12135 * @return @c Eina_True if the modifier key named @p keyname is on, @c
12136 * Eina_False otherwise.
12137 *
12138 * @see evas_key_modifier_add
12139 * @see evas_key_modifier_del
12140 * @see evas_key_modifier_get
12141 * @see evas_key_modifier_on
12142 * @see evas_key_modifier_off
12143 */
12144EAPI Eina_Bool evas_key_modifier_is_set (const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
12145
12146
12147/**
12148 * Checks the state of a given lock key, at the time of the call. If
12149 * the lock is set, such as caps lock, this function returns @c
12150 * Eina_True.
12151 *
12152 * @param l The current locks set, as returned by evas_key_lock_get().
12153 * @param keyname The name of the lock key to check status for.
12154 *
12155 * @return @c Eina_True if the @p keyname lock key is set, @c
12156 * Eina_False otherwise.
12157 *
12158 * @see evas_key_lock_get
12159 * @see evas_key_lock_add
12160 * @see evas_key_lock_del
12161 * @see evas_key_lock_on
12162 * @see evas_key_lock_off
12163 */
12164EAPI Eina_Bool evas_key_lock_is_set (const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
12165
12166
12167/**
12168 * Adds the @p keyname key to the current list of modifier keys.
12169 *
12170 * @param e The pointer to the Evas canvas
12171 * @param keyname The name of the modifier key to add to the list of
12172 * Evas modifiers.
12173 *
12174 * Modifiers are keys like shift, alt and ctrl, i.e., keys which are
12175 * meant to be pressed together with others, altering the behavior of
12176 * the secondly pressed keys somehow. Evas is so that these keys can
12177 * be user defined.
12178 *
12179 * This call allows custom modifiers to be added to the Evas system at
12180 * run time. It is then possible to set and unset modifier keys
12181 * programmatically for other parts of the program to check and act
12182 * on. Programmers using Evas would check for modifier keys on key
12183 * event callbacks using evas_key_modifier_is_set().
12184 *
12185 * @see evas_key_modifier_del
12186 * @see evas_key_modifier_get
12187 * @see evas_key_modifier_on
12188 * @see evas_key_modifier_off
12189 * @see evas_key_modifier_is_set
12190 *
12191 * @note If the programmer instantiates the canvas by means of the
12192 * ecore_evas_new() family of helper functions, Ecore will take
12193 * care of registering on it all standard modifiers: "Shift",
12194 * "Control", "Alt", "Meta", "Hyper", "Super".
12195 */
12196EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
12197
12198/**
12199 * Removes the @p keyname key from the current list of modifier keys
12200 * on canvas @e.
12201 *
12202 * @param e The pointer to the Evas canvas
12203 * @param keyname The name of the key to remove from the modifiers list.
12204 *
12205 * @see evas_key_modifier_add
12206 * @see evas_key_modifier_get
12207 * @see evas_key_modifier_on
12208 * @see evas_key_modifier_off
12209 * @see evas_key_modifier_is_set
12210 */
12211EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
12212
12213/**
12214 * Adds the @p keyname key to the current list of lock keys.
12215 *
12216 * @param e The pointer to the Evas canvas
12217 * @param keyname The name of the key to add to the locks list.
12218 *
12219 * Locks are keys like caps lock, num lock or scroll lock, i.e., keys
12220 * which are meant to be pressed once -- toggling a binary state which
12221 * is bound to it -- and thus altering the behavior of all
12222 * subsequently pressed keys somehow, depending on its state. Evas is
12223 * so that these keys can be defined by the user.
12224 *
12225 * This allows custom locks to be added to the evas system at run
12226 * time. It is then possible to set and unset lock keys
12227 * programmatically for other parts of the program to check and act
12228 * on. Programmers using Evas would check for lock keys on key event
12229 * callbacks using evas_key_lock_is_set().
12230 *
12231 * @see evas_key_lock_get
12232 * @see evas_key_lock_del
12233 * @see evas_key_lock_on
12234 * @see evas_key_lock_off
12235 * @see evas_key_lock_is_set
12236 *
12237 * @note If the programmer instantiates the canvas by means of the
12238 * ecore_evas_new() family of helper functions, Ecore will take
12239 * care of registering on it all standard lock keys: "Caps_Lock",
12240 * "Num_Lock", "Scroll_Lock".
12241 */
12242EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
12243
12244/**
12245 * Removes the @p keyname key from the current list of lock keys on
12246 * canvas @e.
12247 *
12248 * @param e The pointer to the Evas canvas
12249 * @param keyname The name of the key to remove from the locks list.
12250 *
12251 * @see evas_key_lock_get
12252 * @see evas_key_lock_add
12253 * @see evas_key_lock_on
12254 * @see evas_key_lock_off
12255 */
12256EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
12257
12258
12259/**
12260 * Enables or turns on programmatically the modifier key with name @p
12261 * keyname.
12262 *
12263 * @param e The pointer to the Evas canvas
12264 * @param keyname The name of the modifier to enable.
12265 *
12266 * The effect will be as if the key was pressed for the whole time
12267 * between this call and a matching evas_key_modifier_off().
12268 *
12269 * @see evas_key_modifier_add
12270 * @see evas_key_modifier_get
12271 * @see evas_key_modifier_off
12272 * @see evas_key_modifier_is_set
12273 */
12274EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
12275
12276/**
12277 * Disables or turns off programmatically the modifier key with name
12278 * @p keyname.
12279 *
12280 * @param e The pointer to the Evas canvas
12281 * @param keyname The name of the modifier to disable.
12282 *
12283 * @see evas_key_modifier_add
12284 * @see evas_key_modifier_get
12285 * @see evas_key_modifier_on
12286 * @see evas_key_modifier_is_set
12287 */
12288EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
12289
12290/**
12291 * Enables or turns on programmatically the lock key with name @p
12292 * keyname.
12293 *
12294 * @param e The pointer to the Evas canvas
12295 * @param keyname The name of the lock to enable.
12296 *
12297 * The effect will be as if the key was put on its active state after
12298 * this call.
12299 *
12300 * @see evas_key_lock_get
12301 * @see evas_key_lock_add
12302 * @see evas_key_lock_del
12303 * @see evas_key_lock_off
12304 */
12305EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
12306
12307/**
12308 * Disables or turns off programmatically the lock key with name @p
12309 * keyname.
12310 *
12311 * @param e The pointer to the Evas canvas
12312 * @param keyname The name of the lock to disable.
12313 *
12314 * The effect will be as if the key was put on its inactive state
12315 * after this call.
12316 *
12317 * @see evas_key_lock_get
12318 * @see evas_key_lock_add
12319 * @see evas_key_lock_del
12320 * @see evas_key_lock_on
12321 */
12322EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
12323
12324
12325/**
12326 * Creates a bit mask from the @p keyname @b modifier key. Values
12327 * returned from different calls to it may be ORed together,
12328 * naturally.
12329 *
12330 * @param e The canvas whom to query the bit mask from.
12331 * @param keyname The name of the modifier key to create the mask for.
12332 *
12333 * @returns the bit mask or 0 if the @p keyname key wasn't registered as a
12334 * modifier for canvas @p e.
12335 *
12336 * This function is meant to be using in conjunction with
12337 * evas_object_key_grab()/evas_object_key_ungrab(). Go check their
12338 * documentation for more information.
12339 *
12340 * @see evas_key_modifier_add
12341 * @see evas_key_modifier_get
12342 * @see evas_key_modifier_on
12343 * @see evas_key_modifier_off
12344 * @see evas_key_modifier_is_set
12345 * @see evas_object_key_grab
12346 * @see evas_object_key_ungrab
12347 */
12348EAPI Evas_Modifier_Mask evas_key_modifier_mask_get (const Evas *e, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
12349
12350
12351/**
12352 * Requests @p keyname key events be directed to @p obj.
12353 *
12354 * @param obj the object to direct @p keyname events to.
12355 * @param keyname the key to request events for.
12356 * @param modifiers a mask of modifiers that must be present to
12357 * trigger the event.
12358 * @param not_modifiers a mask of modifiers that must @b not be present
12359 * to trigger the event.
12360 * @param exclusive request that the @p obj is the only object
12361 * receiving the @p keyname events.
12362 * @return @c EINA_TRUE, if the call succeeded, @c EINA_FALSE otherwise.
12363 *
12364 * Key grabs allow one or more objects to receive key events for
12365 * specific key strokes even if other objects have focus. Whenever a
12366 * key is grabbed, only the objects grabbing it will get the events
12367 * for the given keys.
12368 *
12369 * @p keyname is a platform dependent symbolic name for the key
12370 * pressed (see @ref Evas_Keys for more information).
12371 *
12372 * @p modifiers and @p not_modifiers are bit masks of all the
12373 * modifiers that must and mustn't, respectively, be pressed along
12374 * with @p keyname key in order to trigger this new key
12375 * grab. Modifiers can be things such as Shift and Ctrl as well as
12376 * user defined types via evas_key_modifier_add(). Retrieve them with
12377 * evas_key_modifier_mask_get() or use @c 0 for empty masks.
12378 *
12379 * @p exclusive will make the given object the only one permitted to
12380 * grab the given key. If given @c EINA_TRUE, subsequent calls on this
12381 * function with different @p obj arguments will fail, unless the key
12382 * is ungrabbed again.
12383 *
12384 * Example code follows.
12385 * @dontinclude evas-events.c
12386 * @skip if (d.focus)
12387 * @until else
12388 *
12389 * See the full example @ref Example_Evas_Events "here".
12390 *
12391 * @see evas_object_key_ungrab
12392 * @see evas_object_focus_set
12393 * @see evas_object_focus_get
12394 * @see evas_focus_get
12395 * @see evas_key_modifier_add
12396 */
12397EAPI Eina_Bool evas_object_key_grab (Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers, Eina_Bool exclusive) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
12398
12399/**
12400 * Removes the grab on @p keyname key events by @p obj.
12401 *
12402 * @param obj the object that has an existing key grab.
12403 * @param keyname the key the grab is set for.
12404 * @param modifiers a mask of modifiers that must be present to
12405 * trigger the event.
12406 * @param not_modifiers a mask of modifiers that must not not be
12407 * present to trigger the event.
12408 *
12409 * Removes a key grab on @p obj if @p keyname, @p modifiers, and @p
12410 * not_modifiers match.
12411 *
12412 * Example code follows.
12413 * @dontinclude evas-events.c
12414 * @skip got here by key grabs
12415 * @until }
12416 *
12417 * See the full example @ref Example_Evas_Events "here".
12418 *
12419 * @see evas_object_key_grab
12420 * @see evas_object_focus_set
12421 * @see evas_object_focus_get
12422 * @see evas_focus_get
12423 */
12424EAPI void evas_object_key_ungrab (Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers) EINA_ARG_NONNULL(1, 2);
12425
12426/**
12427 * @}
12428 */
12429
12430/**
12431 * @defgroup Evas_Touch_Point_List Touch Point List Functions
12432 *
12433 * Functions to get information of touched points in the Evas.
12434 *
12435 * Evas maintains list of touched points on the canvas. Each point has
12436 * its co-ordinates, id and state. You can get the number of touched
12437 * points and information of each point using evas_touch_point_list
12438 * functions.
12439 *
12440 * @ingroup Evas_Canvas
12441 */
12442
12443/**
12444 * @addtogroup Evas_Touch_Point_List
12445 * @{
12446 */
12447
12448/**
12449 * Get the number of touched point in the evas.
12450 *
12451 * @param e The pointer to the Evas canvas.
12452 * @return The number of touched point on the evas.
12453 *
12454 * New touched point is added to the list whenever touching the evas
12455 * and point is removed whenever removing touched point from the evas.
12456 *
12457 * Example:
12458 * @code
12459 * extern Evas *evas;
12460 * int count;
12461 *
12462 * count = evas_touch_point_list_count(evas);
12463 * printf("The count of touch points: %i\n", count);
12464 * @endcode
12465 *
12466 * @see evas_touch_point_list_nth_xy_get()
12467 * @see evas_touch_point_list_nth_id_get()
12468 * @see evas_touch_point_list_nth_state_get()
12469 */
12470EAPI unsigned int evas_touch_point_list_count(Evas *e) EINA_ARG_NONNULL(1);
12471
12472/**
12473 * This function returns the nth touch point's co-ordinates.
12474 *
12475 * @param e The pointer to the Evas canvas.
12476 * @param n The number of the touched point (0 being the first).
12477 * @param x The pointer to a Evas_Coord to be filled in.
12478 * @param y The pointer to a Evas_Coord to be filled in.
12479 *
12480 * Touch point's co-ordinates is updated whenever moving that point
12481 * on the canvas.
12482 *
12483 * Example:
12484 * @code
12485 * extern Evas *evas;
12486 * Evas_Coord x, y;
12487 *
12488 * if (evas_touch_point_list_count(evas))
12489 * {
12490 * evas_touch_point_nth_xy_get(evas, 0, &x, &y);
12491 * printf("The first touch point's co-ordinate: (%i, %i)\n", x, y);
12492 * }
12493 * @endcode
12494 *
12495 * @see evas_touch_point_list_count()
12496 * @see evas_touch_point_list_nth_id_get()
12497 * @see evas_touch_point_list_nth_state_get()
12498 */
12499EAPI void evas_touch_point_list_nth_xy_get(Evas *e, unsigned int n, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
12500
12501/**
12502 * This function returns the @p id of nth touch point.
12503 *
12504 * @param e The pointer to the Evas canvas.
12505 * @param n The number of the touched point (0 being the first).
12506 * @return id of nth touch point, if the call succeeded, -1 otherwise.
12507 *
12508 * The point which comes from Mouse Event has @p id 0 and The point
12509 * which comes from Multi Event has @p id that is same as Multi
12510 * Event's device id.
12511 *
12512 * Example:
12513 * @code
12514 * extern Evas *evas;
12515 * int id;
12516 *
12517 * if (evas_touch_point_list_count(evas))
12518 * {
12519 * id = evas_touch_point_nth_id_get(evas, 0);
12520 * printf("The first touch point's id: %i\n", id);
12521 * }
12522 * @endcode
12523 *
12524 * @see evas_touch_point_list_count()
12525 * @see evas_touch_point_list_nth_xy_get()
12526 * @see evas_touch_point_list_nth_state_get()
12527 */
12528EAPI int evas_touch_point_list_nth_id_get(Evas *e, unsigned int n) EINA_ARG_NONNULL(1);
12529
12530/**
12531 * This function returns the @p state of nth touch point.
12532 *
12533 * @param e The pointer to the Evas canvas.
12534 * @param n The number of the touched point (0 being the first).
12535 * @return @p state of nth touch point, if the call succeeded,
12536 * EVAS_TOUCH_POINT_CANCEL otherwise.
12537 *
12538 * The point's @p state is EVAS_TOUCH_POINT_DOWN when pressed,
12539 * EVAS_TOUCH_POINT_STILL when the point is not moved after pressed,
12540 * EVAS_TOUCH_POINT_MOVE when moved at least once after pressed and
12541 * EVAS_TOUCH_POINT_UP when released.
12542 *
12543 * Example:
12544 * @code
12545 * extern Evas *evas;
12546 * Evas_Touch_Point_State state;
12547 *
12548 * if (evas_touch_point_list_count(evas))
12549 * {
12550 * state = evas_touch_point_nth_state_get(evas, 0);
12551 * printf("The first touch point's state: %i\n", state);
12552 * }
12553 * @endcode
12554 *
12555 * @see evas_touch_point_list_count()
12556 * @see evas_touch_point_list_nth_xy_get()
12557 * @see evas_touch_point_list_nth_id_get()
12558 */
12559EAPI Evas_Touch_Point_State evas_touch_point_list_nth_state_get(Evas *e, unsigned int n) EINA_ARG_NONNULL(1);
12560
12561/**
12562 * @}
12563 */
12564
12565#ifdef __cplusplus
12566}
12567#endif
12568
12569#endif
generated by cgit v1.1 at 2024-08-29 23:01:50 +0000