aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/evas/src/lib/Evas.h
diff options
context:
space:
mode:
authorDavid Walter Seikel2012-01-04 18:41:13 +1000
committerDavid Walter Seikel2012-01-04 18:41:13 +1000
commitdd7595a3475407a7fa96a97393bae8c5220e8762 (patch)
treee341e911d7eb911a51684a7412ef7f7c7605d28e /libraries/evas/src/lib/Evas.h
parentAdd the skeleton. (diff)
downloadSledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.zip
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.gz
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.bz2
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.xz
Add the base Enlightenment Foundation Libraries - eina, eet, evas, ecore, embryo, and edje.
Note that embryo wont be used, but I'm not sure yet if you can build edje without it.
Diffstat (limited to 'libraries/evas/src/lib/Evas.h')
-rw-r--r--libraries/evas/src/lib/Evas.h12236
1 files changed, 12236 insertions, 0 deletions
diff --git a/libraries/evas/src/lib/Evas.h b/libraries/evas/src/lib/Evas.h
new file mode 100644
index 0000000..5898290
--- /dev/null
+++ b/libraries/evas/src/lib/Evas.h
@@ -0,0 +1,12236 @@
1/**
2@mainpage Evas
3
4@version 1.1
5@date 2000-2011
6
7Please see the @ref authors page for contact details.
8@link Evas.h Evas API @endlink
9
10@section toc Table of Contents
11
12@li @ref intro
13@li @ref work
14@li @ref compiling
15@li @ref install
16@li @ref next_steps
17@li @ref intro_example
18
19
20@section intro What is Evas?
21
22Evas is a clean display canvas API for several target display systems
23that can draw anti-aliased text, smooth super and sub-sampled scaled
24images, alpha-blend objects and much more.
25
26It abstracts any need to know much about what the characteristics of
27your display system are or what graphics calls are used to draw them
28and how. It deals on an object level where all you do is create and
29manipulate objects in a canvas, set their properties, and the rest is
30done for you.
31
32Evas optimises the rendering pipeline to minimise effort in redrawing
33changes made to the canvas and so takes this work out of the
34programmers hand, saving a lot of time and energy.
35
36It's small and lean, designed to work on embedded systems all the way
37to large and powerful multi-cpu workstations. It can be compiled to
38only have the features you need for your target platform if you so
39wish, thus keeping it small and lean. It has several display
40back-ends, letting it display on several display systems, making it
41portable for cross-device and cross-platform development.
42
43@subsection intro_not_evas What Evas is not?
44
45Evas is not a widget set or widget toolkit, however it is their
46base. See Elementary (http://docs.enlightenment.org/auto/elementary/)
47for a toolkit based on Evas, Edje, Ecore and other Enlightenment
48technologies.
49
50It is not dependent or aware of main loops, input or output
51systems. Input should be polled from various sources and fed to
52Evas. Similarly, it will not create windows or report windows updates
53to your system, rather just drawing the pixels and reporting to the
54user the areas that were changed. Of course these operations are quite
55common and thus they are ready to use in Ecore, particularly in
56Ecore_Evas (http://docs.enlightenment.org/auto/ecore/).
57
58
59@section work How does Evas work?
60
61Evas is a canvas display library. This is markedly different from most
62display and windowing systems as a canvas is structural and is also a
63state engine, whereas most display and windowing systems are immediate
64mode display targets. Evas handles the logic between a structural
65display via its state engine, and controls the target windowing system
66in order to produce rendered results of the current canvas' state on
67the display.
68
69Immediate mode display systems retain very little, or no state. A
70program will execute a series of commands, as in the pseudo code:
71
72@verbatim
73draw line from position (0, 0) to position (100, 200);
74
75draw rectangle from position (10, 30) to position (50, 500);
76
77bitmap_handle = create_bitmap();
78scale bitmap_handle to size 100 x 100;
79draw image bitmap_handle at position (10, 30);
80@endverbatim
81
82The series of commands is executed by the windowing system and the
83results are displayed on the screen (normally). Once the commands are
84executed the display system has little or no idea of how to reproduce
85this image again, and so has to be instructed by the application how
86to redraw sections of the screen whenever needed. Each successive
87command will be executed as instructed by the application and either
88emulated by software or sent to the graphics hardware on the device to
89be performed.
90
91The advantage of such a system is that it is simple, and gives a
92program tight control over how something looks and is drawn. Given the
93increasing complexity of displays and demands by users to have better
94looking interfaces, more and more work is needing to be done at this
95level by the internals of widget sets, custom display widgets and
96other programs. This means more and more logic and display rendering
97code needs to be written time and time again, each time the
98application needs to figure out how to minimise redraws so that
99display is fast and interactive, and keep track of redraw logic. The
100power comes at a high-price, lots of extra code and work. Programmers
101not very familiar with graphics programming will often make mistakes
102at this level and produce code that is sub optimal. Those familiar
103with this kind of programming will simply get bored by writing the
104same code again and again.
105
106For example, if in the above scene, the windowing system requires the
107application to redraw the area from 0, 0 to 50, 50 (also referred as
108"expose event"), then the programmer must calculate manually the
109updates and repaint it again:
110
111@verbatim
112Redraw from position (0, 0) to position (50, 50):
113
114// what was in area (0, 0, 50, 50)?
115
116// 1. intersection part of line (0, 0) to (100, 200)?
117 draw line from position (0, 0) to position (25, 50);
118
119// 2. intersection part of rectangle (10, 30) to (50, 500)?
120 draw rectangle from position (10, 30) to position (50, 50)
121
122// 3. intersection part of image at (10, 30), size 100 x 100?
123 bitmap_subimage = subregion from position (0, 0) to position (40, 20)
124 draw image bitmap_subimage at position (10, 30);
125@endverbatim
126
127The clever reader might have noticed that, if all elements in the
128above scene are opaque, then the system is doing useless paints: part
129of the line is behind the rectangle, and part of the rectangle is
130behind the image. These useless paints tend to be very costly, as
131pixels tend to be 4 bytes in size, thus an overlapping region of 100 x
132100 pixels is around 40000 useless writes! The developer could write
133code to calculate the overlapping areas and avoid painting then, but
134then it should be mixed with the "expose event" handling mentioned
135above and quickly one realizes the initially simpler method became
136really complex.
137
138Evas is a structural system in which the programmer creates and
139manages display objects and their properties, and as a result of this
140higher level state management, the canvas is able to redraw the set of
141objects when needed to represent the current state of the canvas.
142
143For example, the pseudo code:
144
145@verbatim
146line_handle = create_line();
147set line_handle from position (0, 0) to position (100, 200);
148show line_handle;
149
150rectangle_handle = create_rectangle();
151move rectangle_handle to position (10, 30);
152resize rectangle_handle to size 40 x 470;
153show rectangle_handle;
154
155bitmap_handle = create_bitmap();
156scale bitmap_handle to size 100 x 100;
157move bitmap_handle to position (10, 30);
158show bitmap_handle;
159
160render scene;
161@endverbatim
162
163This may look longer, but when the display needs to be refreshed or
164updated, the programmer only moves, resizes, shows, hides etc. the
165objects that need to change. The programmer simply thinks at the
166object logic level, and the canvas software does the rest of the work
167for them, figuring out what actually changed in the canvas since it
168was last drawn, how to most efficiently redraw the canvas and its
169contents to reflect the current state, and then it can go off and do
170the actual drawing of the canvas.
171
172This lets the programmer think in a more natural way when dealing with
173a display, and saves time and effort of working out how to load and
174display images, render given the current display system etc. Since
175Evas also is portable across different display systems, this also
176gives the programmer the ability to have their code ported and
177displayed on different display systems with very little work.
178
179Evas can be seen as a display system that stands somewhere between a
180widget set and an immediate mode display system. It retains basic
181display logic, but does very little high-level logic such as
182scrollbars, sliders, push buttons etc.
183
184
185@section compiling How to compile using Evas ?
186
187Evas is a library your application links to. The procedure for this is
188very simple. You simply have to compile your application with the
189appropriate compiler flags that the @c pkg-config script outputs. For
190example:
191
192Compiling C or C++ files into object files:
193
194@verbatim
195gcc -c -o main.o main.c `pkg-config --cflags evas`
196@endverbatim
197
198Linking object files into a binary executable:
199
200@verbatim
201gcc -o my_application main.o `pkg-config --libs evas`
202@endverbatim
203
204You simply have to make sure that @c pkg-config is in your shell's @c
205PATH (see the manual page for your appropriate shell) and @c evas.pc
206in @c /usr/lib/pkgconfig or its path in the @c PKG_CONFIG_PATH
207environment variable. It's that simple to link and use Evas once you
208have written your code to use it.
209
210Since the program is linked to Evas, it is now able to use any
211advertised API calls to display graphics in a canvas managed by it, as
212well as use the API calls provided to manage data.
213
214You should make sure you add any extra compile and link flags to your
215compile commands that your application may need as well. The above
216example is only guaranteed to make Evas add it's own requirements.
217
218
219@section install How is it installed?
220
221Simple:
222
223@verbatim
224./configure
225make
226su -
227...
228make install
229@endverbatim
230
231@section next_steps Next Steps
232
233After you understood what Evas is and installed it in your system you
234should proceed understanding the programming interface for all
235objects, then see the specific for the most used elements. We'd
236recommend you to take a while to learn Ecore
237(http://docs.enlightenment.org/auto/ecore/) and Edje
238(http://docs.enlightenment.org/auto/edje/) as they will likely save
239you tons of work compared to using just Evas directly.
240
241Recommended reading:
242
243@li @ref Evas_Object_Group, where you'll get how to basically
244 manipulate generic objects lying on an Evas canvas, handle canvas
245 and object events, etc.
246@li @ref Evas_Object_Rectangle, to learn about the most basic object
247 type on Evas -- the rectangle.
248@li @ref Evas_Object_Polygon, to learn how to create polygon elements
249 on the canvas.
250@li @ref Evas_Line_Group, to learn how to create line elements on the
251 canvas.
252@li @ref Evas_Object_Image, to learn about image objects, over which
253 Evas can do a plethora of operations.
254@li @ref Evas_Object_Text, to learn how to create textual elements on
255 the canvas.
256@li @ref Evas_Object_Textblock, to learn how to create multiline
257 textual elements on the canvas.
258@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define
259 new objects that provide @b custom functions to handle clipping,
260 hiding, moving, resizing, color setting and more. These could
261 be as simple as a group of objects that move together (see @ref
262 Evas_Smart_Object_Clipped) up to implementations of what
263 ends to be a widget, providing some intelligence (thus the name)
264 to Evas objects -- like a button or check box, for example.
265
266@section intro_example Introductory Example
267
268@include evas-buffer-simple.c
269*/
270
271/**
272@page authors Authors
273@author Carsten Haitzler <raster@@rasterman.com>
274@author Till Adam <till@@adam-lilienthal.de>
275@author Steve Ireland <sireland@@pobox.com>
276@author Brett Nash <nash@@nash.id.au>
277@author Tilman Sauerbeck <tilman@@code-monkey.de>
278@author Corey Donohoe <atmos@@atmos.org>
279@author Yuri Hudobin <glassy_ape@@users.sourceforge.net>
280@author Nathan Ingersoll <ningerso@@d.umn.edu>
281@author Willem Monsuwe <willem@@stack.nl>
282@author Jose O Gonzalez <jose_ogp@@juno.com>
283@author Bernhard Nemec <Bernhard.Nemec@@viasyshc.com>
284@author Jorge Luis Zapata Muga <jorgeluis.zapata@@gmail.com>
285@author Cedric Bail <cedric.bail@@free.fr>
286@author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
287@author Vincent Torri <vtorri@@univ-evry.fr>
288@author Tim Horton <hortont424@@gmail.com>
289@author Tom Hacohen <tom@@stosb.com>
290@author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
291@author Iván Briano <ivan@@profusion.mobi>
292@author Gustavo Lima Chaves <glima@@profusion.mobi>
293@author Samsung Electronics <tbd>
294@author Samsung SAIT <tbd>
295@author Sung W. Park <sungwoo@@gmail.com>
296@author Jiyoun Park <jy0703.park@@samsung.com>
297@author Myoungwoon Roy Kim(roy_kim) <myoungwoon.kim@@samsung.com> <myoungwoon@@gmail.com>
298@author Thierry el Borgi <thierry@@substantiel.fr>
299@author ChunEon Park <hermet@@hermet.pe.kr>
300@author Christopher 'devilhorns' Michael <cpmichael1@comcast.net>
301@author Seungsoo Woo <om101.woo@samsung.com>
302
303Please contact <enlightenment-devel@lists.sourceforge.net> to get in
304contact with the developers and maintainers.
305*/
306
307#ifndef _EVAS_H
308#define _EVAS_H
309
310#include <time.h>
311
312#include <Eina.h>
313
314#ifdef EAPI
315# undef EAPI
316#endif
317
318#ifdef _WIN32
319# ifdef EFL_EVAS_BUILD
320# ifdef DLL_EXPORT
321# define EAPI __declspec(dllexport)
322# else
323# define EAPI
324# endif /* ! DLL_EXPORT */
325# else
326# define EAPI __declspec(dllimport)
327# endif /* ! EFL_EVAS_BUILD */
328#else
329# ifdef __GNUC__
330# if __GNUC__ >= 4
331# define EAPI __attribute__ ((visibility("default")))
332# else
333# define EAPI
334# endif
335# else
336# define EAPI
337# endif
338#endif /* ! _WIN32 */
339
340#ifdef __cplusplus
341extern "C" {
342#endif
343
344#define EVAS_VERSION_MAJOR 1
345#define EVAS_VERSION_MINOR 0
346
347typedef struct _Evas_Version
348{
349 int major;
350 int minor;
351 int micro;
352 int revision;
353} Evas_Version;
354
355EAPI extern Evas_Version *evas_version;
356
357/**
358 * @file
359 * @brief These routines are used for Evas library interaction.
360 *
361 * @todo check boolean return values and convert to Eina_Bool
362 * @todo change all api to use EINA_SAFETY_*
363 * @todo finish api documentation
364 */
365
366/* BiDi exposed stuff */
367 /*FIXME: document */
368typedef enum _Evas_BiDi_Direction
369{
370 EVAS_BIDI_DIRECTION_NATURAL,
371 EVAS_BIDI_DIRECTION_NEUTRAL = EVAS_BIDI_DIRECTION_NATURAL,
372 EVAS_BIDI_DIRECTION_LTR,
373 EVAS_BIDI_DIRECTION_RTL
374} Evas_BiDi_Direction;
375
376/**
377 * Identifier of callbacks to be set for Evas canvases or Evas
378 * objects.
379 *
380 * The following figure illustrates some Evas callbacks:
381 *
382 * @image html evas-callbacks.png
383 * @image rtf evas-callbacks.png
384 * @image latex evas-callbacks.eps
385 *
386 * @see evas_object_event_callback_add()
387 * @see evas_event_callback_add()
388 */
389typedef enum _Evas_Callback_Type
390{
391 /*
392 * The following events are only for use with Evas objects, with
393 * evas_object_event_callback_add():
394 */
395 EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */
396 EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
397 EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
398 EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
399 EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
400 EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
401 EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
402 EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
403 EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
404 EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
405 EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
406 EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
407 EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
408 EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
409 EVAS_CALLBACK_SHOW, /**< Show Event */
410 EVAS_CALLBACK_HIDE, /**< Hide Event */
411 EVAS_CALLBACK_MOVE, /**< Move Event */
412 EVAS_CALLBACK_RESIZE, /**< Resize Event */
413 EVAS_CALLBACK_RESTACK, /**< Restack Event */
414 EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
415 EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
416 EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
417 EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */
418
419 /*
420 * The following events are only for use with Evas canvases, with
421 * evas_event_callback_add():
422 */
423 EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
424 EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
425 EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */
426 EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
427 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
428 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
429
430 /*
431 * More Evas object event types - see evas_object_event_callback_add():
432 */
433 EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanims in Evas that throw out original image data) */
434
435 EVAS_CALLBACK_LAST /**< kept as last element/sentinel -- not really an event */
436} Evas_Callback_Type; /**< The types of events triggering a callback */
437
438/**
439 * @def EVAS_CALLBACK_PRIORITY_BEFORE
440 * Slightly more prioritized than default.
441 * @since 1.1.0
442 */
443#define EVAS_CALLBACK_PRIORITY_BEFORE -100
444/**
445 * @def EVAS_CALLBACK_PRIORITY_DEFAULT
446 * Default callback priority level
447 * @since 1.1.0
448 */
449#define EVAS_CALLBACK_PRIORITY_DEFAULT 0
450/**
451 * @def EVAS_CALLBACK_PRIORITY_AFTER
452 * Slightly less prioritized than default.
453 * @since 1.1.0
454 */
455#define EVAS_CALLBACK_PRIORITY_AFTER 100
456
457/**
458 * @typedef Evas_Callback_Priority
459 *
460 * Callback priority value. Range is -32k - 32k. The lower the number, the
461 * bigger the priority.
462 *
463 * @see EVAS_CALLBACK_PRIORITY_AFTER
464 * @see EVAS_CALLBACK_PRIORITY_BEFORE
465 * @see EVAS_CALLBACK_PRIORITY_DEFAULT
466 *
467 * @since 1.1.0
468 */
469typedef short Evas_Callback_Priority;
470
471/**
472 * Flags for Mouse Button events
473 */
474typedef enum _Evas_Button_Flags
475{
476 EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
477 EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< This mouse button press was the 2nd press of a double click */
478 EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< This mouse button press was the 3rd press of a triple click */
479} Evas_Button_Flags; /**< Flags for Mouse Button events */
480
481/**
482 * Flags for Events
483 */
484typedef enum _Evas_Event_Flags
485{
486 EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
487 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 */
488 EVAS_EVENT_FLAG_ON_SCROLL = (1 << 1) /**< This event flag indicates the event occurs while scrolling; for exameple, DOWN event occurs during scrolling; the event should be used for informational purposes and maybe some indications visually, but not actually perform anything */
489} Evas_Event_Flags; /**< Flags for Events */
490
491/**
492 * State of Evas_Coord_Touch_Point
493 */
494typedef enum _Evas_Touch_Point_State
495{
496 EVAS_TOUCH_POINT_DOWN, /**< Touch point is pressed down */
497 EVAS_TOUCH_POINT_UP, /**< Touch point is released */
498 EVAS_TOUCH_POINT_MOVE, /**< Touch point is moved */
499 EVAS_TOUCH_POINT_STILL, /**< Touch point is not moved after pressed */
500 EVAS_TOUCH_POINT_CANCEL /**< Touch point is calcelled */
501} Evas_Touch_Point_State;
502
503/**
504 * Flags for Font Hinting
505 * @ingroup Evas_Font_Group
506 */
507typedef enum _Evas_Font_Hinting_Flags
508{
509 EVAS_FONT_HINTING_NONE, /**< No font hinting */
510 EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
511 EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
512} Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */
513
514/**
515 * Colorspaces for pixel data supported by Evas
516 * @ingroup Evas_Object_Image
517 */
518typedef enum _Evas_Colorspace
519{
520 EVAS_COLORSPACE_ARGB8888, /**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */
521 /* these are not currently supported - but planned for the future */
522 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 */
523 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 */
524 EVAS_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */
525 EVAS_COLORSPACE_GRY8, /**< 8bit grayscale */
526 EVAS_COLORSPACE_YCBCR422601_PL, /**< YCbCr 4:2:2, ITU.BT-601 specifications. The data poitned to is just an array of row pointer, pointing to line of Y,Cb,Y,Cr bytes */
527 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. */
528 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. */
529} Evas_Colorspace; /**< Colorspaces for pixel data supported by Evas */
530
531/**
532 * How to pack items into cells in a table.
533 * @ingroup Evas_Object_Table
534 *
535 * @see evas_object_table_homogeneous_set() for an explanation of the funcion of
536 * each one.
537 */
538typedef enum _Evas_Object_Table_Homogeneous_Mode
539{
540 EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0,
541 EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1,
542 EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2
543} Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode. */
544
545typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< A generic rectangle handle */
546typedef struct _Evas_Point Evas_Point; /**< integer point */
547
548typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */
549typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */
550
551typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */
552typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */
553
554/**
555 * @typedef Evas_Smart_Class
556 *
557 * A smart object's @b base class definition
558 *
559 * @ingroup Evas_Smart_Group
560 */
561typedef struct _Evas_Smart_Class Evas_Smart_Class;
562
563/**
564 * @typedef Evas_Smart_Cb_Description
565 *
566 * A smart object callback description, used to provide introspection
567 *
568 * @ingroup Evas_Smart_Group
569 */
570typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
571
572/**
573 * @typedef Evas_Map
574 *
575 * An opaque handle to map points
576 *
577 * @see evas_map_new()
578 * @see evas_map_free()
579 * @see evas_map_dup()
580 *
581 * @ingroup Evas_Object_Group_Map
582 */
583typedef struct _Evas_Map Evas_Map;
584
585/**
586 * @typedef Evas
587 *
588 * An opaque handle to an Evas canvas.
589 *
590 * @see evas_new()
591 * @see evas_free()
592 *
593 * @ingroup Evas_Canvas
594 */
595typedef struct _Evas Evas;
596
597/**
598 * @typedef Evas_Object
599 * An Evas Object handle.
600 * @ingroup Evas_Object_Group
601 */
602typedef struct _Evas_Object Evas_Object;
603
604typedef void Evas_Performance; /**< An Evas Performance handle */
605typedef struct _Evas_Modifier Evas_Modifier; /**< An opaque type containing information on which modifier keys are registered in an Evas canvas */
606typedef struct _Evas_Lock Evas_Lock; /**< An opaque type containing information on which lock keys are registered in an Evas canvas */
607typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
608typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< A generic datatype for engine specific native surface information */
609
610 /**
611 * @typedef Evas_Video_Surface
612 *
613 * A generic datatype for video specific surface information
614 * @see evas_object_image_video_surface_set
615 * @see evas_object_image_video_surface_get
616 * @since 1.1.0
617 */
618typedef struct _Evas_Video_Surface Evas_Video_Surface;
619
620typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */
621
622typedef int Evas_Coord;
623typedef int Evas_Font_Size;
624typedef int Evas_Angle;
625
626struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */
627{
628 Evas_Coord x; /**< top-left x co-ordinate of rectangle */
629 Evas_Coord y; /**< top-left y co-ordinate of rectangle */
630 Evas_Coord w; /**< width of rectangle */
631 Evas_Coord h; /**< height of rectangle */
632};
633
634struct _Evas_Point
635{
636 int x, y;
637};
638
639struct _Evas_Coord_Point
640{
641 Evas_Coord x, y;
642};
643
644struct _Evas_Coord_Precision_Point
645{
646 Evas_Coord x, y;
647 double xsub, ysub;
648};
649
650struct _Evas_Position
651{
652 Evas_Point output;
653 Evas_Coord_Point canvas;
654};
655
656struct _Evas_Precision_Position
657{
658 Evas_Point output;
659 Evas_Coord_Precision_Point canvas;
660};
661
662typedef enum _Evas_Aspect_Control
663{
664 EVAS_ASPECT_CONTROL_NONE = 0, /**< Preference on scaling unset */
665 EVAS_ASPECT_CONTROL_NEITHER = 1, /**< Same effect as unset preference on scaling */
666 EVAS_ASPECT_CONTROL_HORIZONTAL = 2, /**< Use all horizontal container space to place an object, using the given aspect */
667 EVAS_ASPECT_CONTROL_VERTICAL = 3, /**< Use all vertical container space to place an object, using the given aspect */
668 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 */
669} Evas_Aspect_Control; /**< Aspect types/policies for scaling size hints, used for evas_object_size_hint_aspect_set() */
670
671typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< A source description of pixels for importing pixels */
672typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< A generic Evas Engine information structure */
673typedef struct _Evas_Device Evas_Device; /**< A source device handle - where the event came from */
674typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
675typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
676typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
677typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
678typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
679typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
680typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
681typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
682typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
683typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
684typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
685typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< Event structure for #EVAS_CALLBACK_HOLD event callbacks */
686
687typedef enum _Evas_Load_Error
688{
689 EVAS_LOAD_ERROR_NONE = 0, /**< No error on load */
690 EVAS_LOAD_ERROR_GENERIC = 1, /**< A non-specific error occurred */
691 EVAS_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< File (or file path) does not exist */
692 EVAS_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission deinied to an existing file (or path) */
693 EVAS_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Allocation of resources failure prevented load */
694 EVAS_LOAD_ERROR_CORRUPT_FILE = 5, /**< File corrupt (but was detected as a known format) */
695 EVAS_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */
696} Evas_Load_Error; /**< Evas image load error codes one can get - see evas_load_error_str() too. */
697
698
699typedef enum _Evas_Alloc_Error
700{
701 EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */
702 EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */
703 EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded, but extra memory had to be found by freeing up speculative resources */
704} Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */
705
706typedef enum _Evas_Fill_Spread
707{
708 EVAS_TEXTURE_REFLECT = 0, /**< image fill tiling mode - tiling reflects */
709 EVAS_TEXTURE_REPEAT = 1, /**< tiling repeats */
710 EVAS_TEXTURE_RESTRICT = 2, /**< tiling clamps - range offset ignored */
711 EVAS_TEXTURE_RESTRICT_REFLECT = 3, /**< tiling clamps and any range offset reflects */
712 EVAS_TEXTURE_RESTRICT_REPEAT = 4, /**< tiling clamps and any range offset repeats */
713 EVAS_TEXTURE_PAD = 5 /**< tiling extends with end values */
714} Evas_Fill_Spread; /**< Fill types used for evas_object_image_fill_spread_set() */
715
716typedef enum _Evas_Pixel_Import_Pixel_Format
717{
718 EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
719 EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
720 EVAS_PIXEL_FORMAT_YUV420P_601 = 2 /**< YUV 420 Planar format with CCIR 601 color encoding wuth contiguous planes in the order Y, U and V */
721} Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
722
723struct _Evas_Pixel_Import_Source
724{
725 Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
726 int w, h; /**< width and height of source in pixels */
727 void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
728};
729
730/* magic version number to know what the native surf struct looks like */
731#define EVAS_NATIVE_SURFACE_VERSION 2
732
733typedef enum _Evas_Native_Surface_Type
734{
735 EVAS_NATIVE_SURFACE_NONE,
736 EVAS_NATIVE_SURFACE_X11,
737 EVAS_NATIVE_SURFACE_OPENGL
738} Evas_Native_Surface_Type;
739
740struct _Evas_Native_Surface
741{
742 int version;
743 Evas_Native_Surface_Type type;
744 union {
745 struct {
746 void *visual; /**< visual of the pixmap to use (Visual) */
747 unsigned long pixmap; /**< pixmap id to use (Pixmap) */
748 } x11;
749 struct {
750 unsigned int texture_id; /**< opengl texture id to use from glGenTextures() */
751 unsigned int framebuffer_id; /**< 0 if not a FBO, FBO id otherwise from glGenFramebuffers() */
752 unsigned int internal_format; /**< same as 'internalFormat' for glTexImage2D() */
753 unsigned int format; /**< same as 'format' for glTexImage2D() */
754 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) */
755 } opengl;
756 } data;
757};
758
759/**
760 * @def EVAS_VIDEO_SURFACE_VERSION
761 * Magic version number to know what the video surf struct looks like
762 * @since 1.1.0
763 */
764#define EVAS_VIDEO_SURFACE_VERSION 1
765
766typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface);
767typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b);
768
769struct _Evas_Video_Surface
770{
771 int version;
772
773 Evas_Video_Coord_Cb move; /**< Move the video surface to this position */
774 Evas_Video_Coord_Cb resize; /**< Resize the video surface to that size */
775 Evas_Video_Cb show; /**< Show the video overlay surface */
776 Evas_Video_Cb hide; /**< Hide the video overlay surface */
777 Evas_Video_Cb update_pixels; /**< Please update the Evas_Object_Image pixels when called */
778
779 Evas_Object *parent;
780 void *data;
781};
782
783#define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
784#define EVAS_LAYER_MAX 32767 /**< top-most layer number */
785
786#define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
787#define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
788#define EVAS_TEXT_INVALID -1 /**< Not used for anything */
789#define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
790
791#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() */
792#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() */
793#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) */
794#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) */
795#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 */
796#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 */
797
798/**
799 * How the object should be rendered to output.
800 * @ingroup Evas_Object_Group_Extras
801 */
802typedef enum _Evas_Render_Op
803{
804 EVAS_RENDER_BLEND = 0, /**< default op: d = d*(1-sa) + s */
805 EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
806 EVAS_RENDER_COPY = 2, /**< d = s */
807 EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
808 EVAS_RENDER_ADD = 4, /**< d = d + s */
809 EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
810 EVAS_RENDER_SUB = 6, /**< d = d - s */
811 EVAS_RENDER_SUB_REL = 7, /**< d = d - s*da */
812 EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
813 EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
814 EVAS_RENDER_MASK = 10, /**< d = d*sa */
815 EVAS_RENDER_MUL = 11 /**< d = d*s */
816} Evas_Render_Op; /**< How the object should be rendered to output. */
817
818typedef enum _Evas_Border_Fill_Mode
819{
820 EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */
821 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 */
822 EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */
823} Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */
824
825typedef enum _Evas_Image_Scale_Hint
826{
827 EVAS_IMAGE_SCALE_HINT_NONE = 0, /**< No scale hint at all */
828 EVAS_IMAGE_SCALE_HINT_DYNAMIC = 1, /**< Image is being re-scaled over time, thus turning scaling cache @b off for its data */
829 EVAS_IMAGE_SCALE_HINT_STATIC = 2 /**< Image is not being re-scaled over time, thus turning scaling cache @b on for its data */
830} Evas_Image_Scale_Hint; /**< How an image's data is to be treated by Evas, with regard to scaling cache */
831
832typedef enum _Evas_Image_Animated_Loop_Hint
833{
834 EVAS_IMAGE_ANIMATED_HINT_NONE = 0,
835 EVAS_IMAGE_ANIMATED_HINT_LOOP = 1, /**< Image's animation mode is loop like 1->2->3->1->2->3 */
836 EVAS_IMAGE_ANIMATED_HINT_PINGPONG = 2 /**< Image's animation mode is pingpong like 1->2->3->2->1-> ... */
837} Evas_Image_Animated_Loop_Hint;
838
839typedef enum _Evas_Engine_Render_Mode
840{
841 EVAS_RENDER_MODE_BLOCKING = 0,
842 EVAS_RENDER_MODE_NONBLOCKING = 1,
843} Evas_Engine_Render_Mode;
844
845typedef enum _Evas_Image_Content_Hint
846{
847 EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
848 EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents will change over time */
849 EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents won't change over time */
850} Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
851
852struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
853{
854 int magic; /**< Magic number */
855};
856
857struct _Evas_Event_Mouse_Down /** Mouse button press event */
858{
859 int button; /**< Mouse button number that went down (1 - 32) */
860
861 Evas_Point output; /**< The X/Y location of the cursor */
862 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
863
864 void *data;
865 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
866 Evas_Lock *locks;
867
868 Evas_Button_Flags flags; /**< button flags set during the event */
869 unsigned int timestamp;
870 Evas_Event_Flags event_flags;
871 Evas_Device *dev;
872};
873
874struct _Evas_Event_Mouse_Up /** Mouse button release event */
875{
876 int button; /**< Mouse button number that was raised (1 - 32) */
877
878 Evas_Point output;
879 Evas_Coord_Point canvas;
880
881 void *data;
882 Evas_Modifier *modifiers;
883 Evas_Lock *locks;
884
885 Evas_Button_Flags flags;
886 unsigned int timestamp;
887 Evas_Event_Flags event_flags;
888 Evas_Device *dev;
889};
890
891struct _Evas_Event_Mouse_In /** Mouse enter event */
892{
893 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
894
895 Evas_Point output;
896 Evas_Coord_Point canvas;
897
898 void *data;
899 Evas_Modifier *modifiers;
900 Evas_Lock *locks;
901 unsigned int timestamp;
902 Evas_Event_Flags event_flags;
903 Evas_Device *dev;
904};
905
906struct _Evas_Event_Mouse_Out /** Mouse leave event */
907{
908 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
909
910
911 Evas_Point output;
912 Evas_Coord_Point canvas;
913
914 void *data;
915 Evas_Modifier *modifiers;
916 Evas_Lock *locks;
917 unsigned int timestamp;
918 Evas_Event_Flags event_flags;
919 Evas_Device *dev;
920};
921
922struct _Evas_Event_Mouse_Move /** Mouse button down event */
923{
924 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
925
926 Evas_Position cur, prev;
927
928 void *data;
929 Evas_Modifier *modifiers;
930 Evas_Lock *locks;
931 unsigned int timestamp;
932 Evas_Event_Flags event_flags;
933 Evas_Device *dev;
934};
935
936struct _Evas_Event_Mouse_Wheel /** Wheel event */
937{
938 int direction; /* 0 = default up/down wheel FIXME: more wheel types */
939 int z; /* ...,-2,-1 = down, 1,2,... = up */
940
941 Evas_Point output;
942 Evas_Coord_Point canvas;
943
944 void *data;
945 Evas_Modifier *modifiers;
946 Evas_Lock *locks;
947 unsigned int timestamp;
948 Evas_Event_Flags event_flags;
949 Evas_Device *dev;
950};
951
952struct _Evas_Event_Multi_Down /** Multi button press event */
953{
954 int device; /**< Multi device number that went down (1 or more for extra touches) */
955 double radius, radius_x, radius_y;
956 double pressure, angle;
957
958 Evas_Point output;
959 Evas_Coord_Precision_Point canvas;
960
961 void *data;
962 Evas_Modifier *modifiers;
963 Evas_Lock *locks;
964
965 Evas_Button_Flags flags;
966 unsigned int timestamp;
967 Evas_Event_Flags event_flags;
968 Evas_Device *dev;
969};
970
971struct _Evas_Event_Multi_Up /** Multi button release event */
972{
973 int device; /**< Multi device number that went up (1 or more for extra touches) */
974 double radius, radius_x, radius_y;
975 double pressure, angle;
976
977 Evas_Point output;
978 Evas_Coord_Precision_Point canvas;
979
980 void *data;
981 Evas_Modifier *modifiers;
982 Evas_Lock *locks;
983
984 Evas_Button_Flags flags;
985 unsigned int timestamp;
986 Evas_Event_Flags event_flags;
987 Evas_Device *dev;
988};
989
990struct _Evas_Event_Multi_Move /** Multi button down event */
991{
992 int device; /**< Multi device number that moved (1 or more for extra touches) */
993 double radius, radius_x, radius_y;
994 double pressure, angle;
995
996 Evas_Precision_Position cur;
997
998 void *data;
999 Evas_Modifier *modifiers;
1000 Evas_Lock *locks;
1001 unsigned int timestamp;
1002 Evas_Event_Flags event_flags;
1003 Evas_Device *dev;
1004};
1005
1006struct _Evas_Event_Key_Down /** Key press event */
1007{
1008 char *keyname; /**< the name string of the key pressed */
1009 void *data;
1010 Evas_Modifier *modifiers;
1011 Evas_Lock *locks;
1012
1013 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
1014 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
1015 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 */
1016 unsigned int timestamp;
1017 Evas_Event_Flags event_flags;
1018 Evas_Device *dev;
1019};
1020
1021struct _Evas_Event_Key_Up /** Key release event */
1022{
1023 char *keyname; /**< the name string of the key released */
1024 void *data;
1025 Evas_Modifier *modifiers;
1026 Evas_Lock *locks;
1027
1028 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
1029 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
1030 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 */
1031 unsigned int timestamp;
1032 Evas_Event_Flags event_flags;
1033 Evas_Device *dev;
1034};
1035
1036struct _Evas_Event_Hold /** Hold change event */
1037{
1038 int hold; /**< The hold flag */
1039 void *data;
1040
1041 unsigned int timestamp;
1042 Evas_Event_Flags event_flags;
1043 Evas_Device *dev;
1044};
1045
1046/**
1047 * How the mouse pointer should be handled by Evas.
1048 *
1049 * In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button
1050 * is pressed down over an object and held, with the mouse pointer
1051 * being moved outside of it, the pointer still behaves as being bound
1052 * to that object, albeit out of its drawing region. When the button
1053 * is released, the event will be fed to the object, that may check if
1054 * the final position is over it or not and do something about it.
1055 *
1056 * In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will
1057 * always be bound to the object right below it.
1058 *
1059 * @ingroup Evas_Object_Group_Extras
1060 */
1061typedef enum _Evas_Object_Pointer_Mode
1062{
1063 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
1064 EVAS_OBJECT_POINTER_MODE_NOGRAB /**< pointer always bound to the object right below it */
1065} Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
1066
1067typedef void (*Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info); /**< Evas smart objects' "smart callback" function signature */
1068typedef void (*Evas_Event_Cb) (void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
1069typedef Eina_Bool (*Evas_Object_Event_Post_Cb) (void *data, Evas *e);
1070typedef void (*Evas_Object_Event_Cb) (void *data, Evas *e, Evas_Object *obj, void *event_info); /**< Evas object event callback function signature */
1071typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
1072
1073/**
1074 * @defgroup Evas_Group Top Level Functions
1075 *
1076 * Functions that affect Evas as a whole.
1077 */
1078
1079/**
1080 * Initialize Evas
1081 *
1082 * @return The init counter value.
1083 *
1084 * This function initializes Evas and increments a counter of the
1085 * number of calls to it. It returns the new counter's value.
1086 *
1087 * @see evas_shutdown().
1088 *
1089 * Most EFL users wouldn't be using this function directly, because
1090 * they wouldn't access Evas directly by themselves. Instead, they
1091 * would be using higher level helpers, like @c ecore_evas_init().
1092 * See http://docs.enlightenment.org/auto/ecore/.
1093 *
1094 * You should be using this if your use is something like the
1095 * following. The buffer engine is just one of the many ones Evas
1096 * provides.
1097 *
1098 * @dontinclude evas-buffer-simple.c
1099 * @skip int main
1100 * @until return -1;
1101 * And being the canvas creation something like:
1102 * @skip static Evas *create_canvas
1103 * @until evas_output_viewport_set(canvas,
1104 *
1105 * Note that this is code creating an Evas canvas with no usage of
1106 * Ecore helpers at all -- no linkage with Ecore on this scenario,
1107 * thus. Again, this wouldn't be on Evas common usage for most
1108 * developers. See the full @ref Example_Evas_Buffer_Simple "example".
1109 *
1110 * @ingroup Evas_Group
1111 */
1112EAPI int evas_init (void);
1113
1114/**
1115 * Shutdown Evas
1116 *
1117 * @return Evas' init counter value.
1118 *
1119 * This function finalizes Evas, decrementing the counter of the
1120 * number of calls to the function evas_init(). This new value for the
1121 * counter is returned.
1122 *
1123 * @see evas_init().
1124 *
1125 * If you were the sole user of Evas, by means of evas_init(), you can
1126 * check if it's being properly shut down by expecting a return value
1127 * of 0.
1128 *
1129 * Example code follows.
1130 * @dontinclude evas-buffer-simple.c
1131 * @skip // NOTE: use ecore_evas_buffer_new
1132 * @until evas_shutdown
1133 * Where that function would contain:
1134 * @skip evas_free(canvas)
1135 * @until evas_free(canvas)
1136 *
1137 * Most users would be using ecore_evas_shutdown() instead, like told
1138 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
1139 * "example".
1140 *
1141 * @ingroup Evas_Group
1142 */
1143EAPI int evas_shutdown (void);
1144
1145
1146/**
1147 * Return if any allocation errors have occurred during the prior function
1148 * @return The allocation error flag
1149 *
1150 * This function will return if any memory allocation errors occurred during,
1151 * and what kind they were. The return value will be one of
1152 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
1153 * with each meaning something different.
1154 *
1155 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
1156 * worked as expected.
1157 *
1158 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
1159 * its job and will have exited as cleanly as possible. The programmer
1160 * should consider this as a sign of very low memory and should try and safely
1161 * recover from the prior functions failure (or try free up memory elsewhere
1162 * and try again after more memory is freed).
1163 *
1164 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
1165 * recovered from by evas finding memory of its own it has allocated and
1166 * freeing what it sees as not really usefully allocated memory. What is freed
1167 * may vary. Evas may reduce the resolution of images, free cached images or
1168 * fonts, trhow out pre-rendered data, reduce the complexity of change lists
1169 * etc. Evas and the program will function as per normal after this, but this
1170 * is a sign of low memory, and it is suggested that the program try and
1171 * identify memory it doesn't need, and free it.
1172 *
1173 * Example:
1174 * @code
1175 * extern Evas_Object *object;
1176 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
1177 *
1178 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
1179 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
1180 * {
1181 * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
1182 * fprintf(stderr, " destroy object now as it cannot be used.\n");
1183 * evas_object_del(object);
1184 * object = NULL;
1185 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1186 * my_memory_cleanup();
1187 * }
1188 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
1189 * {
1190 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1191 * my_memory_cleanup();
1192 * }
1193 * @endcode
1194 *
1195 * @ingroup Evas_Group
1196 */
1197EAPI Evas_Alloc_Error evas_alloc_error (void);
1198
1199
1200/**
1201 * @brief Get evas' internal asynchronous events read file descriptor.
1202 *
1203 * @return The canvas' asynchronous events read file descriptor.
1204 *
1205 * Evas' asynchronous events are meant to be dealt with internally,
1206 * i. e., when building stuff to be glued together into the EFL
1207 * infrastructure -- a module, for example. The context which demands
1208 * its use is when calculations need to be done out of the main
1209 * thread, asynchronously, and some action must be performed after
1210 * that.
1211 *
1212 * An example of actual use of this API is for image asynchronous
1213 * preload inside evas. If the canvas was instantiated through
1214 * ecore-evas usage, ecore itself will take care of calling those
1215 * events' processing.
1216 *
1217 * This function returns the read file descriptor where to get the
1218 * asynchronous events of the canvas. Naturally, other mainloops,
1219 * apart from ecore, may make use of it.
1220 *
1221 * @ingroup Evas_Group
1222 */
1223EAPI int evas_async_events_fd_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE;
1224
1225/**
1226 * @brief Trigger the processing of all events waiting on the file
1227 * descriptor returned by evas_async_events_fd_get().
1228 *
1229 * @return The number of events processed.
1230 *
1231 * All asynchronous events queued up by evas_async_events_put() are
1232 * processed here. More precisely, the callback functions, informed
1233 * together with other event parameters, when queued, get called (with
1234 * those parameters), in that order.
1235 *
1236 * @ingroup Evas_Group
1237 */
1238EAPI int evas_async_events_process (void);
1239
1240/**
1241* Insert asynchronous events on the canvas.
1242 *
1243 * @param target The target to be affected by the events.
1244 * @param type The type of callback function.
1245 * @param event_info Information about the event.
1246 * @param func The callback function pointer.
1247 *
1248 * This is the way, for a routine running outside evas' main thread,
1249 * to report an asynchronous event. A callback function is informed,
1250 * whose call is to happen after evas_async_events_process() is
1251 * called.
1252 *
1253 * @ingroup Evas_Group
1254 */
1255EAPI 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);
1256
1257/**
1258 * @defgroup Evas_Canvas Canvas Functions
1259 *
1260 * Low level Evas canvas functions. Sub groups will present more high
1261 * level ones, though.
1262 *
1263 * Most of these functions deal with low level Evas actions, like:
1264 * @li create/destroy raw canvases, not bound to any displaying engine
1265 * @li tell a canvas i got focused (in a windowing context, for example)
1266 * @li tell a canvas a region should not be calculated anymore in rendering
1267 * @li tell a canvas to render its contents, immediately
1268 *
1269 * Most users will be using Evas by means of the @c Ecore_Evas
1270 * wrapper, which deals with all the above mentioned issues
1271 * automatically for them. Thus, you'll be looking at this section
1272 * only if you're building low level stuff.
1273 *
1274 * The groups within present you functions that deal with the canvas
1275 * directly, too, and not yet with its @b objects. They are the
1276 * functions you need to use at a minimum to get a working canvas.
1277 *
1278 * Some of the funcions in this group are exemplified @ref
1279 * Example_Evas_Events "here".
1280 */
1281
1282/**
1283 * Creates a new empty evas.
1284 *
1285 * Note that before you can use the evas, you will to at a minimum:
1286 * @li Set its render method with @ref evas_output_method_set .
1287 * @li Set its viewport size with @ref evas_output_viewport_set .
1288 * @li Set its size of the canvas with @ref evas_output_size_set .
1289 * @li Ensure that the render engine is given the correct settings
1290 * with @ref evas_engine_info_set .
1291 *
1292 * This function should only fail if the memory allocation fails
1293 *
1294 * @note this function is very low level. Instead of using it
1295 * directly, consider using the high level functions in
1296 * Ecore_Evas such as @c ecore_evas_new(). See
1297 * http://docs.enlightenment.org/auto/ecore/.
1298 *
1299 * @attention it is recommended that one calls evas_init() before
1300 * creating new canvas.
1301 *
1302 * @return A new uninitialised Evas canvas on success. Otherwise, @c
1303 * NULL.
1304 * @ingroup Evas_Canvas
1305 */
1306EAPI Evas *evas_new (void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
1307
1308/**
1309 * Frees the given evas and any objects created on it.
1310 *
1311 * Any objects with 'free' callbacks will have those callbacks called
1312 * in this function.
1313 *
1314 * @param e The given evas.
1315 *
1316 * @ingroup Evas_Canvas
1317 */
1318EAPI void evas_free (Evas *e) EINA_ARG_NONNULL(1);
1319
1320/**
1321 * Inform to the evas that it got the focus.
1322 *
1323 * @param e The evas to change information.
1324 * @ingroup Evas_Canvas
1325 */
1326EAPI void evas_focus_in (Evas *e);
1327
1328/**
1329 * Inform to the evas that it lost the focus.
1330 *
1331 * @param e The evas to change information.
1332 * @ingroup Evas_Canvas
1333 */
1334EAPI void evas_focus_out (Evas *e);
1335
1336/**
1337 * Get the focus state known by the given evas
1338 *
1339 * @param e The evas to query information.
1340 * @ingroup Evas_Canvas
1341 */
1342EAPI Eina_Bool evas_focus_state_get (const Evas *e) EINA_PURE;
1343
1344/**
1345 * Push the nochange flag up 1
1346 *
1347 * This tells evas, that while the nochange flag is greater than 0, do not
1348 * mark objects as "changed" when making changes.
1349 *
1350 * @param e The evas to change information.
1351 * @ingroup Evas_Canvas
1352 */
1353EAPI void evas_nochange_push (Evas *e);
1354
1355/**
1356 * Pop the nochange flag down 1
1357 *
1358 * This tells evas, that while the nochange flag is greater than 0, do not
1359 * mark objects as "changed" when making changes.
1360 *
1361 * @param e The evas to change information.
1362 * @ingroup Evas_Canvas
1363 */
1364EAPI void evas_nochange_pop (Evas *e);
1365
1366
1367/**
1368 * Attaches a specific pointer to the evas for fetching later
1369 *
1370 * @param e The canvas to attach the pointer to
1371 * @param data The pointer to attach
1372 * @ingroup Evas_Canvas
1373 */
1374EAPI void evas_data_attach_set (Evas *e, void *data) EINA_ARG_NONNULL(1);
1375
1376/**
1377 * Returns the pointer attached by evas_data_attach_set()
1378 *
1379 * @param e The canvas to attach the pointer to
1380 * @return The pointer attached
1381 * @ingroup Evas_Canvas
1382 */
1383EAPI void *evas_data_attach_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1384
1385
1386/**
1387 * Add a damage rectangle.
1388 *
1389 * @param e The given canvas pointer.
1390 * @param x The rectangle's left position.
1391 * @param y The rectangle's top position.
1392 * @param w The rectangle's width.
1393 * @param h The rectangle's height.
1394 *
1395 * This is the function by which one tells evas that a part of the
1396 * canvas has to be repainted.
1397 *
1398 * @ingroup Evas_Canvas
1399 */
1400EAPI void evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1401
1402/**
1403 * Add an "obscured region" to an Evas canvas.
1404 *
1405 * @param e The given canvas pointer.
1406 * @param x The rectangle's top left corner's horizontal coordinate.
1407 * @param y The rectangle's top left corner's vertical coordinate
1408 * @param w The rectangle's width.
1409 * @param h The rectangle's height.
1410 *
1411 * This is the function by which one tells an Evas canvas that a part
1412 * of it <b>must not</b> be repainted. The region must be
1413 * rectangular and its coordinates inside the canvas viewport are
1414 * passed in the call. After this call, the region specified won't
1415 * participate in any form in Evas' calculations and actions during
1416 * its rendering updates, having its displaying content frozen as it
1417 * was just after this function took place.
1418 *
1419 * We call it "obscured region" because the most common use case for
1420 * this rendering (partial) freeze is something else (most problaby
1421 * other canvas) being on top of the specified rectangular region,
1422 * thus shading it completely from the user's final scene in a
1423 * display. To avoid unnecessary processing, one should indicate to the
1424 * obscured canvas not to bother about the non-important area.
1425 *
1426 * The majority of users won't have to worry about this funcion, as
1427 * they'll be using just one canvas in their applications, with
1428 * nothing inset or on top of it in any form.
1429 *
1430 * To make this region one that @b has to be repainted again, call the
1431 * function evas_obscured_clear().
1432 *
1433 * @note This is a <b>very low level function</b>, which most of
1434 * Evas' users wouldn't care about.
1435 *
1436 * @note This function does @b not flag the canvas as having its state
1437 * changed. If you want to re-render it afterwards expecting new
1438 * contents, you have to add "damage" regions yourself (see
1439 * evas_damage_rectangle_add()).
1440 *
1441 * @see evas_obscured_clear()
1442 * @see evas_render_updates()
1443 *
1444 * Example code follows.
1445 * @dontinclude evas-events.c
1446 * @skip add an obscured
1447 * @until evas_obscured_clear(evas);
1448 *
1449 * In that example, pressing the "Ctrl" and "o" keys will impose or
1450 * remove an obscured region in the middle of the canvas. You'll get
1451 * the same contents at the time the key was pressed, if toggling it
1452 * on, until you toggle it off again (make sure the animation is
1453 * running on to get the idea better). See the full @ref
1454 * Example_Evas_Events "example".
1455 *
1456 * @ingroup Evas_Canvas
1457 */
1458EAPI void evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1459
1460/**
1461 * Remove all "obscured regions" from an Evas canvas.
1462 *
1463 * @param e The given canvas pointer.
1464 *
1465 * This function removes all the rectangles from the obscured regions
1466 * list of the canvas @p e. It takes obscured areas added with
1467 * evas_obscured_rectangle_add() and make them again a regions that @b
1468 * have to be repainted on rendering updates.
1469 *
1470 * @note This is a <b>very low level function</b>, which most of
1471 * Evas' users wouldn't care about.
1472 *
1473 * @note This function does @b not flag the canvas as having its state
1474 * changed. If you want to re-render it afterwards expecting new
1475 * contents, you have to add "damage" regions yourself (see
1476 * evas_damage_rectangle_add()).
1477 *
1478 * @see evas_obscured_rectangle_add() for an example
1479 * @see evas_render_updates()
1480 *
1481 * @ingroup Evas_Canvas
1482 */
1483EAPI void evas_obscured_clear (Evas *e) EINA_ARG_NONNULL(1);
1484
1485/**
1486 * Force immediate renderization of the given Evas canvas.
1487 *
1488 * @param e The given canvas pointer.
1489 * @return A newly allocated list of updated rectangles of the canvas
1490 * (@c Eina_Rectangle structs). Free this list with
1491 * evas_render_updates_free().
1492 *
1493 * This function forces an immediate renderization update of the given
1494 * canvas @e.
1495 *
1496 * @note This is a <b>very low level function</b>, which most of
1497 * Evas' users wouldn't care about. One would use it, for example, to
1498 * grab an Evas' canvas update regions and paint them back, using the
1499 * canvas' pixmap, on a displaying system working below Evas.
1500 *
1501 * @note Evas is a stateful canvas. If no operations changing its
1502 * state took place since the last rendering action, you won't see no
1503 * changes and this call will be a no-op.
1504 *
1505 * Example code follows.
1506 * @dontinclude evas-events.c
1507 * @skip add an obscured
1508 * @until d.obscured = !d.obscured;
1509 *
1510 * See the full @ref Example_Evas_Events "example".
1511 *
1512 * @ingroup Evas_Canvas
1513 */
1514EAPI Eina_List *evas_render_updates (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1515
1516/**
1517 * Free the rectangles returned by evas_render_updates().
1518 *
1519 * @param updates The list of updated rectangles of the canvas.
1520 *
1521 * This function removes the region from the render updates list. It
1522 * makes the region doesn't be render updated anymore.
1523 *
1524 * @see evas_render_updates() for an example
1525 *
1526 * @ingroup Evas_Canvas
1527 */
1528EAPI void evas_render_updates_free (Eina_List *updates);
1529
1530/**
1531 * Force renderization of the given canvas.
1532 *
1533 * @param e The given canvas pointer.
1534 *
1535 * @ingroup Evas_Canvas
1536 */
1537EAPI void evas_render (Evas *e) EINA_ARG_NONNULL(1);
1538
1539/**
1540 * Update the canvas internal objects but not triggering immediate
1541 * renderization.
1542 *
1543 * @param e The given canvas pointer.
1544 *
1545 * This function updates the canvas internal objects not triggering
1546 * renderization. To force renderization function evas_render() should
1547 * be used.
1548 *
1549 * @see evas_render.
1550 *
1551 * @ingroup Evas_Canvas
1552 */
1553EAPI void evas_norender (Evas *e) EINA_ARG_NONNULL(1);
1554
1555/**
1556 * Make the canvas discard internally cached data used for rendering.
1557 *
1558 * @param e The given canvas pointer.
1559 *
1560 * This function flushes the arrays of delete, active and render objects.
1561 * Other things it may also discard are: shared memory segments,
1562 * temporary scratch buffers, cached data to avoid re-compute of that data etc.
1563 *
1564 * @ingroup Evas_Canvas
1565 */
1566EAPI void evas_render_idle_flush (Evas *e) EINA_ARG_NONNULL(1);
1567
1568/**
1569 * Make the canvas discard as much data as possible used by the engine at
1570 * runtime.
1571 *
1572 * @param e The given canvas pointer.
1573 *
1574 * This function will unload images, delete textures and much more, where
1575 * possible. You may also want to call evas_render_idle_flush() immediately
1576 * prior to this to perhaps discard a little more, though evas_render_dump()
1577 * should implicitly delete most of what evas_render_idle_flush() might
1578 * discard too.
1579 *
1580 * @ingroup Evas_Canvas
1581 */
1582EAPI void evas_render_dump (Evas *e) EINA_ARG_NONNULL(1);
1583
1584/**
1585 * @defgroup Evas_Output_Method Render Engine Functions
1586 *
1587 * Functions that are used to set the render engine for a given
1588 * function, and then get that engine working.
1589 *
1590 * The following code snippet shows how they can be used to
1591 * initialise an evas that uses the X11 software engine:
1592 * @code
1593 * Evas *evas;
1594 * Evas_Engine_Info_Software_X11 *einfo;
1595 * extern Display *display;
1596 * extern Window win;
1597 *
1598 * evas_init();
1599 *
1600 * evas = evas_new();
1601 * evas_output_method_set(evas, evas_render_method_lookup("software_x11"));
1602 * evas_output_size_set(evas, 640, 480);
1603 * evas_output_viewport_set(evas, 0, 0, 640, 480);
1604 * einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas);
1605 * einfo->info.display = display;
1606 * einfo->info.visual = DefaultVisual(display, DefaultScreen(display));
1607 * einfo->info.colormap = DefaultColormap(display, DefaultScreen(display));
1608 * einfo->info.drawable = win;
1609 * einfo->info.depth = DefaultDepth(display, DefaultScreen(display));
1610 * evas_engine_info_set(evas, (Evas_Engine_Info *)einfo);
1611 * @endcode
1612 *
1613 * @ingroup Evas_Canvas
1614 */
1615
1616/**
1617 * Look up a numeric ID from a string name of a rendering engine.
1618 *
1619 * @param name the name string of an engine
1620 * @return A numeric (opaque) ID for the rendering engine
1621 * @ingroup Evas_Output_Method
1622 *
1623 * This function looks up a numeric return value for the named engine
1624 * in the string @p name. This is a normal C string, NUL byte
1625 * terminated. The name is case sensitive. If the rendering engine is
1626 * available, a numeric ID for that engine is returned that is not
1627 * 0. If the engine is not available, 0 is returned, indicating an
1628 * invalid engine.
1629 *
1630 * The programmer should NEVER rely on the numeric ID of an engine
1631 * unless it is returned by this function. Programs should NOT be
1632 * written accessing render method ID's directly, without first
1633 * obtaining it from this function.
1634 *
1635 * @attention it is mandatory that one calls evas_init() before
1636 * looking up the render method.
1637 *
1638 * Example:
1639 * @code
1640 * int engine_id;
1641 * Evas *evas;
1642 *
1643 * evas_init();
1644 *
1645 * evas = evas_new();
1646 * if (!evas)
1647 * {
1648 * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
1649 * exit(-1);
1650 * }
1651 * engine_id = evas_render_method_lookup("software_x11");
1652 * if (!engine_id)
1653 * {
1654 * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
1655 * exit(-1);
1656 * }
1657 * evas_output_method_set(evas, engine_id);
1658 * @endcode
1659 */
1660EAPI int evas_render_method_lookup (const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1661
1662/**
1663 * List all the rendering engines compiled into the copy of the Evas library
1664 *
1665 * @return A linked list whose data members are C strings of engine names
1666 * @ingroup Evas_Output_Method
1667 *
1668 * Calling this will return a handle (pointer) to an Evas linked
1669 * list. Each node in the linked list will have the data pointer be a
1670 * (char *) pointer to the name string of the rendering engine
1671 * available. The strings should never be modified, neither should the
1672 * list be modified. This list should be cleaned up as soon as the
1673 * program no longer needs it using evas_render_method_list_free(). If
1674 * no engines are available from Evas, NULL will be returned.
1675 *
1676 * Example:
1677 * @code
1678 * Eina_List *engine_list, *l;
1679 * char *engine_name;
1680 *
1681 * engine_list = evas_render_method_list();
1682 * if (!engine_list)
1683 * {
1684 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1685 * exit(-1);
1686 * }
1687 * printf("Available Evas Engines:\n");
1688 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1689 * printf("%s\n", engine_name);
1690 * evas_render_method_list_free(engine_list);
1691 * @endcode
1692 */
1693EAPI Eina_List *evas_render_method_list (void) EINA_WARN_UNUSED_RESULT;
1694
1695/**
1696 * This function should be called to free a list of engine names
1697 *
1698 * @param list The Eina_List base pointer for the engine list to be freed
1699 * @ingroup Evas_Output_Method
1700 *
1701 * When this function is called it will free the engine list passed in
1702 * as @p list. The list should only be a list of engines generated by
1703 * calling evas_render_method_list(). If @p list is NULL, nothing will
1704 * happen.
1705 *
1706 * Example:
1707 * @code
1708 * Eina_List *engine_list, *l;
1709 * char *engine_name;
1710 *
1711 * engine_list = evas_render_method_list();
1712 * if (!engine_list)
1713 * {
1714 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1715 * exit(-1);
1716 * }
1717 * printf("Available Evas Engines:\n");
1718 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1719 * printf("%s\n", engine_name);
1720 * evas_render_method_list_free(engine_list);
1721 * @endcode
1722 */
1723EAPI void evas_render_method_list_free (Eina_List *list);
1724
1725
1726/**
1727 * Sets the output engine for the given evas.
1728 *
1729 * Once the output engine for an evas is set, any attempt to change it
1730 * will be ignored. The value for @p render_method can be found using
1731 * @ref evas_render_method_lookup .
1732 *
1733 * @param e The given evas.
1734 * @param render_method The numeric engine value to use.
1735 *
1736 * @attention it is mandatory that one calls evas_init() before
1737 * setting the output method.
1738 *
1739 * @ingroup Evas_Output_Method
1740 */
1741EAPI void evas_output_method_set (Evas *e, int render_method) EINA_ARG_NONNULL(1);
1742
1743/**
1744 * Retrieves the number of the output engine used for the given evas.
1745 * @param e The given evas.
1746 * @return The ID number of the output engine being used. @c 0 is
1747 * returned if there is an error.
1748 * @ingroup Evas_Output_Method
1749 */
1750EAPI int evas_output_method_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1751
1752
1753/**
1754 * Retrieves the current render engine info struct from the given evas.
1755 *
1756 * The returned structure is publicly modifiable. The contents are
1757 * valid until either @ref evas_engine_info_set or @ref evas_render
1758 * are called.
1759 *
1760 * This structure does not need to be freed by the caller.
1761 *
1762 * @param e The given evas.
1763 * @return A pointer to the Engine Info structure. @c NULL is returned if
1764 * an engine has not yet been assigned.
1765 * @ingroup Evas_Output_Method
1766 */
1767EAPI Evas_Engine_Info *evas_engine_info_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1768
1769/**
1770 * Applies the engine settings for the given evas from the given @c
1771 * Evas_Engine_Info structure.
1772 *
1773 * To get the Evas_Engine_Info structure to use, call @ref
1774 * evas_engine_info_get . Do not try to obtain a pointer to an
1775 * @c Evas_Engine_Info structure in any other way.
1776 *
1777 * You will need to call this function at least once before you can
1778 * create objects on an evas or render that evas. Some engines allow
1779 * their settings to be changed more than once.
1780 *
1781 * Once called, the @p info pointer should be considered invalid.
1782 *
1783 * @param e The pointer to the Evas Canvas
1784 * @param info The pointer to the Engine Info to use
1785 * @return 1 if no error occurred, 0 otherwise
1786 * @ingroup Evas_Output_Method
1787 */
1788EAPI Eina_Bool evas_engine_info_set (Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1);
1789
1790/**
1791 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1792 *
1793 * Functions that set and retrieve the output and viewport size of an
1794 * evas.
1795 *
1796 * @ingroup Evas_Canvas
1797 */
1798
1799/**
1800 * Sets the output size of the render engine of the given evas.
1801 *
1802 * The evas will render to a rectangle of the given size once this
1803 * function is called. The output size is independent of the viewport
1804 * size. The viewport will be stretched to fill the given rectangle.
1805 *
1806 * The units used for @p w and @p h depend on the engine used by the
1807 * evas.
1808 *
1809 * @param e The given evas.
1810 * @param w The width in output units, usually pixels.
1811 * @param h The height in output units, usually pixels.
1812 * @ingroup Evas_Output_Size
1813 */
1814EAPI void evas_output_size_set (Evas *e, int w, int h) EINA_ARG_NONNULL(1);
1815
1816/**
1817 * Retrieve the output size of the render engine of the given evas.
1818 *
1819 * The output size is given in whatever the output units are for the
1820 * engine.
1821 *
1822 * If either @p w or @p h is @c NULL, then it is ignored. If @p e is
1823 * invalid, the returned results are undefined.
1824 *
1825 * @param e The given evas.
1826 * @param w The pointer to an integer to store the width in.
1827 * @param h The pointer to an integer to store the height in.
1828 * @ingroup Evas_Output_Size
1829 */
1830EAPI void evas_output_size_get (const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1);
1831
1832/**
1833 * Sets the output viewport of the given evas in evas units.
1834 *
1835 * The output viewport is the area of the evas that will be visible to
1836 * the viewer. The viewport will be stretched to fit the output
1837 * target of the evas when rendering is performed.
1838 *
1839 * @note The coordinate values do not have to map 1-to-1 with the output
1840 * target. However, it is generally advised that it is done for ease
1841 * of use.
1842 *
1843 * @param e The given evas.
1844 * @param x The top-left corner x value of the viewport.
1845 * @param y The top-left corner y value of the viewport.
1846 * @param w The width of the viewport. Must be greater than 0.
1847 * @param h The height of the viewport. Must be greater than 0.
1848 * @ingroup Evas_Output_Size
1849 */
1850EAPI void evas_output_viewport_set (Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
1851
1852/**
1853 * Get the render engine's output viewport co-ordinates in canvas units.
1854 * @param e The pointer to the Evas Canvas
1855 * @param x The pointer to a x variable to be filled in
1856 * @param y The pointer to a y variable to be filled in
1857 * @param w The pointer to a width variable to be filled in
1858 * @param h The pointer to a height variable to be filled in
1859 * @ingroup Evas_Output_Size
1860 *
1861 * Calling this function writes the current canvas output viewport
1862 * size and location values into the variables pointed to by @p x, @p
1863 * y, @p w and @p h. On success the variables have the output
1864 * location and size values written to them in canvas units. Any of @p
1865 * x, @p y, @p w or @p h that are NULL will not be written to. If @p e
1866 * is invalid, the results are undefined.
1867 *
1868 * Example:
1869 * @code
1870 * extern Evas *evas;
1871 * Evas_Coord x, y, width, height;
1872 *
1873 * evas_output_viewport_get(evas, &x, &y, &w, &h);
1874 * @endcode
1875 */
1876EAPI void evas_output_viewport_get (const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
1877
1878/**
1879 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1880 *
1881 * Functions that are used to map coordinates from the canvas to the
1882 * screen or the screen to the canvas.
1883 *
1884 * @ingroup Evas_Canvas
1885 */
1886
1887/**
1888 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1889 *
1890 * @param e The pointer to the Evas Canvas
1891 * @param x The screen/output x co-ordinate
1892 * @return The screen co-ordinate translated to canvas unit co-ordinates
1893 * @ingroup Evas_Coord_Mapping_Group
1894 *
1895 * This function takes in a horizontal co-ordinate as the @p x
1896 * parameter and converts it into canvas units, accounting for output
1897 * size, viewport size and location, returning it as the function
1898 * return value. If @p e is invalid, the results are undefined.
1899 *
1900 * Example:
1901 * @code
1902 * extern Evas *evas;
1903 * extern int screen_x;
1904 * Evas_Coord canvas_x;
1905 *
1906 * canvas_x = evas_coord_screen_x_to_world(evas, screen_x);
1907 * @endcode
1908 */
1909EAPI Evas_Coord evas_coord_screen_x_to_world (const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1910
1911/**
1912 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1913 *
1914 * @param e The pointer to the Evas Canvas
1915 * @param y The screen/output y co-ordinate
1916 * @return The screen co-ordinate translated to canvas unit co-ordinates
1917 * @ingroup Evas_Coord_Mapping_Group
1918 *
1919 * This function takes in a vertical co-ordinate as the @p y parameter
1920 * and converts it into canvas units, accounting for output size,
1921 * viewport size and location, returning it as the function return
1922 * value. If @p e is invalid, the results are undefined.
1923 *
1924 * Example:
1925 * @code
1926 * extern Evas *evas;
1927 * extern int screen_y;
1928 * Evas_Coord canvas_y;
1929 *
1930 * canvas_y = evas_coord_screen_y_to_world(evas, screen_y);
1931 * @endcode
1932 */
1933EAPI Evas_Coord evas_coord_screen_y_to_world (const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1934
1935/**
1936 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1937 *
1938 * @param e The pointer to the Evas Canvas
1939 * @param x The canvas x co-ordinate
1940 * @return The output/screen co-ordinate translated to output co-ordinates
1941 * @ingroup Evas_Coord_Mapping_Group
1942 *
1943 * This function takes in a horizontal co-ordinate as the @p x
1944 * parameter and converts it into output units, accounting for output
1945 * size, viewport size and location, returning it as the function
1946 * return value. If @p e is invalid, the results are undefined.
1947 *
1948 * Example:
1949 * @code
1950 * extern Evas *evas;
1951 * int screen_x;
1952 * extern Evas_Coord canvas_x;
1953 *
1954 * screen_x = evas_coord_world_x_to_screen(evas, canvas_x);
1955 * @endcode
1956 */
1957EAPI int evas_coord_world_x_to_screen (const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1958
1959/**
1960 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1961 *
1962 * @param e The pointer to the Evas Canvas
1963 * @param y The canvas y co-ordinate
1964 * @return The output/screen co-ordinate translated to output co-ordinates
1965 * @ingroup Evas_Coord_Mapping_Group
1966 *
1967 * This function takes in a vertical co-ordinate as the @p x parameter
1968 * and converts it into output units, accounting for output size,
1969 * viewport size and location, returning it as the function return
1970 * value. If @p e is invalid, the results are undefined.
1971 *
1972 * Example:
1973 * @code
1974 * extern Evas *evas;
1975 * int screen_y;
1976 * extern Evas_Coord canvas_y;
1977 *
1978 * screen_y = evas_coord_world_y_to_screen(evas, canvas_y);
1979 * @endcode
1980 */
1981EAPI int evas_coord_world_y_to_screen (const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1982
1983/**
1984 * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
1985 *
1986 * Functions that deal with the status of the pointer (mouse cursor).
1987 *
1988 * @ingroup Evas_Canvas
1989 */
1990
1991/**
1992 * This function returns the current known pointer co-ordinates
1993 *
1994 * @param e The pointer to the Evas Canvas
1995 * @param x The pointer to an integer to be filled in
1996 * @param y The pointer to an integer to be filled in
1997 * @ingroup Evas_Pointer_Group
1998 *
1999 * This function returns the current known screen/output co-ordinates
2000 * of the mouse pointer and sets the contents of the integers pointed
2001 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
2002 * valid canvas the results of this function are undefined.
2003 *
2004 * Example:
2005 * @code
2006 * extern Evas *evas;
2007 * int mouse_x, mouse_y;
2008 *
2009 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
2010 * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y);
2011 * @endcode
2012 */
2013EAPI void evas_pointer_output_xy_get (const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1);
2014
2015/**
2016 * This function returns the current known pointer co-ordinates
2017 *
2018 * @param e The pointer to the Evas Canvas
2019 * @param x The pointer to a Evas_Coord to be filled in
2020 * @param y The pointer to a Evas_Coord to be filled in
2021 * @ingroup Evas_Pointer_Group
2022 *
2023 * This function returns the current known canvas unit co-ordinates of
2024 * the mouse pointer and sets the contents of the Evas_Coords pointed
2025 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
2026 * valid canvas the results of this function are undefined.
2027 *
2028 * Example:
2029 * @code
2030 * extern Evas *evas;
2031 * Evas_Coord mouse_x, mouse_y;
2032 *
2033 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
2034 * printf("Mouse is at canvas position %f, %f\n", mouse_x, mouse_y);
2035 * @endcode
2036 */
2037EAPI void evas_pointer_canvas_xy_get (const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
2038
2039/**
2040 * Returns a bitmask with the mouse buttons currently pressed, set to 1
2041 *
2042 * @param e The pointer to the Evas Canvas
2043 * @return A bitmask of the currently depressed buttons on the cavas
2044 * @ingroup Evas_Pointer_Group
2045 *
2046 * Calling this function will return a 32-bit integer with the
2047 * appropriate bits set to 1 that correspond to a mouse button being
2048 * depressed. This limits Evas to a mouse devices with a maximum of 32
2049 * buttons, but that is generally in excess of any host system's
2050 * pointing device abilities.
2051 *
2052 * A canvas by default begins with no mouse buttons being pressed and
2053 * only calls to evas_event_feed_mouse_down(),
2054 * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and
2055 * evas_event_feed_mouse_up_data() will alter that.
2056 *
2057 * The least significant bit corresponds to the first mouse button
2058 * (button 1) and the most significant bit corresponds to the last
2059 * mouse button (button 32).
2060 *
2061 * If @p e is not a valid canvas, the return value is undefined.
2062 *
2063 * Example:
2064 * @code
2065 * extern Evas *evas;
2066 * int button_mask, i;
2067 *
2068 * button_mask = evas_pointer_button_down_mask_get(evas);
2069 * printf("Buttons currently pressed:\n");
2070 * for (i = 0; i < 32; i++)
2071 * {
2072 * if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1);
2073 * }
2074 * @endcode
2075 */
2076EAPI int evas_pointer_button_down_mask_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2077
2078/**
2079 * Returns whether the mouse pointer is logically inside the canvas
2080 *
2081 * @param e The pointer to the Evas Canvas
2082 * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise
2083 * @ingroup Evas_Pointer_Group
2084 *
2085 * When this function is called it will return a value of either 0 or
2086 * 1, depending on if evas_event_feed_mouse_in(),
2087 * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(),
2088 * evas_event_feed_mouse_out_data() have been called to feed in a
2089 * mouse enter event into the canvas.
2090 *
2091 * A return value of 1 indicates the mouse is logically inside the
2092 * canvas, and 0 implies it is logically outside the canvas.
2093 *
2094 * A canvas begins with the mouse being assumed outside (0).
2095 *
2096 * If @p e is not a valid canvas, the return value is undefined.
2097 *
2098 * Example:
2099 * @code
2100 * extern Evas *evas;
2101 *
2102 * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n");
2103 * else printf("Mouse is out!\n");
2104 * @endcode
2105 */
2106EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
2107 EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1);
2108
2109/**
2110 * @defgroup Evas_Canvas_Events Canvas Events
2111 *
2112 * Functions relating to canvas events, which are mainly reports on
2113 * its internal states changing (an object got focused, the rendering
2114 * is updated, etc).
2115 *
2116 * Some of the funcions in this group are exemplified @ref
2117 * Example_Evas_Events "here".
2118 *
2119 * @ingroup Evas_Canvas
2120 */
2121
2122/**
2123 * @addtogroup Evas_Canvas_Events
2124 * @{
2125 */
2126
2127/**
2128 * Add (register) a callback function to a given canvas event.
2129 *
2130 * @param e Canvas to attach a callback to
2131 * @param type The type of event that will trigger the callback
2132 * @param func The (callback) function to be called when the event is
2133 * triggered
2134 * @param data The data pointer to be passed to @p func
2135 *
2136 * This function adds a function callback to the canvas @p e when the
2137 * event of type @p type occurs on it. The function pointer is @p
2138 * func.
2139 *
2140 * In the event of a memory allocation error during the addition of
2141 * the callback to the canvas, evas_alloc_error() should be used to
2142 * determine the nature of the error, if any, and the program should
2143 * sensibly try and recover.
2144 *
2145 * A callback function must have the ::Evas_Event_Cb prototype
2146 * definition. The first parameter (@p data) in this definition will
2147 * have the same value passed to evas_event_callback_add() as the @p
2148 * data parameter, at runtime. The second parameter @p e is the canvas
2149 * pointer on which the event occurred. The third parameter @p
2150 * event_info is a pointer to a data structure that may or may not be
2151 * passed to the callback, depending on the event type that triggered
2152 * the callback. This is so because some events don't carry extra
2153 * context with them, but others do.
2154 *
2155 * The event type @p type to trigger the function may be one of
2156 * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST,
2157 * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT,
2158 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and
2159 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of
2160 * event that will trigger the callback to be called. Only the last
2161 * two of the event types listed here provide useful event information
2162 * data -- a pointer to the recently focused Evas object. For the
2163 * others the @p event_info pointer is going to be @c NULL.
2164 *
2165 * Example:
2166 * @dontinclude evas-events.c
2167 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE
2168 * @until two canvas event callbacks
2169 *
2170 * Looking to the callbacks registered above,
2171 * @dontinclude evas-events.c
2172 * @skip called when our rectangle gets focus
2173 * @until let's have our events back
2174 *
2175 * we see that the canvas flushes its rendering pipeline
2176 * (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb
2177 * routine takes place: it has to redraw that image at a different
2178 * size. Also, the callback on an object being focused comes just
2179 * after we focus it explicitly, on code.
2180 *
2181 * See the full @ref Example_Evas_Events "example".
2182 *
2183 * @note Be careful not to add the same callback multiple times, if
2184 * that's not what you want, because Evas won't check if a callback
2185 * existed before exactly as the one being registered (and thus, call
2186 * it more than once on the event, in this case). This would make
2187 * sense if you passed different functions and/or callback data, only.
2188 */
2189EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2190
2191/**
2192 * Add (register) a callback function to a given canvas event with a
2193 * non-default priority set. Except for the priority field, it's exactly the
2194 * same as @ref evas_event_callback_add
2195 *
2196 * @param e Canvas to attach a callback to
2197 * @param type The type of event that will trigger the callback
2198 * @param priority The priority of the callback, lower values called first.
2199 * @param func The (callback) function to be called when the event is
2200 * triggered
2201 * @param data The data pointer to be passed to @p func
2202 *
2203 * @see evas_event_callback_add
2204 * @since 1.1.0
2205 */
2206EAPI 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);
2207
2208/**
2209 * Delete a callback function from the canvas.
2210 *
2211 * @param e Canvas to remove a callback from
2212 * @param type The type of event that was triggering the callback
2213 * @param func The function that was to be called when the event was triggered
2214 * @return The data pointer that was to be passed to the callback
2215 *
2216 * This function removes the most recently added callback from the
2217 * canvas @p e which was triggered by the event type @p type and was
2218 * calling the function @p func when triggered. If the removal is
2219 * successful it will also return the data pointer that was passed to
2220 * evas_event_callback_add() when the callback was added to the
2221 * canvas. If not successful NULL will be returned.
2222 *
2223 * Example:
2224 * @code
2225 * extern Evas *e;
2226 * void *my_data;
2227 * void focus_in_callback(void *data, Evas *e, void *event_info);
2228 *
2229 * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
2230 * @endcode
2231 */
2232EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
2233
2234/**
2235 * Delete (unregister) a callback function registered to a given
2236 * canvas event.
2237 *
2238 * @param e Canvas to remove an event callback from
2239 * @param type The type of event that was triggering the callback
2240 * @param func The function that was to be called when the event was
2241 * triggered
2242 * @param data The data pointer that was to be passed to the callback
2243 * @return The data pointer that was to be passed to the callback
2244 *
2245 * This function removes <b>the first</b> added callback from the
2246 * canvas @p e matching the event type @p type, the registered
2247 * function pointer @p func and the callback data pointer @p data. If
2248 * the removal is successful it will also return the data pointer that
2249 * was passed to evas_event_callback_add() (that will be the same as
2250 * the parameter) when the callback(s) was(were) added to the
2251 * canvas. If not successful @c NULL will be returned. A common use
2252 * would be to remove an exact match of a callback.
2253 *
2254 * Example:
2255 * @dontinclude evas-events.c
2256 * @skip evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
2257 * @until _object_focus_in_cb, NULL);
2258 *
2259 * See the full @ref Example_Evas_Events "example".
2260 *
2261 * @note For deletion of canvas events callbacks filtering by just
2262 * type and function pointer, user evas_event_callback_del().
2263 */
2264EAPI void *evas_event_callback_del_full (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2265
2266/**
2267 * Push a callback on the post-event callback stack
2268 *
2269 * @param e Canvas to push the callback on
2270 * @param func The function that to be called when the stack is unwound
2271 * @param data The data pointer to be passed to the callback
2272 *
2273 * Evas has a stack of callbacks that get called after all the callbacks for
2274 * an event have triggered (all the objects it triggers on and al the callbacks
2275 * in each object triggered). When all these have been called, the stack is
2276 * unwond from most recently to least recently pushed item and removed from the
2277 * stack calling the callback set for it.
2278 *
2279 * This is intended for doing reverse logic-like processing, example - when a
2280 * child object that happens to get the event later is meant to be able to
2281 * "steal" functions from a parent and thus on unwind of this stack hav its
2282 * function called first, thus being able to set flags, or return 0 from the
2283 * post-callback that stops all other post-callbacks in the current stack from
2284 * being called (thus basically allowing a child to take control, if the event
2285 * callback prepares information ready for taking action, but the post callback
2286 * actually does the action).
2287 *
2288 */
2289EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2290
2291/**
2292 * Remove a callback from the post-event callback stack
2293 *
2294 * @param e Canvas to push the callback on
2295 * @param func The function that to be called when the stack is unwound
2296 *
2297 * This removes a callback from the stack added with
2298 * evas_post_event_callback_push(). The first instance of the function in
2299 * the callback stack is removed from being executed when the stack is
2300 * unwound. Further instances may still be run on unwind.
2301 */
2302EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func);
2303
2304/**
2305 * Remove a callback from 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 * This removes a callback from the stack added with
2312 * evas_post_event_callback_push(). The first instance of the function and data
2313 * in the callback stack is removed from being executed when the stack is
2314 * unwound. Further instances may still be run on unwind.
2315 */
2316EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2317
2318/**
2319 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
2320 *
2321 * Functions that deal with the freezing of input event processing of
2322 * an Evas canvas.
2323 *
2324 * There might be scenarios during a graphical user interface
2325 * program's use when the developer whishes the users wouldn't be able
2326 * to deliver input events to this application. It may, for example,
2327 * be the time for it to populate a view or to change some
2328 * layout. Assuming proper behavior with user interaction during this
2329 * exact time would be hard, as things are in a changing state. The
2330 * programmer can then tell the canvas to ignore input events,
2331 * bringing it back to normal behavior when he/she wants.
2332 *
2333 * Some of the funcions in this group are exemplified @ref
2334 * Example_Evas_Events "here".
2335 *
2336 * @ingroup Evas_Canvas_Events
2337 */
2338
2339/**
2340 * @addtogroup Evas_Event_Freezing_Group
2341 * @{
2342 */
2343
2344/**
2345 * Freeze all input events processing.
2346 *
2347 * @param e The canvas to freeze input events processing on.
2348 *
2349 * This function will indicate to Evas that the canvas @p e is to have
2350 * all input event processing frozen until a matching
2351 * evas_event_thaw() function is called on the same canvas. All events
2352 * of this kind during the freeze will get @b discarded. Every freeze
2353 * call must be matched by a thaw call in order to completely thaw out
2354 * a canvas (i.e. these calls may be nested). The most common use is
2355 * when you don't want the user to interect with your user interface
2356 * when you're populating a view or changing the layout.
2357 *
2358 * Example:
2359 * @dontinclude evas-events.c
2360 * @skip freeze input for 3 seconds
2361 * @until }
2362 * @dontinclude evas-events.c
2363 * @skip let's have our events back
2364 * @until }
2365 *
2366 * See the full @ref Example_Evas_Events "example".
2367 *
2368 * If you run that example, you'll see the canvas ignoring all input
2369 * events for 3 seconds, when the "f" key is pressed. In a more
2370 * realistic code we would be freezing while a toolkit or Edje was
2371 * doing some UI changes, thawing it back afterwards.
2372 */
2373EAPI void evas_event_freeze (Evas *e) EINA_ARG_NONNULL(1);
2374
2375/**
2376 * Thaw a canvas out after freezing (for input events).
2377 *
2378 * @param e The canvas to thaw out.
2379 *
2380 * This will thaw out a canvas after a matching evas_event_freeze()
2381 * call. If this call completely thaws out a canvas, i.e., there's no
2382 * other unbalanced call to evas_event_freeze(), events will start to
2383 * be processed again, but any "missed" events will @b not be
2384 * evaluated.
2385 *
2386 * See evas_event_freeze() for an example.
2387 */
2388EAPI void evas_event_thaw (Evas *e) EINA_ARG_NONNULL(1);
2389
2390/**
2391 * Return the freeze count on input events of a given canvas.
2392 *
2393 * @param e The canvas to fetch the freeze count from.
2394 *
2395 * This returns the number of times the canvas has been told to freeze
2396 * input events. It is possible to call evas_event_freeze() multiple
2397 * times, and these must be matched by evas_event_thaw() calls. This
2398 * call allows the program to discover just how many times things have
2399 * been frozen in case it may want to break out of a deep freeze state
2400 * where the count is high.
2401 *
2402 * Example:
2403 * @code
2404 * extern Evas *evas;
2405 *
2406 * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
2407 * @endcode
2408 *
2409 */
2410EAPI int evas_event_freeze_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2411
2412/**
2413 * After thaw of a canvas, re-evaluate the state of objects and call callbacks
2414 *
2415 * @param e The canvas to evaluate after a thaw
2416 *
2417 * This is normally called after evas_event_thaw() to re-evaluate mouse
2418 * containment and other states and thus also call callbacks for mouse in and
2419 * out on new objects if the state change demands it.
2420 */
2421EAPI void evas_event_thaw_eval (Evas *e) EINA_ARG_NONNULL(1);
2422
2423/**
2424 * @}
2425 */
2426
2427/**
2428 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
2429 *
2430 * Functions to tell Evas that input events happened and should be
2431 * processed.
2432 *
2433 * As explained in @ref intro_not_evas, Evas does not know how to poll
2434 * for input events, so the developer should do it and then feed such
2435 * events to the canvas to be processed. This is only required if
2436 * operating Evas directly. Modules such as Ecore_Evas do that for
2437 * you.
2438 *
2439 * Some of the funcions in this group are exemplified @ref
2440 * Example_Evas_Events "here".
2441 *
2442 * @ingroup Evas_Canvas_Events
2443 */
2444
2445/**
2446 * @addtogroup Evas_Event_Feeding_Group
2447 * @{
2448 */
2449
2450/**
2451 * Mouse down event feed.
2452 *
2453 * @param e The given canvas pointer.
2454 * @param b The button number.
2455 * @param flags The evas button flags.
2456 * @param timestamp The timestamp of the mouse down event.
2457 * @param data The data for canvas.
2458 *
2459 * This function will set some evas properties that is necessary when
2460 * the mouse button is pressed. It prepares information to be treated
2461 * by the callback function.
2462 *
2463 */
2464EAPI void evas_event_feed_mouse_down (Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2465
2466/**
2467 * Mouse up event feed.
2468 *
2469 * @param e The given canvas pointer.
2470 * @param b The button number.
2471 * @param flags evas button flags.
2472 * @param timestamp The timestamp of the mouse up event.
2473 * @param data The data for canvas.
2474 *
2475 * This function will set some evas properties that is necessary when
2476 * the mouse button is released. It prepares information to be treated
2477 * by the callback function.
2478 *
2479 */
2480EAPI void evas_event_feed_mouse_up (Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2481
2482/**
2483 * Mouse move event feed.
2484 *
2485 * @param e The given canvas pointer.
2486 * @param x The horizontal position of the mouse pointer.
2487 * @param y The vertical position of the mouse pointer.
2488 * @param timestamp The timestamp of the mouse up event.
2489 * @param data The data for canvas.
2490 *
2491 * This function will set some evas properties that is necessary when
2492 * the mouse is moved from its last position. It prepares information
2493 * to be treated by the callback function.
2494 *
2495 */
2496EAPI void evas_event_feed_mouse_move (Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2497
2498/**
2499 * Mouse in event feed.
2500 *
2501 * @param e The given canvas pointer.
2502 * @param timestamp The timestamp of the mouse up event.
2503 * @param data The data for canvas.
2504 *
2505 * This function will set some evas properties that is necessary when
2506 * the mouse in event happens. It prepares information to be treated
2507 * by the callback function.
2508 *
2509 */
2510EAPI void evas_event_feed_mouse_in (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2511
2512/**
2513 * Mouse out event feed.
2514 *
2515 * @param e The given canvas pointer.
2516 * @param timestamp Timestamp of the mouse up event.
2517 * @param data The data for canvas.
2518 *
2519 * This function will set some evas properties that is necessary when
2520 * the mouse out event happens. It prepares information to be treated
2521 * by the callback function.
2522 *
2523 */
2524EAPI void evas_event_feed_mouse_out (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2525 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);
2526 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);
2527 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);
2528
2529/**
2530 * Mouse cancel event feed.
2531 *
2532 * @param e The given canvas pointer.
2533 * @param timestamp The timestamp of the mouse up event.
2534 * @param data The data for canvas.
2535 *
2536 * This function will call evas_event_feed_mouse_up() when a
2537 * mouse cancel event happens.
2538 *
2539 */
2540EAPI void evas_event_feed_mouse_cancel (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2541
2542/**
2543 * Mouse wheel event feed.
2544 *
2545 * @param e The given canvas pointer.
2546 * @param direction The wheel mouse direction.
2547 * @param z How much mouse wheel was scrolled up or down.
2548 * @param timestamp The timestamp of the mouse up event.
2549 * @param data The data for canvas.
2550 *
2551 * This function will set some evas properties that is necessary when
2552 * the mouse wheel is scrolled up or down. It prepares information to
2553 * be treated by the callback function.
2554 *
2555 */
2556EAPI void evas_event_feed_mouse_wheel (Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2557
2558/**
2559 * Key down event feed
2560 *
2561 * @param e The canvas to thaw out
2562 * @param keyname Name of the key
2563 * @param key The key pressed.
2564 * @param string A String
2565 * @param compose The compose string
2566 * @param timestamp Timestamp of the mouse up event
2567 * @param data Data for canvas.
2568 *
2569 * This function will set some evas properties that is necessary when
2570 * a key is pressed. It prepares information to be treated by the
2571 * callback function.
2572 *
2573 */
2574EAPI 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);
2575
2576/**
2577 * Key up event feed
2578 *
2579 * @param e The canvas to thaw out
2580 * @param keyname Name of the key
2581 * @param key The key released.
2582 * @param string string
2583 * @param compose compose
2584 * @param timestamp Timestamp of the mouse up event
2585 * @param data Data for canvas.
2586 *
2587 * This function will set some evas properties that is necessary when
2588 * a key is released. It prepares information to be treated by the
2589 * callback function.
2590 *
2591 */
2592EAPI 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);
2593
2594/**
2595 * Hold event feed
2596 *
2597 * @param e The given canvas pointer.
2598 * @param hold The hold.
2599 * @param timestamp The timestamp of the mouse up event.
2600 * @param data The data for canvas.
2601 *
2602 * This function makes the object to stop sending events.
2603 *
2604 */
2605EAPI void evas_event_feed_hold (Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2606
2607/**
2608 * Re feed event.
2609 *
2610 * @param e The given canvas pointer.
2611 * @param event_copy the event to refeed
2612 * @param event_type Event type
2613 *
2614 * This function re-feeds the event pointed by event_copy
2615 *
2616 * This function call evas_event_feed_* functions, so it can
2617 * cause havoc if not used wisely. Please use it responsibly.
2618 */
2619EAPI void evas_event_refeed_event (Evas *e, void *event_copy, Evas_Callback_Type event_type) EINA_ARG_NONNULL(1);
2620
2621
2622/**
2623 * @}
2624 */
2625
2626/**
2627 * @}
2628 */
2629
2630/**
2631 * @defgroup Evas_Image_Group Image Functions
2632 *
2633 * Functions that deals with images at canvas level.
2634 *
2635 * @ingroup Evas_Canvas
2636 */
2637
2638/**
2639 * @addtogroup Evas_Image_Group
2640 * @{
2641 */
2642
2643/**
2644 * Flush the image cache of the canvas.
2645 *
2646 * @param e The given evas pointer.
2647 *
2648 * This function flushes image cache of canvas.
2649 *
2650 */
2651EAPI void evas_image_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2652
2653/**
2654 * Reload the image cache
2655 *
2656 * @param e The given evas pointer.
2657 *
2658 * This function reloads the image cache of canvas.
2659 *
2660 */
2661EAPI void evas_image_cache_reload (Evas *e) EINA_ARG_NONNULL(1);
2662
2663/**
2664 * Set the image cache.
2665 *
2666 * @param e The given evas pointer.
2667 * @param size The cache size.
2668 *
2669 * This function sets the image cache of canvas in bytes.
2670 *
2671 */
2672EAPI void evas_image_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2673
2674/**
2675 * Get the image cache
2676 *
2677 * @param e The given evas pointer.
2678 *
2679 * This function returns the image cache size of canvas in bytes.
2680 *
2681 */
2682EAPI int evas_image_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2683
2684/**
2685 * Get the maximum image size evas can possibly handle
2686 *
2687 * @param e The given evas pointer.
2688 * @param maxw Pointer to hold the return value in pixels of the maxumum width
2689 * @param maxh Pointer to hold the return value in pixels of the maximum height
2690 *
2691 * This function returns the larges image or surface size that evas can handle
2692 * in pixels, and if there is one, returns EINA_TRUE. It returns EINA_FALSE
2693 * if no extra constraint on maximum image size exists. You still should
2694 * check the return values of @p maxw and @p maxh as there may still be a
2695 * limit, just a much higher one.
2696 *
2697 * @since 1.1
2698 */
2699EAPI Eina_Bool evas_image_max_size_get (const Evas *e, int *maxw, int *maxh) EINA_ARG_NONNULL(1);
2700
2701/**
2702 * @}
2703 */
2704
2705/**
2706 * @defgroup Evas_Font_Group Font Functions
2707 *
2708 * Functions that deals with fonts.
2709 *
2710 * @ingroup Evas_Canvas
2711 */
2712
2713/**
2714 * Changes the font hinting for the given evas.
2715 *
2716 * @param e The given evas.
2717 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2718 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2719 * @ingroup Evas_Font_Group
2720 */
2721EAPI void evas_font_hinting_set (Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1);
2722
2723/**
2724 * Retrieves the font hinting used by the given evas.
2725 *
2726 * @param e The given evas to query.
2727 * @return The hinting in use, one of #EVAS_FONT_HINTING_NONE,
2728 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2729 * @ingroup Evas_Font_Group
2730 */
2731EAPI Evas_Font_Hinting_Flags evas_font_hinting_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2732
2733/**
2734 * Checks if the font hinting is supported by the given evas.
2735 *
2736 * @param e The given evas to query.
2737 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2738 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2739 * @return @c EINA_TRUE if it is supported, @c EINA_FALSE otherwise.
2740 * @ingroup Evas_Font_Group
2741 */
2742EAPI Eina_Bool evas_font_hinting_can_hint (const Evas *e, Evas_Font_Hinting_Flags hinting) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2743
2744
2745/**
2746 * Force the given evas and associated engine to flush its font cache.
2747 *
2748 * @param e The given evas to flush font cache.
2749 * @ingroup Evas_Font_Group
2750 */
2751EAPI void evas_font_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2752
2753/**
2754 * Changes the size of font cache of the given evas.
2755 *
2756 * @param e The given evas to flush font cache.
2757 * @param size The size, in bytes.
2758 *
2759 * @ingroup Evas_Font_Group
2760 */
2761EAPI void evas_font_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2762
2763/**
2764 * Changes the size of font cache of the given evas.
2765 *
2766 * @param e The given evas to flush font cache.
2767 * @return The size, in bytes.
2768 *
2769 * @ingroup Evas_Font_Group
2770 */
2771EAPI int evas_font_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2772
2773
2774/**
2775 * List of available font descriptions known or found by this evas.
2776 *
2777 * The list depends on Evas compile time configuration, such as
2778 * fontconfig support, and the paths provided at runtime as explained
2779 * in @ref Evas_Font_Path_Group.
2780 *
2781 * @param e The evas instance to query.
2782 * @return a newly allocated list of strings. Do not change the
2783 * strings. Be sure to call evas_font_available_list_free()
2784 * after you're done.
2785 *
2786 * @ingroup Evas_Font_Group
2787 */
2788EAPI Eina_List *evas_font_available_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2789
2790/**
2791 * Free list of font descriptions returned by evas_font_dir_available_list().
2792 *
2793 * @param e The evas instance that returned such list.
2794 * @param available the list returned by evas_font_dir_available_list().
2795 *
2796 * @ingroup Evas_Font_Group
2797 */
2798EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1);
2799
2800/**
2801 * @defgroup Evas_Font_Path_Group Font Path Functions
2802 *
2803 * Functions that edit the paths being used to load fonts.
2804 *
2805 * @ingroup Evas_Font_Group
2806 */
2807
2808/**
2809 * Removes all font paths loaded into memory for the given evas.
2810 * @param e The given evas.
2811 * @ingroup Evas_Font_Path_Group
2812 */
2813EAPI void evas_font_path_clear (Evas *e) EINA_ARG_NONNULL(1);
2814
2815/**
2816 * Appends a font path to the list of font paths used by the given evas.
2817 * @param e The given evas.
2818 * @param path The new font path.
2819 * @ingroup Evas_Font_Path_Group
2820 */
2821EAPI void evas_font_path_append (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2822
2823/**
2824 * Prepends a font path to the list of font paths used by the given evas.
2825 * @param e The given evas.
2826 * @param path The new font path.
2827 * @ingroup Evas_Font_Path_Group
2828 */
2829EAPI void evas_font_path_prepend (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2830
2831/**
2832 * Retrieves the list of font paths used by the given evas.
2833 * @param e The given evas.
2834 * @return The list of font paths used.
2835 * @ingroup Evas_Font_Path_Group
2836 */
2837EAPI const Eina_List *evas_font_path_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2838
2839/**
2840 * @defgroup Evas_Object_Group Generic Object Functions
2841 *
2842 * Functions that manipulate generic Evas objects.
2843 *
2844 * All Evas displaying units are Evas objects. One handles them all by
2845 * means of the handle ::Evas_Object. Besides Evas treats their
2846 * objects equally, they have @b types, which define their specific
2847 * behavior (and individual API).
2848 *
2849 * Evas comes with a set of built-in object types:
2850 * - rectangle,
2851 * - line,
2852 * - polygon,
2853 * - text,
2854 * - textblock and
2855 * - image.
2856 *
2857 * These functions apply to @b any Evas object, whichever type thay
2858 * may have.
2859 *
2860 * @note The built-in types which are most used are rectangles, text
2861 * and images. In fact, with these ones one can create 2D interfaces
2862 * of arbitrary complexity and EFL makes it easy.
2863 */
2864
2865/**
2866 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
2867 *
2868 * Methods that are broadly used, like those that change the color,
2869 * clippers and geometry of an Evas object.
2870 *
2871 * An example on the most used functions in this group can be seen @ref
2872 * Example_Evas_Object_Manipulation "here".
2873 *
2874 * For function dealing with stacking, the examples are gathered @ref
2875 * Example_Evas_Stacking "here".
2876 *
2877 * @ingroup Evas_Object_Group
2878 */
2879
2880/**
2881 * @addtogroup Evas_Object_Group_Basic
2882 * @{
2883 */
2884
2885/**
2886 * Clip one object to another.
2887 *
2888 * @param obj The object to be clipped
2889 * @param clip The object to clip @p obj by
2890 *
2891 * This function will clip the object @p obj to the area occupied by
2892 * the object @p clip. This means the object @p obj will only be
2893 * visible within the area occupied by the clipping object (@p clip).
2894 *
2895 * The color of the object being clipped will be multiplied by the
2896 * color of the clipping one, so the resulting color for the former
2897 * will be <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color
2898 * element (red, green, blue and alpha).
2899 *
2900 * Clipping is recursive, so clipping objects may be clipped by
2901 * others, and their color will in term be multiplied. You may @b not
2902 * set up circular clipping lists (i.e. object 1 clips object 2, which
2903 * clips object 1): the behavior of Evas is undefined in this case.
2904 *
2905 * Objects which do not clip others are visible in the canvas as
2906 * normal; <b>those that clip one or more objects become invisible
2907 * themselves</b>, only affecting what they clip. If an object ceases
2908 * to have other objects being clipped by it, it will become visible
2909 * again.
2910 *
2911 * The visibility of an object affects the objects that are clipped by
2912 * it, so if the object clipping others is not shown (as in
2913 * evas_object_show()), the objects clipped by it will not be shown
2914 * either.
2915 *
2916 * If @p obj was being clipped by another object when this function is
2917 * called, it gets implicitly removed from the old clipper's domain
2918 * and is made now to be clipped by its new clipper.
2919 *
2920 * The following figure illustrates some clipping in Evas:
2921 *
2922 * @image html clipping.png
2923 * @image rtf clipping.png
2924 * @image latex clipping.eps
2925 *
2926 * @note At the moment the <b>only objects that can validly be used to
2927 * clip other objects are rectangle objects</b>. All other object
2928 * types are invalid and the result of using them is undefined. The
2929 * clip object @p clip must be a valid object, but can also be @c
2930 * NULL, in which case the effect of this function is the same as
2931 * calling evas_object_clip_unset() on the @p obj object.
2932 *
2933 * Example:
2934 * @dontinclude evas-object-manipulation.c
2935 * @skip solid white clipper (note that it's the default color for a
2936 * @until evas_object_show(d.clipper);
2937 *
2938 * See the full @ref Example_Evas_Object_Manipulation "example".
2939 */
2940EAPI void evas_object_clip_set (Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2);
2941
2942/**
2943 * Get the object clipping @p obj (if any).
2944 *
2945 * @param obj The object to get the clipper from
2946 *
2947 * This function returns the object clipping @p obj. If @p obj is
2948 * not being clipped at all, @c NULL is returned. The object @p obj
2949 * must be a valid ::Evas_Object.
2950 *
2951 * See also evas_object_clip_set(), evas_object_clip_unset() and
2952 * evas_object_clipees_get().
2953 *
2954 * Example:
2955 * @dontinclude evas-object-manipulation.c
2956 * @skip if (evas_object_clip_get(d.img) == d.clipper)
2957 * @until return
2958 *
2959 * See the full @ref Example_Evas_Object_Manipulation "example".
2960 */
2961EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2962
2963/**
2964 * Disable/cease clipping on a clipped @p obj object.
2965 *
2966 * @param obj The object to cease clipping on
2967 *
2968 * This function disables clipping for the object @p obj, if it was
2969 * already clipped, i.e., its visibility and color get detached from
2970 * the previous clipper. If it wasn't, this has no effect. The object
2971 * @p obj must be a valid ::Evas_Object.
2972 *
2973 * See also evas_object_clip_set() (for an example),
2974 * evas_object_clipees_get() and evas_object_clip_get().
2975 *
2976 */
2977EAPI void evas_object_clip_unset (Evas_Object *obj);
2978
2979/**
2980 * Return a list of objects currently clipped by @p obj.
2981 *
2982 * @param obj The object to get a list of clippees from
2983 * @return a list of objects being clipped by @p obj
2984 *
2985 * This returns the internal list handle that contains all objects
2986 * clipped by the object @p obj. If none are clipped by it, the call
2987 * returns @c NULL. This list is only valid until the clip list is
2988 * changed and should be fetched again with another call to
2989 * evas_object_clipees_get() if any objects being clipped by this
2990 * object are unclipped, clipped by a new object, deleted or get the
2991 * clipper deleted. These operations will invalidate the list
2992 * returned, so it should not be used anymore after that point. Any
2993 * use of the list after this may have undefined results, possibly
2994 * leading to crashes. The object @p obj must be a valid
2995 * ::Evas_Object.
2996 *
2997 * See also evas_object_clip_set(), evas_object_clip_unset() and
2998 * evas_object_clip_get().
2999 *
3000 * Example:
3001 * @code
3002 * extern Evas_Object *obj;
3003 * Evas_Object *clipper;
3004 *
3005 * clipper = evas_object_clip_get(obj);
3006 * if (clipper)
3007 * {
3008 * Eina_List *clippees, *l;
3009 * Evas_Object *obj_tmp;
3010 *
3011 * clippees = evas_object_clipees_get(clipper);
3012 * printf("Clipper clips %i objects\n", eina_list_count(clippees));
3013 * EINA_LIST_FOREACH(clippees, l, obj_tmp)
3014 * evas_object_show(obj_tmp);
3015 * }
3016 * @endcode
3017 */
3018EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3019
3020
3021/**
3022 * Sets or unsets a given object as the currently focused one on its
3023 * canvas.
3024 *
3025 * @param obj The object to be focused or unfocused.
3026 * @param focus @c EINA_TRUE, to set it as focused or @c EINA_FALSE,
3027 * to take away the focus from it.
3028 *
3029 * Changing focus only affects where (key) input events go. There can
3030 * be only one object focused at any time. If @p focus is @c
3031 * EINA_TRUE, @p obj will be set as the currently focused object and
3032 * it will receive all keyboard events that are not exclusive key
3033 * grabs on other objects.
3034 *
3035 * Example:
3036 * @dontinclude evas-events.c
3037 * @skip evas_object_focus_set
3038 * @until evas_object_focus_set
3039 *
3040 * See the full example @ref Example_Evas_Events "here".
3041 *
3042 * @see evas_object_focus_get
3043 * @see evas_focus_get
3044 * @see evas_object_key_grab
3045 * @see evas_object_key_ungrab
3046 */
3047EAPI void evas_object_focus_set (Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
3048
3049/**
3050 * Retrieve whether an object has the focus.
3051 *
3052 * @param obj The object to retrieve focus information from.
3053 * @return @c EINA_TRUE if the object has the focus, @c EINA_FALSE
3054 * otherwise.
3055 *
3056 * If the passed object is the currently focused one, @c EINA_TRUE is
3057 * returned. @c EINA_FALSE is returned, otherwise.
3058 *
3059 * Example:
3060 * @dontinclude evas-events.c
3061 * @skip And again
3062 * @until something is bad
3063 *
3064 * See the full example @ref Example_Evas_Events "here".
3065 *
3066 * @see evas_object_focus_set
3067 * @see evas_focus_get
3068 * @see evas_object_key_grab
3069 * @see evas_object_key_ungrab
3070 */
3071EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3072
3073
3074/**
3075 * Sets the layer of the its canvas that the given object will be part
3076 * of.
3077 *
3078 * @param obj The given Evas object.
3079 * @param l The number of the layer to place the object on.
3080 * Must be between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
3081 *
3082 * If you don't use this function, you'll be dealing with an @b unique
3083 * layer of objects, the default one. Additional layers are handy when
3084 * you don't want a set of objects to interfere with another set with
3085 * regard to @b stacking. Two layers are completely disjoint in that
3086 * matter.
3087 *
3088 * This is a low-level function, which you'd be using when something
3089 * should be always on top, for example.
3090 *
3091 * @warning Be careful, it doesn't make sense to change the layer of
3092 * smart objects' children. Smart objects have a layer of their own,
3093 * which should contain all their children objects.
3094 *
3095 * @see evas_object_layer_get()
3096 */
3097EAPI void evas_object_layer_set (Evas_Object *obj, short l) EINA_ARG_NONNULL(1);
3098
3099/**
3100 * Retrieves the layer of its canvas that the given object is part of.
3101 *
3102 * @param obj The given Evas object to query layer from
3103 * @return Number of the its layer
3104 *
3105 * @see evas_object_layer_set()
3106 */
3107EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3108
3109
3110/**
3111 * Sets the name of the given Evas object to the given name.
3112 *
3113 * @param obj The given object.
3114 * @param name The given name.
3115 *
3116 * There might be occasions where one would like to name his/her
3117 * objects.
3118 *
3119 * Example:
3120 * @dontinclude evas-events.c
3121 * @skip d.bg = evas_object_rectangle_add(d.canvas);
3122 * @until evas_object_name_set(d.bg, "our dear rectangle");
3123 *
3124 * See the full @ref Example_Evas_Events "example".
3125 */
3126EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
3127
3128/**
3129 * Retrieves the name of the given Evas object.
3130 *
3131 * @param obj The given object.
3132 * @return The name of the object or @c NULL, if no name has been given
3133 * to it.
3134 *
3135 * Example:
3136 * @dontinclude evas-events.c
3137 * @skip fprintf(stdout, "An object got focused: %s\n",
3138 * @until evas_focus_get
3139 *
3140 * See the full @ref Example_Evas_Events "example".
3141 */
3142EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3143
3144
3145/**
3146 * Increments object reference count to defer its deletion.
3147 *
3148 * @param obj The given Evas object to reference
3149 *
3150 * This increments the reference count of an object, which if greater
3151 * than 0 will defer deletion by evas_object_del() until all
3152 * references are released back (counter back to 0). References cannot
3153 * go below 0 and unreferencing past that will result in the reference
3154 * count being limited to 0. References are limited to <c>2^32 - 1</c>
3155 * for an object. Referencing it more than this will result in it
3156 * being limited to this value.
3157 *
3158 * @see evas_object_unref()
3159 * @see evas_object_del()
3160 *
3161 * @note This is a <b>very simple<b> reference counting mechanism! For
3162 * instance, Evas is not ready to check for pending references on a
3163 * canvas deletion, or things like that. This is useful on scenarios
3164 * where, inside a code block, callbacks exist which would possibly
3165 * delete an object we are operating on afterwards. Then, one would
3166 * evas_object_ref() it on the beginning of the block and
3167 * evas_object_unref() it on the end. It would then be deleted at this
3168 * point, if it should be.
3169 *
3170 * Example:
3171 * @code
3172 * evas_object_ref(obj);
3173 *
3174 * // action here...
3175 * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
3176 * // more action here...
3177 * evas_object_unref(obj);
3178 * @endcode
3179 *
3180 * @ingroup Evas_Object_Group_Basic
3181 * @since 1.1.0
3182 */
3183EAPI void evas_object_ref (Evas_Object *obj);
3184
3185/**
3186 * Decrements object reference count.
3187 *
3188 * @param obj The given Evas object to unreference
3189 *
3190 * This decrements the reference count of an object. If the object has
3191 * had evas_object_del() called on it while references were more than
3192 * 0, it will be deleted at the time this function is called and puts
3193 * the counter back to 0. See evas_object_ref() for more information.
3194 *
3195 * @see evas_object_ref() (for an example)
3196 * @see evas_object_del()
3197 *
3198 * @ingroup Evas_Object_Group_Basic
3199 * @since 1.1.0
3200 */
3201EAPI void evas_object_unref (Evas_Object *obj);
3202
3203
3204/**
3205 * Marks the given Evas object for deletion (when Evas will free its
3206 * memory).
3207 *
3208 * @param obj The given Evas object.
3209 *
3210 * This call will mark @p obj for deletion, which will take place
3211 * whenever it has no more references to it (see evas_object_ref() and
3212 * evas_object_unref()).
3213 *
3214 * At actual deletion time, which may or may not be just after this
3215 * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks will
3216 * be called. If the object currently had the focus, its
3217 * ::EVAS_CALLBACK_FOCUS_OUT callback will also be called.
3218 *
3219 * @see evas_object_ref()
3220 * @see evas_object_unref()
3221 *
3222 * @ingroup Evas_Object_Group_Basic
3223 */
3224EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
3225
3226/**
3227 * Move the given Evas object to the given location inside its
3228 * canvas' viewport.
3229 *
3230 * @param obj The given Evas object.
3231 * @param x X position to move the object to, in canvas units.
3232 * @param y Y position to move the object to, in canvas units.
3233 *
3234 * Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback
3235 * will be called.
3236 *
3237 * @note Naturally, newly created objects are placed at the canvas'
3238 * origin: <code>0, 0</code>.
3239 *
3240 * Example:
3241 * @dontinclude evas-object-manipulation.c
3242 * @skip evas_object_image_border_set(d.clipper_border, 3, 3, 3, 3);
3243 * @until evas_object_show
3244 *
3245 * See the full @ref Example_Evas_Object_Manipulation "example".
3246 *
3247 * @ingroup Evas_Object_Group_Basic
3248 */
3249EAPI void evas_object_move (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
3250
3251/**
3252 * Changes the size of the given Evas object.
3253 *
3254 * @param obj The given Evas object.
3255 * @param w The new width of the Evas object.
3256 * @param h The new height of the Evas object.
3257 *
3258 * Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback
3259 * will be called.
3260 *
3261 * @note Newly created objects have zeroed dimensions. Then, you most
3262 * probably want to use evas_object_resize() on them after they are
3263 * created.
3264 *
3265 * @note Be aware that resizing an object changes its drawing area,
3266 * but that does imply the object is rescaled! For instance, images
3267 * are filled inside their drawing area using the specifications of
3268 * evas_object_image_fill_set(). Thus to scale the image to match
3269 * exactly your drawing area, you need to change the
3270 * evas_object_image_fill_set() as well.
3271 *
3272 * @note This is more evident in images, but text, textblock, lines
3273 * and polygons will behave similarly. Check their specific APIs to
3274 * know how to achieve your desired behavior. Consider the following
3275 * example:
3276 *
3277 * @code
3278 * // rescale image to fill exactly its area without tiling:
3279 * evas_object_resize(img, w, h);
3280 * evas_object_image_fill_set(img, 0, 0, w, h);
3281 * @endcode
3282 *
3283 * @ingroup Evas_Object_Group_Basic
3284 */
3285EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
3286
3287/**
3288 * Retrieves the position and (rectangular) size of the given Evas
3289 * object.
3290 *
3291 * @param obj The given Evas object.
3292 * @param x Pointer to an integer in which to store the X coordinate
3293 * of the object.
3294 * @param y Pointer to an integer in which to store the Y coordinate
3295 * of the object.
3296 * @param w Pointer to an integer in which to store the width of the
3297 * object.
3298 * @param h Pointer to an integer in which to store the height of the
3299 * object.
3300 *
3301 * The position, naturally, will be relative to the top left corner of
3302 * the canvas' viewport.
3303 *
3304 * @note Use @c NULL pointers on the geometry components you're not
3305 * interested in: they'll be ignored by the function.
3306 *
3307 * Example:
3308 * @dontinclude evas-events.c
3309 * @skip int w, h, cw, ch;
3310 * @until return
3311 *
3312 * See the full @ref Example_Evas_Events "example".
3313 *
3314 * @ingroup Evas_Object_Group_Basic
3315 */
3316EAPI 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);
3317
3318
3319/**
3320 * Makes the given Evas object visible.
3321 *
3322 * @param obj The given Evas object.
3323 *
3324 * Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW
3325 * callback will be called.
3326 *
3327 * @see evas_object_hide() for more on object visibility.
3328 * @see evas_object_visible_get()
3329 *
3330 * @ingroup Evas_Object_Group_Basic
3331 */
3332EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1);
3333
3334/**
3335 * Makes the given Evas object invisible.
3336 *
3337 * @param obj The given Evas object.
3338 *
3339 * Hidden objects, besides not being shown at all in your canvas,
3340 * won't be checked for changes on the canvas rendering
3341 * process. Furthermore, they will not catch input events. Thus, they
3342 * are much ligher (in processing needs) than an object that is
3343 * invisible due to indirect causes, such as being clipped or out of
3344 * the canvas' viewport.
3345 *
3346 * Besides becoming hidden, @p obj object's ::EVAS_CALLBACK_SHOW
3347 * callback will be called.
3348 *
3349 * @note All objects are created in the hidden state! If you want them
3350 * shown, use evas_object_show() after their creation.
3351 *
3352 * @see evas_object_show()
3353 * @see evas_object_visible_get()
3354 *
3355 * Example:
3356 * @dontinclude evas-object-manipulation.c
3357 * @skip if (evas_object_visible_get(d.clipper))
3358 * @until return
3359 *
3360 * See the full @ref Example_Evas_Object_Manipulation "example".
3361 *
3362 * @ingroup Evas_Object_Group_Basic
3363 */
3364EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1);
3365
3366/**
3367 * Retrieves whether or not the given Evas object is visible.
3368 *
3369 * @param obj The given Evas object.
3370 * @return @c EINA_TRUE if the object is visible, @c EINA_FALSE
3371 * otherwise.
3372 *
3373 * This retrieves an object's visibily as the one enforced by
3374 * evas_object_show() and evas_object_hide().
3375 *
3376 * @note The value returned isn't, by any means, influenced by
3377 * clippers covering @obj, it being out of its canvas' viewport or
3378 * stacked below other object.
3379 *
3380 * @see evas_object_show()
3381 * @see evas_object_hide() (for an example)
3382 *
3383 * @ingroup Evas_Object_Group_Basic
3384 */
3385EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3386
3387
3388/**
3389 * Sets the general/main color of the given Evas object to the given
3390 * one.
3391 *
3392 * @param obj The given Evas object.
3393 * @param r The red component of the given color.
3394 * @param g The green component of the given color.
3395 * @param b The blue component of the given color.
3396 * @param a The alpha component of the given color.
3397 *
3398 * @see evas_object_color_get() (for an example)
3399 * @note These color values are expected to be premultiplied by @p a.
3400 *
3401 * @ingroup Evas_Object_Group_Basic
3402 */
3403EAPI void evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
3404
3405/**
3406 * Retrieves the general/main color of the given Evas object.
3407 *
3408 * @param obj The given Evas object to retrieve color from.
3409 * @param r Pointer to an integer in which to store the red component
3410 * of the color.
3411 * @param g Pointer to an integer in which to store the green
3412 * component of the color.
3413 * @param b Pointer to an integer in which to store the blue component
3414 * of the color.
3415 * @param a Pointer to an integer in which to store the alpha
3416 * component of the color.
3417 *
3418 * Retrieves the “main” color's RGB component (and alpha channel)
3419 * values, <b>which range from 0 to 255</b>. For the alpha channel,
3420 * which defines the object's transparency level, 0 means totally
3421 * trasparent, while 255 means opaque. These color values are
3422 * premultiplied by the alpha value.
3423 *
3424 * Usually you’ll use this attribute for text and rectangle objects,
3425 * where the “main” color is their unique one. If set for objects
3426 * which themselves have colors, like the images one, those colors get
3427 * modulated by this one.
3428 *
3429 * @note All newly created Evas rectangles get the default color
3430 * values of <code>255 255 255 255</code> (opaque white).
3431 *
3432 * @note Use @c NULL pointers on the components you're not interested
3433 * in: they'll be ignored by the function.
3434 *
3435 * Example:
3436 * @dontinclude evas-object-manipulation.c
3437 * @skip int alpha, r, g, b;
3438 * @until return
3439 *
3440 * See the full @ref Example_Evas_Object_Manipulation "example".
3441 *
3442 * @ingroup Evas_Object_Group_Basic
3443 */
3444EAPI void evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
3445
3446
3447/**
3448 * Retrieves the Evas canvas that the given object lives on.
3449 *
3450 * @param obj The given Evas object.
3451 * @return A pointer to the canvas where the object is on.
3452 *
3453 * This function is most useful at code contexts where you need to
3454 * operate on the canvas but have only the object pointer.
3455 *
3456 * @ingroup Evas_Object_Group_Basic
3457 */
3458EAPI Evas *evas_object_evas_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3459
3460/**
3461 * Retrieves the type of the given Evas object.
3462 *
3463 * @param obj The given object.
3464 * @return The type of the object.
3465 *
3466 * For Evas' builtin types, the return strings will be one of:
3467 * - <c>"rectangle"</c>,
3468 * - <c>"line"</c>,
3469 * - <c>"polygon"</c>,
3470 * - <c>"text"</c>,
3471 * - <c>"textblock"</c> and
3472 * - <c>"image"</c>.
3473 *
3474 * For Evas smart objects (see @ref Evas_Smart_Group), the name of the
3475 * smart class itself is returned on this call. For the built-in smart
3476 * objects, these names are:
3477 * - <c>"EvasObjectSmartClipped"</c>, for the clipped smart object
3478 * - <c>"Evas_Object_Box"</c>, for the box object and
3479 * - <c>"Evas_Object_Table"</c>, for the table object.
3480 *
3481 * Example:
3482 * @dontinclude evas-object-manipulation.c
3483 * @skip d.img = evas_object_image_filled_add(d.canvas);
3484 * @until border on the
3485 *
3486 * See the full @ref Example_Evas_Object_Manipulation "example".
3487 */
3488EAPI const char *evas_object_type_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3489
3490/**
3491 * Raise @p obj to the top of its layer.
3492 *
3493 * @param obj the object to raise
3494 *
3495 * @p obj will, then, be the highest one in the layer it belongs
3496 * to. Object on other layers won't get touched.
3497 *
3498 * @see evas_object_stack_above()
3499 * @see evas_object_stack_below()
3500 * @see evas_object_lower()
3501 */
3502EAPI void evas_object_raise (Evas_Object *obj) EINA_ARG_NONNULL(1);
3503
3504/**
3505 * Lower @p obj to the bottom of its layer.
3506 *
3507 * @param obj the object to lower
3508 *
3509 * @p obj will, then, be the lowest one in the layer it belongs
3510 * to. Objects on other layers won't get touched.
3511 *
3512 * @see evas_object_stack_above()
3513 * @see evas_object_stack_below()
3514 * @see evas_object_raise()
3515 */
3516EAPI void evas_object_lower (Evas_Object *obj) EINA_ARG_NONNULL(1);
3517
3518/**
3519 * Stack @p obj immediately above @p above
3520 *
3521 * @param obj the object to stack
3522 * @param above the object above which to stack
3523 *
3524 * Objects, in a given canvas, are stacked in the order they get added
3525 * to it. This means that, if they overlap, the highest ones will
3526 * cover the lowest ones, in that order. This function is a way to
3527 * change the stacking order for the objects.
3528 *
3529 * This function is intended to be used with <b>objects belonging to
3530 * the same layer</b> in a given canvas, otherwise it will fail (and
3531 * accomplish nothing).
3532 *
3533 * If you have smart objects on your canvas and @p obj is a member of
3534 * one of them, then @p above must also be a member of the same
3535 * smart object.
3536 *
3537 * Similarly, if @p obj is not a member of a smart object, @p above
3538 * must not be either.
3539 *
3540 * @see evas_object_layer_get()
3541 * @see evas_object_layer_set()
3542 * @see evas_object_stack_below()
3543 */
3544EAPI void evas_object_stack_above (Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2);
3545
3546/**
3547 * Stack @p obj immediately below @p below
3548 *
3549 * @param obj the object to stack
3550 * @param below the object below which to stack
3551 *
3552 * Objects, in a given canvas, are stacked in the order they get added
3553 * to it. This means that, if they overlap, the highest ones will
3554 * cover the lowest ones, in that order. This function is a way to
3555 * change the stacking order for the objects.
3556 *
3557 * This function is intended to be used with <b>objects belonging to
3558 * the same layer</b> in a given canvas, otherwise it will fail (and
3559 * accomplish nothing).
3560 *
3561 * If you have smart objects on your canvas and @p obj is a member of
3562 * one of them, then @p below must also be a member of the same
3563 * smart object.
3564 *
3565 * Similarly, if @p obj is not a member of a smart object, @p below
3566 * must not be either.
3567 *
3568 * @see evas_object_layer_get()
3569 * @see evas_object_layer_set()
3570 * @see evas_object_stack_below()
3571 */
3572EAPI void evas_object_stack_below (Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2);
3573
3574/**
3575 * Get the Evas object stacked right above @p obj
3576 *
3577 * @param obj an #Evas_Object
3578 * @return the #Evas_Object directly above @p obj, if any, or @c NULL,
3579 * if none
3580 *
3581 * This function will traverse layers in its search, if there are
3582 * objects on layers above the one @p obj is placed at.
3583 *
3584 * @see evas_object_layer_get()
3585 * @see evas_object_layer_set()
3586 * @see evas_object_below_get()
3587 *
3588 */
3589EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3590
3591/**
3592 * Get the Evas object stacked right below @p obj
3593 *
3594 * @param obj an #Evas_Object
3595 * @return the #Evas_Object directly below @p obj, if any, or @c NULL,
3596 * if none
3597 *
3598 * This function will traverse layers in its search, if there are
3599 * objects on layers below the one @p obj is placed at.
3600 *
3601 * @see evas_object_layer_get()
3602 * @see evas_object_layer_set()
3603 * @see evas_object_below_get()
3604 */
3605EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3606
3607/**
3608 * @}
3609 */
3610
3611/**
3612 * @defgroup Evas_Object_Group_Events Object Events
3613 *
3614 * Objects generate events when they are moved, resized, when their
3615 * visibility change, when they are deleted and so on. These methods
3616 * allow one to be notified about and to handle such events.
3617 *
3618 * Objects also generate events on input (keyboard and mouse), if they
3619 * accept them (are visible, focused, etc).
3620 *
3621 * For each of those events, Evas provides a way for one to register
3622 * callback functions to be issued just after they happen.
3623 *
3624 * The following figure illustrates some Evas (event) callbacks:
3625 *
3626 * @image html evas-callbacks.png
3627 * @image rtf evas-callbacks.png
3628 * @image latex evas-callbacks.eps
3629 *
3630 * Thees events have their values in the #Evas_Callback_Type
3631 * enumeration, which has also ones happening on the canvas level (se
3632 * #Evas_Canvas_Events).
3633 *
3634 * Examples on this group of functions can be found @ref
3635 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
3636 *
3637 * @ingroup Evas_Object_Group
3638 */
3639
3640/**
3641 * @addtogroup Evas_Object_Group_Events
3642 * @{
3643 */
3644
3645/**
3646 * Add (register) a callback function to a given Evas object event.
3647 *
3648 * @param obj Object to attach a callback to
3649 * @param type The type of event that will trigger the callback
3650 * @param func The function to be called when the event is triggered
3651 * @param data The data pointer to be passed to @p func
3652 *
3653 * This function adds a function callback to an object when the event
3654 * of type @p type occurs on object @p obj. The function is @p func.
3655 *
3656 * In the event of a memory allocation error during addition of the
3657 * callback to the object, evas_alloc_error() should be used to
3658 * determine the nature of the error, if any, and the program should
3659 * sensibly try and recover.
3660 *
3661 * A callback function must have the ::Evas_Object_Event_Cb prototype
3662 * definition. The first parameter (@p data) in this definition will
3663 * have the same value passed to evas_object_event_callback_add() as
3664 * the @p data parameter, at runtime. The second parameter @p e is the
3665 * canvas pointer on which the event occurred. The third parameter is
3666 * a pointer to the object on which event occurred. Finally, the
3667 * fourth parameter @p event_info is a pointer to a data structure
3668 * that may or may not be passed to the callback, depending on the
3669 * event type that triggered the callback. This is so because some
3670 * events don't carry extra context with them, but others do.
3671 *
3672 * The event type @p type to trigger the function may be one of
3673 * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT,
3674 * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP,
3675 * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL,
3676 * #EVAS_CALLBACK_MULTI_DOWN, #EVAS_CALLBACK_MULTI_UP,
3677 * #EVAS_CALLBACK_MULTI_MOVE, #EVAS_CALLBACK_FREE,
3678 * #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP,
3679 * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT,
3680 * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE,
3681 * #EVAS_CALLBACK_RESIZE, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL,
3682 * #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS,
3683 * #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED.
3684 *
3685 * This determines the kind of event that will trigger the callback.
3686 * What follows is a list explaining better the nature of each type of
3687 * event, along with their associated @p event_info pointers:
3688 *
3689 * - #EVAS_CALLBACK_MOUSE_IN: @p event_info is a pointer to an
3690 * #Evas_Event_Mouse_In struct\n\n
3691 * This event is triggered when the mouse pointer enters the area
3692 * (not shaded by other objects) of the object @p obj. This may
3693 * occur by the mouse pointer being moved by
3694 * evas_event_feed_mouse_move() calls, or by the object being shown,
3695 * raised, moved, resized, or other objects being moved out of the
3696 * way, hidden or lowered, whatever may cause the mouse pointer to
3697 * get on top of @p obj, having been on top of another object
3698 * previously.
3699 *
3700 * - #EVAS_CALLBACK_MOUSE_OUT: @p event_info is a pointer to an
3701 * #Evas_Event_Mouse_Out struct\n\n
3702 * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is,
3703 * but it occurs when the mouse pointer exits an object's area. Note
3704 * that no mouse out events will be reported if the mouse pointer is
3705 * implicitly grabbed to an object (mouse buttons are down, having
3706 * been pressed while the pointer was over that object). In these
3707 * cases, mouse out events will be reported once all buttons are
3708 * released, if the mouse pointer has left the object's area. The
3709 * indirect ways of taking off the mouse pointer from an object,
3710 * like cited above, for #EVAS_CALLBACK_MOUSE_IN, also apply here,
3711 * naturally.
3712 *
3713 * - #EVAS_CALLBACK_MOUSE_DOWN: @p event_info is a pointer to an
3714 * #Evas_Event_Mouse_Down struct\n\n
3715 * This event is triggered by a mouse button being pressed while the
3716 * mouse pointer is over an object. If the pointer mode for Evas is
3717 * #EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this
3718 * object to <b>passively grab the mouse</b> until all mouse buttons
3719 * have been released: all future mouse events will be reported to
3720 * only this object until no buttons are down. That includes mouse
3721 * move events, mouse in and mouse out events, and further button
3722 * presses. When all buttons are released, event propagation will
3723 * occur as normal (see #Evas_Object_Pointer_Mode).
3724 *
3725 * - #EVAS_CALLBACK_MOUSE_UP: @p event_info is a pointer to an
3726 * #Evas_Event_Mouse_Up struct\n\n
3727 * This event is triggered by a mouse button being released while
3728 * the mouse pointer is over an object's area (or when passively
3729 * grabbed to an object).
3730 *
3731 * - #EVAS_CALLBACK_MOUSE_MOVE: @p event_info is a pointer to an
3732 * #Evas_Event_Mouse_Move struct\n\n
3733 * This event is triggered by the mouse pointer being moved while
3734 * over an object's area (or while passively grabbed to an object).
3735 *
3736 * - #EVAS_CALLBACK_MOUSE_WHEEL: @p event_info is a pointer to an
3737 * #Evas_Event_Mouse_Wheel struct\n\n
3738 * This event is triggered by the mouse wheel being rolled while the
3739 * mouse pointer is over an object (or passively grabbed to an
3740 * object).
3741 *
3742 * - #EVAS_CALLBACK_MULTI_DOWN: @p event_info is a pointer to an
3743 * #Evas_Event_Multi_Down struct
3744 *
3745 * - #EVAS_CALLBACK_MULTI_UP: @p event_info is a pointer to an
3746 * #Evas_Event_Multi_Up struct
3747 *
3748 * - #EVAS_CALLBACK_MULTI_MOVE: @p event_info is a pointer to an
3749 * #Evas_Event_Multi_Move struct
3750 *
3751 * - #EVAS_CALLBACK_FREE: @p event_info is @c NULL \n\n
3752 * This event is triggered just before Evas is about to free all
3753 * memory used by an object and remove all references to it. This is
3754 * useful for programs to use if they attached data to an object and
3755 * want to free it when the object is deleted. The object is still
3756 * valid when this callback is called, but after it returns, there
3757 * is no guarantee on the object's validity.
3758 *
3759 * - #EVAS_CALLBACK_KEY_DOWN: @p event_info is a pointer to an
3760 * #Evas_Event_Key_Down struct\n\n
3761 * This callback is called when a key is pressed and the focus is on
3762 * the object, or a key has been grabbed to a particular object
3763 * which wants to intercept the key press regardless of what object
3764 * has the focus.
3765 *
3766 * - #EVAS_CALLBACK_KEY_UP: @p event_info is a pointer to an
3767 * #Evas_Event_Key_Up struct \n\n
3768 * This callback is called when a key is released and the focus is
3769 * on the object, or a key has been grabbed to a particular object
3770 * which wants to intercept the key release regardless of what
3771 * object has the focus.
3772 *
3773 * - #EVAS_CALLBACK_FOCUS_IN: @p event_info is @c NULL \n\n
3774 * This event is called when an object gains the focus. When it is
3775 * called the object has already gained the focus.
3776 *
3777 * - #EVAS_CALLBACK_FOCUS_OUT: @p event_info is @c NULL \n\n
3778 * This event is triggered when an object loses the focus. When it
3779 * is called the object has already lost the focus.
3780 *
3781 * - #EVAS_CALLBACK_SHOW: @p event_info is @c NULL \n\n
3782 * This event is triggered by the object being shown by
3783 * evas_object_show().
3784 *
3785 * - #EVAS_CALLBACK_HIDE: @p event_info is @c NULL \n\n
3786 * This event is triggered by an object being hidden by
3787 * evas_object_hide().
3788 *
3789 * - #EVAS_CALLBACK_MOVE: @p event_info is @c NULL \n\n
3790 * This event is triggered by an object being
3791 * moved. evas_object_move() can trigger this, as can any
3792 * object-specific manipulations that would mean the object's origin
3793 * could move.
3794 *
3795 * - #EVAS_CALLBACK_RESIZE: @p event_info is @c NULL \n\n
3796 * This event is triggered by an object being resized. Resizes can
3797 * be triggered by evas_object_resize() or by any object-specific
3798 * calls that may cause the object to resize.
3799 *
3800 * - #EVAS_CALLBACK_RESTACK: @p event_info is @c NULL \n\n
3801 * This event is triggered by an object being re-stacked. Stacking
3802 * changes can be triggered by
3803 * evas_object_stack_below()/evas_object_stack_above() and others.
3804 *
3805 * - #EVAS_CALLBACK_DEL: @p event_info is @c NULL.
3806 *
3807 * - #EVAS_CALLBACK_HOLD: @p event_info is a pointer to an
3808 * #Evas_Event_Hold struct
3809 *
3810 * - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @p event_info is @c NULL.
3811 *
3812 * - #EVAS_CALLBACK_IMAGE_PRELOADED: @p event_info is @c NULL.
3813 *
3814 * - #EVAS_CALLBACK_IMAGE_UNLOADED: @p event_info is @c NULL.
3815 *
3816 * @note Be careful not to add the same callback multiple times, if
3817 * that's not what you want, because Evas won't check if a callback
3818 * existed before exactly as the one being registered (and thus, call
3819 * it more than once on the event, in this case). This would make
3820 * sense if you passed different functions and/or callback data, only.
3821 *
3822 * Example:
3823 * @dontinclude evas-events.c
3824 * @skip evas_object_event_callback_add(
3825 * @until }
3826 *
3827 * See the full example @ref Example_Evas_Events "here".
3828 *
3829 */
3830 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);
3831
3832/**
3833 * Add (register) a callback function to a given Evas object event with a
3834 * non-default priority set. Except for the priority field, it's exactly the
3835 * same as @ref evas_object_event_callback_add
3836 *
3837 * @param obj Object to attach a callback to
3838 * @param type The type of event that will trigger the callback
3839 * @param priority The priority of the callback, lower values called first.
3840 * @param func The function to be called when the event is triggered
3841 * @param data The data pointer to be passed to @p func
3842 *
3843 * @see evas_object_event_callback_add
3844 * @since 1.1.0
3845 */
3846EAPI 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);
3847
3848/**
3849 * Delete a callback function from an object
3850 *
3851 * @param obj Object to remove a callback from
3852 * @param type The type of event that was triggering the callback
3853 * @param func The function that was to be called when the event was triggered
3854 * @return The data pointer that was to be passed to the callback
3855 *
3856 * This function removes the most recently added callback from the
3857 * object @p obj which was triggered by the event type @p type and was
3858 * calling the function @p func when triggered. If the removal is
3859 * successful it will also return the data pointer that was passed to
3860 * evas_object_event_callback_add() when the callback was added to the
3861 * object. If not successful NULL will be returned.
3862 *
3863 * Example:
3864 * @code
3865 * extern Evas_Object *object;
3866 * void *my_data;
3867 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3868 *
3869 * my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
3870 * @endcode
3871 */
3872EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3);
3873
3874/**
3875 * Delete (unregister) a callback function registered to a given
3876 * Evas object event.
3877 *
3878 * @param obj Object to remove a callback from
3879 * @param type The type of event that was triggering the callback
3880 * @param func The function that was to be called when the event was
3881 * triggered
3882 * @param data The data pointer that was to be passed to the callback
3883 * @return The data pointer that was to be passed to the callback
3884 *
3885 * This function removes the most recently added callback from the
3886 * object @p obj, which was triggered by the event type @p type and was
3887 * calling the function @p func with data @p data, when triggered. If
3888 * the removal is successful it will also return the data pointer that
3889 * was passed to evas_object_event_callback_add() (that will be the
3890 * same as the parameter) when the callback was added to the
3891 * object. In errors, @c NULL will be returned.
3892 *
3893 * @note For deletion of Evas object events callbacks filtering by
3894 * just type and function pointer, user
3895 * evas_object_event_callback_del().
3896 *
3897 * Example:
3898 * @code
3899 * extern Evas_Object *object;
3900 * void *my_data;
3901 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3902 *
3903 * my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
3904 * @endcode
3905 */
3906EAPI 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);
3907
3908
3909/**
3910 * Set whether an Evas object is to pass (ignore) events.
3911 *
3912 * @param obj the Evas object to operate on
3913 * @param pass whether @p obj is to pass events (@c EINA_TRUE) or not
3914 * (@c EINA_FALSE)
3915 *
3916 * If @p pass is @c EINA_TRUE, it will make events on @p obj to be @b
3917 * ignored. They will be triggered on the @b next lower object (that
3918 * is not set to pass events), instead (see evas_object_below_get()).
3919 *
3920 * If @p pass is @c EINA_FALSE, events will be processed on that
3921 * object as normal.
3922 *
3923 * @see evas_object_pass_events_get() for an example
3924 * @see evas_object_repeat_events_set()
3925 * @see evas_object_propagate_events_set()
3926 * @see evas_object_freeze_events_set()
3927 */
3928EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1);
3929
3930/**
3931 * Determine whether an object is set to pass (ignore) events.
3932 *
3933 * @param obj the Evas object to get information from.
3934 * @return pass whether @p obj is set to pass events (@c EINA_TRUE) or not
3935 * (@c EINA_FALSE)
3936 *
3937 * Example:
3938 * @dontinclude evas-stacking.c
3939 * @skip if (strcmp(ev->keyname, "p") == 0)
3940 * @until }
3941 *
3942 * See the full @ref Example_Evas_Stacking "example".
3943 *
3944 * @see evas_object_pass_events_set()
3945 * @see evas_object_repeat_events_get()
3946 * @see evas_object_propagate_events_get()
3947 * @see evas_object_freeze_events_get()
3948 */
3949EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3950
3951/**
3952 * Set whether an Evas object is to repeat events.
3953 *
3954 * @param obj the Evas object to operate on
3955 * @param repeat whether @p obj is to repeat events (@c EINA_TRUE) or not
3956 * (@c EINA_FALSE)
3957 *
3958 * If @p repeat is @c EINA_TRUE, it will make events on @p obj to also
3959 * be repeated for the @b next lower object in the objects' stack (see
3960 * see evas_object_below_get()).
3961 *
3962 * If @p repeat is @c EINA_FALSE, events occurring on @p obj will be
3963 * processed only on it.
3964 *
3965 * Example:
3966 * @dontinclude evas-stacking.c
3967 * @skip if (strcmp(ev->keyname, "r") == 0)
3968 * @until }
3969 *
3970 * See the full @ref Example_Evas_Stacking "example".
3971 *
3972 * @see evas_object_repeat_events_get()
3973 * @see evas_object_pass_events_set()
3974 * @see evas_object_propagate_events_set()
3975 * @see evas_object_freeze_events_set()
3976 */
3977EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
3978
3979/**
3980 * Determine whether an object is set to repeat events.
3981 *
3982 * @param obj the given Evas object pointer
3983 * @retrieve whether @p obj is set to repeat events (@c EINA_TRUE)
3984 * or not (@c EINA_FALSE)
3985 *
3986 * @see evas_object_repeat_events_set() for an example
3987 * @see evas_object_pass_events_get()
3988 * @see evas_object_propagate_events_get()
3989 * @see evas_object_freeze_events_get()
3990 */
3991EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3992
3993/**
3994 * Set whether events on a smart object's member should get propagated
3995 * up to its parent.
3996 *
3997 * @param obj the smart object's child to operate on
3998 * @param prop whether to propagate events (@c EINA_TRUE) or not (@c
3999 * EINA_FALSE)
4000 *
4001 * This function has @b no effect if @p obj is not a member of a smart
4002 * object.
4003 *
4004 * If @p prop is @c EINA_TRUE, events occurring on this object will be
4005 * propagated on to the smart object of which @p obj is a member. If
4006 * @p prop is @c EINA_FALSE, events occurring on this object will @b
4007 * not be propagated on to the smart object of which @p obj is a
4008 * member. The default value is @c EINA_TRUE.
4009 *
4010 * @see evas_object_propagate_events_get()
4011 * @see evas_object_repeat_events_set()
4012 * @see evas_object_pass_events_set()
4013 * @see evas_object_freeze_events_set()
4014 */
4015EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1);
4016
4017/**
4018 * Retrieve whether an Evas object is set to propagate events.
4019 *
4020 * @param obj the given Evas object pointer
4021 * @return whether @p obj is set to propagate events (@c EINA_TRUE)
4022 * or not (@c EINA_FALSE)
4023 *
4024 * @see evas_object_propagate_events_set()
4025 * @see evas_object_repeat_events_get()
4026 * @see evas_object_pass_events_get()
4027 * @see evas_object_freeze_events_get()
4028 */
4029EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4030
4031/**
4032 * Set whether an Evas object is to freeze (discard) events.
4033 *
4034 * @param obj the Evas object to operate on
4035 * @param pass whether @p obj is to freeze events (@c EINA_TRUE) or not
4036 * (@c EINA_FALSE)
4037 *
4038 * If @p freeze is @c EINA_TRUE, it will make events on @p obj to be @b
4039 * discarded. Unlike evas_object_pass_events_set(), events will not be
4040 * passed to @b next lower object. This API can be used for blocking
4041 * events while @p obj is on transiting.
4042 *
4043 * If @p freeze is @c EINA_FALSE, events will be processed on that
4044 * object as normal.
4045 *
4046 * @see evas_object_freeze_events_get()
4047 * @see evas_object_pass_events_set()
4048 * @see evas_object_repeat_events_set()
4049 * @see evas_object_propagate_events_set()
4050 * @since 1.1.0
4051 */
4052EAPI void evas_object_freeze_events_set(Evas_Object *obj, Eina_Bool freeze) EINA_ARG_NONNULL(1);
4053
4054/**
4055 * Determine whether an object is set to freeze (discard) events.
4056 *
4057 * @param obj the Evas object to get information from.
4058 * @return freeze whether @p obj is set to freeze events (@c EINA_TRUE) or
4059 * not (@c EINA_FALSE)
4060 *
4061 * @see evas_object_freeze_events_set()
4062 * @see evas_object_pass_events_get()
4063 * @see evas_object_repeat_events_get()
4064 * @see evas_object_propagate_events_get()
4065 * @since 1.1.0
4066 */
4067EAPI Eina_Bool evas_object_freeze_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4068
4069/**
4070 * @}
4071 */
4072
4073/**
4074 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspective, 3D...)
4075 *
4076 * Evas allows different transformations to be applied to all kinds of
4077 * objects. These are applied by means of UV mapping.
4078 *
4079 * With UV mapping, one maps points in the source object to a 3D space
4080 * positioning at target. This allows rotation, perspective, scale and
4081 * lots of other effects, depending on the map that is used.
4082 *
4083 * Each map point may carry a multiplier color. If properly
4084 * calculated, these can do shading effects on the object, producing
4085 * 3D effects.
4086 *
4087 * As usual, Evas provides both the raw and easy to use methods. The
4088 * raw methods allow developer to create its maps somewhere else,
4089 * maybe load them from some file format. The easy to use methods,
4090 * calculate the points given some high-level parameters, such as
4091 * rotation angle, ambient light and so on.
4092 *
4093 * @note applying mapping will reduce performance, so use with
4094 * care. The impact on performance depends on engine in
4095 * use. Software is quite optimized, but not as fast as OpenGL.
4096 *
4097 * @section sec-map-points Map points
4098 * @subsection subsec-rotation Rotation
4099 *
4100 * A map consists of a set of points, currently only four are supported. Each
4101 * of these points contains a set of canvas coordinates @c x and @c y that
4102 * can be used to alter the geometry of the mapped object, and a @c z
4103 * coordinate that indicates the depth of that point. This last coordinate
4104 * does not normally affect the map, but it's used by several of the utility
4105 * functions to calculate the right position of the point given other
4106 * parameters.
4107 *
4108 * The coordinates for each point are set with evas_map_point_coord_set().
4109 * The following image shows a map set to match the geometry of an existing
4110 * object.
4111 *
4112 * @image html map-set-map-points-1.png
4113 * @image rtf map-set-map-points-1.png
4114 * @image latex map-set-map-points-1.eps
4115 *
4116 * This is a common practice, so there are a few functions that help make it
4117 * easier.
4118 *
4119 * evas_map_util_points_populate_from_geometry() sets the coordinates of each
4120 * point in the given map to match the rectangle defined by the function
4121 * parameters.
4122 *
4123 * evas_map_util_points_populate_from_object() and
4124 * evas_map_util_points_populate_from_object_full() both take an object and
4125 * set the map points to match its geometry. The difference between the two
4126 * is that the first function sets the @c z value of all points to 0, while
4127 * the latter receives the value to set in said coordinate as a parameter.
4128 *
4129 * The following lines of code all produce the same result as in the image
4130 * above.
4131 * @code
4132 * evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
4133 * // Assuming o is our original object
4134 * evas_object_move(o, 100, 100);
4135 * evas_object_resize(o, 200, 200);
4136 * evas_map_util_points_populate_from_object(m, o);
4137 * evas_map_util_points_populate_from_object_full(m, o, 0);
4138 * @endcode
4139 *
4140 * Several effects can be applied to an object by simply setting each point
4141 * of the map to the right coordinates. For example, a simulated perspective
4142 * could be achieve as follows.
4143 *
4144 * @image html map-set-map-points-2.png
4145 * @image rtf map-set-map-points-2.png
4146 * @image latex map-set-map-points-2.eps
4147 *
4148 * As said before, the @c z coordinate is unused here so when setting points
4149 * by hand, its value is of no importance.
4150 *
4151 * @image html map-set-map-points-3.png
4152 * @image rtf map-set-map-points-3.png
4153 * @image latex map-set-map-points-3.eps
4154 *
4155 * In all three cases above, setting the map to be used by the object is the
4156 * same.
4157 * @code
4158 * evas_object_map_set(o, m);
4159 * evas_object_map_enable_set(o, EINA_TRUE);
4160 * @endcode
4161 *
4162 * Doing things this way, however, is a lot of work that can be avoided by
4163 * using the provided utility functions, as described in the next section.
4164 *
4165 * @section map-utils Utility functions
4166 *
4167 * Utility functions take an already set up map and alter it to produce a
4168 * specific effect. For example, to rotate an object around its own center
4169 * you would need to take the rotation angle, the coordinates of each corner
4170 * of the object and do all the math to get the new set of coordinates that
4171 * need to tbe set in the map.
4172 *
4173 * Or you can use this code:
4174 * @code
4175 * evas_object_geometry_get(o, &x, &y, &w, &h);
4176 * m = evas_map_new(4);
4177 * evas_map_util_points_populate_from_object(m, o);
4178 * evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
4179 * evas_object_map_set(o, m);
4180 * evas_object_map_enable_set(o, EINA_TRUE);
4181 * evas_map_free(m);
4182 * @endcode
4183 *
4184 * Which will rotate the object around its center point in a 45 degree angle
4185 * in the clockwise direction, taking it from this
4186 *
4187 * @image html map-rotation-2d-1.png
4188 * @image rtf map-rotation-2d-1.png
4189 * @image latex map-rotation-2d-1.eps
4190 *
4191 * to this
4192 *
4193 * @image html map-rotation-2d-2.png
4194 * @image rtf map-rotation-2d-2.png
4195 * @image latex map-rotation-2d-2.eps
4196 *
4197 * Objects may be rotated around any other point just by setting the last two
4198 * paramaters of the evas_map_util_rotate() function to the right values. A
4199 * circle of roughly the diameter of the object overlaid on each image shows
4200 * where the center of rotation is set for each example.
4201 *
4202 * For example, this code
4203 * @code
4204 * evas_object_geometry_get(o, &x, &y, &w, &h);
4205 * m = evas_map_new(4);
4206 * evas_map_util_points_populate_from_object(m, o);
4207 * evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
4208 * evas_object_map_set(o, m);
4209 * evas_object_map_enable_set(o, EINA_TRUE);
4210 * evas_map_free(m);
4211 * @endcode
4212 *
4213 * produces something like
4214 *
4215 * @image html map-rotation-2d-3.png
4216 * @image rtf map-rotation-2d-3.png
4217 * @image latex map-rotation-2d-3.eps
4218 *
4219 * And the following
4220 * @code
4221 * evas_output_size_get(evas, &w, &h);
4222 * m = evas_map_new(4);
4223 * evas_map_util_points_populate_from_object(m, o);
4224 * evas_map_util_rotate(m, 45, w, h);
4225 * evas_object_map_set(o, m);
4226 * evas_object_map_enable_set(o, EINA_TRUE);
4227 * evas_map_free(m);
4228 * @endcode
4229 *
4230 * rotates the object around the center of the window
4231 *
4232 * @image html map-rotation-2d-4.png
4233 * @image rtf map-rotation-2d-4.png
4234 * @image latex map-rotation-2d-4.eps
4235 *
4236 * @subsection subsec-3d 3D Maps
4237 *
4238 * Maps can also be used to achieve the effect of 3-dimensionality. When doing
4239 * this, the @c z coordinate of each point counts, with higher values meaning
4240 * the point is further into the screen, and smaller values (negative, usually)
4241 * meaning the point is closwer towards the user.
4242 *
4243 * Thinking in 3D also introduces the concept of back-face of an object. An
4244 * object is said to be facing the user when all its points are placed in a
4245 * clockwise fashion. The next image shows this, with each point showing the
4246 * with which is identified within the map.
4247 *
4248 * @image html map-point-order-face.png
4249 * @image rtf map-point-order-face.png
4250 * @image latex map-point-order-face.eps
4251 *
4252 * Rotating this map around the @c Y axis would leave the order of the points
4253 * in a counter-clockwise fashion, as seen in the following image.
4254 *
4255 * @image html map-point-order-back.png
4256 * @image rtf map-point-order-back.png
4257 * @image latex map-point-order-back.eps
4258 *
4259 * This way we can say that we are looking at the back face of the object.
4260 * This will have stronger implications later when we talk about lighting.
4261 *
4262 * To know if a map is facing towards the user or not it's enough to use
4263 * the evas_map_util_clockwise_get() function, but this is normally done
4264 * after all the other operations are applied on the map.
4265 *
4266 * @subsection subsec-3d-rot 3D rotation and perspective
4267 *
4268 * Much like evas_map_util_rotate(), there's the function
4269 * evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
4270 * to an object. As in its 2D counterpart, the rotation can be applied around
4271 * any point in the canvas, this time with a @c z coordinate too. The rotation
4272 * can also be around any of the 3 axis.
4273 *
4274 * Starting from this simple setup
4275 *
4276 * @image html map-3d-basic-1.png
4277 * @image rtf map-3d-basic-1.png
4278 * @image latex map-3d-basic-1.eps
4279 *
4280 * and setting maps so that the blue square to rotate on all axis around a
4281 * sphere that uses the object as its center, and the red square to rotate
4282 * around the @c Y axis, we get the following. A simple overlay over the image
4283 * shows the original geometry of each object and the axis around which they
4284 * are being rotated, with the @c Z one not appearing due to being orthogonal
4285 * to the screen.
4286 *
4287 * @image html map-3d-basic-2.png
4288 * @image rtf map-3d-basic-2.png
4289 * @image latex map-3d-basic-2.eps
4290 *
4291 * which doesn't look very real. This can be helped by adding perspective
4292 * to the transformation, which can be simply done by calling
4293 * evas_map_util_3d_perspective() on the map after its position has been set.
4294 * The result in this case, making the vanishing point the center of each
4295 * object:
4296 *
4297 * @image html map-3d-basic-3.png
4298 * @image rtf map-3d-basic-3.png
4299 * @image latex map-3d-basic-3.eps
4300 *
4301 * @section sec-color Color and lighting
4302 *
4303 * Each point in a map can be set to a color, which will be multiplied with
4304 * the objects own color and linearly interpolated in between adjacent points.
4305 * This is done with evas_map_point_color_set() for each point of the map,
4306 * or evas_map_util_points_color_set() to set every point to the same color.
4307 *
4308 * When using 3D effects, colors can be used to improve the looks of them by
4309 * simulating a light source. The evas_map_util_3d_lighting() function makes
4310 * this task easier by taking the coordinates of the light source and its
4311 * color, along with the color of the ambient light. Evas then sets the color
4312 * of each point based on the distance to the light source, the angle with
4313 * which the object is facing the light and the ambient light. Here, the
4314 * orientation of each point as explained before, becomes more important.
4315 * If the map is defined counter-clockwise, the object will be facing away
4316 * from the user and thus become obscured, since no light would be reflecting
4317 * from it.
4318 *
4319 * @image html map-light.png
4320 * @image rtf map-light.png
4321 * @image latex map-light.eps
4322 * @note Object facing the light source
4323 *
4324 * @image html map-light2.png
4325 * @image rtf map-light2.png
4326 * @image latex map-light2.eps
4327 * @note Same object facing away from the user
4328 *
4329 * @section Image mapping
4330 *
4331 * @image html map-uv-mapping-1.png
4332 * @image rtf map-uv-mapping-1.png
4333 * @image latex map-uv-mapping-1.eps
4334 *
4335 * Images need some special handlign when mapped. Evas can easily take care
4336 * of objects and do almost anything with them, but it's completely oblivious
4337 * to the content of images, so each point in the map needs to be told to what
4338 * pixel in the source image it belongs. Failing to do may sometimes result
4339 * in the expected behavior, or it may look like a partial work.
4340 *
4341 * The next image illustrates one possibility of a map being set to an image
4342 * object, without setting the right UV mapping for each point. The objects
4343 * themselves are mapped properly to their new geometry, but the image content
4344 * may not be displayed correctly within the mapped object.
4345 *
4346 * @image html map-uv-mapping-2.png
4347 * @image rtf map-uv-mapping-2.png
4348 * @image latex map-uv-mapping-2.eps
4349 *
4350 * Once Evas knows how to handle the source image within the map, it will
4351 * transform it as needed. This is done with evas_map_point_image_uv_set(),
4352 * which tells the map to which pixel in image it maps.
4353 *
4354 * To match our example images to the maps above all we need is the size of
4355 * each image, which can always be found with evas_object_image_size_get().
4356 *
4357 * @code
4358 * evas_map_point_image_uv_set(m, 0, 0, 0);
4359 * evas_map_point_image_uv_set(m, 1, 150, 0);
4360 * evas_map_point_image_uv_set(m, 2, 150, 200);
4361 * evas_map_point_image_uv_set(m, 3, 0, 200);
4362 * evas_object_map_set(o, m);
4363 * evas_object_map_enable_set(o, EINA_TRUE);
4364 *
4365 * evas_map_point_image_uv_set(m, 0, 0, 0);
4366 * evas_map_point_image_uv_set(m, 1, 120, 0);
4367 * evas_map_point_image_uv_set(m, 2, 120, 160);
4368 * evas_map_point_image_uv_set(m, 3, 0, 160);
4369 * evas_object_map_set(o2, m);
4370 * evas_object_map_enable_set(o2, EINA_TRUE);
4371 * @endcode
4372 *
4373 * To get
4374 *
4375 * @image html map-uv-mapping-3.png
4376 * @image rtf map-uv-mapping-3.png
4377 * @image latex map-uv-mapping-3.eps
4378 *
4379 * Maps can also be set to use part of an image only, or even map them inverted,
4380 * and combined with evas_object_image_source_set() it can be used to achieve
4381 * more interesting results.
4382 *
4383 * @code
4384 * evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
4385 * evas_map_point_image_uv_set(m, 0, 0, h);
4386 * evas_map_point_image_uv_set(m, 1, w, h);
4387 * evas_map_point_image_uv_set(m, 2, w, h / 3);
4388 * evas_map_point_image_uv_set(m, 3, 0, h / 3);
4389 * evas_object_map_set(o, m);
4390 * evas_object_map_enable_set(o, EINA_TRUE);
4391 * @endcode
4392 *
4393 * @image html map-uv-mapping-4.png
4394 * @image rtf map-uv-mapping-4.png
4395 * @image latex map-uv-mapping-4.eps
4396 *
4397 * Examples:
4398 * @li @ref Example_Evas_Map_Overview
4399 *
4400 * @ingroup Evas_Object_Group
4401 *
4402 * @{
4403 */
4404
4405/**
4406 * Enable or disable the map that is set.
4407 *
4408 * Enable or disable the use of map for the object @p obj.
4409 * On enable, the object geometry will be saved, and the new geometry will
4410 * change (position and size) to reflect the map geometry set.
4411 *
4412 * If the object doesn't have a map set (with evas_object_map_set()), the
4413 * initial geometry will be undefined. It is advised to always set a map
4414 * to the object first, and then call this function to enable its use.
4415 *
4416 * @param obj object to enable the map on
4417 * @param enabled enabled state
4418 */
4419EAPI void evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled);
4420
4421/**
4422 * Get the map enabled state
4423 *
4424 * This returns the currently enabled state of the map on the object indicated.
4425 * The default map enable state is off. You can enable and disable it with
4426 * evas_object_map_enable_set().
4427 *
4428 * @param obj object to get the map enabled state from
4429 * @return the map enabled state
4430 */
4431EAPI Eina_Bool evas_object_map_enable_get (const Evas_Object *obj);
4432
4433/**
4434 * Set the map source object
4435 *
4436 * This sets the object from which the map is taken - can be any object that
4437 * has map enabled on it.
4438 *
4439 * Currently not implemented. for future use.
4440 *
4441 * @param obj object to set the map source of
4442 * @param src the source object from which the map is taken
4443 */
4444EAPI void evas_object_map_source_set (Evas_Object *obj, Evas_Object *src);
4445
4446/**
4447 * Get the map source object
4448 *
4449 * @param obj object to set the map source of
4450 * @return the object set as the source
4451 *
4452 * @see evas_object_map_source_set()
4453 */
4454EAPI Evas_Object *evas_object_map_source_get (const Evas_Object *obj);
4455
4456/**
4457 * Set current object transformation map.
4458 *
4459 * This sets the map on a given object. It is copied from the @p map pointer,
4460 * so there is no need to keep the @p map object if you don't need it anymore.
4461 *
4462 * A map is a set of 4 points which have canvas x, y coordinates per point,
4463 * with an optional z point value as a hint for perspective correction, if it
4464 * is available. As well each point has u and v coordinates. These are like
4465 * "texture coordinates" in OpenGL in that they define a point in the source
4466 * image that is mapped to that map vertex/point. The u corresponds to the x
4467 * coordinate of this mapped point and v, the y coordinate. Note that these
4468 * coordinates describe a bounding region to sample. If you have a 200x100
4469 * source image and want to display it at 200x100 with proper pixel
4470 * precision, then do:
4471 *
4472 * @code
4473 * Evas_Map *m = evas_map_new(4);
4474 * evas_map_point_coord_set(m, 0, 0, 0, 0);
4475 * evas_map_point_coord_set(m, 1, 200, 0, 0);
4476 * evas_map_point_coord_set(m, 2, 200, 100, 0);
4477 * evas_map_point_coord_set(m, 3, 0, 100, 0);
4478 * evas_map_point_image_uv_set(m, 0, 0, 0);
4479 * evas_map_point_image_uv_set(m, 1, 200, 0);
4480 * evas_map_point_image_uv_set(m, 2, 200, 100);
4481 * evas_map_point_image_uv_set(m, 3, 0, 100);
4482 * evas_object_map_set(obj, m);
4483 * evas_map_free(m);
4484 * @endcode
4485 *
4486 * Note that the map points a uv coordinates match the image geometry. If
4487 * the @p map parameter is NULL, the stored map will be freed and geometry
4488 * prior to enabling/setting a map will be restored.
4489 *
4490 * @param obj object to change transformation map
4491 * @param map new map to use
4492 *
4493 * @see evas_map_new()
4494 */
4495EAPI void evas_object_map_set (Evas_Object *obj, const Evas_Map *map);
4496
4497/**
4498 * Get current object transformation map.
4499 *
4500 * This returns the current internal map set on the indicated object. It is
4501 * intended for read-only acces and is only valid as long as the object is
4502 * not deleted or the map on the object is not changed. If you wish to modify
4503 * the map and set it back do the following:
4504 *
4505 * @code
4506 * const Evas_Map *m = evas_object_map_get(obj);
4507 * Evas_Map *m2 = evas_map_dup(m);
4508 * evas_map_util_rotate(m2, 30.0, 0, 0);
4509 * evas_object_map_set(obj);
4510 * evas_map_free(m2);
4511 * @endcode
4512 *
4513 * @param obj object to query transformation map.
4514 * @return map reference to map in use. This is an internal data structure, so
4515 * do not modify it.
4516 *
4517 * @see evas_object_map_set()
4518 */
4519EAPI const Evas_Map *evas_object_map_get (const Evas_Object *obj);
4520
4521
4522/**
4523 * Populate source and destination map points to match exactly object.
4524 *
4525 * Usually one initialize map of an object to match it's original
4526 * position and size, then transform these with evas_map_util_*
4527 * functions, such as evas_map_util_rotate() or
4528 * evas_map_util_3d_rotate(). The original set is done by this
4529 * function, avoiding code duplication all around.
4530 *
4531 * @param m map to change all 4 points (must be of size 4).
4532 * @param obj object to use unmapped geometry to populate map coordinates.
4533 * @param z Point Z Coordinate hint (pre-perspective transform). This value
4534 * will be used for all four points.
4535 *
4536 * @see evas_map_util_points_populate_from_object()
4537 * @see evas_map_point_coord_set()
4538 * @see evas_map_point_image_uv_set()
4539 */
4540EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
4541
4542/**
4543 * Populate source and destination map points to match exactly object.
4544 *
4545 * Usually one initialize map of an object to match it's original
4546 * position and size, then transform these with evas_map_util_*
4547 * functions, such as evas_map_util_rotate() or
4548 * evas_map_util_3d_rotate(). The original set is done by this
4549 * function, avoiding code duplication all around.
4550 *
4551 * Z Point coordinate is assumed as 0 (zero).
4552 *
4553 * @param m map to change all 4 points (must be of size 4).
4554 * @param obj object to use unmapped geometry to populate map coordinates.
4555 *
4556 * @see evas_map_util_points_populate_from_object_full()
4557 * @see evas_map_util_points_populate_from_geometry()
4558 * @see evas_map_point_coord_set()
4559 * @see evas_map_point_image_uv_set()
4560 */
4561EAPI void evas_map_util_points_populate_from_object (Evas_Map *m, const Evas_Object *obj);
4562
4563/**
4564 * Populate source and destination map points to match given geometry.
4565 *
4566 * Similar to evas_map_util_points_populate_from_object_full(), this
4567 * call takes raw values instead of querying object's unmapped
4568 * geometry. The given width will be used to calculate destination
4569 * points (evas_map_point_coord_set()) and set the image uv
4570 * (evas_map_point_image_uv_set()).
4571 *
4572 * @param m map to change all 4 points (must be of size 4).
4573 * @param x Point X Coordinate
4574 * @param y Point Y Coordinate
4575 * @param w width to use to calculate second and third points.
4576 * @param h height to use to calculate third and fourth points.
4577 * @param z Point Z Coordinate hint (pre-perspective transform). This value
4578 * will be used for all four points.
4579 *
4580 * @see evas_map_util_points_populate_from_object()
4581 * @see evas_map_point_coord_set()
4582 * @see evas_map_point_image_uv_set()
4583 */
4584EAPI 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);
4585
4586/**
4587 * Set color of all points to given color.
4588 *
4589 * This call is useful to reuse maps after they had 3d lightning or
4590 * any other colorization applied before.
4591 *
4592 * @param m map to change the color of.
4593 * @param r red (0 - 255)
4594 * @param g green (0 - 255)
4595 * @param b blue (0 - 255)
4596 * @param a alpha (0 - 255)
4597 *
4598 * @see evas_map_point_color_set()
4599 */
4600EAPI void evas_map_util_points_color_set (Evas_Map *m, int r, int g, int b, int a);
4601
4602/**
4603 * Change the map to apply the given rotation.
4604 *
4605 * This rotates the indicated map's coordinates around the center coordinate
4606 * given by @p cx and @p cy as the rotation center. The points will have their
4607 * X and Y coordinates rotated clockwise by @p degrees degress (360.0 is a
4608 * full rotation). Negative values for degrees will rotate counter-clockwise
4609 * by that amount. All coordinates are canvas global coordinates.
4610 *
4611 * @param m map to change.
4612 * @param degrees amount of degrees from 0.0 to 360.0 to rotate.
4613 * @param cx rotation's center horizontal position.
4614 * @param cy rotation's center vertical position.
4615 *
4616 * @see evas_map_point_coord_set()
4617 * @see evas_map_util_zoom()
4618 */
4619EAPI void evas_map_util_rotate (Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
4620
4621/**
4622 * Change the map to apply the given zooming.
4623 *
4624 * Like evas_map_util_rotate(), this zooms the points of the map from a center
4625 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
4626 * parameters specify how much to zoom in the X and Y direction respectively.
4627 * A value of 1.0 means "don't zoom". 2.0 means "dobule the size". 0.5 is
4628 * "half the size" etc. All coordinates are canvas global coordinates.
4629 *
4630 * @param m map to change.
4631 * @param zoomx horizontal zoom to use.
4632 * @param zoomy vertical zoom to use.
4633 * @param cx zooming center horizontal position.
4634 * @param cy zooming center vertical position.
4635 *
4636 * @see evas_map_point_coord_set()
4637 * @see evas_map_util_rotate()
4638 */
4639EAPI void evas_map_util_zoom (Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
4640
4641/**
4642 * Rotate the map around 3 axes in 3D
4643 *
4644 * This will rotate not just around the "Z" axis as in evas_map_util_rotate()
4645 * (which is a convenience call for those only wanting 2D). This will rotate
4646 * around the X, Y and Z axes. The Z axis points "into" the screen with low
4647 * values at the screen and higher values further away. The X axis runs from
4648 * left to right on the screen and the Y axis from top to bottom. Like with
4649 * evas_map_util_rotate() you provide a center point to rotate around (in 3D).
4650 *
4651 * @param m map to change.
4652 * @param dx amount of degrees from 0.0 to 360.0 to rotate arount X axis.
4653 * @param dy amount of degrees from 0.0 to 360.0 to rotate arount Y axis.
4654 * @param dz amount of degrees from 0.0 to 360.0 to rotate arount Z axis.
4655 * @param cx rotation's center horizontal position.
4656 * @param cy rotation's center vertical position.
4657 * @param cz rotation's center vertical position.
4658 */
4659EAPI void evas_map_util_3d_rotate (Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz);
4660
4661/**
4662 * Perform lighting calculations on the given Map
4663 *
4664 * This is used to apply lighting calculations (from a single light source)
4665 * to a given map. The R, G and B values of each vertex will be modified to
4666 * reflect the lighting based on the lixth point coordinates, the light
4667 * color and the ambient color, and at what angle the map is facing the
4668 * light source. A surface should have its points be declared in a
4669 * clockwise fashion if the face is "facing" towards you (as opposed to
4670 * away from you) as faces have a "logical" side for lighting.
4671 *
4672 * @image html map-light3.png
4673 * @image rtf map-light3.png
4674 * @image latex map-light3.eps
4675 * @note Grey object, no lighting used
4676 *
4677 * @image html map-light4.png
4678 * @image rtf map-light4.png
4679 * @image latex map-light4.eps
4680 * @note Lights out! Every color set to 0
4681 *
4682 * @image html map-light5.png
4683 * @image rtf map-light5.png
4684 * @image latex map-light5.eps
4685 * @note Ambient light to full black, red light coming from close at the
4686 * bottom-left vertex
4687 *
4688 * @image html map-light6.png
4689 * @image rtf map-light6.png
4690 * @image latex map-light6.eps
4691 * @note Same light as before, but not the light is set to 0 and ambient light
4692 * is cyan
4693 *
4694 * @image html map-light7.png
4695 * @image rtf map-light7.png
4696 * @image latex map-light7.eps
4697 * @note Both lights are on
4698 *
4699 * @image html map-light8.png
4700 * @image rtf map-light8.png
4701 * @image latex map-light8.eps
4702 * @note Both lights again, but this time both are the same color.
4703 *
4704 * @param m map to change.
4705 * @param lx X coordinate in space of light point
4706 * @param ly Y coordinate in space of light point
4707 * @param lz Z coordinate in space of light point
4708 * @param lr light red value (0 - 255)
4709 * @param lg light green value (0 - 255)
4710 * @param lb light blue value (0 - 255)
4711 * @param ar ambient color red value (0 - 255)
4712 * @param ag ambient color green value (0 - 255)
4713 * @param ab ambient color blue value (0 - 255)
4714 */
4715EAPI 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);
4716
4717/**
4718 * Apply a perspective transform to the map
4719 *
4720 * This applies a given perspective (3D) to the map coordinates. X, Y and Z
4721 * values are used. The px and py points specify the "infinite distance" point
4722 * in the 3D conversion (where all lines converge to like when artists draw
4723 * 3D by hand). The @p z0 value specifis the z value at which there is a 1:1
4724 * mapping between spatial coorinates and screen coordinates. Any points
4725 * on this z value will not have their X and Y values modified in the transform.
4726 * Those further away (Z value higher) will shrink into the distance, and
4727 * those less than this value will expand and become bigger. The @p foc value
4728 * determines the "focal length" of the camera. This is in reality the distance
4729 * between the camera lens plane itself (at or closer than this rendering
4730 * results are undefined) and the "z0" z value. This allows for some "depth"
4731 * control and @p foc must be greater than 0.
4732 *
4733 * @param m map to change.
4734 * @param px The pespective distance X coordinate
4735 * @param py The pespective distance Y coordinate
4736 * @param z0 The "0" z plane value
4737 * @param foc The focal distance
4738 */
4739EAPI void evas_map_util_3d_perspective (Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
4740
4741/**
4742 * Get the clockwise state of a map
4743 *
4744 * This determines if the output points (X and Y. Z is not used) are
4745 * clockwise or anti-clockwise. This can be used for "back-face culling". This
4746 * is where you hide objects that "face away" from you. In this case objects
4747 * that are not clockwise.
4748 *
4749 * @param m map to query.
4750 * @return 1 if clockwise, 0 otherwise
4751 */
4752EAPI Eina_Bool evas_map_util_clockwise_get (Evas_Map *m);
4753
4754
4755/**
4756 * Create map of transformation points to be later used with an Evas object.
4757 *
4758 * This creates a set of points (currently only 4 is supported. no other
4759 * number for @p count will work). That is empty and ready to be modified
4760 * with evas_map calls.
4761 *
4762 * @param count number of points in the map.
4763 * @return a newly allocated map or @c NULL on errors.
4764 *
4765 * @see evas_map_free()
4766 * @see evas_map_dup()
4767 * @see evas_map_point_coord_set()
4768 * @see evas_map_point_image_uv_set()
4769 * @see evas_map_util_points_populate_from_object_full()
4770 * @see evas_map_util_points_populate_from_object()
4771 *
4772 * @see evas_object_map_set()
4773 */
4774EAPI Evas_Map *evas_map_new (int count);
4775
4776/**
4777 * Set the smoothing for map rendering
4778 *
4779 * This sets smoothing for map rendering. If the object is a type that has
4780 * its own smoothing settings, then both the smooth settings for this object
4781 * and the map must be turned off. By default smooth maps are enabled.
4782 *
4783 * @param m map to modify. Must not be NULL.
4784 * @param enabled enable or disable smooth map rendering
4785 */
4786EAPI void evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled);
4787
4788/**
4789 * get the smoothing for map rendering
4790 *
4791 * This gets smoothing for map rendering.
4792 *
4793 * @param m map to get the smooth from. Must not be NULL.
4794 */
4795EAPI Eina_Bool evas_map_smooth_get (const Evas_Map *m);
4796
4797/**
4798 * Set the alpha flag for map rendering
4799 *
4800 * This sets alpha flag for map rendering. If the object is a type that has
4801 * its own alpha settings, then this will take precedence. Only image objects
4802 * have this currently.
4803 * Setting this off stops alpha blending of the map area, and is
4804 * useful if you know the object and/or all sub-objects is 100% solid.
4805 *
4806 * @param m map to modify. Must not be NULL.
4807 * @param enabled enable or disable alpha map rendering
4808 */
4809EAPI void evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled);
4810
4811/**
4812 * get the alpha flag for map rendering
4813 *
4814 * This gets the alph flag for map rendering.
4815 *
4816 * @param m map to get the alpha from. Must not be NULL.
4817 */
4818EAPI Eina_Bool evas_map_alpha_get (const Evas_Map *m);
4819
4820/**
4821 * Copy a previously allocated map.
4822 *
4823 * This makes a duplicate of the @p m object and returns it.
4824 *
4825 * @param m map to copy. Must not be NULL.
4826 * @return newly allocated map with the same count and contents as @p m.
4827 */
4828EAPI Evas_Map *evas_map_dup (const Evas_Map *m);
4829
4830/**
4831 * Free a previously allocated map.
4832 *
4833 * This frees a givem map @p m and all memory associated with it. You must NOT
4834 * free a map returned by evas_object_map_get() as this is internal.
4835 *
4836 * @param m map to free.
4837 */
4838EAPI void evas_map_free (Evas_Map *m);
4839
4840/**
4841 * Get a maps size.
4842 *
4843 * Returns the number of points in a map. Should be at least 4.
4844 *
4845 * @param m map to get size.
4846 * @return -1 on error, points otherwise.
4847 */
4848EAPI int evas_map_count_get (const Evas_Map *m) EINA_CONST;
4849
4850/**
4851 * Change the map point's coordinate.
4852 *
4853 * This sets the fixed point's coordinate in the map. Note that points
4854 * describe the outline of a quadrangle and are ordered either clockwise
4855 * or anit-clock-wise. It is suggested to keep your quadrangles concave and
4856 * non-complex, though these polygon modes may work, they may not render
4857 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
4858 * 2 and 3, and 3 and 0 to describe the edges of the quandrangle.
4859 *
4860 * The X and Y and Z coordinates are in canvas units. Z is optional and may
4861 * or may not be honored in drawing. Z is a hint and does not affect the
4862 * X and Y rendered coordinates. It may be used for calculating fills with
4863 * perspective correct rendering.
4864 *
4865 * Remember all coordinates are canvas global ones like with move and reize
4866 * in evas.
4867 *
4868 * @param m map to change point. Must not be @c NULL.
4869 * @param idx index of point to change. Must be smaller than map size.
4870 * @param x Point X Coordinate
4871 * @param y Point Y Coordinate
4872 * @param z Point Z Coordinate hint (pre-perspective transform)
4873 *
4874 * @see evas_map_util_rotate()
4875 * @see evas_map_util_zoom()
4876 * @see evas_map_util_points_populate_from_object_full()
4877 * @see evas_map_util_points_populate_from_object()
4878 */
4879EAPI void evas_map_point_coord_set (Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
4880
4881/**
4882 * Get the map point's coordinate.
4883 *
4884 * This returns the coordinates of the given point in the map.
4885 *
4886 * @param m map to query point.
4887 * @param idx index of point to query. Must be smaller than map size.
4888 * @param x where to return the X coordinate.
4889 * @param y where to return the Y coordinate.
4890 * @param z where to return the Z coordinate.
4891 */
4892EAPI void evas_map_point_coord_get (const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
4893
4894/**
4895 * Change the map point's U and V texture source point
4896 *
4897 * This sets the U and V coordinates for the point. This determines which
4898 * coordinate in the source image is mapped to the given point, much like
4899 * OpenGL and textures. Notes that these points do select the pixel, but
4900 * are double floating point values to allow for accuracy and sub-pixel
4901 * selection.
4902 *
4903 * @param m map to change the point of.
4904 * @param idx index of point to change. Must be smaller than map size.
4905 * @param u the X coordinate within the image/texture source
4906 * @param v the Y coordinate within the image/texture source
4907 *
4908 * @see evas_map_point_coord_set()
4909 * @see evas_object_map_set()
4910 * @see evas_map_util_points_populate_from_object_full()
4911 * @see evas_map_util_points_populate_from_object()
4912 */
4913EAPI void evas_map_point_image_uv_set (Evas_Map *m, int idx, double u, double v);
4914
4915/**
4916 * Get the map point's U and V texture source points
4917 *
4918 * This returns the texture points set by evas_map_point_image_uv_set().
4919 *
4920 * @param m map to query point.
4921 * @param idx index of point to query. Must be smaller than map size.
4922 * @param u where to write the X coordinate within the image/texture source
4923 * @param v where to write the Y coordinate within the image/texture source
4924 */
4925EAPI void evas_map_point_image_uv_get (const Evas_Map *m, int idx, double *u, double *v);
4926
4927/**
4928 * Set the color of a vertex in the map
4929 *
4930 * This sets the color of the vertex in the map. Colors will be linearly
4931 * interpolated between vertex points through the map. Color will multiply
4932 * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
4933 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
4934 * have no affect on modifying the texture pixels.
4935 *
4936 * @param m map to change the color of.
4937 * @param idx index of point to change. Must be smaller than map size.
4938 * @param r red (0 - 255)
4939 * @param g green (0 - 255)
4940 * @param b blue (0 - 255)
4941 * @param a alpha (0 - 255)
4942 *
4943 * @see evas_map_util_points_color_set()
4944 * @see evas_map_point_coord_set()
4945 * @see evas_object_map_set()
4946 */
4947EAPI void evas_map_point_color_set (Evas_Map *m, int idx, int r, int g, int b, int a);
4948
4949/**
4950 * Get the color set on a vertex in the map
4951 *
4952 * This gets the color set by evas_map_point_color_set() on the given vertex
4953 * of the map.
4954 *
4955 * @param m map to get the color of the vertex from.
4956 * @param idx index of point get. Must be smaller than map size.
4957 * @param r pointer to red return
4958 * @param g pointer to green return
4959 * @param b pointer to blue return
4960 * @param a pointer to alpha return (0 - 255)
4961 *
4962 * @see evas_map_point_coord_set()
4963 * @see evas_object_map_set()
4964 */
4965EAPI void evas_map_point_color_get (const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
4966/**
4967 * @}
4968 */
4969
4970/**
4971 * @defgroup Evas_Object_Group_Size_Hints Size Hints
4972 *
4973 * Objects may carry hints, so that another object that acts as a
4974 * manager (see @ref Evas_Smart_Object_Group) may know how to properly
4975 * position and resize its subordinate objects. The Size Hints provide
4976 * a common interface that is recommended as the protocol for such
4977 * information.
4978 *
4979 * For example, box objects use alignment hints to align its
4980 * lines/columns inside its container, padding hints to set the
4981 * padding between each individual child, etc.
4982 *
4983 * Examples on their usage:
4984 * - @ref Example_Evas_Size_Hints "evas-hints.c"
4985 * - @ref Example_Evas_Aspect_Hints "evas-aspect-hints.c"
4986 *
4987 * @ingroup Evas_Object_Group
4988 */
4989
4990/**
4991 * @addtogroup Evas_Object_Group_Size_Hints
4992 * @{
4993 */
4994
4995/**
4996 * Retrieves the hints for an object's minimum size.
4997 *
4998 * @param obj The given Evas object to query hints from.
4999 * @param w Pointer to an integer in which to store the minimum width.
5000 * @param h Pointer to an integer in which to store the minimum height.
5001 *
5002 * These are hints on the minimim sizes @p obj should have. This is
5003 * not a size enforcement in any way, it's just a hint that should be
5004 * used whenever appropriate.
5005 *
5006 * @note Use @c NULL pointers on the hint components you're not
5007 * interested in: they'll be ignored by the function.
5008 *
5009 * @see evas_object_size_hint_min_set() for an example
5010 */
5011EAPI void evas_object_size_hint_min_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
5012
5013/**
5014 * Sets the hints for an object's minimum size.
5015 *
5016 * @param obj The given Evas object to query hints from.
5017 * @param w Integer to use as the minimum width hint.
5018 * @param h Integer to use as the minimum height hint.
5019 *
5020 * This is not a size enforcement in any way, it's just a hint that
5021 * should be used whenever appropriate.
5022 *
5023 * Values @c 0 will be treated as unset hint components, when queried
5024 * by managers.
5025 *
5026 * Example:
5027 * @dontinclude evas-hints.c
5028 * @skip evas_object_size_hint_min_set
5029 * @until return
5030 *
5031 * In this example the minimum size hints change de behavior of an
5032 * Evas box when layouting its children. See the full @ref
5033 * Example_Evas_Size_Hints "example".
5034 *
5035 * @see evas_object_size_hint_min_get()
5036 */
5037EAPI void evas_object_size_hint_min_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
5038
5039/**
5040 * Retrieves the hints for an object's maximum size.
5041 *
5042 * @param obj The given Evas object to query hints from.
5043 * @param w Pointer to an integer in which to store the maximum width.
5044 * @param h Pointer to an integer in which to store the maximum height.
5045 *
5046 * These are hints on the maximum sizes @p obj should have. This is
5047 * not a size enforcement in any way, it's just a hint that should be
5048 * used whenever appropriate.
5049 *
5050 * @note Use @c NULL pointers on the hint components you're not
5051 * interested in: they'll be ignored by the function.
5052 *
5053 * @see evas_object_size_hint_max_set()
5054 */
5055EAPI void evas_object_size_hint_max_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
5056
5057/**
5058 * Sets the hints for an object's maximum size.
5059 *
5060 * @param obj The given Evas object to query hints from.
5061 * @param w Integer to use as the maximum width hint.
5062 * @param h Integer to use as the maximum height hint.
5063 *
5064 * This is not a size enforcement in any way, it's just a hint that
5065 * should be used whenever appropriate.
5066 *
5067 * Values @c -1 will be treated as unset hint components, when queried
5068 * by managers.
5069 *
5070 * Example:
5071 * @dontinclude evas-hints.c
5072 * @skip evas_object_size_hint_max_set
5073 * @until return
5074 *
5075 * In this example the maximum size hints change de behavior of an
5076 * Evas box when layouting its children. See the full @ref
5077 * Example_Evas_Size_Hints "example".
5078 *
5079 * @see evas_object_size_hint_max_get()
5080 */
5081EAPI void evas_object_size_hint_max_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
5082
5083/**
5084 * Retrieves the hints for an object's optimum size.
5085 *
5086 * @param obj The given Evas object to query hints from.
5087 * @param w Pointer to an integer in which to store the requested width.
5088 * @param h Pointer to an integer in which to store the requested height.
5089 *
5090 * These are hints on the optimum sizes @p obj should have. This is
5091 * not a size enforcement in any way, it's just a hint that should be
5092 * used whenever appropriate.
5093 *
5094 * @note Use @c NULL pointers on the hint components you're not
5095 * interested in: they'll be ignored by the function.
5096 *
5097 * @see evas_object_size_hint_request_set()
5098 */
5099EAPI void evas_object_size_hint_request_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
5100
5101/**
5102 * Sets the hints for an object's optimum size.
5103 *
5104 * @param obj The given Evas object to query hints from.
5105 * @param w Integer to use as the preferred width hint.
5106 * @param h Integer to use as the preferred height hint.
5107 *
5108 * This is not a size enforcement in any way, it's just a hint that
5109 * should be used whenever appropriate.
5110 *
5111 * Values @c 0 will be treated as unset hint components, when queried
5112 * by managers.
5113 *
5114 * @see evas_object_size_hint_request_get()
5115 */
5116EAPI void evas_object_size_hint_request_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
5117
5118/**
5119 * Retrieves the hints for an object's aspect ratio.
5120 *
5121 * @param obj The given Evas object to query hints from.
5122 * @param aspect Returns the policy/type of aspect ratio applied to @p obj.
5123 * @param w Pointer to an integer in which to store the aspect's width
5124 * ratio term.
5125 * @param h Pointer to an integer in which to store the aspect's
5126 * height ratio term.
5127 *
5128 * The different aspect ratio policies are documented in the
5129 * #Evas_Aspect_Control type. A container respecting these size hints
5130 * would @b resize its children accordingly to those policies.
5131 *
5132 * For any policy, if any of the given aspect ratio terms are @c 0,
5133 * the object's container should ignore the aspect and scale @p obj to
5134 * occupy the whole available area. If they are both positive
5135 * integers, that proportion will be respected, under each scaling
5136 * policy.
5137 *
5138 * These images illustrate some of the #Evas_Aspect_Control policies:
5139 *
5140 * @image html any-policy.png
5141 * @image rtf any-policy.png
5142 * @image latex any-policy.eps
5143 *
5144 * @image html aspect-control-none-neither.png
5145 * @image rtf aspect-control-none-neither.png
5146 * @image latex aspect-control-none-neither.eps
5147 *
5148 * @image html aspect-control-both.png
5149 * @image rtf aspect-control-both.png
5150 * @image latex aspect-control-both.eps
5151 *
5152 * @image html aspect-control-horizontal.png
5153 * @image rtf aspect-control-horizontal.png
5154 * @image latex aspect-control-horizontal.eps
5155 *
5156 * This is not a size enforcement in any way, it's just a hint that
5157 * should be used whenever appropriate.
5158 *
5159 * @note Use @c NULL pointers on the hint components you're not
5160 * interested in: they'll be ignored by the function.
5161 *
5162 * Example:
5163 * @dontinclude evas-aspect-hints.c
5164 * @skip if (strcmp(ev->keyname, "c") == 0)
5165 * @until }
5166 *
5167 * See the full @ref Example_Evas_Aspect_Hints "example".
5168 *
5169 * @see evas_object_size_hint_aspect_set()
5170 */
5171EAPI 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);
5172
5173/**
5174 * Sets the hints for an object's aspect ratio.
5175 *
5176 * @param obj The given Evas object to query hints from.
5177 * @param aspect The policy/type of aspect ratio to apply to @p obj.
5178 * @param w Integer to use as aspect width ratio term.
5179 * @param h Integer to use as aspect height ratio term.
5180 *
5181 * This is not a size enforcement in any way, it's just a hint that should
5182 * be used whenever appropriate.
5183 *
5184 * If any of the given aspect ratio terms are @c 0,
5185 * the object's container will ignore the aspect and scale @p obj to
5186 * occupy the whole available area, for any given policy.
5187 *
5188 * @see evas_object_size_hint_aspect_get() for more information.
5189 */
5190EAPI void evas_object_size_hint_aspect_set (Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
5191
5192/**
5193 * Retrieves the hints for on object's alignment.
5194 *
5195 * @param obj The given Evas object to query hints from.
5196 * @param x Pointer to a double in which to store the horizontal
5197 * alignment hint.
5198 * @param y Pointer to a double in which to store the vertical
5199 * alignment hint.
5200 *
5201 * This is not a size enforcement in any way, it's just a hint that
5202 * should be used whenever appropriate.
5203 *
5204 * @note Use @c NULL pointers on the hint components you're not
5205 * interested in: they'll be ignored by the function.
5206 *
5207 * @see evas_object_size_hint_align_set() for more information
5208 */
5209EAPI void evas_object_size_hint_align_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
5210
5211/**
5212 * Sets the hints for an object's alignment.
5213 *
5214 * @param obj The given Evas object to query hints from.
5215 * @param x Double, ranging from @c 0.0 to @c 1.0 or with the
5216 * special value #EVAS_HINT_FILL, to use as horizontal alignment hint.
5217 * @param y Double, ranging from @c 0.0 to @c 1.0 or with the
5218 * special value #EVAS_HINT_FILL, to use as vertical alignment hint.
5219 *
5220 * These are hints on how to align an object <b>inside the boundaries
5221 * of a container/manager</b>. Accepted values are in the @c 0.0 to @c
5222 * 1.0 range, with the special value #EVAS_HINT_FILL used to specify
5223 * "justify" or "fill" by some users. In this case, maximum size hints
5224 * should be enforced with higher priority, if they are set. Also, any
5225 * padding hint set on objects should add up to the alignment space on
5226 * the final scene composition.
5227 *
5228 * See documentation of possible users: in Evas, they are the @ref
5229 * Evas_Object_Box "box" and @ref Evas_Object_Table "table" smart
5230 * objects.
5231 *
5232 * For the horizontal component, @c 0.0 means to the left, @c 1.0
5233 * means to the right. Analogously, for the vertical component, @c 0.0
5234 * to the top, @c 1.0 means to the bottom.
5235 *
5236 * See the following figure:
5237 *
5238 * @image html alignment-hints.png
5239 * @image rtf alignment-hints.png
5240 * @image latex alignment-hints.eps
5241 *
5242 * This is not a size enforcement in any way, it's just a hint that
5243 * should be used whenever appropriate.
5244 *
5245 * Example:
5246 * @dontinclude evas-hints.c
5247 * @skip evas_object_size_hint_align_set
5248 * @until return
5249 *
5250 * In this example the alignment hints change de behavior of an Evas
5251 * box when layouting its children. See the full @ref
5252 * Example_Evas_Size_Hints "example".
5253 *
5254 * @see evas_object_size_hint_align_get()
5255 * @see evas_object_size_hint_max_set()
5256 * @see evas_object_size_hint_padding_set()
5257 */
5258EAPI void evas_object_size_hint_align_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
5259
5260/**
5261 * Retrieves the hints for an object's weight.
5262 *
5263 * @param obj The given Evas object to query hints from.
5264 * @param x Pointer to a double in which to store the horizontal weight.
5265 * @param y Pointer to a double in which to store the vertical weight.
5266 *
5267 * Accepted values are zero or positive values. Some users might use
5268 * this hint as a boolean, but some might consider it as a @b
5269 * proportion, see documentation of possible users, which in Evas are
5270 * the @ref Evas_Object_Box "box" and @ref Evas_Object_Table "table"
5271 * smart objects.
5272 *
5273 * This is not a size enforcement in any way, it's just a hint that
5274 * should be used whenever appropriate.
5275 *
5276 * @note Use @c NULL pointers on the hint components you're not
5277 * interested in: they'll be ignored by the function.
5278 *
5279 * @see evas_object_size_hint_weight_set() for an example
5280 */
5281EAPI void evas_object_size_hint_weight_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
5282
5283/**
5284 * Sets the hints for an object's weight.
5285 *
5286 * @param obj The given Evas object to query hints from.
5287 * @param x Nonnegative double value to use as horizontal weight hint.
5288 * @param y Nonnegative double value to use as vertical weight hint.
5289 *
5290 * This is not a size enforcement in any way, it's just a hint that
5291 * should be used whenever appropriate.
5292 *
5293 * This is a hint on how a container object should @b resize a given
5294 * child within its area. Containers may adhere to the simpler logic
5295 * of just expanding the child object's dimensions to fit its own (see
5296 * the #EVAS_HINT_EXPAND helper weight macro) or the complete one of
5297 * taking each child's weight hint as real @b weights to how much of
5298 * its size to allocate for them in each axis. A container is supposed
5299 * to, after @b normalizing the weights of its children (with weight
5300 * hints), distribute the space it has to layout them by those factors
5301 * -- most weighted children get larger in this process than the least
5302 * ones.
5303 *
5304 * Example:
5305 * @dontinclude evas-hints.c
5306 * @skip evas_object_size_hint_weight_set
5307 * @until return
5308 *
5309 * In this example the weight hints change de behavior of an Evas box
5310 * when layouting its children. See the full @ref
5311 * Example_Evas_Size_Hints "example".
5312 *
5313 * @see evas_object_size_hint_weight_get() for more information
5314 */
5315EAPI void evas_object_size_hint_weight_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
5316
5317/**
5318 * Retrieves the hints for an object's padding space.
5319 *
5320 * @param obj The given Evas object to query hints from.
5321 * @param l Pointer to an integer in which to store left padding.
5322 * @param r Pointer to an integer in which to store right padding.
5323 * @param t Pointer to an integer in which to store top padding.
5324 * @param b Pointer to an integer in which to store bottom padding.
5325 *
5326 * Padding is extra space an object takes on each of its delimiting
5327 * rectangle sides, in canvas units. This space will be rendered
5328 * transparent, naturally, as in the following figure:
5329 *
5330 * @image html padding-hints.png
5331 * @image rtf padding-hints.png
5332 * @image latex padding-hints.eps
5333 *
5334 * This is not a size enforcement in any way, it's just a hint that
5335 * should be used whenever appropriate.
5336 *
5337 * @note Use @c NULL pointers on the hint components you're not
5338 * interested in: they'll be ignored by the function.
5339 *
5340 * Example:
5341 * @dontinclude evas-hints.c
5342 * @skip evas_object_size_hint_padding_set
5343 * @until return
5344 *
5345 * In this example the padding hints change de behavior of an Evas box
5346 * when layouting its children. See the full @ref
5347 * Example_Evas_Size_Hints "example".
5348 *
5349 * @see evas_object_size_hint_padding_set()
5350 */
5351EAPI 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);
5352
5353/**
5354 * Sets the hints for an object's padding space.
5355 *
5356 * @param obj The given Evas object to query hints from.
5357 * @param l Integer to specify left padding.
5358 * @param r Integer to specify right padding.
5359 * @param t Integer to specify top padding.
5360 * @param b Integer to specify bottom padding.
5361 *
5362 * This is not a size enforcement in any way, it's just a hint that
5363 * should be used whenever appropriate.
5364 *
5365 * @see evas_object_size_hint_padding_get() for more information
5366 */
5367EAPI 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);
5368
5369/**
5370 * @}
5371 */
5372
5373/**
5374 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
5375 *
5376 * Miscellaneous functions that also apply to any object, but are less
5377 * used or not implemented by all objects.
5378 *
5379 * Examples on this group of functions can be found @ref
5380 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
5381 *
5382 * @ingroup Evas_Object_Group
5383 */
5384
5385/**
5386 * @addtogroup Evas_Object_Group_Extras
5387 * @{
5388 */
5389
5390/**
5391 * Set an attached data pointer to an object with a given string key.
5392 *
5393 * @param obj The object to attach the data pointer to
5394 * @param key The string key for the data to access it
5395 * @param data The ponter to the data to be attached
5396 *
5397 * This attaches the pointer @p data to the object @p obj, given the
5398 * access string @p key. This pointer will stay "hooked" to the object
5399 * until a new pointer with the same string key is attached with
5400 * evas_object_data_set() or it is deleted with
5401 * evas_object_data_del(). On deletion of the object @p obj, the
5402 * pointers will not be accessible from the object anymore.
5403 *
5404 * You can find the pointer attached under a string key using
5405 * evas_object_data_get(). It is the job of the calling application to
5406 * free any data pointed to by @p data when it is no longer required.
5407 *
5408 * If @p data is @c NULL, the old value stored at @p key will be
5409 * removed but no new value will be stored. This is synonymous with
5410 * calling evas_object_data_del() with @p obj and @p key.
5411 *
5412 * @note This function is very handy when you have data associated
5413 * specifically to an Evas object, being of use only when dealing with
5414 * it. Than you don't have the burden to a pointer to it elsewhere,
5415 * using this family of functions.
5416 *
5417 * Example:
5418 *
5419 * @code
5420 * int *my_data;
5421 * extern Evas_Object *obj;
5422 *
5423 * my_data = malloc(500);
5424 * evas_object_data_set(obj, "name_of_data", my_data);
5425 * printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data"));
5426 * @endcode
5427 */
5428EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2);
5429
5430/**
5431 * Return an attached data pointer on an Evas object by its given
5432 * string key.
5433 *
5434 * @param obj The object to which the data was attached
5435 * @param key The string key the data was stored under
5436 * @return The data pointer stored, or @c NULL if none was stored
5437 *
5438 * This function will return the data pointer attached to the object
5439 * @p obj, stored using the string key @p key. If the object is valid
5440 * and a data pointer was stored under the given key, that pointer
5441 * will be returned. If this is not the case, @c NULL will be
5442 * returned, signifying an invalid object or a non-existent key. It is
5443 * possible that a @c NULL pointer was stored given that key, but this
5444 * situation is non-sensical and thus can be considered an error as
5445 * well. @c NULL pointers are never stored as this is the return value
5446 * if an error occurs.
5447 *
5448 * Example:
5449 *
5450 * @code
5451 * int *my_data;
5452 * extern Evas_Object *obj;
5453 *
5454 * my_data = evas_object_data_get(obj, "name_of_my_data");
5455 * if (my_data) printf("Data stored was %p\n", my_data);
5456 * else printf("No data was stored on the object\n");
5457 * @endcode
5458 */
5459EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
5460
5461/**
5462 * Delete an attached data pointer from an object.
5463 *
5464 * @param obj The object to delete the data pointer from
5465 * @param key The string key the data was stored under
5466 * @return The original data pointer stored at @p key on @p obj
5467 *
5468 * This will remove the stored data pointer from @p obj stored under
5469 * @p key and return this same pointer, if actually there was data
5470 * there, or @c NULL, if nothing was stored under that key.
5471 *
5472 * Example:
5473 *
5474 * @code
5475 * int *my_data;
5476 * extern Evas_Object *obj;
5477 *
5478 * my_data = evas_object_data_del(obj, "name_of_my_data");
5479 * @endcode
5480 */
5481EAPI void *evas_object_data_del (Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
5482
5483
5484/**
5485 * Set pointer behavior.
5486 *
5487 * @param obj
5488 * @param setting desired behavior.
5489 *
5490 * This function has direct effect on event callbacks related to
5491 * mouse.
5492 *
5493 * If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse
5494 * is down at this object, events will be restricted to it as source,
5495 * mouse moves, for example, will be emitted even if outside this
5496 * object area.
5497 *
5498 * If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will
5499 * be emitted just when inside this object area.
5500 *
5501 * The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB.
5502 *
5503 * @ingroup Evas_Object_Group_Extras
5504 */
5505EAPI void evas_object_pointer_mode_set (Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1);
5506
5507/**
5508 * Determine how pointer will behave.
5509 * @param obj
5510 * @return pointer behavior.
5511 * @ingroup Evas_Object_Group_Extras
5512 */
5513EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5514
5515
5516/**
5517 * Sets whether or not the given Evas object is to be drawn anti-aliased.
5518 *
5519 * @param obj The given Evas object.
5520 * @param anti_alias 1 if the object is to be anti_aliased, 0 otherwise.
5521 * @ingroup Evas_Object_Group_Extras
5522 */
5523EAPI void evas_object_anti_alias_set (Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1);
5524
5525/**
5526 * Retrieves whether or not the given Evas object is to be drawn anti_aliased.
5527 * @param obj The given Evas object.
5528 * @return @c 1 if the object is to be anti_aliased. @c 0 otherwise.
5529 * @ingroup Evas_Object_Group_Extras
5530 */
5531EAPI Eina_Bool evas_object_anti_alias_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5532
5533
5534/**
5535 * Sets the scaling factor for an Evas object. Does not affect all
5536 * objects.
5537 *
5538 * @param obj The given Evas object.
5539 * @param scale The scaling factor. <c>1.0</c> means no scaling,
5540 * default size.
5541 *
5542 * This will multiply the object's dimension by the given factor, thus
5543 * altering its geometry (width and height). Useful when you want
5544 * scalable UI elements, possibly at run time.
5545 *
5546 * @note Only text and textblock objects have scaling change
5547 * handlers. Other objects won't change visually on this call.
5548 *
5549 * @see evas_object_scale_get()
5550 *
5551 * @ingroup Evas_Object_Group_Extras
5552 */
5553EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
5554
5555/**
5556 * Retrieves the scaling factor for the given Evas object.
5557 *
5558 * @param obj The given Evas object.
5559 * @return The scaling factor.
5560 *
5561 * @ingroup Evas_Object_Group_Extras
5562 *
5563 * @see evas_object_scale_set()
5564 */
5565EAPI double evas_object_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5566
5567
5568/**
5569 * Sets the render_op to be used for rendering the Evas object.
5570 * @param obj The given Evas object.
5571 * @param render_op one of the Evas_Render_Op values.
5572 * @ingroup Evas_Object_Group_Extras
5573 */
5574EAPI void evas_object_render_op_set (Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1);
5575
5576/**
5577 * Retrieves the current value of the operation used for rendering the Evas object.
5578 * @param obj The given Evas object.
5579 * @return one of the enumerated values in Evas_Render_Op.
5580 * @ingroup Evas_Object_Group_Extras
5581 */
5582EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5583
5584/**
5585 * Set whether to use precise (usually expensive) point collision
5586 * detection for a given Evas object.
5587 *
5588 * @param obj The given object.
5589 * @param precise whether to use precise point collision detection or
5590 * not The default value is false.
5591 *
5592 * Use this function to make Evas treat objects' transparent areas as
5593 * @b not belonging to it with regard to mouse pointer events. By
5594 * default, all of the object's boundary rectangle will be taken in
5595 * account for them.
5596 *
5597 * @warning By using precise point collision detection you'll be
5598 * making Evas more resource intensive.
5599 *
5600 * Example code follows.
5601 * @dontinclude evas-events.c
5602 * @skip if (strcmp(ev->keyname, "p") == 0)
5603 * @until }
5604 *
5605 * See the full example @ref Example_Evas_Events "here".
5606 *
5607 * @see evas_object_precise_is_inside_get()
5608 * @ingroup Evas_Object_Group_Extras
5609 */
5610 EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1);
5611
5612/**
5613 * Determine whether an object is set to use precise point collision
5614 * detection.
5615 *
5616 * @param obj The given object.
5617 * @return whether @p obj is set to use precise point collision
5618 * detection or not The default value is false.
5619 *
5620 * @see evas_object_precise_is_inside_set() for an example
5621 *
5622 * @ingroup Evas_Object_Group_Extras
5623 */
5624 EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5625
5626/**
5627 * Set a hint flag on the given Evas object that it's used as a "static
5628 * clipper".
5629 *
5630 * @param obj The given object.
5631 * @param is_static_clip @c EINA_TRUE if it's to be used as a static
5632 * clipper, @c EINA_FALSE otherwise
5633 *
5634 * This is a hint to Evas that this object is used as a big static
5635 * clipper and shouldn't be moved with children and otherwise
5636 * considered specially. The default value for new objects is @c
5637 * EINA_FALSE.
5638 *
5639 * @see evas_object_static_clip_get()
5640 *
5641 * @ingroup Evas_Object_Group_Extras
5642 */
5643 EAPI void evas_object_static_clip_set (Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1);
5644
5645/**
5646 * Get the "static clipper" hint flag for a given Evas object.
5647 *
5648 * @param obj The given object.
5649 * @returrn @c EINA_TRUE if it's set as a static clipper, @c
5650 * EINA_FALSE otherwise
5651 *
5652 * @see evas_object_static_clip_set() for more details
5653 *
5654 * @ingroup Evas_Object_Group_Extras
5655 */
5656 EAPI Eina_Bool evas_object_static_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5657
5658/**
5659 * @}
5660 */
5661
5662/**
5663 * @defgroup Evas_Object_Group_Find Finding Objects
5664 *
5665 * Functions that allows finding objects by their position, name or
5666 * other properties.
5667 *
5668 * @ingroup Evas_Object_Group
5669 */
5670
5671/**
5672 * @addtogroup Evas_Object_Group_Find
5673 * @{
5674 */
5675
5676/**
5677 * Retrieve the object that currently has focus.
5678 *
5679 * @param e The Evas canvas to query for focused object on.
5680 * @return The object that has focus or @c NULL if there is not one.
5681 *
5682 * Evas can have (at most) one of its objects focused at a time.
5683 * Focused objects will be the ones having <b>key events</b> delivered
5684 * to, which the programmer can act upon by means of
5685 * evas_object_event_callback_add() usage.
5686 *
5687 * @note Most users wouldn't be dealing directly with Evas' focused
5688 * objects. Instead, they would be using a higher level library for
5689 * that (like a toolkit, as Elementary) to handle focus and who's
5690 * receiving input for them.
5691 *
5692 * This call returns the object that currently has focus on the canvas
5693 * @p e or @c NULL, if none.
5694 *
5695 * @see evas_object_focus_set
5696 * @see evas_object_focus_get
5697 * @see evas_object_key_grab
5698 * @see evas_object_key_ungrab
5699 *
5700 * Example:
5701 * @dontinclude evas-events.c
5702 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
5703 * @until evas_object_focus_set(d.bg, EINA_TRUE);
5704 * @dontinclude evas-events.c
5705 * @skip called when our rectangle gets focus
5706 * @until }
5707 *
5708 * In this example the @c event_info is exactly a pointer to that
5709 * focused rectangle. See the full @ref Example_Evas_Events "example".
5710 *
5711 * @ingroup Evas_Object_Group_Find
5712 */
5713EAPI Evas_Object *evas_focus_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5714
5715/**
5716 * Retrieves the object on the given evas with the given name.
5717 * @param e The given evas.
5718 * @param name The given name.
5719 * @return If successful, the Evas object with the given name. Otherwise,
5720 * @c NULL.
5721 * @ingroup Evas_Object_Group_Find
5722 */
5723EAPI Evas_Object *evas_object_name_find (const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5724
5725/**
5726 * Retrieve the Evas object stacked at the top of a given position in
5727 * a canvas
5728 *
5729 * @param e A handle to the canvas.
5730 * @param x The horizontal coordinate of the position
5731 * @param y The vertical coordinate of the position
5732 * @param include_pass_events_objects Boolean flag to include or not
5733 * objects which pass events in this calculation
5734 * @param include_hidden_objects Boolean flag to include or not hidden
5735 * objects in this calculation
5736 * @return The Evas object that is over all other objects at the given
5737 * position.
5738 *
5739 * This function will traverse all the layers of the given canvas,
5740 * from top to bottom, querying for objects with areas covering the
5741 * given position. The user can remove from from the query
5742 * objects which are hidden and/or which are set to pass events.
5743 *
5744 * @warning This function will @b skip objects parented by smart
5745 * objects, acting only on the ones at the "top level", with regard to
5746 * object parenting.
5747 */
5748EAPI 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) EINA_PURE;
5749
5750/**
5751 * Retrieve the Evas object stacked at the top at the position of the
5752 * mouse cursor, over a given canvas
5753 *
5754 * @param e A handle to the canvas.
5755 * @return The Evas object that is over all other objects at the mouse
5756 * pointer's position
5757 *
5758 * This function will traverse all the layers of the given canvas,
5759 * from top to bottom, querying for objects with areas covering the
5760 * mouse pointer's position, over @p e.
5761 *
5762 * @warning This function will @b skip objects parented by smart
5763 * objects, acting only on the ones at the "top level", with regard to
5764 * object parenting.
5765 */
5766EAPI Evas_Object *evas_object_top_at_pointer_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5767
5768/**
5769 * Retrieve the Evas object stacked at the top of a given rectangular
5770 * region in a canvas
5771 *
5772 * @param e A handle to the canvas.
5773 * @param x The top left corner's horizontal coordinate for the
5774 * rectangular region
5775 * @param y The top left corner's vertical coordinate for the
5776 * rectangular region
5777 * @param w The width of the rectangular region
5778 * @param h The height of the rectangular region
5779 * @param include_pass_events_objects Boolean flag to include or not
5780 * objects which pass events in this calculation
5781 * @param include_hidden_objects Boolean flag to include or not hidden
5782 * objects in this calculation
5783 * @return The Evas object that is over all other objects at the given
5784 * rectangular region.
5785 *
5786 * This function will traverse all the layers of the given canvas,
5787 * from top to bottom, querying for objects with areas overlapping
5788 * with the given rectangular region inside @p e. The user can remove
5789 * from the query objects which are hidden and/or which are set to
5790 * pass events.
5791 *
5792 * @warning This function will @b skip objects parented by smart
5793 * objects, acting only on the ones at the "top level", with regard to
5794 * object parenting.
5795 */
5796EAPI 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) EINA_PURE;
5797
5798/**
5799 * Retrieve a list of Evas objects lying over a given position in
5800 * a canvas
5801 *
5802 * @param e A handle to the canvas.
5803 * @param x The horizontal coordinate of the position
5804 * @param y The vertical coordinate of the position
5805 * @param include_pass_events_objects Boolean flag to include or not
5806 * objects which pass events in this calculation
5807 * @param include_hidden_objects Boolean flag to include or not hidden
5808 * objects in this calculation
5809 * @return The list of Evas objects that are over the given position
5810 * in @p e
5811 *
5812 * This function will traverse all the layers of the given canvas,
5813 * from top to bottom, querying for objects with areas covering the
5814 * given position. The user can remove from from the query
5815 * objects which are hidden and/or which are set to pass events.
5816 *
5817 * @warning This function will @b skip objects parented by smart
5818 * objects, acting only on the ones at the "top level", with regard to
5819 * object parenting.
5820 */
5821EAPI 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) EINA_PURE;
5822 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) EINA_PURE;
5823
5824/**
5825 * Get the lowest (stacked) Evas object on the canvas @p
5826 *
5827 * @param e a valid canvas pointer
5828 * @return a pointer to the lowest object on it, if any, or @c NULL,
5829 * otherwise
5830 *
5831 * This function will take all populated layers in the canvas into
5832 * account, getting the lowest object for the lowest layer, naturally.
5833 *
5834 * @see evas_object_layer_get()
5835 * @see evas_object_layer_set()
5836 * @see evas_object_below_get()
5837 * @see evas_object_above_get()
5838 *
5839 * @warning This function will @b skip objects parented by smart
5840 * objects, acting only on the ones at the "top level", with regard to
5841 * object parenting.
5842 */
5843EAPI Evas_Object *evas_object_bottom_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5844
5845/**
5846 * Get the highest (stacked) Evas object on the canvas @p
5847 *
5848 * @param e a valid canvas pointer
5849 * @return a pointer to the highest object on it, if any, or @c NULL,
5850 * otherwise
5851 *
5852 * This function will take all populated layers in the canvas into
5853 * account, getting the highest object for the highest layer,
5854 * naturally.
5855 *
5856 * @see evas_object_layer_get()
5857 * @see evas_object_layer_set()
5858 * @see evas_object_below_get()
5859 * @see evas_object_above_get()
5860 *
5861 * @warning This function will @b skip objects parented by smart
5862 * objects, acting only on the ones at the "top level", with regard to
5863 * object parenting.
5864 */
5865EAPI Evas_Object *evas_object_top_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5866
5867/**
5868 * @}
5869 */
5870
5871/**
5872 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
5873 *
5874 * Evas provides a way to intercept method calls. The interceptor
5875 * callback may opt to completely deny the call, or may check and
5876 * change the parameters before continuing. The continuation of an
5877 * intercepted call is done by calling the intercepted call again,
5878 * from inside the interceptor callback.
5879 *
5880 * @ingroup Evas_Object_Group
5881 */
5882
5883/**
5884 * @addtogroup Evas_Object_Group_Interceptors
5885 * @{
5886 */
5887
5888typedef void (*Evas_Object_Intercept_Show_Cb) (void *data, Evas_Object *obj);
5889typedef void (*Evas_Object_Intercept_Hide_Cb) (void *data, Evas_Object *obj);
5890typedef void (*Evas_Object_Intercept_Move_Cb) (void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
5891typedef void (*Evas_Object_Intercept_Resize_Cb) (void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
5892typedef void (*Evas_Object_Intercept_Raise_Cb) (void *data, Evas_Object *obj);
5893typedef void (*Evas_Object_Intercept_Lower_Cb) (void *data, Evas_Object *obj);
5894typedef void (*Evas_Object_Intercept_Stack_Above_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
5895typedef void (*Evas_Object_Intercept_Stack_Below_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
5896typedef void (*Evas_Object_Intercept_Layer_Set_Cb) (void *data, Evas_Object *obj, int l);
5897typedef void (*Evas_Object_Intercept_Color_Set_Cb) (void *data, Evas_Object *obj, int r, int g, int b, int a);
5898typedef void (*Evas_Object_Intercept_Clip_Set_Cb) (void *data, Evas_Object *obj, Evas_Object *clip);
5899typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *obj);
5900
5901/**
5902 * Set the callback function that intercepts a show event of a object.
5903 *
5904 * @param obj The given canvas object pointer.
5905 * @param func The given function to be the callback function.
5906 * @param data The data passed to the callback function.
5907 *
5908 * This function sets a callback function to intercepts a show event
5909 * of a canvas object.
5910 *
5911 * @see evas_object_intercept_show_callback_del().
5912 *
5913 */
5914EAPI void evas_object_intercept_show_callback_add (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
5915
5916/**
5917 * Unset the callback function that intercepts a show event of a
5918 * object.
5919 *
5920 * @param obj The given canvas object pointer.
5921 * @param func The given callback function.
5922 *
5923 * This function sets a callback function to intercepts a show event
5924 * of a canvas object.
5925 *
5926 * @see evas_object_intercept_show_callback_add().
5927 *
5928 */
5929EAPI void *evas_object_intercept_show_callback_del (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2);
5930
5931/**
5932 * Set the callback function that intercepts a hide event of a object.
5933 *
5934 * @param obj The given canvas object pointer.
5935 * @param func The given function to be the callback function.
5936 * @param data The data passed to the callback function.
5937 *
5938 * This function sets a callback function to intercepts a hide event
5939 * of a canvas object.
5940 *
5941 * @see evas_object_intercept_hide_callback_del().
5942 *
5943 */
5944EAPI void evas_object_intercept_hide_callback_add (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
5945
5946/**
5947 * Unset the callback function that intercepts a hide event of a
5948 * object.
5949 *
5950 * @param obj The given canvas object pointer.
5951 * @param func The given callback function.
5952 *
5953 * This function sets a callback function to intercepts a hide event
5954 * of a canvas object.
5955 *
5956 * @see evas_object_intercept_hide_callback_add().
5957 *
5958 */
5959EAPI void *evas_object_intercept_hide_callback_del (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2);
5960
5961/**
5962 * Set the callback function that intercepts a move event of a object.
5963 *
5964 * @param obj The given canvas object pointer.
5965 * @param func The given function to be the callback function.
5966 * @param data The data passed to the callback function.
5967 *
5968 * This function sets a callback function to intercepts a move event
5969 * of a canvas object.
5970 *
5971 * @see evas_object_intercept_move_callback_del().
5972 *
5973 */
5974EAPI void evas_object_intercept_move_callback_add (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
5975
5976/**
5977 * Unset the callback function that intercepts a move event of a
5978 * object.
5979 *
5980 * @param obj The given canvas object pointer.
5981 * @param func The given callback function.
5982 *
5983 * This function sets a callback function to intercepts a move event
5984 * of a canvas object.
5985 *
5986 * @see evas_object_intercept_move_callback_add().
5987 *
5988 */
5989EAPI void *evas_object_intercept_move_callback_del (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2);
5990
5991 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);
5992 EAPI void *evas_object_intercept_resize_callback_del (Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2);
5993 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);
5994 EAPI void *evas_object_intercept_raise_callback_del (Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2);
5995 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);
5996 EAPI void *evas_object_intercept_lower_callback_del (Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2);
5997 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);
5998 EAPI void *evas_object_intercept_stack_above_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2);
5999 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);
6000 EAPI void *evas_object_intercept_stack_below_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2);
6001 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);
6002 EAPI void *evas_object_intercept_layer_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2);
6003 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);
6004 EAPI void *evas_object_intercept_color_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2);
6005 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);
6006 EAPI void *evas_object_intercept_clip_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2);
6007 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);
6008 EAPI void *evas_object_intercept_clip_unset_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2);
6009
6010/**
6011 * @}
6012 */
6013
6014/**
6015 * @defgroup Evas_Object_Specific Specific Object Functions
6016 *
6017 * Functions that work on specific objects.
6018 *
6019 */
6020
6021/**
6022 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
6023 *
6024 * @brief Function to create evas rectangle objects.
6025 *
6026 * This function may seem useless given there are no functions to manipulate
6027 * the created rectangle, however the rectangle is actually very useful and can
6028 * be manipulate using the generic @ref Evas_Object_Group
6029 * "evas object functions".
6030 *
6031 * For an example of use of an evas_object_rectangle see @ref
6032 * Example_Evas_Object_Manipulation "here".
6033 *
6034 * @ingroup Evas_Object_Specific
6035 */
6036
6037/**
6038 * Adds a rectangle to the given evas.
6039 * @param e The given evas.
6040 * @return The new rectangle object.
6041 *
6042 * @ingroup Evas_Object_Rectangle
6043 */
6044EAPI Evas_Object *evas_object_rectangle_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6045
6046/**
6047 * @defgroup Evas_Object_Image Image Object Functions
6048 *
6049 * Here are grouped together functions used to create and manipulate
6050 * image objects. They are available to whichever occasion one needs
6051 * complex imagery on a GUI that could not be achieved by the other
6052 * Evas' primitive object types, or to make image manipulations.
6053 *
6054 * Evas will support whichever image file types it was compiled with
6055 * support to (its image loaders) -- check your software packager for
6056 * that information and see
6057 * evas_object_image_extension_can_load_get().
6058 *
6059 * @section Evas_Object_Image_Basics Image object basics
6060 *
6061 * The most common use of image objects -- to display an image on the
6062 * canvas -- is achieved by a common function triplet:
6063 * @code
6064 * img = evas_object_image_add(canvas);
6065 * evas_object_image_file_set(img, "path/to/img", NULL);
6066 * evas_object_image_fill_set(img, 0, 0, w, h);
6067 * @endcode
6068 * The first function, naturally, is creating the image object. Then,
6069 * one must set an source file on it, so that it knows where to fetch
6070 * image data from. Next, one must set <b>how to fill the image
6071 * object's area</b> with that given pixel data. One could use just a
6072 * sub-region of the original image or even have it tiled repeatedly
6073 * on the image object. For the common case of having the whole source
6074 * image to be displayed on the image object, streched to the
6075 * destination's size, there's also a function helper, to be used
6076 * instead of evas_object_image_fill_set():
6077 * @code
6078 * evas_object_image_filled_set(img, EINA_TRUE);
6079 * @endcode
6080 * See those functions' documentation for more details.
6081 *
6082 * @section Evas_Object_Image_Scale Scale and resizing
6083 *
6084 * Resizing of image objects will scale their respective source images
6085 * to their areas, if they are set to "fill" the object's area
6086 * (evas_object_image_filled_set()). If the user wants any control on
6087 * the aspect ratio of an image for different sizes, he/she has to
6088 * take care of that themselves. There are functions to make images to
6089 * get loaded scaled (up or down) in memory, already, if the user is
6090 * going to use them at pre-determined sizes and wants to save
6091 * computations.
6092 *
6093 * Evas has even a scale cache, which will take care of caching scaled
6094 * versions of images with more often usage/hits. Finally, one can
6095 * have images being rescaled @b smoothly by Evas (more
6096 * computationally expensive) or not.
6097 *
6098 * @section Evas_Object_Image_Performance Performance hints
6099 *
6100 * When dealing with image objects, there are some tricks to boost the
6101 * performance of your application, if it does intense image loading
6102 * and/or manipulations, as in animations on a UI.
6103 *
6104 * @subsection Evas_Object_Image_Load Load hints
6105 *
6106 * In image viewer applications, for example, the user will be looking
6107 * at a given image, at full size, and will desire that the navigation
6108 * to the adjacent images on his/her album be fluid and fast. Thus,
6109 * while displaying a given image, the program can be on the
6110 * background loading the next and previous imagens already, so that
6111 * displaying them on the sequence is just a matter of repainting the
6112 * screen (and not decoding image data).
6113 *
6114 * Evas addresses this issue with <b>image pre-loading</b>. The code
6115 * for the situation above would be something like the following:
6116 * @code
6117 * prev = evas_object_image_filled_add(canvas);
6118 * evas_object_image_file_set(prev, "/path/to/prev", NULL);
6119 * evas_object_image_preload(prev, EINA_TRUE);
6120 *
6121 * next = evas_object_image_filled_add(canvas);
6122 * evas_object_image_file_set(next, "/path/to/next", NULL);
6123 * evas_object_image_preload(next, EINA_TRUE);
6124 * @endcode
6125 *
6126 * If you're loading images which are too big, consider setting
6127 * previously it's loading size to something smaller, in case you
6128 * won't expose them in real size. It may speed up the loading
6129 * considerably:
6130 * @code
6131 * //to load a scaled down version of the image in memory, if that's
6132 * //the size you'll be displaying it anyway
6133 * evas_object_image_load_scale_down_set(img, zoom);
6134 *
6135 * //optional: if you know you'll be showing a sub-set of the image's
6136 * //pixels, you can avoid loading the complementary data
6137 * evas_object_image_load_region_set(img, x, y, w, h);
6138 * @endcode
6139 * Refer to Elementary's Photocam widget for a high level (smart)
6140 * object which does lots of loading speed-ups for you.
6141 *
6142 * @subsection Evas_Object_Image_Animation Animation hints
6143 *
6144 * If you want to animate image objects on a UI (what you'd get by
6145 * concomitant usage of other libraries, like Ecore and Edje), there
6146 * are also some tips on how to boost the performance of your
6147 * application. If the animation involves resizing of an image (thus,
6148 * re-scaling), you'd better turn off smooth scaling on it @b during
6149 * the animation, turning it back on afterwrads, for less
6150 * computations. Also, in this case you'd better flag the image object
6151 * in question not to cache scaled versions of it:
6152 * @code
6153 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC);
6154 *
6155 * // resizing takes place in between
6156 *
6157 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC);
6158 * @endcode
6159 *
6160 * Finally, movement of opaque images through the canvas is less
6161 * expensive than of translucid ones, because of blending
6162 * computations.
6163 *
6164 * @section Evas_Object_Image_Borders Borders
6165 *
6166 * Evas provides facilities for one to specify an image's region to be
6167 * treated specially -- as "borders". This will make those regions be
6168 * treated specially on resizing scales, by keeping their aspect. This
6169 * makes setting frames around other objects on UIs easy.
6170 * See the following figures for a visual explanation:\n
6171 * @htmlonly
6172 * <img src="image-borders.png" style="max-width: 100%;" />
6173 * <a href="image-borders.png">Full-size</a>
6174 * @endhtmlonly
6175 * @image rtf image-borders.png
6176 * @image latex image-borders.eps width=\textwidth
6177 * @htmlonly
6178 * <img src="border-effect.png" style="max-width: 100%;" />
6179 * <a href="border-effect.png">Full-size</a>
6180 * @endhtmlonly
6181 * @image rtf border-effect.png
6182 * @image latex border-effect.eps width=\textwidth
6183 *
6184 * @section Evas_Object_Image_Manipulation Manipulating pixels
6185 *
6186 * Evas image objects can be used to manipulate raw pixels in many
6187 * ways. The meaning of the data in the pixel arrays will depend on
6188 * the image's color space, be warned (see next section). You can set
6189 * your own data as an image's pixel data, fetch an image's pixel data
6190 * for saving/altering, convert images between different color spaces
6191 * and even advanced operations like setting a native surface as image
6192 * objecs' data.
6193 *
6194 * @section Evas_Object_Image_Color_Spaces Color spaces
6195 *
6196 * Image objects may return or accept "image data" in multiple
6197 * formats. This is based on the color space of an object. Here is a
6198 * rundown on formats:
6199 *
6200 * - #EVAS_COLORSPACE_ARGB8888:
6201 * .
6202 * This pixel format is a linear block of pixels, starting at the
6203 * top-left row by row until the bottom right of the image or pixel
6204 * region. All pixels are 32-bit unsigned int's with the high-byte
6205 * being alpha and the low byte being blue in the format ARGB. Alpha
6206 * may or may not be used by evas depending on the alpha flag of the
6207 * image, but if not used, should be set to 0xff anyway.
6208 * \n\n
6209 * This colorspace uses premultiplied alpha. That means that R, G
6210 * and B cannot exceed A in value. The conversion from
6211 * non-premultiplied colorspace is:
6212 * \n\n
6213 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
6214 * \n\n
6215 * So 50% transparent blue will be: 0x80000080. This will not be
6216 * "dark" - just 50% transparent. Values are 0 == black, 255 ==
6217 * solid or full red, green or blue.
6218 *
6219 * - #EVAS_COLORSPACE_YCBCR422P601_PL:
6220 * .
6221 * This is a pointer-list indirected set of YUV (YCbCr) pixel
6222 * data. This means that the data returned or set is not actual
6223 * pixel data, but pointers TO lines of pixel data. The list of
6224 * pointers will first be N rows of pointers to the Y plane -
6225 * pointing to the first pixel at the start of each row in the Y
6226 * plane. N is the height of the image data in pixels. Each pixel in
6227 * the Y, U and V planes is 1 byte exactly, packed. The next N / 2
6228 * pointers will point to rows in the U plane, and the next N / 2
6229 * pointers will point to the V plane rows. U and V planes are half
6230 * the horizontal and vertical resolution of the Y plane.
6231 * \n\n
6232 * Row order is top to bottom and row pixels are stored left to
6233 * right.
6234 * \n\n
6235 * There is a limitation that these images MUST be a multiple of 2
6236 * pixels in size horizontally or vertically. This is due to the U
6237 * and V planes being half resolution. Also note that this assumes
6238 * the itu601 YUV colorspace specification. This is defined for
6239 * standard television and mpeg streams. HDTV may use the itu709
6240 * specification.
6241 * \n\n
6242 * Values are 0 to 255, indicating full or no signal in that plane
6243 * respectively.
6244 *
6245 * - #EVAS_COLORSPACE_YCBCR422P709_PL:
6246 * .
6247 * Not implemented yet.
6248 *
6249 * - #EVAS_COLORSPACE_RGB565_A5P:
6250 * .
6251 * In the process of being implemented in 1 engine only. This may
6252 * change.
6253 * \n\n
6254 * This is a pointer to image data for 16-bit half-word pixel data
6255 * in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue),
6256 * with the high-byte containing red and the low byte containing
6257 * blue, per pixel. This data is packed row by row from the top-left
6258 * to the bottom right.
6259 * \n\n
6260 * If the image has an alpha channel enabled there will be an extra
6261 * alpha plane after the color pixel plane. If not, then this data
6262 * will not exist and should not be accessed in any way. This plane
6263 * is a set of pixels with 1 byte per pixel defining the alpha
6264 * values of all pixels in the image from the top-left to the bottom
6265 * right of the image, row by row. Even though the values of the
6266 * alpha pixels can be 0 to 255, only values 0 through to 32 are
6267 * used, 32 being solid and 0 being transparent.
6268 * \n\n
6269 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
6270 * with 0 being black and 31 or 63 being full red, green or blue
6271 * respectively. This colorspace is also pre-multiplied like
6272 * EVAS_COLORSPACE_ARGB8888 so:
6273 * \n\n
6274 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
6275 *
6276 * - #EVAS_COLORSPACE_GRY8:
6277 * .
6278 * The image is just a alpha mask (8 bit's per pixel). This is used
6279 * for alpha masking.
6280 *
6281 * Some examples on this group of functions can be found @ref
6282 * Example_Evas_Images "here".
6283 *
6284 * @ingroup Evas_Object_Specific
6285 */
6286
6287/**
6288 * @addtogroup Evas_Object_Image
6289 * @{
6290 */
6291
6292typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o);
6293
6294
6295/**
6296 * Creates a new image object on the given Evas @p e canvas.
6297 *
6298 * @param e The given canvas.
6299 * @return The created image object handle.
6300 *
6301 * @note If you intend to @b display an image somehow in a GUI,
6302 * besides binding it to a real image file/source (with
6303 * evas_object_image_file_set(), for example), you'll have to tell
6304 * this image object how to fill its space with the pixels it can get
6305 * from the source. See evas_object_image_filled_add(), for a helper
6306 * on the common case of scaling up an image source to the whole area
6307 * of the image object.
6308 *
6309 * @see evas_object_image_fill_set()
6310 *
6311 * Example:
6312 * @code
6313 * img = evas_object_image_add(canvas);
6314 * evas_object_image_file_set(img, "/path/to/img", NULL);
6315 * @endcode
6316 */
6317EAPI Evas_Object *evas_object_image_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6318
6319/**
6320 * Creates a new image object that @b automatically scales its bound
6321 * image to the object's area, on both axis.
6322 *
6323 * @param e The given canvas.
6324 * @return The created image object handle.
6325 *
6326 * This is a helper function around evas_object_image_add() and
6327 * evas_object_image_filled_set(). It has the same effect of applying
6328 * those functions in sequence, which is a very common use case.
6329 *
6330 * @note Whenever this object gets resized, the bound image will be
6331 * rescaled, too.
6332 *
6333 * @see evas_object_image_add()
6334 * @see evas_object_image_filled_set()
6335 * @see evas_object_image_fill_set()
6336 */
6337EAPI Evas_Object *evas_object_image_filled_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6338
6339
6340/**
6341 * Sets the data for an image from memory to be loaded
6342 *
6343 * This is the same as evas_object_image_file_set() but the file to be loaded
6344 * may exist at an address in memory (the data for the file, not the filename
6345 * itself). The @p data at the address is copied and stored for future use, so
6346 * no @p data needs to be kept after this call is made. It will be managed and
6347 * freed for you when no longer needed. The @p size is limited to 2 gigabytes
6348 * in size, and must be greater than 0. A NULL @p data pointer is also invalid.
6349 * Set the filename to NULL to reset to empty state and have the image file
6350 * data freed from memory using evas_object_image_file_set().
6351 *
6352 * The @p format is optional (pass NULL if you don't need/use it). It is used
6353 * to help Evas guess better which loader to use for the data. It may simply
6354 * be the "extension" of the file as it would normally be on disk such as
6355 * "jpg" or "png" or "gif" etc.
6356 *
6357 * @param obj The given image object.
6358 * @param data The image file data address
6359 * @param size The size of the image file data in bytes
6360 * @param format The format of the file (optional), or @c NULL if not needed
6361 * @param key The image key in file, or @c NULL.
6362 */
6363EAPI void evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2);
6364
6365/**
6366 * Set the source file from where an image object must fetch the real
6367 * image data (it may be an Eet file, besides pure image ones).
6368 *
6369 * @param obj The given image object.
6370 * @param file The image file path.
6371 * @param key The image key in @p file (if its an Eet one), or @c
6372 * NULL, otherwise.
6373 *
6374 * If the file supports multiple data stored in it (as Eet files do),
6375 * you can specify the key to be used as the index of the image in
6376 * this file.
6377 *
6378 * Example:
6379 * @code
6380 * img = evas_object_image_add(canvas);
6381 * evas_object_image_file_set(img, "/path/to/img", NULL);
6382 * err = evas_object_image_load_error_get(img);
6383 * if (err != EVAS_LOAD_ERROR_NONE)
6384 * {
6385 * fprintf(stderr, "could not load image '%s'. error string is \"%s\"\n",
6386 * valid_path, evas_load_error_str(err));
6387 * }
6388 * else
6389 * {
6390 * evas_object_image_fill_set(img, 0, 0, w, h);
6391 * evas_object_resize(img, w, h);
6392 * evas_object_show(img);
6393 * }
6394 * @endcode
6395 */
6396EAPI void evas_object_image_file_set (Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
6397
6398/**
6399 * Retrieve the source file from where an image object is to fetch the
6400 * real image data (it may be an Eet file, besides pure image ones).
6401 *
6402 * @param obj The given image object.
6403 * @param file Location to store the image file path.
6404 * @param key Location to store the image key (if @p file is an Eet
6405 * one).
6406 *
6407 * You must @b not modify the strings on the returned pointers.
6408 *
6409 * @note Use @c NULL pointers on the file components you're not
6410 * interested in: they'll be ignored by the function.
6411 */
6412EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2);
6413
6414/**
6415 * Set the dimensions for an image object's border, a region which @b
6416 * won't ever be scaled together with its center.
6417 *
6418 * @param obj The given image object.
6419 * @param l The border's left width.
6420 * @param r The border's right width.
6421 * @param t The border's top width.
6422 * @param b The border's bottom width.
6423 *
6424 * When Evas is rendering, an image source may be scaled to fit the
6425 * size of its image object. This function sets an area from the
6426 * borders of the image inwards which is @b not to be scaled. This
6427 * function is useful for making frames and for widget theming, where,
6428 * for example, buttons may be of varying sizes, but their border size
6429 * must remain constant.
6430 *
6431 * The units used for @p l, @p r, @p t and @p b are canvas units.
6432 *
6433 * @note The border region itself @b may be scaled by the
6434 * evas_object_image_border_scale_set() function.
6435 *
6436 * @note By default, image objects have no borders set, i. e. @c l, @c
6437 * r, @c t and @c b start as @c 0.
6438 *
6439 * See the following figures for visual explanation:\n
6440 * @htmlonly
6441 * <img src="image-borders.png" style="max-width: 100%;" />
6442 * <a href="image-borders.png">Full-size</a>
6443 * @endhtmlonly
6444 * @image rtf image-borders.png
6445 * @image latex image-borders.eps width=\textwidth
6446 * @htmlonly
6447 * <img src="border-effect.png" style="max-width: 100%;" />
6448 * <a href="border-effect.png">Full-size</a>
6449 * @endhtmlonly
6450 * @image rtf border-effect.png
6451 * @image latex border-effect.eps width=\textwidth
6452 *
6453 * @see evas_object_image_border_get()
6454 * @see evas_object_image_border_center_fill_set()
6455 */
6456EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1);
6457
6458/**
6459 * Retrieve the dimensions for an image object's border, a region
6460 * which @b won't ever be scaled together with its center.
6461 *
6462 * @param obj The given image object.
6463 * @param l Location to store the border's left width in.
6464 * @param r Location to store the border's right width in.
6465 * @param t Location to store the border's top width in.
6466 * @param b Location to store the border's bottom width in.
6467 *
6468 * @note Use @c NULL pointers on the border components you're not
6469 * interested in: they'll be ignored by the function.
6470 *
6471 * See @ref evas_object_image_border_set() for more details.
6472 */
6473EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
6474
6475/**
6476 * Sets @b how the center part of the given image object (not the
6477 * borders) should be drawn when Evas is rendering it.
6478 *
6479 * @param obj The given image object.
6480 * @param fill Fill mode of the center region of @p obj (a value in
6481 * #Evas_Border_Fill_Mode).
6482 *
6483 * This function sets how the center part of the image object's source
6484 * image is to be drawn, which must be one of the values in
6485 * #Evas_Border_Fill_Mode. By center we mean the complementary part of
6486 * that defined by evas_object_image_border_set(). This one is very
6487 * useful for making frames and decorations. You would most probably
6488 * also be using a filled image (as in evas_object_image_filled_set())
6489 * to use as a frame.
6490 *
6491 * @see evas_object_image_border_center_fill_get()
6492 */
6493EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1);
6494
6495/**
6496 * Retrieves @b how the center part of the given image object (not the
6497 * borders) is to be drawn when Evas is rendering it.
6498 *
6499 * @param obj The given image object.
6500 * @return fill Fill mode of the center region of @p obj (a value in
6501 * #Evas_Border_Fill_Mode).
6502 *
6503 * See @ref evas_object_image_fill_set() for more details.
6504 */
6505EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6506
6507/**
6508 * Set whether the image object's fill property should track the
6509 * object's size.
6510 *
6511 * @param obj The given image object.
6512 * @param setting @c EINA_TRUE, to make the fill property follow
6513 * object size or @c EINA_FALSE, otherwise
6514 *
6515 * If @p setting is @c EINA_TRUE, then every evas_object_resize() will
6516 * @b automatically trigger a call to evas_object_image_fill_set()
6517 * with the that new size (and @c 0, @c 0 as source image's origin),
6518 * so the bound image will fill the whole object's area.
6519 *
6520 * @see evas_object_image_filled_add()
6521 * @see evas_object_image_fill_get()
6522 */
6523EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
6524
6525/**
6526 * Retrieve whether the image object's fill property should track the
6527 * object's size.
6528 *
6529 * @param obj The given image object.
6530 * @return @c EINA_TRUE if it is tracking, @c EINA_FALSE, if not (and
6531 * evas_object_fill_set() must be called manually).
6532 *
6533 * @see evas_object_image_filled_set() for more information
6534 */
6535EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6536
6537/**
6538 * Sets the scaling factor (multiplier) for the borders of an image
6539 * object.
6540 *
6541 * @param obj The given image object.
6542 * @param scale The scale factor (default is @c 1.0 - i.e. no scaling)
6543 *
6544 * @see evas_object_image_border_set()
6545 * @see evas_object_image_border_scale_get()
6546 */
6547EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale);
6548
6549/**
6550 * Retrieves the scaling factor (multiplier) for the borders of an
6551 * image object.
6552 *
6553 * @param obj The given image object.
6554 * @return The scale factor set for its borders
6555 *
6556 * @see evas_object_image_border_set()
6557 * @see evas_object_image_border_scale_set()
6558 */
6559EAPI double evas_object_image_border_scale_get (const Evas_Object *obj);
6560
6561/**
6562 * Set how to fill an image object's drawing rectangle given the
6563 * (real) image bound to it.
6564 *
6565 * @param obj The given image object to operate on.
6566 * @param x The x coordinate (from the top left corner of the bound
6567 * image) to start drawing from.
6568 * @param y The y coordinate (from the top left corner of the bound
6569 * image) to start drawing from.
6570 * @param w The width the bound image will be displayed at.
6571 * @param h The height the bound image will be displayed at.
6572 *
6573 * Note that if @p w or @p h are smaller than the dimensions of
6574 * @p obj, the displayed image will be @b tiled around the object's
6575 * area. To have only one copy of the bound image drawn, @p x and @p y
6576 * must be 0 and @p w and @p h need to be the exact width and height
6577 * of the image object itself, respectively.
6578 *
6579 * See the following image to better understand the effects of this
6580 * call. On this diagram, both image object and original image source
6581 * have @c a x @c a dimentions and the image itself is a circle, with
6582 * empty space around it:
6583 *
6584 * @image html image-fill.png
6585 * @image rtf image-fill.png
6586 * @image latex image-fill.eps
6587 *
6588 * @warning The default values for the fill parameters are @p x = 0,
6589 * @p y = 0, @p w = 0 and @p h = 0. Thus, if you're not using the
6590 * evas_object_image_filled_add() helper and want your image
6591 * displayed, you'll have to set valid values with this fuction on
6592 * your object.
6593 *
6594 * @note evas_object_image_filled_set() is a helper function which
6595 * will @b override the values set here automatically, for you, in a
6596 * given way.
6597 */
6598EAPI 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);
6599
6600/**
6601 * Retrieve how an image object is to fill its drawing rectangle,
6602 * given the (real) image bound to it.
6603 *
6604 * @param obj The given image object.
6605 * @param x Location to store the x coordinate (from the top left
6606 * corner of the bound image) to start drawing from.
6607 * @param y Location to store the y coordinate (from the top left
6608 * corner of the bound image) to start drawing from.
6609 * @param w Location to store the width the bound image is to be
6610 * displayed at.
6611 * @param h Location to store the height the bound image is to be
6612 * displayed at.
6613 *
6614 * @note Use @c NULL pointers on the fill components you're not
6615 * interested in: they'll be ignored by the function.
6616 *
6617 * See @ref evas_object_image_fill_set() for more details.
6618 */
6619EAPI 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);
6620
6621/**
6622 * Sets the tiling mode for the given evas image object's fill.
6623 * @param obj The given evas image object.
6624 * @param spread One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT,
6625 * EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.
6626 */
6627EAPI void evas_object_image_fill_spread_set (Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1);
6628
6629/**
6630 * Retrieves the spread (tiling mode) for the given image object's
6631 * fill.
6632 *
6633 * @param obj The given evas image object.
6634 * @return The current spread mode of the image object.
6635 */
6636EAPI Evas_Fill_Spread evas_object_image_fill_spread_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6637
6638/**
6639 * Sets the size of the given image object.
6640 *
6641 * @param obj The given image object.
6642 * @param w The new width of the image.
6643 * @param h The new height of the image.
6644 *
6645 * This function will scale down or crop the image so that it is
6646 * treated as if it were at the given size. If the size given is
6647 * smaller than the image, it will be cropped. If the size given is
6648 * larger, then the image will be treated as if it were in the upper
6649 * left hand corner of a larger image that is otherwise transparent.
6650 */
6651EAPI void evas_object_image_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
6652
6653/**
6654 * Retrieves the size of the given image object.
6655 *
6656 * @param obj The given image object.
6657 * @param w Location to store the width of the image in, or @c NULL.
6658 * @param h Location to store the height of the image in, or @c NULL.
6659 *
6660 * See @ref evas_object_image_size_set() for more details.
6661 */
6662EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
6663
6664/**
6665 * Retrieves the row stride of the given image object.
6666 *
6667 * @param obj The given image object.
6668 * @return The stride of the image (<b>in bytes</b>).
6669 *
6670 * The row stride is the number of bytes between the start of a row
6671 * and the start of the next row for image data.
6672 */
6673EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6674
6675/**
6676 * Retrieves a number representing any error that occurred during the
6677 * last loading of the given image object's source image.
6678 *
6679 * @param obj The given image object.
6680 * @return A value giving the last error that occurred. It should be
6681 * one of the #Evas_Load_Error values. #EVAS_LOAD_ERROR_NONE
6682 * is returned if there was no error.
6683 */
6684EAPI Evas_Load_Error evas_object_image_load_error_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6685
6686/**
6687 * Sets the raw image data of the given image object.
6688 *
6689 * @param obj The given image object.
6690 * @param data The raw data, or @c NULL.
6691 *
6692 * Note that the raw data must be of the same size (see
6693 * evas_object_image_size_set(), which has to be called @b before this
6694 * one) and colorspace (see evas_object_image_colorspace_set()) of the
6695 * image. If data is @c NULL, the current image data will be
6696 * freed. Naturally, if one does not set an image object's data
6697 * manually, it will still have one, allocated by Evas.
6698 *
6699 * @see evas_object_image_data_get()
6700 */
6701EAPI void evas_object_image_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
6702
6703/**
6704 * Get a pointer to the raw image data of the given image object.
6705 *
6706 * @param obj The given image object.
6707 * @param for_writing Whether the data being retrieved will be
6708 * modified (@c EINA_TRUE) or not (@c EINA_FALSE).
6709 * @return The raw image data.
6710 *
6711 * This function returns a pointer to an image object's internal pixel
6712 * buffer, for reading only or read/write. If you request it for
6713 * writing, the image will be marked dirty so that it gets redrawn at
6714 * the next update.
6715 *
6716 * Each time you call this function on an image object, its data
6717 * buffer will have an internal reference counter
6718 * incremented. Decrement it back by using
6719 * evas_object_image_data_set(). This is specially important for the
6720 * directfb Evas engine.
6721 *
6722 * This is best suited for when you want to modify an existing image,
6723 * without changing its dimensions.
6724 *
6725 * @note The contents' formart returned by it depend on the color
6726 * space of the given image object.
6727 *
6728 * @note You may want to use evas_object_image_data_update_add() to
6729 * inform data changes, if you did any.
6730 *
6731 * @see evas_object_image_data_set()
6732 */
6733EAPI void *evas_object_image_data_get (const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6734
6735/**
6736 * Converts the raw image data of the given image object to the
6737 * specified colorspace.
6738 *
6739 * Note that this function does not modify the raw image data. If the
6740 * requested colorspace is the same as the image colorspace nothing is
6741 * done and NULL is returned. You should use
6742 * evas_object_image_colorspace_get() to check the current image
6743 * colorspace.
6744 *
6745 * See @ref evas_object_image_colorspace_get.
6746 *
6747 * @param obj The given image object.
6748 * @param to_cspace The colorspace to which the image raw data will be converted.
6749 * @return data A newly allocated data in the format specified by to_cspace.
6750 */
6751EAPI void *evas_object_image_data_convert (Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6752
6753/**
6754 * Replaces the raw image data of the given image object.
6755 *
6756 * @param obj The given image object.
6757 * @param data The raw data to replace.
6758 *
6759 * This function lets the application replace an image object's
6760 * internal pixel buffer with an user-allocated one. For best results,
6761 * you should generally first call evas_object_image_size_set() with
6762 * the width and height for the new buffer.
6763 *
6764 * This call is best suited for when you will be using image data with
6765 * different dimensions than the existing image data, if any. If you
6766 * only need to modify the existing image in some fashion, then using
6767 * evas_object_image_data_get() is probably what you are after.
6768 *
6769 * Note that the caller is responsible for freeing the buffer when
6770 * finished with it, as user-set image data will not be automatically
6771 * freed when the image object is deleted.
6772 *
6773 * See @ref evas_object_image_data_get() for more details.
6774 *
6775 */
6776EAPI void evas_object_image_data_copy_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
6777
6778/**
6779 * Mark a sub-region of the given image object to be redrawn.
6780 *
6781 * @param obj The given image object.
6782 * @param x X-offset of the region to be updated.
6783 * @param y Y-offset of the region to be updated.
6784 * @param w Width of the region to be updated.
6785 * @param h Height of the region to be updated.
6786 *
6787 * This function schedules a particular rectangular region of an image
6788 * object to be updated (redrawn) at the next rendering cycle.
6789 */
6790EAPI void evas_object_image_data_update_add (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
6791
6792/**
6793 * Enable or disable alpha channel usage on the given image object.
6794 *
6795 * @param obj The given image object.
6796 * @param has_alpha Whether to use alpha channel (@c EINA_TRUE) data
6797 * or not (@c EINA_FALSE).
6798 *
6799 * This function sets a flag on an image object indicating whether or
6800 * not to use alpha channel data. A value of @c EINA_TRUE makes it use
6801 * alpha channel data, and @c EINA_FALSE makes it ignore that
6802 * data. Note that this has nothing to do with an object's color as
6803 * manipulated by evas_object_color_set().
6804 *
6805 * @see evas_object_image_alpha_get()
6806 */
6807EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1);
6808
6809/**
6810 * Retrieve whether alpha channel data is being used on the given
6811 * image object.
6812 *
6813 * @param obj The given image object.
6814 * @return Whether the alpha channel data is being used (@c EINA_TRUE)
6815 * or not (@c EINA_FALSE).
6816 *
6817 * This function returns @c EINA_TRUE if the image object's alpha
6818 * channel is being used, or @c EINA_FALSE otherwise.
6819 *
6820 * See @ref evas_object_image_alpha_set() for more details.
6821 */
6822EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6823
6824/**
6825 * Sets whether to use high-quality image scaling algorithm on the
6826 * given image object.
6827 *
6828 * @param obj The given image object.
6829 * @param smooth_scale Whether to use smooth scale or not.
6830 *
6831 * When enabled, a higher quality image scaling algorithm is used when
6832 * scaling images to sizes other than the source image's original
6833 * one. This gives better results but is more computationally
6834 * expensive.
6835 *
6836 * @note Image objects get created originally with smooth scaling @b
6837 * on.
6838 *
6839 * @see evas_object_image_smooth_scale_get()
6840 */
6841EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1);
6842
6843/**
6844 * Retrieves whether the given image object is using high-quality
6845 * image scaling algorithm.
6846 *
6847 * @param obj The given image object.
6848 * @return Whether smooth scale is being used.
6849 *
6850 * See @ref evas_object_image_smooth_scale_set() for more details.
6851 */
6852EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6853
6854/**
6855 * Preload an image object's image data in the background
6856 *
6857 * @param obj The given image object.
6858 * @param cancel @c EINA_FALSE will add it the preloading work queue,
6859 * @c EINA_TRUE will remove it (if it was issued before).
6860 *
6861 * This function requests the preload of the data image in the
6862 * background. The work is queued before being processed (because
6863 * there might be other pending requests of this type).
6864 *
6865 * Whenever the image data gets loaded, Evas will call
6866 * #EVAS_CALLBACK_IMAGE_PRELOADED registered callbacks on @p obj (what
6867 * may be immediately, if the data was already preloaded before).
6868 *
6869 * Use @c EINA_TRUE for @p cancel on scenarios where you don't need
6870 * the image data preloaded anymore.
6871 *
6872 * @note Any evas_object_show() call after evas_object_image_preload()
6873 * will make the latter to be @b cancelled, with the loading process
6874 * now taking place @b synchronously (and, thus, blocking the return
6875 * of the former until the image is loaded). It is highly advisable,
6876 * then, that the user preload an image with it being @b hidden, just
6877 * to be shown on the #EVAS_CALLBACK_IMAGE_PRELOADED event's callback.
6878 */
6879EAPI void evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1);
6880
6881/**
6882 * Reload an image object's image data.
6883 *
6884 * @param obj The given image object pointer.
6885 *
6886 * This function reloads the image data bound to image object @p obj.
6887 */
6888EAPI void evas_object_image_reload (Evas_Object *obj) EINA_ARG_NONNULL(1);
6889
6890/**
6891 * Save the given image object's contents to an (image) file.
6892 *
6893 * @param obj The given image object.
6894 * @param file The filename to be used to save the image (extension
6895 * obligatory).
6896 * @param key The image key in the file (if an Eet one), or @c NULL,
6897 * otherwise.
6898 * @param flags String containing the flags to be used (@c NULL for
6899 * none).
6900 *
6901 * The extension suffix on @p file will determine which <b>saver
6902 * module</b> Evas is to use when saving, thus the final file's
6903 * format. If the file supports multiple data stored in it (Eet ones),
6904 * you can specify the key to be used as the index of the image in it.
6905 *
6906 * You can specify some flags when saving the image. Currently
6907 * acceptable flags are @c quality and @c compress. Eg.: @c
6908 * "quality=100 compress=9"
6909 */
6910EAPI Eina_Bool evas_object_image_save (const Evas_Object *obj, const char *file, const char *key, const char *flags) EINA_ARG_NONNULL(1, 2);
6911
6912/**
6913 * Import pixels from given source to a given canvas image object.
6914 *
6915 * @param obj The given canvas object.
6916 * @param pixels The pixel's source to be imported.
6917 *
6918 * This function imports pixels from a given source to a given canvas image.
6919 *
6920 */
6921EAPI Eina_Bool evas_object_image_pixels_import (Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2);
6922
6923/**
6924 * Set the callback function to get pixels from a canva's image.
6925 *
6926 * @param obj The given canvas pointer.
6927 * @param func The callback function.
6928 * @param data The data pointer to be passed to @a func.
6929 *
6930 * This functions sets a function to be the callback function that get
6931 * pixes from a image of the canvas.
6932 *
6933 */
6934EAPI 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);
6935
6936/**
6937 * Mark whether the given image object is dirty (needs to be redrawn).
6938 *
6939 * @param obj The given image object.
6940 * @param dirty Whether the image is dirty.
6941 */
6942EAPI void evas_object_image_pixels_dirty_set (Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1);
6943
6944/**
6945 * Retrieves whether the given image object is dirty (needs to be redrawn).
6946 *
6947 * @param obj The given image object.
6948 * @return Whether the image is dirty.
6949 */
6950EAPI Eina_Bool evas_object_image_pixels_dirty_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6951
6952/**
6953 * Set the DPI resolution of an image object's source image.
6954 *
6955 * @param obj The given canvas pointer.
6956 * @param dpi The new DPI resolution.
6957 *
6958 * This function sets the DPI resolution of a given loaded canvas
6959 * image. Most useful for the SVG image loader.
6960 *
6961 * @see evas_object_image_load_dpi_get()
6962 */
6963EAPI void evas_object_image_load_dpi_set (Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1);
6964
6965/**
6966 * Get the DPI resolution of a loaded image object in the canvas.
6967 *
6968 * @param obj The given canvas pointer.
6969 * @return The DPI resolution of the given canvas image.
6970 *
6971 * This function returns the DPI resolution of the given canvas image.
6972 *
6973 * @see evas_object_image_load_dpi_set() for more details
6974 */
6975EAPI double evas_object_image_load_dpi_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6976
6977/**
6978 * Set the size of a given image object's source image, when loading
6979 * it.
6980 *
6981 * @param obj The given canvas object.
6982 * @param w The new width of the image's load size.
6983 * @param h The new height of the image's load size.
6984 *
6985 * This function sets a new (loading) size for the given canvas
6986 * image.
6987 *
6988 * @see evas_object_image_load_size_get()
6989 */
6990EAPI void evas_object_image_load_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
6991
6992/**
6993 * Get the size of a given image object's source image, when loading
6994 * it.
6995 *
6996 * @param obj The given image object.
6997 * @param w Where to store the new width of the image's load size.
6998 * @param h Where to store the new height of the image's load size.
6999 *
7000 * @note Use @c NULL pointers on the size components you're not
7001 * interested in: they'll be ignored by the function.
7002 *
7003 * @see evas_object_image_load_size_set() for more details
7004 */
7005EAPI void evas_object_image_load_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
7006
7007/**
7008 * Set the scale down factor of a given image object's source image,
7009 * when loading it.
7010 *
7011 * @param obj The given image object pointer.
7012 * @param scale_down The scale down factor.
7013 *
7014 * This function sets the scale down factor of a given canvas
7015 * image. Most useful for the SVG image loader.
7016 *
7017 * @see evas_object_image_load_scale_down_get()
7018 */
7019EAPI void evas_object_image_load_scale_down_set (Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1);
7020
7021/**
7022 * get the scale down factor of a given image object's source image,
7023 * when loading it.
7024 *
7025 * @param obj The given image object pointer.
7026 *
7027 * @see evas_object_image_load_scale_down_set() for more details
7028 */
7029EAPI int evas_object_image_load_scale_down_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7030
7031/**
7032 * Inform a given image object to load a selective region of its
7033 * source image.
7034 *
7035 * @param obj The given image object pointer.
7036 * @param x X-offset of the region to be loaded.
7037 * @param y Y-offset of the region to be loaded.
7038 * @param w Width of the region to be loaded.
7039 * @param h Height of the region to be loaded.
7040 *
7041 * This function is useful when one is not showing all of an image's
7042 * area on its image object.
7043 *
7044 * @note The image loader for the image format in question has to
7045 * support selective region loading in order to this function to take
7046 * effect.
7047 *
7048 * @see evas_object_image_load_region_get()
7049 */
7050EAPI void evas_object_image_load_region_set (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
7051
7052/**
7053 * Retrieve the coordinates of a given image object's selective
7054 * (source image) load region.
7055 *
7056 * @param obj The given image object pointer.
7057 * @param x Where to store the X-offset of the region to be loaded.
7058 * @param y Where to store the Y-offset of the region to be loaded.
7059 * @param w Where to store the width of the region to be loaded.
7060 * @param h Where to store the height of the region to be loaded.
7061 *
7062 * @note Use @c NULL pointers on the coordinates you're not interested
7063 * in: they'll be ignored by the function.
7064 *
7065 * @see evas_object_image_load_region_get()
7066 */
7067EAPI void evas_object_image_load_region_get (const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
7068
7069/**
7070 * Define if the orientation information in the image file should be honored.
7071 *
7072 * @param obj The given image object pointer.
7073 * @param enable @p EINA_TRUE means that it should honor the orientation information
7074 * @since 1.1
7075 */
7076EAPI void evas_object_image_load_orientation_set (Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
7077
7078/**
7079 * Get if the orientation information in the image file should be honored.
7080 *
7081 * @param obj The given image object pointer.
7082 * @since 1.1
7083 */
7084EAPI Eina_Bool evas_object_image_load_orientation_get (const Evas_Object *obj) EINA_ARG_NONNULL(1);
7085
7086/**
7087 * Set the colorspace of a given image of the canvas.
7088 *
7089 * @param obj The given image object pointer.
7090 * @param cspace The new color space.
7091 *
7092 * This function sets the colorspace of given canvas image.
7093 *
7094 */
7095EAPI void evas_object_image_colorspace_set (Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1);
7096
7097/**
7098 * Get the colorspace of a given image of the canvas.
7099 *
7100 * @param obj The given image object pointer.
7101 * @return The colorspace of the image.
7102 *
7103 * This function returns the colorspace of given canvas image.
7104 *
7105 */
7106EAPI Evas_Colorspace evas_object_image_colorspace_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7107
7108/**
7109 * Set the native surface of a given image of the canvas
7110 *
7111 * @param obj The given canvas pointer.
7112 * @param surf The new native surface.
7113 *
7114 * This function sets a native surface of a given canvas image.
7115 *
7116 */
7117EAPI void evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2);
7118
7119/**
7120 * Get the native surface of a given image of the canvas
7121 *
7122 * @param obj The given canvas pointer.
7123 * @return The native surface of the given canvas image.
7124 *
7125 * This function returns the native surface of a given canvas image.
7126 *
7127 */
7128EAPI Evas_Native_Surface *evas_object_image_native_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7129
7130/**
7131 * Set the video surface linked to a given image of the canvas
7132 *
7133 * @param obj The given canvas pointer.
7134 * @param surf The new video surface.
7135 * @since 1.1.0
7136 *
7137 * This function link a video surface to a given canvas image.
7138 *
7139 */
7140EAPI void evas_object_image_video_surface_set (Evas_Object *obj, Evas_Video_Surface *surf) EINA_ARG_NONNULL(1);
7141
7142/**
7143 * Get the video surface linekd to a given image of the canvas
7144 *
7145 * @param obj The given canvas pointer.
7146 * @return The video surface of the given canvas image.
7147 * @since 1.1.0
7148 *
7149 * This function returns the video surface linked to a given canvas image.
7150 *
7151 */
7152EAPI const Evas_Video_Surface *evas_object_image_video_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7153
7154/**
7155 * Set the scale hint of a given image of the canvas.
7156 *
7157 * @param obj The given image object pointer.
7158 * @param hint The scale hint, a value in
7159 * #Evas_Image_Scale_Hint.
7160 *
7161 * This function sets the scale hint value of the given image object
7162 * in the canvas, which will affect how Evas is to cache scaled
7163 * versions of its original source image.
7164 *
7165 * @see evas_object_image_scale_hint_get()
7166 */
7167EAPI void evas_object_image_scale_hint_set (Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1);
7168
7169/**
7170 * Get the scale hint of a given image of the canvas.
7171 *
7172 * @param obj The given image object pointer.
7173 * @return The scale hint value set on @p obj, a value in
7174 * #Evas_Image_Scale_Hint.
7175 *
7176 * This function returns the scale hint value of the given image
7177 * object of the canvas.
7178 *
7179 * @see evas_object_image_scale_hint_set() for more details.
7180 */
7181EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7182
7183/**
7184 * Set the content hint setting of a given image object of the canvas.
7185 *
7186 * @param obj The given canvas pointer.
7187 * @param hint The content hint value, one of the
7188 * #Evas_Image_Content_Hint ones.
7189 *
7190 * This function sets the content hint value of the given image of the
7191 * canvas. For example, if you're on the GL engine and your driver
7192 * implementation supports it, setting this hint to
7193 * #EVAS_IMAGE_CONTENT_HINT_DYNAMIC will make it need @b zero copies
7194 * at texture upload time, which is an "expensive" operation.
7195 *
7196 * @see evas_object_image_content_hint_get()
7197 */
7198EAPI void evas_object_image_content_hint_set (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1);
7199
7200/**
7201 * Get the content hint setting of a given image object of the canvas.
7202 *
7203 * @param obj The given canvas pointer.
7204 * @return hint The content hint value set on it, one of the
7205 * #Evas_Image_Content_Hint ones (#EVAS_IMAGE_CONTENT_HINT_NONE means
7206 * an error).
7207 *
7208 * This function returns the content hint value of the given image of
7209 * the canvas.
7210 *
7211 * @see evas_object_image_content_hint_set()
7212 */
7213EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7214
7215
7216/**
7217 * Enable an image to be used as an alpha mask.
7218 *
7219 * This will set any flags, and discard any excess image data not used as an
7220 * alpha mask.
7221 *
7222 * Note there is little point in using a image as alpha mask unless it has an
7223 * alpha channel.
7224 *
7225 * @param obj Object to use as an alpha mask.
7226 * @param ismask Use image as alphamask, must be true.
7227 */
7228EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1);
7229
7230/**
7231 * Set the source object on an image object to used as a @b proxy.
7232 *
7233 * @param obj Proxy (image) object.
7234 * @param src Source object to use for the proxy.
7235 * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
7236 *
7237 * If an image object is set to behave as a @b proxy, it will mirror
7238 * the rendering contents of a given @b source object in its drawing
7239 * region, without affecting that source in any way. The source must
7240 * be another valid Evas object. Other effects may be applied to the
7241 * proxy, such as a map (see evas_object_map_set()) to create a
7242 * reflection of the original object (for example).
7243 *
7244 * Any existing source object on @p obj will be removed after this
7245 * call. Setting @p src to @c NULL clears the proxy object (not in
7246 * "proxy state" anymore).
7247 *
7248 * @warning You cannot set a proxy as another proxy's source.
7249 *
7250 * @see evas_object_image_source_get()
7251 * @see evas_object_image_source_unset()
7252 */
7253EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1);
7254
7255/**
7256 * Get the current source object of an image object.
7257 *
7258 * @param obj Image object
7259 * @return Source object (if any), or @c NULL, if not in "proxy mode"
7260 * (or on errors).
7261 *
7262 * @see evas_object_image_source_set() for more details
7263 */
7264EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1);
7265
7266/**
7267 * Clear the source object on a proxy image object.
7268 *
7269 * @param obj Image object to clear source of.
7270 * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
7271 *
7272 * This is equivalent to calling evas_object_image_source_set() with a
7273 * @c NULL source.
7274 */
7275EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1);
7276
7277/**
7278 * Check if a file extension may be supported by @ref Evas_Object_Image.
7279 *
7280 * @param file The file to check
7281 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
7282 * @since 1.1.0
7283 *
7284 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
7285 *
7286 * This functions is threadsafe.
7287 */
7288EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
7289
7290/**
7291 * Check if a file extension may be supported by @ref Evas_Object_Image.
7292 *
7293 * @param file The file to check, it should be an Eina_Stringshare.
7294 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
7295 * @since 1.1.0
7296 *
7297 * This functions is threadsafe.
7298 */
7299EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
7300
7301/**
7302 * Check if an image object can be animated (have multiple frames)
7303 *
7304 * @param obj Image object
7305 * @return whether obj support animation
7306 *
7307 * This returns if the image file of an image object is capable of animation
7308 * such as an animated gif file might. This is only useful to be called once
7309 * the image object file has been set.
7310 *
7311 * Example:
7312 * @code
7313 * extern Evas_Object *obj;
7314 *
7315 * if (evas_object_image_animated_get(obj))
7316 * {
7317 * int frame_count;
7318 * int loop_count;
7319 * Evas_Image_Animated_Loop_Hint loop_type;
7320 * double duration;
7321 *
7322 * frame_count = evas_object_image_animated_frame_count_get(obj);
7323 * printf("This image has %d frames\n",frame_count);
7324 *
7325 * duration = evas_object_image_animated_frame_duration_get(obj,1,0);
7326 * printf("Frame 1's duration is %f. You had better set object's frame to 2 after this duration using timer\n");
7327 *
7328 * loop_count = evas_object_image_animated_loop_count_get(obj);
7329 * printf("loop count is %d. You had better run loop %d times\n",loop_count,loop_count);
7330 *
7331 * loop_type = evas_object_image_animated_loop_type_get(obj);
7332 * if (loop_type == EVAS_IMAGE_ANIMATED_HINT_LOOP)
7333 * printf("You had better set frame like 1->2->3->1->2->3...\n");
7334 * else if (loop_type == EVAS_IMAGE_ANIMATED_HINT_PINGPONG)
7335 * printf("You had better set frame like 1->2->3->2->1->2...\n");
7336 * else
7337 * printf("Unknown loop type\n");
7338 *
7339 * evas_object_image_animated_frame_set(obj,1);
7340 * printf("You set image object's frame to 1. You can see frame 1\n");
7341 * }
7342 * @endcode
7343 *
7344 * @see evas_object_image_animated_get()
7345 * @see evas_object_image_animated_frame_count_get()
7346 * @see evas_object_image_animated_loop_type_get()
7347 * @see evas_object_image_animated_loop_count_get()
7348 * @see evas_object_image_animated_frame_duration_get()
7349 * @see evas_object_image_animated_frame_set()
7350 * @since 1.1.0
7351 */
7352EAPI Eina_Bool evas_object_image_animated_get(const Evas_Object *obj);
7353
7354/**
7355 * Get the total number of frames of the image object.
7356 *
7357 * @param obj Image object
7358 * @return The number of frames
7359 *
7360 * This returns total number of frames the image object supports (if animated)
7361 *
7362 * @see evas_object_image_animated_get()
7363 * @see evas_object_image_animated_frame_count_get()
7364 * @see evas_object_image_animated_loop_type_get()
7365 * @see evas_object_image_animated_loop_count_get()
7366 * @see evas_object_image_animated_frame_duration_get()
7367 * @see evas_object_image_animated_frame_set()
7368 * @since 1.1.0
7369 */
7370EAPI int evas_object_image_animated_frame_count_get(const Evas_Object *obj);
7371
7372/**
7373 * Get the kind of looping the image object does.
7374 *
7375 * @param obj Image object
7376 * @return Loop type of the image object
7377 *
7378 * This returns the kind of looping the image object wants to do.
7379 *
7380 * If it returns EVAS_IMAGE_ANIMATED_HINT_LOOP, you should display frames in a sequence like:
7381 * 1->2->3->1->2->3->1...
7382 * If it returns EVAS_IMAGE_ANIMATED_HINT_PINGPONG, it is better to
7383 * display frames in a sequence like: 1->2->3->2->1->2->3->1...
7384 *
7385 * The default type is EVAS_IMAGE_ANIMATED_HINT_LOOP.
7386 *
7387 * @see evas_object_image_animated_get()
7388 * @see evas_object_image_animated_frame_count_get()
7389 * @see evas_object_image_animated_loop_type_get()
7390 * @see evas_object_image_animated_loop_count_get()
7391 * @see evas_object_image_animated_frame_duration_get()
7392 * @see evas_object_image_animated_frame_set()
7393 * @since 1.1.0
7394 */
7395EAPI Evas_Image_Animated_Loop_Hint evas_object_image_animated_loop_type_get(const Evas_Object *obj);
7396
7397/**
7398 * Get the number times the animation of the object loops.
7399 *
7400 * @param obj Image object
7401 * @return The number of loop of an animated image object
7402 *
7403 * This returns loop count of image. The loop count is the number of times
7404 * the animation will play fully from first to last frame until the animation
7405 * should stop (at the final frame).
7406 *
7407 * If 0 is returned, then looping should happen indefinitely (no limit to
7408 * the number of times it loops).
7409 *
7410 * @see evas_object_image_animated_get()
7411 * @see evas_object_image_animated_frame_count_get()
7412 * @see evas_object_image_animated_loop_type_get()
7413 * @see evas_object_image_animated_loop_count_get()
7414 * @see evas_object_image_animated_frame_duration_get()
7415 * @see evas_object_image_animated_frame_set()
7416 * @since 1.1.0
7417 */
7418EAPI int evas_object_image_animated_loop_count_get(const Evas_Object *obj);
7419
7420/**
7421 * Get the duration of a sequence of frames.
7422 *
7423 * @param obj Image object
7424 * @param start_frame The first frame
7425 * @param fram_num Number of frames in the sequence
7426 *
7427 * This returns total duration that the specified sequence of frames should
7428 * take in seconds.
7429 *
7430 * If you set start_frame to 1 and frame_num 0, you get frame 1's duration
7431 * If you set start_frame to 1 and frame_num 1, you get frame 1's duration +
7432 * frame2's duration
7433 *
7434 * @see evas_object_image_animated_get()
7435 * @see evas_object_image_animated_frame_count_get()
7436 * @see evas_object_image_animated_loop_type_get()
7437 * @see evas_object_image_animated_loop_count_get()
7438 * @see evas_object_image_animated_frame_duration_get()
7439 * @see evas_object_image_animated_frame_set()
7440 * @since 1.1.0
7441 */
7442EAPI double evas_object_image_animated_frame_duration_get(const Evas_Object *obj, int start_frame, int fram_num);
7443
7444/**
7445 * Set the frame to current frame of an image object
7446 *
7447 * @param obj The given image object.
7448 * @param frame_num The index of current frame
7449 *
7450 * This set image object's current frame to frame_num with 1 being the first
7451 * frame.
7452 *
7453 * @see evas_object_image_animated_get()
7454 * @see evas_object_image_animated_frame_count_get()
7455 * @see evas_object_image_animated_loop_type_get()
7456 * @see evas_object_image_animated_loop_count_get()
7457 * @see evas_object_image_animated_frame_duration_get()
7458 * @see evas_object_image_animated_frame_set()
7459 * @since 1.1.0
7460 */
7461EAPI void evas_object_image_animated_frame_set(Evas_Object *obj, int frame_num);
7462/**
7463 * @}
7464 */
7465
7466/**
7467 * @defgroup Evas_Object_Text Text Object Functions
7468 *
7469 * Functions that operate on single line, single style text objects.
7470 *
7471 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
7472 *
7473 * See some @ref Example_Evas_Text "examples" on this group of functions.
7474 *
7475 * @ingroup Evas_Object_Specific
7476 */
7477
7478/**
7479 * @addtogroup Evas_Object_Text
7480 * @{
7481 */
7482
7483/* basic styles (4 bits allocated use 0->10 now, 5 left) */
7484#define EVAS_TEXT_STYLE_MASK_BASIC 0xf
7485
7486/**
7487 * Text style type creation macro. Use style types on the 's'
7488 * arguments, being 'x' your style variable.
7489 */
7490#define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
7491 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
7492
7493#define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
7494
7495/**
7496 * Text style type creation macro. This one will impose shadow
7497 * directions on the style type variable -- use the @c
7498 * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* values on 's', incremmentally.
7499 */
7500#define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
7501 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
7502
7503 typedef enum _Evas_Text_Style_Type
7504 {
7505 EVAS_TEXT_STYLE_PLAIN, /**< plain, standard text */
7506 EVAS_TEXT_STYLE_SHADOW, /**< text with shadow underneath */
7507 EVAS_TEXT_STYLE_OUTLINE, /**< text with an outline */
7508 EVAS_TEXT_STYLE_SOFT_OUTLINE, /**< text with a soft outline */
7509 EVAS_TEXT_STYLE_GLOW, /**< text with a glow effect */
7510 EVAS_TEXT_STYLE_OUTLINE_SHADOW, /**< text with both outline and shadow effects */
7511 EVAS_TEXT_STYLE_FAR_SHADOW, /**< text with (far) shadow underneath */
7512 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW, /**< text with outline and soft shadow effects combined */
7513 EVAS_TEXT_STYLE_SOFT_SHADOW, /**< text with (soft) shadow underneath */
7514 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW, /**< text with (far soft) shadow underneath */
7515
7516 /* OR these to modify shadow direction (3 bits needed) */
7517 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< shadow growing to bottom right */
7518 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< shadow growing to the bottom */
7519 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< shadow growing to bottom left */
7520 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< shadow growing to the left */
7521 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< shadow growing to top left */
7522 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< shadow growing to the top */
7523 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< shadow growing to top right */
7524 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< shadow growing to the right */
7525 } 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 */
7526
7527/**
7528 * Creates a new text object on the provided canvas.
7529 *
7530 * @param e The canvas to create the text object on.
7531 * @return @c NULL on error, a pointer to a new text object on
7532 * success.
7533 *
7534 * Text objects are for simple, single line text elements. If you want
7535 * more elaborated text blocks, see @ref Evas_Object_Textblock.
7536 *
7537 * @see evas_object_text_font_source_set()
7538 * @see evas_object_text_font_set()
7539 * @see evas_object_text_text_set()
7540 */
7541EAPI Evas_Object *evas_object_text_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7542
7543/**
7544 * Set the font (source) file to be used on a given text object.
7545 *
7546 * @param obj The text object to set font for.
7547 * @param font The font file's path.
7548 *
7549 * This function allows the font file to be explicitly set for a given
7550 * text object, overriding system lookup, which will first occur in
7551 * the given file's contents.
7552 *
7553 * @see evas_object_text_font_get()
7554 */
7555EAPI void evas_object_text_font_source_set (Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1);
7556
7557/**
7558 * Get the font file's path which is being used on a given text
7559 * object.
7560 *
7561 * @param obj The text object to set font for.
7562 * @param font The font file's path.
7563 *
7564 * @see evas_object_text_font_get() for more details
7565 */
7566EAPI const char *evas_object_text_font_source_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7567
7568/**
7569 * Set the font family and size on a given text object.
7570 *
7571 * @param obj The text object to set font for.
7572 * @param font The font (family) name.
7573 * @param size The font size, in points.
7574 *
7575 * This function allows the font name and size of a text object to be
7576 * set. The @p font string has to follow fontconfig's convention on
7577 * naming fonts, as it's the underlying lybrary used to query system
7578 * fonts by Evas (see the @c fc-list command's output, on your system,
7579 * to get an idea).
7580 *
7581 * @see evas_object_text_font_get()
7582 * @see evas_object_text_font_source_set()
7583 */
7584 EAPI void evas_object_text_font_set (Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1);
7585
7586/**
7587 * Retrieve the font family and size in use on a given text object.
7588 *
7589 * @param obj The evas text object to query for font information.
7590 * @param font A pointer to the location to store the font name in.
7591 * @param size A pointer to the location to store the font size in.
7592 *
7593 * This function allows the font name and size of a text object to be
7594 * queried. Be aware that the font name string is still owned by Evas
7595 * and should @b not have free() called on it by the caller of the
7596 * function.
7597 *
7598 * @see evas_object_text_font_set()
7599 */
7600EAPI void evas_object_text_font_get (const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1);
7601
7602/**
7603 * Sets the text string to be displayed by the given text object.
7604 *
7605 * @param obj The text object to set text string on.
7606 * @param text Text string to display on it.
7607 *
7608 * @see evas_object_text_text_get()
7609 */
7610EAPI void evas_object_text_text_set (Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
7611
7612/**
7613 * Retrieves the text string currently being displayed by the given
7614 * text object.
7615 *
7616 * @param obj The given text object.
7617 * @return The text string currently being displayed on it.
7618 *
7619 * @note Do not free() the return value.
7620 *
7621 * @see evas_object_text_text_set()
7622 */
7623EAPI const char *evas_object_text_text_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7624
7625/**
7626 * @brief Sets the BiDi delimiters used in the textblock.
7627 *
7628 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
7629 * is useful for example in recipients fields of e-mail clients where bidi
7630 * oddities can occur when mixing rtl and ltr.
7631 *
7632 * @param obj The given text object.
7633 * @param delim A null terminated string of delimiters, e.g ",|".
7634 * @since 1.1.0
7635 */
7636EAPI void evas_object_text_bidi_delimiters_set(Evas_Object *obj, const char *delim);
7637
7638/**
7639 * @brief Gets the BiDi delimiters used in the textblock.
7640 *
7641 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
7642 * is useful for example in recipients fields of e-mail clients where bidi
7643 * oddities can occur when mixing rtl and ltr.
7644 *
7645 * @param obj The given text object.
7646 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
7647 * @since 1.1.0
7648 */
7649EAPI const char *evas_object_text_bidi_delimiters_get(const Evas_Object *obj);
7650
7651 EAPI Evas_Coord evas_object_text_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7652 EAPI Evas_Coord evas_object_text_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7653 EAPI Evas_Coord evas_object_text_max_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7654 EAPI Evas_Coord evas_object_text_max_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7655 EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7656 EAPI Evas_Coord evas_object_text_vert_advance_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7657 EAPI Evas_Coord evas_object_text_inset_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7658
7659/**
7660 * Retrieve position and dimension information of a character within a text @c Evas_Object.
7661 *
7662 * This function is used to obtain the X, Y, width and height of a the character
7663 * located at @p pos within the @c Evas_Object @p obj. @p obj must be a text object
7664 * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx,
7665 * @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to that
7666 * parameter.
7667 *
7668 * @param obj The text object to retrieve position information for.
7669 * @param pos The character position to request co-ordinates for.
7670 * @param cx A pointer to an @c Evas_Coord to store the X value in (can be NULL).
7671 * @param cy A pointer to an @c Evas_Coord to store the Y value in (can be NULL).
7672 * @param cw A pointer to an @c Evas_Coord to store the Width value in (can be NULL).
7673 * @param ch A pointer to an @c Evas_Coord to store the Height value in (can be NULL).
7674 *
7675 * @returns EINA_FALSE on success, EINA_TRUE on error.
7676 */
7677EAPI 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);
7678 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);
7679
7680/**
7681 * Returns the logical position of the last char in the text
7682 * up to the pos given. this is NOT the position of the last char
7683 * because of the possibility of RTL in the text.
7684 */
7685EAPI int evas_object_text_last_up_to_pos (const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
7686
7687/**
7688 * Retrieves the style on use on the given text object.
7689 *
7690 * @param obj the given text object to set style on.
7691 * @return the style type in use.
7692 *
7693 * @see evas_object_text_style_set() for more details.
7694 */
7695EAPI Evas_Text_Style_Type evas_object_text_style_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7696
7697/**
7698 * Sets the style to apply on the given text object.
7699 *
7700 * @param obj the given text object to set style on.
7701 * @param type a style type.
7702 *
7703 * Text object styles are one of the values in
7704 * #Evas_Text_Style_Type. Some of those values are combinations of
7705 * more than one style, and some account for the direction of the
7706 * rendering of shadow effects.
7707 *
7708 * @note One may use the helper macros #EVAS_TEXT_STYLE_BASIC_SET and
7709 * #EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET to assemble a style value.
7710 *
7711 * The following figure illustrates the text styles:
7712 *
7713 * @image html text-styles.png
7714 * @image rtf text-styles.png
7715 * @image latex text-styles.eps
7716 *
7717 * @see evas_object_text_style_get()
7718 * @see evas_object_text_shadow_color_set()
7719 * @see evas_object_text_outline_color_set()
7720 * @see evas_object_text_glow_color_set()
7721 * @see evas_object_text_glow2_color_set()
7722 */
7723EAPI void evas_object_text_style_set (Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1);
7724
7725/**
7726 * Sets the shadow color for the given text object.
7727 *
7728 * @param obj The given Evas text object.
7729 * @param r The red component of the given color.
7730 * @param g The green component of the given color.
7731 * @param b The blue component of the given color.
7732 * @param a The alpha component of the given color.
7733 *
7734 * Shadow effects, which are fading colors decorating the text
7735 * underneath it, will just be shown if the object is set to one of
7736 * the following styles:
7737 *
7738 * - #EVAS_TEXT_STYLE_SHADOW
7739 * - #EVAS_TEXT_STYLE_OUTLINE_SHADOW
7740 * - #EVAS_TEXT_STYLE_FAR_SHADOW
7741 * - #EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW
7742 * - #EVAS_TEXT_STYLE_SOFT_SHADOW
7743 * - #EVAS_TEXT_STYLE_FAR_SOFT_SHADOW
7744 *
7745 * One can also change de direction the shadow grows to, with
7746 * evas_object_text_style_set().
7747 *
7748 * @see evas_object_text_shadow_color_get()
7749 */
7750EAPI void evas_object_text_shadow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
7751
7752/**
7753 * Retrieves the shadow color for the given text object.
7754 *
7755 * @param obj The given Evas text object.
7756 * @param r Pointer to variable to hold the red component of the given
7757 * color.
7758 * @param g Pointer to variable to hold the green component of the
7759 * given color.
7760 * @param b Pointer to variable to hold the blue component of the
7761 * given color.
7762 * @param a Pointer to variable to hold the alpha component of the
7763 * given color.
7764 *
7765 * @note Use @c NULL pointers on the color components you're not
7766 * interested in: they'll be ignored by the function.
7767 *
7768 * @see evas_object_text_shadow_color_set() for more details.
7769 */
7770EAPI void evas_object_text_shadow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
7771
7772/**
7773 * Sets the glow color for the given text object.
7774 *
7775 * @param obj The given Evas text object.
7776 * @param r The red component of the given color.
7777 * @param g The green component of the given color.
7778 * @param b The blue component of the given color.
7779 * @param a The alpha component of the given color.
7780 *
7781 * Glow effects, which are glowing colors decorating the text's
7782 * surroundings, will just be shown if the object is set to the
7783 * #EVAS_TEXT_STYLE_GLOW style.
7784 *
7785 * @note Glow effects are placed from a short distance of the text
7786 * itself, but no touching it. For glowing effects right on the
7787 * borders of the glyphs, see 'glow 2' effects
7788 * (evas_object_text_glow2_color_set()).
7789 *
7790 * @see evas_object_text_glow_color_get()
7791 */
7792EAPI void evas_object_text_glow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
7793
7794/**
7795 * Retrieves the glow color for the given text object.
7796 *
7797 * @param obj The given Evas text object.
7798 * @param r Pointer to variable to hold the red component of the given
7799 * color.
7800 * @param g Pointer to variable to hold the green component of the
7801 * given color.
7802 * @param b Pointer to variable to hold the blue component of the
7803 * given color.
7804 * @param a Pointer to variable to hold the alpha component of the
7805 * given color.
7806 *
7807 * @note Use @c NULL pointers on the color components you're not
7808 * interested in: they'll be ignored by the function.
7809 *
7810 * @see evas_object_text_glow_color_set() for more details.
7811 */
7812EAPI void evas_object_text_glow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
7813
7814/**
7815 * Sets the 'glow 2' color for the given text object.
7816 *
7817 * @param obj The given Evas text object.
7818 * @param r The red component of the given color.
7819 * @param g The green component of the given color.
7820 * @param b The blue component of the given color.
7821 * @param a The alpha component of the given color.
7822 *
7823 * 'Glow 2' effects, which are glowing colors decorating the text's
7824 * (immediate) surroundings, will just be shown if the object is set
7825 * to the #EVAS_TEXT_STYLE_GLOW style. See also
7826 * evas_object_text_glow_color_set().
7827 *
7828 * @see evas_object_text_glow2_color_get()
7829 */
7830EAPI void evas_object_text_glow2_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
7831
7832/**
7833 * Retrieves the 'glow 2' color for the given text object.
7834 *
7835 * @param obj The given Evas text object.
7836 * @param r Pointer to variable to hold the red component of the given
7837 * color.
7838 * @param g Pointer to variable to hold the green component of the
7839 * given color.
7840 * @param b Pointer to variable to hold the blue component of the
7841 * given color.
7842 * @param a Pointer to variable to hold the alpha component of the
7843 * given color.
7844 *
7845 * @note Use @c NULL pointers on the color components you're not
7846 * interested in: they'll be ignored by the function.
7847 *
7848 * @see evas_object_text_glow2_color_set() for more details.
7849 */
7850EAPI void evas_object_text_glow2_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
7851
7852/**
7853 * Sets the outline color for the given text object.
7854 *
7855 * @param obj The given Evas text object.
7856 * @param r The red component of the given color.
7857 * @param g The green component of the given color.
7858 * @param b The blue component of the given color.
7859 * @param a The alpha component of the given color.
7860 *
7861 * Outline effects (colored lines around text glyphs) will just be
7862 * shown if the object is set to one of the following styles:
7863 * - #EVAS_TEXT_STYLE_OUTLINE
7864 * - #EVAS_TEXT_STYLE_SOFT_OUTLINE
7865 * - #EVAS_TEXT_STYLE_OUTLINE_SHADOW
7866 * - #EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW
7867 *
7868 * @see evas_object_text_outline_color_get()
7869 */
7870EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
7871
7872/**
7873 * Retrieves the outline color for the given text object.
7874 *
7875 * @param obj The given Evas text object.
7876 * @param r Pointer to variable to hold the red component of the given
7877 * color.
7878 * @param g Pointer to variable to hold the green component of the
7879 * given color.
7880 * @param b Pointer to variable to hold the blue component of the
7881 * given color.
7882 * @param a Pointer to variable to hold the alpha component of the
7883 * given color.
7884 *
7885 * @note Use @c NULL pointers on the color components you're not
7886 * interested in: they'll be ignored by the function.
7887 *
7888 * @see evas_object_text_outline_color_set() for more details.
7889 */
7890EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
7891
7892/**
7893 * Gets the text style pad of a text object.
7894 *
7895 * @param obj The given text object.
7896 * @param l The left pad (or @c NULL).
7897 * @param r The right pad (or @c NULL).
7898 * @param t The top pad (or @c NULL).
7899 * @param b The bottom pad (or @c NULL).
7900 *
7901 */
7902EAPI void evas_object_text_style_pad_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
7903
7904/**
7905 * Retrieves the direction of the text currently being displayed in the
7906 * text object.
7907 * @param obj The given evas text object.
7908 * @return the direction of the text
7909 */
7910EAPI Evas_BiDi_Direction evas_object_text_direction_get (const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
7911
7912/**
7913 * @}
7914 */
7915
7916/**
7917 * @defgroup Evas_Object_Textblock Textblock Object Functions
7918 *
7919 * Functions used to create and manipulate textblock objects. Unlike
7920 * @ref Evas_Object_Text, these handle complex text, doing multiple
7921 * styles and multiline text based on HTML-like tags. Of these extra
7922 * features will be heavier on memory and processing cost.
7923 *
7924 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
7925 *
7926 * This part explains about the textblock object's API and proper usage.
7927 * If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal.
7928 * The main user of the textblock object is the edje entry object in Edje, so
7929 * that's a good place to learn from, but I think this document is more than
7930 * enough, if it's not, please contact me and I'll update it.
7931 *
7932 * @subsection textblock_intro Introduction
7933 * The textblock objects is, as implied, an object that can show big chunks of
7934 * text. Textblock supports many features including: Text formatting, automatic
7935 * and manual text alignment, embedding items (for example icons) and more.
7936 * Textblock has three important parts, the text paragraphs, the format nodes
7937 * and the cursors.
7938 *
7939 * You can use markup to format text, for example: "<font_size=50>Big!</font_size>".
7940 * You can also put more than one style directive in one tag:
7941 * "<font_size=50 color=#F00>Big and Red!</font_size>".
7942 * Please notice that we used "</font_size>" although the format also included
7943 * color, this is because the first format determines the matching closing tag's
7944 * name. You can also use anonymous tags, like: "<font_size=30>Big</>" which
7945 * just pop any type of format, but it's advised to use the named alternatives
7946 * instead.
7947 *
7948 * @subsection textblock_cursors Textblock Object Cursors
7949 * A textblock Cursor @ref Evas_Textblock_Cursor is data type that represents
7950 * a position in a textblock. Each cursor contains information about the
7951 * paragraph it points to, the position in that paragraph and the object itself.
7952 * Cursors register to textblock objects upon creation, this means that once
7953 * you created a cursor, it belongs to a specific obj and you can't for example
7954 * copy a cursor "into" a cursor of a different object. Registered cursors
7955 * also have the added benefit of updating automatically upon textblock changes,
7956 * this means that if you have a cursor pointing to a specific character, it'll
7957 * still point to it even after you change the whole object completely (as long
7958 * as the char was not deleted), this is not possible without updating, because
7959 * as mentioned, each cursor holds a character position. There are many
7960 * functions that handle cursors, just check out the evas_textblock_cursor*
7961 * functions. For creation and deletion of cursors check out:
7962 * @see evas_object_textblock_cursor_new()
7963 * @see evas_textblock_cursor_free()
7964 * @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).
7965 *
7966 * @subsection textblock_paragraphs Textblock Object Paragraphs
7967 * The textblock object is made out of text splitted to paragraphs (delimited
7968 * by the paragraph separation character). Each paragraph has many (or none)
7969 * format nodes associated with it which are responsible for the formatting
7970 * of that paragraph.
7971 *
7972 * @subsection textblock_format_nodes Textblock Object Format Nodes
7973 * As explained in @ref textblock_paragraphs each one of the format nodes
7974 * is associated with a paragraph.
7975 * There are two types of format nodes, visible and invisible:
7976 * Visible: formats that a cursor can point to, i.e formats that
7977 * occupy space, for example: newlines, tabs, items and etc. Some visible items
7978 * are made of two parts, in this case, only the opening tag is visible.
7979 * A closing tag (i.e a </tag> tag) should NEVER be visible.
7980 * Invisible: formats that don't occupy space, for example: bold and underline.
7981 * Being able to access format nodes is very important for some uses. For
7982 * example, edje uses the "<a>" format to create links in the text (and pop
7983 * popups above them when clicked). For the textblock object a is just a
7984 * formatting instruction (how to color the text), but edje utilizes the access
7985 * to the format nodes to make it do more.
7986 * For more information, take a look at all the evas_textblock_node_format_*
7987 * functions.
7988 * The translation of "<tag>" tags to actual format is done according to the
7989 * tags defined in the style, see @ref evas_textblock_style_set
7990 *
7991 * @subsection textblock_special_formats Special Formats
7992 * Textblock supports various format directives that can be used either in
7993 * markup, or by calling @ref evas_object_textblock_format_append or
7994 * @ref evas_object_textblock_format_prepend. In addition to the mentioned
7995 * format directives, textblock allows creating additional format directives
7996 * using "tags" that can be set in the style see @ref evas_textblock_style_set .
7997 *
7998 * Textblock supports the following formats:
7999 * @li font - Font description in fontconfig like format, e.g: "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
8000 * @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".
8001 * @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".
8002 * @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".
8003 * @li lang - Overrides the language defined in "font". E.g: "lang=he" is the same as "font=:lang=he".
8004 * @li font_fallbacks - A comma delimited list of fonts to try if finding the main font fails.
8005 * @li font_size - The font size in points.
8006 * @li font_source - The source of the font, e.g an eet file.
8007 * @li color - Text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8008 * @li underline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8009 * @li underline2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8010 * @li outline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8011 * @li shadow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8012 * @li glow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8013 * @li glow2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8014 * @li backing_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8015 * @li strikethrough_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
8016 * @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%.
8017 * @li valign - Either "top", "bottom", "middle", "center", "baseline", "base", a value between 0.0 and 1.0, or a value between 0% to 100%.
8018 * @li wrap - "word", "char", "mixed", or "none".
8019 * @li left_margin - Either "reset", or a pixel value indicating the margin.
8020 * @li right_margin - Either "reset", or a pixel value indicating the margin.
8021 * @li underline - "on", "off", "single", or "double".
8022 * @li strikethrough - "on" or "off"
8023 * @li backing - "on" or "off"
8024 * @li style - Either "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow", or "far_soft_shadow".
8025 * @li tabstops - Pixel value for tab width.
8026 * @li linesize - Force a line size in pixels.
8027 * @li linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
8028 * @li linegap - Force a line gap in pixels.
8029 * @li linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
8030 * @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.
8031 * @li linefill - Either a float value or percentage indicating how much to fill the line.
8032 * @li ellipsis - Value between 0.0-1.0 to indicate the type of ellipsis, or -1.0 to indicate ellipsis isn't wanted.
8033 * @li password - "on" or "off". This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off.
8034 *
8035 *
8036 * @todo put here some usage examples
8037 *
8038 * @ingroup Evas_Object_Specific
8039 *
8040 * @{
8041 */
8042
8043 typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
8044 typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
8045 /**
8046 * @typedef Evas_Object_Textblock_Node_Format
8047 * A format node.
8048 */
8049 typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
8050 typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
8051
8052 struct _Evas_Textblock_Rectangle
8053 {
8054 Evas_Coord x, y, w, h;
8055 };
8056
8057 typedef enum _Evas_Textblock_Text_Type
8058 {
8059 EVAS_TEXTBLOCK_TEXT_RAW,
8060 EVAS_TEXTBLOCK_TEXT_PLAIN,
8061 EVAS_TEXTBLOCK_TEXT_MARKUP
8062 } Evas_Textblock_Text_Type;
8063
8064 typedef enum _Evas_Textblock_Cursor_Type
8065 {
8066 EVAS_TEXTBLOCK_CURSOR_UNDER,
8067 EVAS_TEXTBLOCK_CURSOR_BEFORE
8068 } Evas_Textblock_Cursor_Type;
8069
8070
8071/**
8072 * Adds a textblock to the given evas.
8073 * @param e The given evas.
8074 * @return The new textblock object.
8075 */
8076EAPI Evas_Object *evas_object_textblock_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8077
8078
8079/**
8080 * Returns the unescaped version of escape.
8081 * @param escape the string to be escaped
8082 * @return the unescaped version of escape
8083 */
8084EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8085
8086/**
8087 * Returns the escaped version of the string.
8088 * @param string to escape
8089 * @param len_ret the len of the part of the string that was used.
8090 * @return the escaped string.
8091 */
8092EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8093
8094/**
8095 * Return the unescaped version of the string between start and end.
8096 *
8097 * @param escape_start the start of the string.
8098 * @param escape_end the end of the string.
8099 * @return the unescaped version of the range
8100 */
8101EAPI 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) EINA_PURE;
8102
8103
8104/**
8105 * Creates a new textblock style.
8106 * @return The new textblock style.
8107 */
8108EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
8109
8110/**
8111 * Destroys a textblock style.
8112 * @param ts The textblock style to free.
8113 */
8114EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
8115
8116/**
8117 * Sets the style ts to the style passed as text by text.
8118 * Expected a string consisting of many (or none) tag='format' pairs.
8119 *
8120 * @param ts the style to set.
8121 * @param text the text to parse - NOT NULL.
8122 * @return Returns no value.
8123 */
8124EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
8125
8126/**
8127 * Return the text of the style ts.
8128 * @param ts the style to get it's text.
8129 * @return the text of the style or null on error.
8130 */
8131EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8132
8133
8134/**
8135 * Set the objects style to ts.
8136 * @param obj the Evas object to set the style to.
8137 * @param ts the style to set.
8138 * @return Returns no value.
8139 */
8140EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
8141
8142/**
8143 * Return the style of an object.
8144 * @param obj the object to get the style from.
8145 * @return the style of the object.
8146 */
8147EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8148
8149/**
8150 * @brief Set the "replacement character" to use for the given textblock object.
8151 *
8152 * @param obj The given textblock object.
8153 * @param ch The charset name.
8154 */
8155EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1);
8156
8157/**
8158 * @brief Get the "replacement character" for given textblock object. Returns
8159 * NULL if no replacement character is in use.
8160 *
8161 * @param obj The given textblock object
8162 * @return replacement character or @c NULL
8163 */
8164EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8165
8166/**
8167 * @brief Sets the vertical alignment of text within the textblock object
8168 * as a whole.
8169 *
8170 * Normally alignment is 0.0 (top of object). Values given should be
8171 * between 0.0 and 1.0 (1.0 bottom of object, 0.5 being vertically centered
8172 * etc.).
8173 *
8174 * @param obj The given textblock object.
8175 * @param align A value between 0.0 and 1.0
8176 * @since 1.1.0
8177 */
8178EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align);
8179
8180/**
8181 * @brief Gets the vertical alignment of a textblock
8182 *
8183 * @param obj The given textblock object.
8184 * @return The elignment set for the object
8185 * @since 1.1.0
8186 */
8187EAPI double evas_object_textblock_valign_get(const Evas_Object *obj);
8188
8189/**
8190 * @brief Sets the BiDi delimiters used in the textblock.
8191 *
8192 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
8193 * is useful for example in recipients fields of e-mail clients where bidi
8194 * oddities can occur when mixing rtl and ltr.
8195 *
8196 * @param obj The given textblock object.
8197 * @param delim A null terminated string of delimiters, e.g ",|".
8198 * @since 1.1.0
8199 */
8200EAPI void evas_object_textblock_bidi_delimiters_set(Evas_Object *obj, const char *delim);
8201
8202/**
8203 * @brief Gets the BiDi delimiters used in the textblock.
8204 *
8205 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
8206 * is useful for example in recipients fields of e-mail clients where bidi
8207 * oddities can occur when mixing rtl and ltr.
8208 *
8209 * @param obj The given textblock object.
8210 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
8211 * @since 1.1.0
8212 */
8213EAPI const char *evas_object_textblock_bidi_delimiters_get(const Evas_Object *obj);
8214
8215/**
8216 * @brief Sets newline mode. When true, newline character will behave
8217 * as a paragraph separator.
8218 *
8219 * @param obj The given textblock object.
8220 * @param mode EINA_TRUE for legacy mode, EINA_FALSE otherwise.
8221 * @since 1.1.0
8222 */
8223EAPI void evas_object_textblock_legacy_newline_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1);
8224
8225/**
8226 * @brief Gets newline mode. When true, newline character behaves
8227 * as a paragraph separator.
8228 *
8229 * @param obj The given textblock object.
8230 * @return EINA_TRUE if in legacy mode, EINA_FALSE otherwise.
8231 * @since 1.1.0
8232 */
8233EAPI Eina_Bool evas_object_textblock_legacy_newline_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8234
8235
8236/**
8237 * Sets the tetxblock's text to the markup text.
8238 *
8239 * @note assumes text does not include the unicode object replacement char (0xFFFC)
8240 *
8241 * @param obj the textblock object.
8242 * @param text the markup text to use.
8243 * @return Return no value.
8244 */
8245EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
8246
8247/**
8248 * Prepends markup to the cursor cur.
8249 *
8250 * @note assumes text does not include the unicode object replacement char (0xFFFC)
8251 *
8252 * @param cur the cursor to prepend to.
8253 * @param text the markup text to prepend.
8254 * @return Return no value.
8255 */
8256EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
8257
8258/**
8259 * Return the markup of the object.
8260 *
8261 * @param obj the Evas object.
8262 * @return the markup text of the object.
8263 */
8264EAPI const char *evas_object_textblock_text_markup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
8265
8266
8267/**
8268 * Return the object's main cursor.
8269 *
8270 * @param obj the object.
8271 * @return the obj's main cursor.
8272 */
8273EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8274
8275/**
8276 * Create a new cursor, associate it to the obj and init it to point
8277 * to the start of the textblock. Association to the object means the cursor
8278 * will be updated when the object will change.
8279 *
8280 * @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).
8281 *
8282 * @param obj the object to associate to.
8283 * @return the new cursor.
8284 */
8285EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8286
8287
8288/**
8289 * Free the cursor and unassociate it from the object.
8290 * @note do not use it to free unassociated cursors.
8291 *
8292 * @param cur the cursor to free.
8293 * @return Returns no value.
8294 */
8295EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8296
8297
8298/**
8299 * Sets the cursor to the start of the first text node.
8300 *
8301 * @param cur the cursor to update.
8302 * @return Returns no value.
8303 */
8304EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8305
8306/**
8307 * sets the cursor to the end of the last text node.
8308 *
8309 * @param cur the cursor to set.
8310 * @return Returns no value.
8311 */
8312EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8313
8314/**
8315 * Advances to the start of the next text node
8316 *
8317 * @param cur the cursor to update
8318 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
8319 */
8320EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8321
8322/**
8323 * Advances to the end of the previous text node
8324 *
8325 * @param cur the cursor to update
8326 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
8327 */
8328EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8329
8330/**
8331 * Returns the
8332 *
8333 * @param obj The evas, must not be NULL.
8334 * @param anchor the anchor name to get
8335 * @return Returns the list format node corresponding to the anchor, may be null if there are none.
8336 */
8337EAPI const Eina_List *evas_textblock_node_format_list_get(const Evas_Object *obj, const char *anchor) EINA_ARG_NONNULL(1, 2);
8338
8339/**
8340 * Returns the first format node.
8341 *
8342 * @param obj The evas, must not be NULL.
8343 * @return Returns the first format node, may be null if there are none.
8344 */
8345EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
8346
8347/**
8348 * Returns the last format node.
8349 *
8350 * @param obj The evas textblock, must not be NULL.
8351 * @return Returns the first format node, may be null if there are none.
8352 */
8353EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
8354
8355/**
8356 * Returns the next format node (after n)
8357 *
8358 * @param n the current format node - not null.
8359 * @return Returns the next format node, may be null.
8360 */
8361EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
8362
8363/**
8364 * Returns the prev format node (after n)
8365 *
8366 * @param n the current format node - not null.
8367 * @return Returns the prev format node, may be null.
8368 */
8369EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
8370
8371/**
8372 * Remove a format node and it's match. i.e, removes a <tag> </tag> pair.
8373 * Assumes the node is the first part of <tag> i.e, this won't work if
8374 * n is a closing tag.
8375 *
8376 * @param obj the Evas object of the textblock - not null.
8377 * @param n the current format node - not null.
8378 */
8379EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
8380
8381/**
8382 * Sets the cursor to point to the place where format points to.
8383 *
8384 * @param cur the cursor to update.
8385 * @param n the format node to update according.
8386 * @deprecated duplicate of evas_textblock_cursor_at_format_set
8387 */
8388EINA_DEPRECATED EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
8389
8390/**
8391 * Return the format node at the position pointed by cur.
8392 *
8393 * @param cur the position to look at.
8394 * @return the format node if found, NULL otherwise.
8395 * @see evas_textblock_cursor_format_is_visible_get()
8396 */
8397EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8398
8399/**
8400 * Get the text format representation of the format node.
8401 *
8402 * @param fmt the format node.
8403 * @return the textual format of the format node.
8404 */
8405EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fnode) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
8406
8407/**
8408 * Set the cursor to point to the position of fmt.
8409 *
8410 * @param cur the cursor to update
8411 * @param fmt the format to update according to.
8412 */
8413EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
8414
8415/**
8416 * Check if the current cursor position is a visible format. This way is more
8417 * efficient than evas_textblock_cursor_format_get() to check for the existence
8418 * of a visible format.
8419 *
8420 * @param cur the cursor to look at.
8421 * @return #EINA_TRUE if the cursor points to a visible format, #EINA_FALSE otherwise.
8422 * @see evas_textblock_cursor_format_get()
8423 */
8424EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8425
8426/**
8427 * Advances to the next format node
8428 *
8429 * @param cur the cursor to be updated.
8430 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8431 */
8432EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8433
8434/**
8435 * Advances to the previous format node.
8436 *
8437 * @param cur the cursor to update.
8438 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8439 */
8440EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8441
8442/**
8443 * Returns true if the cursor points to a format.
8444 *
8445 * @param cur the cursor to check.
8446 * @return Returns #EINA_TRUE if a cursor points to a format #EINA_FALSE otherwise.
8447 */
8448EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8449
8450/**
8451 * Advances 1 char forward.
8452 *
8453 * @param cur the cursor to advance.
8454 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8455 */
8456EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8457
8458/**
8459 * Advances 1 char backward.
8460 *
8461 * @param cur the cursor to advance.
8462 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
8463 */
8464EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8465
8466/**
8467 * Go to the first char in the node the cursor is pointing on.
8468 *
8469 * @param cur the cursor to update.
8470 * @return Returns no value.
8471 */
8472EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8473
8474/**
8475 * Go to the last char in a text node.
8476 *
8477 * @param cur the cursor to update.
8478 * @return Returns no value.
8479 */
8480EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8481
8482/**
8483 * Go to the start of the current line
8484 *
8485 * @param cur the cursor to update.
8486 * @return Returns no value.
8487 */
8488EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8489
8490/**
8491 * Go to the end of the current line.
8492 *
8493 * @param cur the cursor to update.
8494 * @return Returns no value.
8495 */
8496EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8497
8498/**
8499 * Return the current cursor pos.
8500 *
8501 * @param cur the cursor to take the position from.
8502 * @return the position or -1 on error
8503 */
8504EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8505
8506/**
8507 * Set the cursor pos.
8508 *
8509 * @param cur the cursor to be set.
8510 * @param pos the pos to set.
8511 */
8512EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
8513
8514/**
8515 * Go to the start of the line passed
8516 *
8517 * @param cur cursor to update.
8518 * @param line numer to set.
8519 * @return #EINA_TRUE on success, #EINA_FALSE on error.
8520 */
8521EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
8522
8523/**
8524 * Compare two cursors.
8525 *
8526 * @param cur1 the first cursor.
8527 * @param cur2 the second cursor.
8528 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
8529 */
8530EAPI int evas_textblock_cursor_compare(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
8531
8532/**
8533 * Make cur_dest point to the same place as cur. Does not work if they don't
8534 * point to the same object.
8535 *
8536 * @param cur the source cursor.
8537 * @param cur_dest destination cursor.
8538 * @return Returns no value.
8539 */
8540EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
8541
8542
8543/**
8544 * Adds text to the current cursor position and set the cursor to *before*
8545 * the start of the text just added.
8546 *
8547 * @param cur the cursor to where to add text at.
8548 * @param _text the text to add.
8549 * @return Returns the len of the text added.
8550 * @see evas_textblock_cursor_text_prepend()
8551 */
8552EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
8553
8554/**
8555 * Adds text to the current cursor position and set the cursor to *after*
8556 * the start of the text just added.
8557 *
8558 * @param cur the cursor to where to add text at.
8559 * @param _text the text to add.
8560 * @return Returns the len of the text added.
8561 * @see evas_textblock_cursor_text_append()
8562 */
8563EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
8564
8565
8566/**
8567 * Adds format to the current cursor position. If the format being added is a
8568 * visible format, add it *before* the cursor position, otherwise, add it after.
8569 * This behavior is because visible formats are like characters and invisible
8570 * should be stacked in a way that the last one is added last.
8571 *
8572 * This function works with native formats, that means that style defined
8573 * tags like <br> won't work here. For those kind of things use markup prepend.
8574 *
8575 * @param cur the cursor to where to add format at.
8576 * @param format the format to add.
8577 * @return Returns true if a visible format was added, false otherwise.
8578 * @see evas_textblock_cursor_format_prepend()
8579 */
8580
8581/**
8582 * Check if the current cursor position points to the terminating null of the
8583 * last paragraph. (shouldn't be allowed to point to the terminating null of
8584 * any previous paragraph anyway.
8585 *
8586 * @param cur the cursor to look at.
8587 * @return #EINA_TRUE if the cursor points to the terminating null, #EINA_FALSE otherwise.
8588 */
8589EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
8590
8591/**
8592 * Adds format to the current cursor position. If the format being added is a
8593 * visible format, add it *before* the cursor position, otherwise, add it after.
8594 * This behavior is because visible formats are like characters and invisible
8595 * should be stacked in a way that the last one is added last.
8596 * If the format is visible the cursor is advanced after it.
8597 *
8598 * This function works with native formats, that means that style defined
8599 * tags like <br> won't work here. For those kind of things use markup prepend.
8600 *
8601 * @param cur the cursor to where to add format at.
8602 * @param format the format to add.
8603 * @return Returns true if a visible format was added, false otherwise.
8604 * @see evas_textblock_cursor_format_prepend()
8605 */
8606EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
8607
8608/**
8609 * Delete the character at the location of the cursor. If there's a format
8610 * pointing to this position, delete it as well.
8611 *
8612 * @param cur the cursor pointing to the current location.
8613 * @return Returns no value.
8614 */
8615EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
8616
8617/**
8618 * Delete the range between cur1 and cur2.
8619 *
8620 * @param cur1 one side of the range.
8621 * @param cur2 the second side of the range
8622 * @return Returns no value.
8623 */
8624EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
8625
8626
8627/**
8628 * Return the text of the paragraph cur points to - returns the text in markup..
8629 *
8630 * @param cur the cursor pointing to the paragraph.
8631 * @return the text on success, NULL otherwise.
8632 */
8633EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8634
8635/**
8636 * Return the length of the paragraph, cheaper the eina_unicode_strlen()
8637 *
8638 * @param cur the position of the paragraph.
8639 * @return the length of the paragraph on success, -1 otehrwise.
8640 */
8641EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8642
8643/**
8644 * Return the currently visible range.
8645 *
8646 * @param start the start of the range.
8647 * @param end the end of the range.
8648 * @return EINA_TRUE on success. EINA_FALSE otherwise.
8649 * @since 1.1.0
8650 */
8651Eina_Bool evas_textblock_cursor_visible_range_get(Evas_Textblock_Cursor *start, Evas_Textblock_Cursor *end) EINA_ARG_NONNULL(1, 2);
8652
8653/**
8654 * Return the format nodes in the range between cur1 and cur2.
8655 *
8656 * @param cur1 one side of the range.
8657 * @param cur2 the other side of the range
8658 * @return the foramt nodes in the range. You have to free it.
8659 * @since 1.1.0
8660 */
8661EAPI 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) EINA_PURE;
8662
8663/**
8664 * Return the text in the range between cur1 and cur2
8665 *
8666 * @param cur1 one side of the range.
8667 * @param cur2 the other side of the range
8668 * @param format The form on which to return the text. Markup - in textblock markup. Plain - UTF8.
8669 * @return the text in the range
8670 * @see elm_entry_markup_to_utf8()
8671 */
8672EAPI 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) EINA_PURE;
8673
8674/**
8675 * Return the content of the cursor.
8676 *
8677 * @param cur the cursor
8678 * @return the text in the range
8679 */
8680EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8681
8682
8683/**
8684 * Returns the geometry of the cursor. Depends on the type of cursor requested.
8685 * This should be used instead of char_geometry_get because there are weird
8686 * special cases with BiDi text.
8687 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
8688 * get, except for the case of the last char of a line which depends on the
8689 * paragraph direction.
8690 *
8691 * in '|' cursor mode (i.e a line between two chars) it is very varyable.
8692 * For example consider the following visual string:
8693 * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
8694 * a '|' between the c and the C.
8695 *
8696 * @param cur the cursor.
8697 * @param cx the x of the cursor
8698 * @param cy the y of the cursor
8699 * @param cw the width of the cursor
8700 * @param ch the height of the cursor
8701 * @param dir the direction of the cursor, can be NULL.
8702 * @param ctype the type of the cursor.
8703 * @return line number of the char on success, -1 on error.
8704 */
8705EAPI 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);
8706
8707/**
8708 * Returns the geometry of the char at cur.
8709 *
8710 * @param cur the position of the char.
8711 * @param cx the x of the char.
8712 * @param cy the y of the char.
8713 * @param cw the w of the char.
8714 * @param ch the h of the char.
8715 * @return line number of the char on success, -1 on error.
8716 */
8717EAPI 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);
8718
8719/**
8720 * Returns the geometry of the pen at cur.
8721 *
8722 * @param cur the position of the char.
8723 * @param cpen_x the pen_x of the char.
8724 * @param cy the y of the char.
8725 * @param cadv the adv of the char.
8726 * @param ch the h of the char.
8727 * @return line number of the char on success, -1 on error.
8728 */
8729EAPI 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);
8730
8731/**
8732 * Returns the geometry of the line at cur.
8733 *
8734 * @param cur the position of the line.
8735 * @param cx the x of the line.
8736 * @param cy the y of the line.
8737 * @param cw the width of the line.
8738 * @param ch the height of the line.
8739 * @return line number of the line on success, -1 on error.
8740 */
8741EAPI 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);
8742
8743/**
8744 * Set the position of the cursor according to the X and Y coordinates.
8745 *
8746 * @param cur the cursor to set.
8747 * @param x coord to set by.
8748 * @param y coord to set by.
8749 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
8750 */
8751EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
8752
8753/**
8754 * Set the cursor position according to the y coord.
8755 *
8756 * @param cur the cur to be set.
8757 * @param y the coord to set by.
8758 * @return the line number found, -1 on error.
8759 */
8760EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
8761
8762/**
8763 * Get the geometry of a range.
8764 *
8765 * @param cur1 one side of the range.
8766 * @param cur2 other side of the range.
8767 * @return a list of Rectangles representing the geometry of the range.
8768 */
8769EAPI 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) EINA_PURE;
8770 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);
8771
8772
8773/**
8774 * Checks if the cursor points to the end of the line.
8775 *
8776 * @param cur the cursor to check.
8777 * @return #EINA_TRUE if true, #EINA_FALSE otherwise.
8778 */
8779EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8780
8781
8782/**
8783 * Get the geometry of a line number.
8784 *
8785 * @param obj the object.
8786 * @param line the line number.
8787 * @param cx x coord of the line.
8788 * @param cy y coord of the line.
8789 * @param cw w coord of the line.
8790 * @param ch h coord of the line.
8791 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
8792 */
8793EAPI 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);
8794
8795/**
8796 * Clear the textblock object.
8797 * @note Does *NOT* free the Evas object itself.
8798 *
8799 * @param obj the object to clear.
8800 * @return nothing.
8801 */
8802EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
8803
8804/**
8805 * Get the formatted width and height. This calculates the actual size after restricting
8806 * the textblock to the current size of the object.
8807 * The main difference between this and @ref evas_object_textblock_size_native_get
8808 * is that the "native" function does not wrapping into account
8809 * it just calculates the real width of the object if it was placed on an
8810 * infinite canvas, while this function gives the size after wrapping
8811 * according to the size restrictions of the object.
8812 *
8813 * For example for a textblock containing the text: "You shall not pass!"
8814 * with no margins or padding and assuming a monospace font and a size of
8815 * 7x10 char widths (for simplicity) has a native size of 19x1
8816 * and a formatted size of 5x4.
8817 *
8818 *
8819 * @param obj the Evas object.
8820 * @param w[out] the width of the object.
8821 * @param h[out] the height of the object
8822 * @return Returns no value.
8823 * @see evas_object_textblock_size_native_get
8824 */
8825EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
8826
8827/**
8828 * Get the native width and height. This calculates the actual size without taking account
8829 * the current size of the object.
8830 * The main difference between this and @ref evas_object_textblock_size_formatted_get
8831 * is that the "native" function does not take wrapping into account
8832 * it just calculates the real width of the object if it was placed on an
8833 * infinite canvas, while the "formatted" function gives the size after
8834 * wrapping text according to the size restrictions of the object.
8835 *
8836 * For example for a textblock containing the text: "You shall not pass!"
8837 * with no margins or padding and assuming a monospace font and a size of
8838 * 7x10 char widths (for simplicity) has a native size of 19x1
8839 * and a formatted size of 5x4.
8840 *
8841 * @param obj the Evas object of the textblock
8842 * @param w[out] the width returned
8843 * @param h[out] the height returned
8844 * @return Returns no value.
8845 */
8846EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
8847 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);
8848/**
8849 * @}
8850 */
8851
8852/**
8853 * @defgroup Evas_Line_Group Line Object Functions
8854 *
8855 * Functions used to deal with evas line objects.
8856 *
8857 * @ingroup Evas_Object_Specific
8858 *
8859 * @{
8860 */
8861
8862/**
8863 * Adds a new evas line object to the given evas.
8864 * @param e The given evas.
8865 * @return The new evas line object.
8866 */
8867EAPI Evas_Object *evas_object_line_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8868
8869/**
8870 * Sets the coordinates of the end points of the given evas line object.
8871 * @param obj The given evas line object.
8872 * @param x1 The X coordinate of the first point.
8873 * @param y1 The Y coordinate of the first point.
8874 * @param x2 The X coordinate of the second point.
8875 * @param y2 The Y coordinate of the second point.
8876 */
8877EAPI void evas_object_line_xy_set (Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2);
8878
8879/**
8880 * Retrieves the coordinates of the end points of the given evas line object.
8881 * @param obj The given line object.
8882 * @param x1 Pointer to an integer in which to store the X coordinate of the
8883 * first end point.
8884 * @param y1 Pointer to an integer in which to store the Y coordinate of the
8885 * first end point.
8886 * @param x2 Pointer to an integer in which to store the X coordinate of the
8887 * second end point.
8888 * @param y2 Pointer to an integer in which to store the Y coordinate of the
8889 * second end point.
8890 */
8891EAPI void evas_object_line_xy_get (const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2);
8892/**
8893 * @}
8894 */
8895
8896/**
8897 * @defgroup Evas_Object_Polygon Polygon Object Functions
8898 *
8899 * Functions that operate on evas polygon objects.
8900 *
8901 * Hint: as evas does not provide ellipse, smooth paths or circle, one
8902 * can calculate points and convert these to a polygon.
8903 *
8904 * @ingroup Evas_Object_Specific
8905 *
8906 * @{
8907 */
8908
8909/**
8910 * Adds a new evas polygon object to the given evas.
8911 * @param e The given evas.
8912 * @return A new evas polygon object.
8913 */
8914EAPI Evas_Object *evas_object_polygon_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8915
8916/**
8917 * Adds the given point to the given evas polygon object.
8918 * @param obj The given evas polygon object.
8919 * @param x The X coordinate of the given point.
8920 * @param y The Y coordinate of the given point.
8921 * @ingroup Evas_Polygon_Group
8922 */
8923EAPI void evas_object_polygon_point_add (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
8924
8925/**
8926 * Removes all of the points from the given evas polygon object.
8927 * @param obj The given polygon object.
8928 */
8929EAPI void evas_object_polygon_points_clear (Evas_Object *obj) EINA_ARG_NONNULL(1);
8930/**
8931 * @}
8932 */
8933
8934/**
8935 * @defgroup Evas_Smart_Group Smart Functions
8936 *
8937 * Functions that deal with #Evas_Smart structs, creating definition
8938 * (classes) of objects that will have customized behavior for methods
8939 * like evas_object_move(), evas_object_resize(),
8940 * evas_object_clip_set() and others.
8941 *
8942 * These objects will accept the generic methods defined in @ref
8943 * Evas_Object_Group and the extensions defined in @ref
8944 * Evas_Smart_Object_Group. There are a couple of existent smart
8945 * objects in Evas itself (see @ref Evas_Object_Box, @ref
8946 * Evas_Object_Table and @ref Evas_Smart_Object_Clipped).
8947 *
8948 * See also some @ref Example_Evas_Smart_Objects "examples" of this
8949 * group of functions.
8950 */
8951
8952/**
8953 * @addtogroup Evas_Smart_Group
8954 * @{
8955 */
8956
8957/**
8958 * @def EVAS_SMART_CLASS_VERSION
8959 *
8960 * The version you have to put into the version field in the
8961 * #Evas_Smart_Class struct. Used to safeguard from binaries with old
8962 * smart object intefaces running with newer ones.
8963 *
8964 * @ingroup Evas_Smart_Group
8965 */
8966#define EVAS_SMART_CLASS_VERSION 4
8967/**
8968 * @struct _Evas_Smart_Class
8969 *
8970 * A smart object's @b base class definition
8971 *
8972 * @ingroup Evas_Smart_Group
8973 */
8974struct _Evas_Smart_Class
8975{
8976 const char *name; /**< the name string of the class */
8977 int version;
8978 void (*add) (Evas_Object *o); /**< code to be run when adding object to a canvas */
8979 void (*del) (Evas_Object *o); /**< code to be run when removing object to a canvas */
8980 void (*move) (Evas_Object *o, Evas_Coord x, Evas_Coord y); /**< code to be run when moving object on a canvas */
8981 void (*resize) (Evas_Object *o, Evas_Coord w, Evas_Coord h); /**< code to be run when resizing object on a canvas */
8982 void (*show) (Evas_Object *o); /**< code to be run when showing object on a canvas */
8983 void (*hide) (Evas_Object *o); /**< code to be run when hiding object on a canvas */
8984 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 */
8985 void (*clip_set) (Evas_Object *o, Evas_Object *clip); /**< code to be run when setting clipper of object on a canvas */
8986 void (*clip_unset) (Evas_Object *o); /**< code to be run when unsetting clipper of object on a canvas */
8987 void (*calculate) (Evas_Object *o); /**< code to be run when object has rendering updates on a canvas */
8988 void (*member_add) (Evas_Object *o, Evas_Object *child); /**< code to be run when child member is added to object */
8989 void (*member_del) (Evas_Object *o, Evas_Object *child); /**< code to be run when child member is removed from object */
8990
8991 const Evas_Smart_Class *parent; /**< this class inherits from this parent */
8992 const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, @c NULL terminated */
8993 void *interfaces; /**< to be used in a future near you */
8994 const void *data;
8995};
8996
8997/**
8998 * @struct _Evas_Smart_Cb_Description
8999 *
9000 * Describes a callback issued by a smart object
9001 * (evas_object_smart_callback_call()), as defined in its smart object
9002 * class. This is particularly useful to explain to end users and
9003 * their code (i.e., introspection) what the parameter @c event_info
9004 * will point to.
9005 *
9006 * @ingroup Evas_Smart_Group
9007 */
9008struct _Evas_Smart_Cb_Description
9009{
9010 const char *name; /**< callback name ("changed", for example) */
9011
9012 /**
9013 * @brief Hint on the type of @c event_info parameter's contents on
9014 * a #Evas_Smart_Cb callback.
9015 *
9016 * The type string uses the pattern similar to
9017 * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures,
9018 * but extended to optionally include variable names within
9019 * brackets preceding types. Example:
9020 *
9021 * @li Structure with two integers:
9022 * @c "(ii)"
9023 *
9024 * @li Structure called 'x' with two integers named 'a' and 'b':
9025 * @c "[x]([a]i[b]i)"
9026 *
9027 * @li Array of integers:
9028 * @c "ai"
9029 *
9030 * @li Array called 'x' of struct with two integers:
9031 * @c "[x]a(ii)"
9032 *
9033 * @note This type string is used as a hint and is @b not validated
9034 * or enforced in any way. Implementors should make the best
9035 * use of it to help bindings, documentation and other users
9036 * of introspection features.
9037 */
9038 const char *type;
9039};
9040
9041/**
9042 * @def EVAS_SMART_CLASS_INIT_NULL
9043 * Initializer to zero a whole Evas_Smart_Class structure.
9044 *
9045 * @see EVAS_SMART_CLASS_INIT_VERSION
9046 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
9047 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9048 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9049 * @ingroup Evas_Smart_Group
9050 */
9051#define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
9052
9053/**
9054 * @def EVAS_SMART_CLASS_INIT_VERSION
9055 * Initializer to zero a whole Evas_Smart_Class structure and set version.
9056 *
9057 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
9058 * latest EVAS_SMART_CLASS_VERSION.
9059 *
9060 * @see EVAS_SMART_CLASS_INIT_NULL
9061 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
9062 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9063 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9064 * @ingroup Evas_Smart_Group
9065 */
9066#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}
9067
9068/**
9069 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
9070 * Initializer to zero a whole Evas_Smart_Class structure and set name
9071 * and version.
9072 *
9073 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
9074 * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
9075 *
9076 * It will keep a reference to name field as a "const char *", that is,
9077 * name must be available while the structure is used (hint: static or global!)
9078 * and will not be modified.
9079 *
9080 * @see EVAS_SMART_CLASS_INIT_NULL
9081 * @see EVAS_SMART_CLASS_INIT_VERSION
9082 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9083 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9084 * @ingroup Evas_Smart_Group
9085 */
9086#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}
9087
9088/**
9089 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9090 * Initializer to zero a whole Evas_Smart_Class structure and set name,
9091 * version and parent class.
9092 *
9093 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
9094 * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
9095 * parent class.
9096 *
9097 * It will keep a reference to name field as a "const char *", that is,
9098 * name must be available while the structure is used (hint: static or global!)
9099 * and will not be modified. Similarly, parent reference will be kept.
9100 *
9101 * @see EVAS_SMART_CLASS_INIT_NULL
9102 * @see EVAS_SMART_CLASS_INIT_VERSION
9103 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
9104 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9105 * @ingroup Evas_Smart_Group
9106 */
9107#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}
9108
9109/**
9110 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
9111 * Initializer to zero a whole Evas_Smart_Class structure and set name,
9112 * version, parent class and callbacks definition.
9113 *
9114 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
9115 * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
9116 * class and callbacks at this level.
9117 *
9118 * It will keep a reference to name field as a "const char *", that is,
9119 * name must be available while the structure is used (hint: static or global!)
9120 * and will not be modified. Similarly, parent and callbacks reference
9121 * will be kept.
9122 *
9123 * @see EVAS_SMART_CLASS_INIT_NULL
9124 * @see EVAS_SMART_CLASS_INIT_VERSION
9125 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
9126 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
9127 * @ingroup Evas_Smart_Group
9128 */
9129#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}
9130
9131/**
9132 * @def EVAS_SMART_SUBCLASS_NEW
9133 *
9134 * Convenience macro to subclass a given Evas smart class.
9135 *
9136 * @param smart_name The name used for the smart class. e.g:
9137 * @c "Evas_Object_Box".
9138 * @param prefix Prefix used for all variables and functions defined
9139 * and referenced by this macro.
9140 * @param api_type Type of the structure used as API for the smart
9141 * class. Either #Evas_Smart_Class or something derived from it.
9142 * @param parent_type Type of the parent class API.
9143 * @param parent_func Function that gets the parent class. e.g:
9144 * evas_object_box_smart_class_get().
9145 * @param cb_desc Array of callback descriptions for this smart class.
9146 *
9147 * This macro saves some typing when writing a smart class derived
9148 * from another one. In order to work, the user @b must provide some
9149 * functions adhering to the following guidelines:
9150 * - @<prefix@>_smart_set_user(): the @b internal @c _smart_set
9151 * function (defined by this macro) will call this one, provided by
9152 * the user, after inheriting everything from the parent, which
9153 * should <b>take care of setting the right member functions for
9154 * the class</b>, both overrides and extensions, if any.
9155 * - If this new class should be subclassable as well, a @b public @c
9156 * _smart_set() function is desirable to fill in the class used as
9157 * parent by the children. It's up to the user to provide this
9158 * interface, which will most likely call @<prefix@>_smart_set() to
9159 * get the job done.
9160 *
9161 * After the macro's usage, the following will be defined for use:
9162 * - @<prefix@>_parent_sc: A pointer to the @b parent smart
9163 * class. When calling parent functions from overloaded ones, use
9164 * this global variable.
9165 * - @<prefix@>_smart_class_new(): this function returns the
9166 * #Evas_Smart needed to create smart objects with this class,
9167 * which should be passed to evas_object_smart_add().
9168 *
9169 * @warning @p smart_name has to be a pointer to a globally available
9170 * string! The smart class created here will just have a pointer set
9171 * to that, and all object instances will depend on it for smart class
9172 * name lookup.
9173 *
9174 * @ingroup Evas_Smart_Group
9175 */
9176#define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
9177 static const parent_type * prefix##_parent_sc = NULL; \
9178 static void prefix##_smart_set_user(api_type *api); \
9179 static void prefix##_smart_set(api_type *api) \
9180 { \
9181 Evas_Smart_Class *sc; \
9182 if (!(sc = (Evas_Smart_Class *)api)) \
9183 return; \
9184 if (!prefix##_parent_sc) \
9185 prefix##_parent_sc = parent_func(); \
9186 evas_smart_class_inherit(sc, (const Evas_Smart_Class *)prefix##_parent_sc); \
9187 prefix##_smart_set_user(api); \
9188 } \
9189 static Evas_Smart * prefix##_smart_class_new(void) \
9190 { \
9191 static Evas_Smart *smart = NULL; \
9192 static api_type api; \
9193 if (!smart) \
9194 { \
9195 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
9196 memset(&api, 0, sizeof(api_type)); \
9197 sc->version = EVAS_SMART_CLASS_VERSION; \
9198 sc->name = smart_name; \
9199 sc->callbacks = cb_desc; \
9200 prefix##_smart_set(&api); \
9201 smart = evas_smart_class_new(sc); \
9202 } \
9203 return smart; \
9204 }
9205
9206/**
9207 * @def EVAS_SMART_DATA_ALLOC
9208 *
9209 * Convenience macro to allocate smart data only if needed.
9210 *
9211 * When writing a subclassable smart object, the @c .add() function
9212 * will need to check if the smart private data was already allocated
9213 * by some child object or not. This macro makes it easier to do it.
9214 *
9215 * @note This is an idiom used when one calls the parent's @c. add()
9216 * after the specialized code. Naturally, the parent's base smart data
9217 * has to be contemplated as the specialized one's first member, for
9218 * things to work.
9219 *
9220 * @param o Evas object passed to the @c .add() function
9221 * @param priv_type The type of the data to allocate
9222 *
9223 * @ingroup Evas_Smart_Group
9224 */
9225#define EVAS_SMART_DATA_ALLOC(o, priv_type) \
9226 priv_type *priv; \
9227 priv = evas_object_smart_data_get(o); \
9228 if (!priv) { \
9229 priv = (priv_type *)calloc(1, sizeof(priv_type)); \
9230 if (!priv) return; \
9231 evas_object_smart_data_set(o, priv); \
9232 }
9233
9234
9235/**
9236 * Free an #Evas_Smart struct
9237 *
9238 * @param s the #Evas_Smart struct to free
9239 *
9240 * @warning If this smart handle was created using
9241 * evas_smart_class_new(), the associated #Evas_Smart_Class will not
9242 * be freed.
9243 *
9244 * @note If you're using the #EVAS_SMART_SUBCLASS_NEW schema to create your
9245 * smart object, note that an #Evas_Smart handle will be shared amongst all
9246 * instances of the given smart class, through a static variable.
9247 * Evas will internally count references on #Evas_Smart handles and free them
9248 * when they are not referenced anymore. Thus, this function is of no use
9249 * for Evas users, most probably.
9250 */
9251EAPI void evas_smart_free (Evas_Smart *s) EINA_ARG_NONNULL(1);
9252
9253/**
9254 * Creates a new #Evas_Smart from a given #Evas_Smart_Class struct
9255 *
9256 * @param sc the smart class definition
9257 * @return a new #Evas_Smart pointer
9258 *
9259 * #Evas_Smart handles are necessary to create new @b instances of
9260 * smart objects belonging to the class described by @p sc. That
9261 * handle will contain, besides the smart class interface definition,
9262 * all its smart callbacks infrastructure set, too.
9263 *
9264 * @note If you are willing to subclass a given smart class to
9265 * construct yours, consider using the #EVAS_SMART_SUBCLASS_NEW macro,
9266 * which will make use of this function automatically for you.
9267 */
9268EAPI Evas_Smart *evas_smart_class_new (const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
9269
9270/**
9271 * Get the #Evas_Smart_Class handle of an #Evas_Smart struct
9272 *
9273 * @param s a valid #Evas_Smart pointer
9274 * @return the #Evas_Smart_Class in it
9275 */
9276EAPI const Evas_Smart_Class *evas_smart_class_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9277
9278
9279/**
9280 * @brief Get the data pointer set on an #Evas_Smart struct
9281 *
9282 * @param s a valid #Evas_Smart handle
9283 *
9284 * This data pointer is set as the data field in the #Evas_Smart_Class
9285 * passed in to evas_smart_class_new().
9286 */
9287EAPI void *evas_smart_data_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9288
9289/**
9290 * Get the smart callbacks known by this #Evas_Smart handle's smart
9291 * class hierarchy.
9292 *
9293 * @param s A valid #Evas_Smart handle.
9294 * @param[out] count Returns the number of elements in the returned
9295 * array.
9296 * @return The array with callback descriptions known by this smart
9297 * class, with its size returned in @a count parameter. It
9298 * should not be modified in any way. If no callbacks are
9299 * known, @c NULL is returned. The array is sorted by event
9300 * names and elements refer to the original values given to
9301 * evas_smart_class_new()'s #Evas_Smart_Class::callbacks
9302 * (pointer to them).
9303 *
9304 * This is likely different from
9305 * evas_object_smart_callbacks_descriptions_get() as it will contain
9306 * the callbacks of @b all this class hierarchy sorted, while the
9307 * direct smart class member refers only to that specific class and
9308 * should not include parent's.
9309 *
9310 * If no callbacks are known, this function returns @c NULL.
9311 *
9312 * The array elements and thus their contents will be @b references to
9313 * original values given to evas_smart_class_new() as
9314 * Evas_Smart_Class::callbacks.
9315 *
9316 * The array is sorted by Evas_Smart_Cb_Description::name. The last
9317 * array element is a @c NULL pointer and is not accounted for in @a
9318 * count. Loop iterations can check any of these size indicators.
9319 *
9320 * @note objects may provide per-instance callbacks, use
9321 * evas_object_smart_callbacks_descriptions_get() to get those
9322 * as well.
9323 * @see evas_object_smart_callbacks_descriptions_get()
9324 */
9325EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
9326
9327
9328/**
9329 * Find a callback description for the callback named @a name.
9330 *
9331 * @param s The #Evas_Smart where to search for class registered smart
9332 * event callbacks.
9333 * @param name Name of the desired callback, which must @b not be @c
9334 * NULL. The search has a special case for @a name being the
9335 * same pointer as registered with #Evas_Smart_Cb_Description.
9336 * One can use it to avoid excessive use of strcmp().
9337 * @return A reference to the description if found, or @c NULL, otherwise
9338 *
9339 * @see evas_smart_callbacks_descriptions_get()
9340 */
9341EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2) EINA_PURE;
9342
9343
9344/**
9345 * Sets one class to inherit from the other.
9346 *
9347 * Copy all function pointers, set @c parent to @a parent_sc and copy
9348 * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
9349 * using @a parent_sc_size as reference.
9350 *
9351 * This is recommended instead of a single memcpy() since it will take
9352 * care to not modify @a sc name, version, callbacks and possible
9353 * other members.
9354 *
9355 * @param sc child class.
9356 * @param parent_sc parent class, will provide attributes.
9357 * @param parent_sc_size size of parent_sc structure, child should be at least
9358 * this size. Everything after @c Evas_Smart_Class size is copied
9359 * using regular memcpy().
9360 */
9361EAPI 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);
9362
9363/**
9364 * Get the number of users of the smart instance
9365 *
9366 * @param s The Evas_Smart to get the usage count of
9367 * @return The number of uses of the smart instance
9368 *
9369 * This function tells you how many more uses of the smart instance are in
9370 * existence. This should be used before freeing/clearing any of the
9371 * Evas_Smart_Class that was used to create the smart instance. The smart
9372 * instance will refer to data in the Evas_Smart_Class used to create it and
9373 * thus you cannot remove the original data until all users of it are gone.
9374 * When the usage count goes to 0, you can evas_smart_free() the smart
9375 * instance @p s and remove from memory any of the Evas_Smart_Class that
9376 * was used to create the smart instance, if you desire. Removing it from
9377 * memory without doing this will cause problems (crashes, undefined
9378 * behavior etc. etc.), so either never remove the original
9379 * Evas_Smart_Class data from memory (have it be a constant structure and
9380 * data), or use this API call and be very careful.
9381 */
9382EAPI int evas_smart_usage_get(const Evas_Smart *s);
9383
9384 /**
9385 * @def evas_smart_class_inherit
9386 * Easy to use version of evas_smart_class_inherit_full().
9387 *
9388 * This version will use sizeof(parent_sc), copying everything.
9389 *
9390 * @param sc child class, will have methods copied from @a parent_sc
9391 * @param parent_sc parent class, will provide contents to be copied.
9392 * @return 1 on success, 0 on failure.
9393 * @ingroup Evas_Smart_Group
9394 */
9395#define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, parent_sc, sizeof(*parent_sc))
9396
9397/**
9398 * @}
9399 */
9400
9401/**
9402 * @defgroup Evas_Smart_Object_Group Smart Object Functions
9403 *
9404 * Functions dealing with Evas smart objects (instances).
9405 *
9406 * Smart objects are groupings of primitive Evas objects that behave
9407 * as a cohesive group. For instance, a file manager icon may be a
9408 * smart object composed of an image object, a text label and two
9409 * rectangles that appear behind the image and text when the icon is
9410 * selected. As a smart object, the normal Evas object API could be
9411 * used on the icon object.
9412 *
9413 * Besides that, generally smart objects implement a <b>specific
9414 * API</b>, so that users interect with its own custom features. The
9415 * API takes form of explicit exported functions one may call and
9416 * <b>smart callbacks</b>.
9417 *
9418 * @section Evas_Smart_Object_Group_Callbacks Smart events and callbacks
9419 *
9420 * Smart objects can elect events (smart events, from now on) ocurring
9421 * inside of them to be reported back to their users via callback
9422 * functions (smart callbacks). This way, you can extend Evas' own
9423 * object events. They are defined by an <b>event string</b>, which
9424 * identifies them uniquely. There's also a function prototype
9425 * definition for the callback functions: #Evas_Smart_Cb.
9426 *
9427 * When defining an #Evas_Smart_Class, smart object implementors are
9428 * strongly encorauged to properly set the Evas_Smart_Class::callbacks
9429 * callbacks description array, so that the users of the smart object
9430 * can have introspection on its events API <b>at run time</b>.
9431 *
9432 * See some @ref Example_Evas_Smart_Objects "examples" of this group
9433 * of functions.
9434 *
9435 * @see @ref Evas_Smart_Group for class definitions.
9436 */
9437
9438/**
9439 * @addtogroup Evas_Smart_Object_Group
9440 * @{
9441 */
9442
9443/**
9444 * Instantiates a new smart object described by @p s.
9445 *
9446 * @param e the canvas on which to add the object
9447 * @param s the #Evas_Smart describing the smart object
9448 * @return a new #Evas_Object handle
9449 *
9450 * This is the function one should use when defining the public
9451 * function @b adding an instance of the new smart object to a given
9452 * canvas. It will take care of setting all of its internals to work
9453 * as they should, if the user set things properly, as seem on the
9454 * #EVAS_SMART_SUBCLASS_NEW, for example.
9455 *
9456 * @ingroup Evas_Smart_Object_Group
9457 */
9458EAPI Evas_Object *evas_object_smart_add (Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC;
9459
9460/**
9461 * Set an Evas object as a member of a given smart object.
9462 *
9463 * @param obj The member object
9464 * @param smart_obj The smart object
9465 *
9466 * Members will automatically be stacked and layered together with the
9467 * smart object. The various stacking functions will operate on
9468 * members relative to the other members instead of the entire canvas,
9469 * since they now live on an exclusive layer (see
9470 * evas_object_stack_above(), for more details).
9471 *
9472 * Any @p smart_obj object's specific implementation of the @c
9473 * member_add() smart function will take place too, naturally.
9474 *
9475 * @see evas_object_smart_member_del()
9476 * @see evas_object_smart_members_get()
9477 *
9478 * @ingroup Evas_Smart_Object_Group
9479 */
9480EAPI void evas_object_smart_member_add (Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2);
9481
9482/**
9483 * Removes a member object from a given smart object.
9484 *
9485 * @param obj the member object
9486 * @ingroup Evas_Smart_Object_Group
9487 *
9488 * This removes a member object from a smart object, if it was added
9489 * to any. The object will still be on the canvas, but no longer
9490 * associated with whichever smart object it was associated with.
9491 *
9492 * @see evas_object_smart_member_add() for more details
9493 * @see evas_object_smart_members_get()
9494 */
9495EAPI void evas_object_smart_member_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
9496
9497/**
9498 * Retrieves the list of the member objects of a given Evas smart
9499 * object
9500 *
9501 * @param obj the smart object to get members from
9502 * @return Returns the list of the member objects of @p obj.
9503 *
9504 * The returned list should be freed with @c eina_list_free() when you
9505 * no longer need it.
9506 *
9507 * @see evas_object_smart_member_add()
9508 * @see evas_object_smart_member_del()
9509*/
9510EAPI Eina_List *evas_object_smart_members_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9511
9512/**
9513 * Gets the parent smart object of a given Evas object, if it has one.
9514 *
9515 * @param obj the Evas object you want to get the parent smart object
9516 * from
9517 * @return Returns the parent smart object of @a obj or @c NULL, if @a
9518 * obj is not a smart member of any
9519 *
9520 * @ingroup Evas_Smart_Object_Group
9521 */
9522EAPI Evas_Object *evas_object_smart_parent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9523
9524/**
9525 * Checks whether a given smart object or any of its smart object
9526 * parents is of a given smart class.
9527 *
9528 * @param obj An Evas smart object to check the type of
9529 * @param type The @b name (type) of the smart class to check for
9530 * @return @c EINA_TRUE, if @a obj or any of its parents is of type @a
9531 * type, @c EINA_FALSE otherwise
9532 *
9533 * If @p obj is not a smart object, this call will fail
9534 * immediately. Otherwise, make sure evas_smart_class_inherit() or its
9535 * sibling functions were used correctly when creating the smart
9536 * object's class, so it has a valid @b parent smart class pointer
9537 * set.
9538 *
9539 * The checks use smart classes names and <b>string
9540 * comparison</b>. There is a version of this same check using
9541 * <b>pointer comparison</b>, since a smart class' name is a single
9542 * string in Evas.
9543 *
9544 * @see evas_object_smart_type_check_ptr()
9545 * @see #EVAS_SMART_SUBCLASS_NEW
9546 *
9547 * @ingroup Evas_Smart_Object_Group
9548 */
9549EAPI Eina_Bool evas_object_smart_type_check (const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
9550
9551/**
9552 * Checks whether a given smart object or any of its smart object
9553 * parents is of a given smart class, <b>using pointer comparison</b>.
9554 *
9555 * @param obj An Evas smart object to check the type of
9556 * @param type The type (name string) to check for. Must be the name
9557 * @return @c EINA_TRUE, if @a obj or any of its parents is of type @a
9558 * type, @c EINA_FALSE otherwise
9559 *
9560 * @see evas_object_smart_type_check() for more details
9561 *
9562 * @ingroup Evas_Smart_Object_Group
9563 */
9564EAPI Eina_Bool evas_object_smart_type_check_ptr (const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
9565
9566/**
9567 * Get the #Evas_Smart from which @p obj smart object was created.
9568 *
9569 * @param obj a smart object
9570 * @return the #Evas_Smart handle or @c NULL, on errors
9571 *
9572 * @ingroup Evas_Smart_Object_Group
9573 */
9574EAPI Evas_Smart *evas_object_smart_smart_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9575
9576/**
9577 * Retrieve user data stored on a given smart object.
9578 *
9579 * @param obj The smart object's handle
9580 * @return A pointer to data stored using
9581 * evas_object_smart_data_set(), or @c NULL, if none has been
9582 * set.
9583 *
9584 * @see evas_object_smart_data_set()
9585 *
9586 * @ingroup Evas_Smart_Object_Group
9587 */
9588EAPI void *evas_object_smart_data_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9589
9590/**
9591 * Store a pointer to user data for a given smart object.
9592 *
9593 * @param obj The smart object's handle
9594 * @param data A pointer to user data
9595 *
9596 * This data is stored @b independently of the one set by
9597 * evas_object_data_set(), naturally.
9598 *
9599 * @see evas_object_smart_data_get()
9600 *
9601 * @ingroup Evas_Smart_Object_Group
9602 */
9603EAPI void evas_object_smart_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
9604
9605/**
9606 * Add (register) a callback function to the smart event specified by
9607 * @p event on the smart object @p obj.
9608 *
9609 * @param obj a smart object
9610 * @param event the event's name string
9611 * @param func the callback function
9612 * @param data user data to be passed to the callback function
9613 *
9614 * Smart callbacks look very similar to Evas callbacks, but are
9615 * implemented as smart object's custom ones.
9616 *
9617 * This function adds a function callback to an smart object when the
9618 * event named @p event occurs in it. The function is @p func.
9619 *
9620 * In the event of a memory allocation error during addition of the
9621 * callback to the object, evas_alloc_error() should be used to
9622 * determine the nature of the error, if any, and the program should
9623 * sensibly try and recover.
9624 *
9625 * A smart callback function must have the ::Evas_Smart_Cb prototype
9626 * definition. The first parameter (@p data) in this definition will
9627 * have the same value passed to evas_object_smart_callback_add() as
9628 * the @p data parameter, at runtime. The second parameter @p obj is a
9629 * handle to the object on which the event occurred. The third
9630 * parameter, @p event_info, is a pointer to data which is totally
9631 * dependent on the smart object's implementation and semantic for the
9632 * given event.
9633 *
9634 * There is an infrastructure for introspection on smart objects'
9635 * events (see evas_smart_callbacks_descriptions_get()), but no
9636 * internal smart objects on Evas implement them yet.
9637 *
9638 * @see @ref Evas_Smart_Object_Group_Callbacks for more details.
9639 *
9640 * @see evas_object_smart_callback_del()
9641 * @ingroup Evas_Smart_Object_Group
9642 */
9643EAPI 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);
9644
9645/**
9646 * Add (register) a callback function to the smart event specified by
9647 * @p event on the smart object @p obj. Except for the priority field,
9648 * it's exactly the same as @ref evas_object_smart_callback_add
9649 *
9650 * @param obj a smart object
9651 * @param event the event's name string
9652 * @param priority The priority of the callback, lower values called first.
9653 * @param func the callback function
9654 * @param data user data to be passed to the callback function
9655 *
9656 * @see evas_object_smart_callback_add
9657 * @since 1.1.0
9658 * @ingroup Evas_Smart_Object_Group
9659 */
9660EAPI void evas_object_smart_callback_priority_add(Evas_Object *obj, const char *event, Evas_Callback_Priority priority, Evas_Smart_Cb func, const void *data);
9661
9662/**
9663 * Delete (unregister) a callback function from the smart event
9664 * specified by @p event on the smart object @p obj.
9665 *
9666 * @param obj a smart object
9667 * @param event the event's name string
9668 * @param func the callback function
9669 * @return the data pointer
9670 *
9671 * This function removes <b>the first</b> added smart callback on the
9672 * object @p obj matching the event name @p event and the registered
9673 * function pointer @p func. If the removal is successful it will also
9674 * return the data pointer that was passed to
9675 * evas_object_smart_callback_add() (that will be the same as the
9676 * parameter) when the callback(s) was(were) added to the canvas. If
9677 * not successful @c NULL will be returned.
9678 *
9679 * @see evas_object_smart_callback_add() for more details.
9680 *
9681 * @ingroup Evas_Smart_Object_Group
9682 */
9683EAPI void *evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3);
9684
9685/**
9686 * Call a given smart callback on the smart object @p obj.
9687 *
9688 * @param obj the smart object
9689 * @param event the event's name string
9690 * @param event_info pointer to an event specific struct or information to
9691 * pass to the callback functions registered on this smart event
9692 *
9693 * This should be called @b internally, from the smart object's own
9694 * code, when some specific event has occurred and the implementor
9695 * wants is to pertain to the object's events API (see @ref
9696 * Evas_Smart_Object_Group_Callbacks). The documentation for the smart
9697 * object should include a list of possible events and what type of @p
9698 * event_info to expect for each of them. Also, when defining an
9699 * #Evas_Smart_Class, smart object implementors are strongly
9700 * encorauged to properly set the Evas_Smart_Class::callbacks
9701 * callbacks description array, so that the users of the smart object
9702 * can have introspection on its events API <b>at run time</b>.
9703 *
9704 * @ingroup Evas_Smart_Object_Group
9705 */
9706EAPI void evas_object_smart_callback_call (Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2);
9707
9708
9709/**
9710 * Set an smart object @b instance's smart callbacks descriptions.
9711 *
9712 * @param obj A smart object
9713 * @param descriptions @c NULL terminated array with
9714 * #Evas_Smart_Cb_Description descriptions. Array elements won't be
9715 * modified at run time, but references to them and their contents
9716 * will be made, so this array should be kept alive during the whole
9717 * object's lifetime.
9718 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
9719 *
9720 * These descriptions are hints to be used by introspection and are
9721 * not enforced in any way.
9722 *
9723 * It will not be checked if instance callbacks descriptions have the
9724 * same name as respective possibly registered in the smart object
9725 * @b class. Both are kept in different arrays and users of
9726 * evas_object_smart_callbacks_descriptions_get() should handle this
9727 * case as they wish.
9728 *
9729 * @note Becase @p descriptions must be @c NULL terminated, and
9730 * because a @c NULL name makes little sense, too,
9731 * Evas_Smart_Cb_Description::name must @b not be @c NULL.
9732 *
9733 * @note While instance callbacks descriptions are possible, they are
9734 * @b not recommended. Use @b class callbacks descriptions
9735 * instead as they make you smart object user's life simpler and
9736 * will use less memory, as descriptions and arrays will be
9737 * shared among all instances.
9738 *
9739 * @ingroup Evas_Smart_Object_Group
9740 */
9741EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1);
9742
9743/**
9744 * Retrieve an smart object's know smart callback descriptions (both
9745 * instance and class ones).
9746 *
9747 * @param obj The smart object to get callback descriptions from.
9748 * @param class_descriptions Where to store class callbacks
9749 * descriptions array, if any is known. If no descriptions are
9750 * known, @c NULL is returned
9751 * @param class_count Returns how many class callbacks descriptions
9752 * are known.
9753 * @param instance_descriptions Where to store instance callbacks
9754 * descriptions array, if any is known. If no descriptions are
9755 * known, @c NULL is returned.
9756 * @param instance_count Returns how many instance callbacks
9757 * descriptions are known.
9758 *
9759 * This call searchs for registered callback descriptions for both
9760 * instance and class of the given smart object. These arrays will be
9761 * sorted by Evas_Smart_Cb_Description::name and also @c NULL
9762 * terminated, so both @a class_count and @a instance_count can be
9763 * ignored, if the caller wishes so. The terminator @c NULL is not
9764 * counted in these values.
9765 *
9766 * @note If just class descriptions are of interest, try
9767 * evas_smart_callbacks_descriptions_get() instead.
9768 *
9769 * @note Use @c NULL pointers on the descriptions/counters you're not
9770 * interested in: they'll be ignored by the function.
9771 *
9772 * @see evas_smart_callbacks_descriptions_get()
9773 *
9774 * @ingroup Evas_Smart_Object_Group
9775 */
9776EAPI 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);
9777
9778/**
9779 * Find callback description for callback called @a name.
9780 *
9781 * @param obj the smart object.
9782 * @param name name of desired callback, must @b not be @c NULL. The
9783 * search have a special case for @a name being the same
9784 * pointer as registered with Evas_Smart_Cb_Description, one
9785 * can use it to avoid excessive use of strcmp().
9786 * @param class_description pointer to return class description or @c
9787 * NULL if not found. If parameter is @c NULL, no search will
9788 * be done on class descriptions.
9789 * @param instance_description pointer to return instance description
9790 * or @c NULL if not found. If parameter is @c NULL, no search
9791 * will be done on instance descriptions.
9792 * @return reference to description if found, @c NULL if not found.
9793 */
9794EAPI 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);
9795
9796
9797/**
9798 * Mark smart object as changed, dirty.
9799 *
9800 * @param obj The given Evas smart object
9801 *
9802 * This will flag the given object as needing recalculation,
9803 * forcefully. As an effect, on the next rendering cycle it's @b
9804 * calculate() (see #Evas_Smart_Class) smart function will be called.
9805 *
9806 * @see evas_object_smart_need_recalculate_set().
9807 * @see evas_object_smart_calculate().
9808 *
9809 * @ingroup Evas_Smart_Object_Group
9810 */
9811EAPI void evas_object_smart_changed (Evas_Object *obj) EINA_ARG_NONNULL(1);
9812
9813/**
9814 * Set or unset the flag signalling that a given smart object needs to
9815 * get recalculated.
9816 *
9817 * @param obj the smart object
9818 * @param value whether one wants to set (@c EINA_TRUE) or to unset
9819 * (@c EINA_FALSE) the flag.
9820 *
9821 * If this flag is set, then the @c calculate() smart function of @p
9822 * obj will be called, if one is provided, during rendering phase of
9823 * Evas (see evas_render()), after which this flag will be
9824 * automatically unset.
9825 *
9826 * If that smart function is not provided for the given object, this
9827 * flag will be left unchanged.
9828 *
9829 * @note just setting this flag will not make the canvas' whole scene
9830 * dirty, by itself, and evas_render() will have no effect. To
9831 * force that, use evas_object_smart_changed(), that will also
9832 * automatically call this function automatically, with @c
9833 * EINA_TRUE as parameter.
9834 *
9835 * @see evas_object_smart_need_recalculate_get()
9836 * @see evas_object_smart_calculate()
9837 * @see evas_smart_objects_calculate()
9838 *
9839 * @ingroup Evas_Smart_Object_Group
9840 */
9841EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
9842
9843/**
9844 * Get the value of the flag signalling that a given smart object needs to
9845 * get recalculated.
9846 *
9847 * @param obj the smart object
9848 * @return if flag is set or not.
9849 *
9850 * @note this flag will be unset during the rendering phase, when the
9851 * @c calculate() smart function is called, if one is provided.
9852 * If it's not provided, then the flag will be left unchanged
9853 * after the rendering phase.
9854 *
9855 * @see evas_object_smart_need_recalculate_set(), for more details
9856 *
9857 * @ingroup Evas_Smart_Object_Group
9858 */
9859EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9860
9861/**
9862 * Call the @b calculate() smart function immediataly on a given smart
9863 * object.
9864 *
9865 * @param obj the smart object's handle
9866 *
9867 * This will force immediate calculations (see #Evas_Smart_Class)
9868 * needed for renderization of this object and, besides, unset the
9869 * flag on it telling it needs recalculation for the next rendering
9870 * phase.
9871 *
9872 * @see evas_object_smart_need_recalculate_set()
9873 *
9874 * @ingroup Evas_Smart_Object_Group
9875 */
9876EAPI void evas_object_smart_calculate (Evas_Object *obj) EINA_ARG_NONNULL(1);
9877
9878/**
9879 * Call user-provided @c calculate() smart functions and unset the
9880 * flag signalling that the object needs to get recalculated to @b all
9881 * smart objects in the canvas.
9882 *
9883 * @param e The canvas to calculate all smart objects in
9884 *
9885 * @see evas_object_smart_need_recalculate_set()
9886 *
9887 * @ingroup Evas_Smart_Object_Group
9888 */
9889EAPI void evas_smart_objects_calculate (Evas *e);
9890
9891/**
9892 * This gets the internal counter that counts the number of smart calculations
9893 *
9894 * @param e The canvas to get the calculate counter from
9895 *
9896 * Whenever evas performs smart object calculations on the whole canvas
9897 * it increments a counter by 1. This is the smart object calculate counter
9898 * that this function returns the value of. It starts at the value of 0 and
9899 * will increase (and eventually wrap around to negative values and so on) by
9900 * 1 every time objects are calculated. You can use this counter to ensure
9901 * you dont re-do calculations withint the same calculation generation/run
9902 * if the calculations maybe cause self-feeding effects.
9903 *
9904 * @ingroup Evas_Smart_Object_Group
9905 * @since 1.1
9906 */
9907EAPI int evas_smart_objects_calculate_count_get (const Evas *e);
9908
9909/**
9910 * Moves all children objects of a given smart object relative to a
9911 * given offset.
9912 *
9913 * @param obj the smart object.
9914 * @param dx horizontal offset (delta).
9915 * @param dy vertical offset (delta).
9916 *
9917 * This will make each of @p obj object's children to move, from where
9918 * they before, with those delta values (offsets) on both directions.
9919 *
9920 * @note This is most useful on custom smart @c move() functions.
9921 *
9922 * @note Clipped smart objects already make use of this function on
9923 * their @c move() smart function definition.
9924 */
9925EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1);
9926
9927/**
9928 * @}
9929 */
9930
9931/**
9932 * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
9933 *
9934 * Clipped smart object is a base to construct other smart objects
9935 * based on the concept of having an internal clipper that is applied
9936 * to all children objects. This clipper will control the visibility,
9937 * clipping and color of sibling objects (remember that the clipping
9938 * is recursive, and clipper color modulates the color of its
9939 * clippees). By default, this base will also move children relatively
9940 * to the parent, and delete them when parent is deleted. In other
9941 * words, it is the base for simple object grouping.
9942 *
9943 * See some @ref Example_Evas_Smart_Objects "examples" of this group
9944 * of functions.
9945 *
9946 * @see evas_object_smart_clipped_smart_set()
9947 *
9948 * @ingroup Evas_Smart_Object_Group
9949 */
9950
9951/**
9952 * @addtogroup Evas_Smart_Object_Clipped
9953 * @{
9954 */
9955
9956/**
9957 * Every subclass should provide this at the beginning of their own
9958 * data set with evas_object_smart_data_set().
9959 */
9960 typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
9961 struct _Evas_Object_Smart_Clipped_Data
9962 {
9963 Evas_Object *clipper;
9964 Evas *evas;
9965 };
9966
9967
9968/**
9969 * Get the clipper object for the given clipped smart object.
9970 *
9971 * @param obj the clipped smart object to retrieve associated clipper
9972 * from.
9973 * @return the clipper object.
9974 *
9975 * Use this function if you want to change any of this clipper's
9976 * properties, like colors.
9977 *
9978 * @see evas_object_smart_clipped_smart_add()
9979 */
9980EAPI Evas_Object *evas_object_smart_clipped_clipper_get (Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9981
9982/**
9983 * Set a given smart class' callbacks so it implements the <b>clipped smart
9984 * object"</b>'s interface.
9985 *
9986 * @param sc The smart class handle to operate on
9987 *
9988 * This call will assign all the required methods of the @p sc
9989 * #Evas_Smart_Class instance to the implementations set for clipped
9990 * smart objects. If one wants to "subclass" it, call this function
9991 * and then override desired values. If one wants to call any original
9992 * method, save it somewhere. Example:
9993 *
9994 * @code
9995 * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
9996 *
9997 * static void my_class_smart_add(Evas_Object *o)
9998 * {
9999 * parent_sc.add(o);
10000 * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
10001 * 255, 0, 0, 255);
10002 * }
10003 *
10004 * Evas_Smart_Class *my_class_new(void)
10005 * {
10006 * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
10007 * if (!parent_sc.name)
10008 * {
10009 * evas_object_smart_clipped_smart_set(&sc);
10010 * parent_sc = sc;
10011 * sc.add = my_class_smart_add;
10012 * }
10013 * return &sc;
10014 * }
10015 * @endcode
10016 *
10017 * Default behavior for each of #Evas_Smart_Class functions on a
10018 * clipped smart object are:
10019 * - @c add: creates a hidden clipper with "infinite" size, to clip
10020 * any incoming members;
10021 * - @c del: delete all children objects;
10022 * - @c move: move all objects relative relatively;
10023 * - @c resize: <b>not defined</b>;
10024 * - @c show: if there are children objects, show clipper;
10025 * - @c hide: hides clipper;
10026 * - @c color_set: set the color of clipper;
10027 * - @c clip_set: set clipper of clipper;
10028 * - @c clip_unset: unset the clipper of clipper;
10029 *
10030 * @note There are other means of assigning parent smart classes to
10031 * child ones, like the #EVAS_SMART_SUBCLASS_NEW macro or the
10032 * evas_smart_class_inherit_full() function.
10033 */
10034EAPI void evas_object_smart_clipped_smart_set (Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
10035
10036/**
10037 * Get a pointer to the <b>clipped smart object's</b> class, to use
10038 * for proper inheritance
10039 *
10040 * @see #Evas_Smart_Object_Clipped for more information on this smart
10041 * class
10042 */
10043EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get (void) EINA_CONST;
10044
10045/**
10046 * @}
10047 */
10048
10049/**
10050 * @defgroup Evas_Object_Box Box Smart Object
10051 *
10052 * A box is a convenience smart object that packs children inside it
10053 * in @b sequence, using a layouting function specified by the
10054 * user. There are a couple of pre-made layouting functions <b>built-in
10055 * in Evas</b>, all of them using children size hints to define their
10056 * size and alignment inside their cell space.
10057 *
10058 * Examples on this smart object's usage:
10059 * - @ref Example_Evas_Box
10060 * - @ref Example_Evas_Size_Hints
10061 *
10062 * @see @ref Evas_Object_Group_Size_Hints
10063 *
10064 * @ingroup Evas_Smart_Object_Group
10065 */
10066
10067/**
10068 * @addtogroup Evas_Object_Box
10069 * @{
10070 */
10071
10072/**
10073 * @typedef Evas_Object_Box_Api
10074 *
10075 * Smart class extension, providing extra box object requirements.
10076 *
10077 * @ingroup Evas_Object_Box
10078 */
10079 typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
10080
10081/**
10082 * @typedef Evas_Object_Box_Data
10083 *
10084 * Smart object instance data, providing box object requirements.
10085 *
10086 * @ingroup Evas_Object_Box
10087 */
10088 typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
10089
10090/**
10091 * @typedef Evas_Object_Box_Option
10092 *
10093 * The base structure for a box option. Box options are a way of
10094 * extending box items properties, which will be taken into account
10095 * for layouting decisions. The box layouting functions provided by
10096 * Evas will only rely on objects' canonical size hints to layout
10097 * them, so the basic box option has @b no (custom) property set.
10098 *
10099 * Users creating their own layouts, but not depending on extra child
10100 * items' properties, would be fine just using
10101 * evas_object_box_layout_set(). But if one desires a layout depending
10102 * on extra child properties, he/she has to @b subclass the box smart
10103 * object. Thus, by using evas_object_box_smart_class_get() and
10104 * evas_object_box_smart_set(), the @c option_new() and @c
10105 * option_free() smart class functions should be properly
10106 * redefined/extended.
10107 *
10108 * Object properties are bound to an integer identifier and must have
10109 * a name string. Their values are open to any data. See the API on
10110 * option properties for more details.
10111 *
10112 * @ingroup Evas_Object_Box
10113 */
10114 typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
10115
10116/**
10117 * @typedef Evas_Object_Box_Layout
10118 *
10119 * Function signature for an Evas box object layouting routine. By
10120 * @a o it will be passed the box object in question, by @a priv it will
10121 * be passed the box's internal data and, by @a user_data, it will be
10122 * passed any custom data one could have set to a given box layouting
10123 * function, with evas_object_box_layout_set().
10124 *
10125 * @ingroup Evas_Object_Box
10126 */
10127 typedef void (*Evas_Object_Box_Layout) (Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
10128
10129/**
10130 * @def EVAS_OBJECT_BOX_API_VERSION
10131 *
10132 * Current version for Evas box object smart class, a value which goes
10133 * to _Evas_Object_Box_Api::version.
10134 *
10135 * @ingroup Evas_Object_Box
10136 */
10137#define EVAS_OBJECT_BOX_API_VERSION 1
10138
10139/**
10140 * @struct _Evas_Object_Box_Api
10141 *
10142 * This structure should be used by any smart class inheriting from
10143 * the box's one, to provide custom box behavior which could not be
10144 * achieved only by providing a layout function, with
10145 * evas_object_box_layout_set().
10146 *
10147 * @extends Evas_Smart_Class
10148 * @ingroup Evas_Object_Box
10149 */
10150 struct _Evas_Object_Box_Api
10151 {
10152 Evas_Smart_Class base; /**< Base smart class struct, need for all smart objects */
10153 int version; /**< Version of this smart class definition */
10154 Evas_Object_Box_Option *(*append) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child); /**< Smart function to append child elements in boxes */
10155 Evas_Object_Box_Option *(*prepend) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child); /**< Smart function to prepend child elements in boxes */
10156 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 */
10157 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 */
10158 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 positon on boxes */
10159 Evas_Object *(*remove) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child); /**< Smart function to remove a child element from boxes */
10160 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 */
10161 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 */
10162 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 */
10163 const char *(*property_name_get)(Evas_Object *o, int property); /**< Smart function to get the name of a custom property of box children */
10164 int (*property_id_get) (Evas_Object *o, const char *name); /**< Smart function to get the numerical ID of a custom property of box children */
10165 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 */
10166 void (*option_free) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt); /**< Smart function to delete a box option struct */
10167 };
10168
10169/**
10170 * @def EVAS_OBJECT_BOX_API_INIT
10171 *
10172 * Initializer for a whole #Evas_Object_Box_Api structure, with
10173 * @c NULL values on its specific fields.
10174 *
10175 * @param smart_class_init initializer to use for the "base" field
10176 * (#Evas_Smart_Class).
10177 *
10178 * @see EVAS_SMART_CLASS_INIT_NULL
10179 * @see EVAS_SMART_CLASS_INIT_VERSION
10180 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
10181 * @see EVAS_OBJECT_BOX_API_INIT_NULL
10182 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
10183 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
10184 * @ingroup Evas_Object_Box
10185 */
10186#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}
10187
10188/**
10189 * @def EVAS_OBJECT_BOX_API_INIT_NULL
10190 *
10191 * Initializer to zero out a whole #Evas_Object_Box_Api structure.
10192 *
10193 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
10194 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
10195 * @see EVAS_OBJECT_BOX_API_INIT
10196 * @ingroup Evas_Object_Box
10197 */
10198#define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
10199
10200/**
10201 * @def EVAS_OBJECT_BOX_API_INIT_VERSION
10202 *
10203 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
10204 * set a specific version on it.
10205 *
10206 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will set
10207 * the version field of #Evas_Smart_Class (base field) to the latest
10208 * #EVAS_SMART_CLASS_VERSION.
10209 *
10210 * @see EVAS_OBJECT_BOX_API_INIT_NULL
10211 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
10212 * @see EVAS_OBJECT_BOX_API_INIT
10213 * @ingroup Evas_Object_Box
10214 */
10215#define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
10216
10217/**
10218 * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
10219 *
10220 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
10221 * set its name and version.
10222 *
10223 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will also
10224 * set the version field of #Evas_Smart_Class (base field) to the
10225 * latest #EVAS_SMART_CLASS_VERSION and name it to the specific value.
10226 *
10227 * It will keep a reference to the name field as a <c>"const char *"</c>,
10228 * i.e., the name must be available while the structure is
10229 * used (hint: static or global variable!) and must not be modified.
10230 *
10231 * @see EVAS_OBJECT_BOX_API_INIT_NULL
10232 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
10233 * @see EVAS_OBJECT_BOX_API_INIT
10234 * @ingroup Evas_Object_Box
10235 */
10236#define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
10237
10238/**
10239 * @struct _Evas_Object_Box_Data
10240 *
10241 * This structure augments clipped smart object's instance data,
10242 * providing extra members required by generic box implementation. If
10243 * a subclass inherits from #Evas_Object_Box_Api, then it may augment
10244 * #Evas_Object_Box_Data to fit its own needs.
10245 *
10246 * @extends Evas_Object_Smart_Clipped_Data
10247 * @ingroup Evas_Object_Box
10248 */
10249 struct _Evas_Object_Box_Data
10250 {
10251 Evas_Object_Smart_Clipped_Data base;
10252 const Evas_Object_Box_Api *api;
10253 struct {
10254 double h, v;
10255 } align;
10256 struct {
10257 Evas_Coord h, v;
10258 } pad;
10259 Eina_List *children;
10260 struct {
10261 Evas_Object_Box_Layout cb;
10262 void *data;
10263 void (*free_data)(void *data);
10264 } layout;
10265 Eina_Bool layouting : 1;
10266 Eina_Bool children_changed : 1;
10267 };
10268
10269 struct _Evas_Object_Box_Option
10270 {
10271 Evas_Object *obj; /**< Pointer to the box child object, itself */
10272 Eina_Bool max_reached:1;
10273 Eina_Bool min_reached:1;
10274 Evas_Coord alloc_size;
10275 }; /**< #Evas_Object_Box_Option struct fields */
10276
10277/**
10278 * Set the default box @a api struct (Evas_Object_Box_Api)
10279 * with the default values. May be used to extend that API.
10280 *
10281 * @param api The box API struct to set back, most probably with
10282 * overriden fields (on class extensions scenarios)
10283 */
10284EAPI void evas_object_box_smart_set (Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
10285
10286/**
10287 * Get the Evas box smart class, for inheritance purposes.
10288 *
10289 * @return the (canonical) Evas box smart class.
10290 *
10291 * The returned value is @b not to be modified, just use it as your
10292 * parent class.
10293 */
10294EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get (void) EINA_CONST;
10295
10296/**
10297 * Set a new layouting function to a given box object
10298 *
10299 * @param o The box object to operate on.
10300 * @param cb The new layout function to set on @p o.
10301 * @param data Data pointer to be passed to @p cb.
10302 * @param free_data Function to free @p data, if need be.
10303 *
10304 * A box layout function affects how a box object displays child
10305 * elements within its area. The list of pre-defined box layouts
10306 * available in Evas is:
10307 * - evas_object_box_layout_horizontal()
10308 * - evas_object_box_layout_vertical()
10309 * - evas_object_box_layout_homogeneous_horizontal()
10310 * - evas_object_box_layout_homogeneous_vertical()
10311 * - evas_object_box_layout_homogeneous_max_size_horizontal()
10312 * - evas_object_box_layout_homogeneous_max_size_vertical()
10313 * - evas_object_box_layout_flow_horizontal()
10314 * - evas_object_box_layout_flow_vertical()
10315 * - evas_object_box_layout_stack()
10316 *
10317 * Refer to each of their documentation texts for details on them.
10318 *
10319 * @note A box layouting function will be triggered by the @c
10320 * 'calculate' smart callback of the box's smart class.
10321 */
10322EAPI 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);
10323
10324/**
10325 * Add a new box object on the provided canvas.
10326 *
10327 * @param evas The canvas to create the box object on.
10328 * @return @c NULL on error, a pointer to a new box object on
10329 * success.
10330 *
10331 * After instantiation, if a box object hasn't its layout function
10332 * set, via evas_object_box_layout_set(), it will have it by default
10333 * set to evas_object_box_layout_horizontal(). The remaining
10334 * properties of the box must be set/retrieved via
10335 * <c>evas_object_box_{h,v}_{align,padding}_{get,set)()</c>.
10336 */
10337EAPI Evas_Object *evas_object_box_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
10338
10339/**
10340 * Add a new box as a @b child of a given smart object.
10341 *
10342 * @param parent The parent smart object to put the new box in.
10343 * @return @c NULL on error, a pointer to a new box object on
10344 * success.
10345 *
10346 * This is a helper function that has the same effect of putting a new
10347 * box object into @p parent by use of evas_object_smart_member_add().
10348 *
10349 * @see evas_object_box_add()
10350 */
10351EAPI Evas_Object *evas_object_box_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
10352
10353/**
10354 * Layout function which sets the box @a o to a (basic) horizontal box
10355 *
10356 * @param o The box object in question
10357 * @param priv The smart data of the @p o
10358 * @param data The data pointer passed on
10359 * evas_object_box_layout_set(), if any
10360 *
10361 * In this layout, the box object's overall behavior is controlled by
10362 * its padding/alignment properties, which are set by the
10363 * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
10364 * functions. The size hints of the elements in the box -- set by the
10365 * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
10366 * -- also control the way this function works.
10367 *
10368 * \par Box's properties:
10369 * @c align_h controls the horizontal alignment of the child objects
10370 * relative to the containing box. When set to @c 0.0, children are
10371 * aligned to the left. A value of @c 1.0 makes them aligned to the
10372 * right border. Values in between align them proportionally. Note
10373 * that if the size required by the children, which is given by their
10374 * widths and the @c padding_h property of the box, is bigger than the
10375 * their container's width, the children will be displayed out of the
10376 * box's bounds. A negative value of @c align_h makes the box to
10377 * @b justify its children. The padding between them, in this case, is
10378 * corrected so that the leftmost one touches the left border and the
10379 * rightmost one touches the right border (even if they must
10380 * overlap). The @c align_v and @c padding_v properties of the box
10381 * @b don't contribute to its behaviour when this layout is chosen.
10382 *
10383 * \par Child element's properties:
10384 * @c align_x does @b not influence the box's behavior. @c padding_l
10385 * and @c padding_r sum up to the container's horizontal padding
10386 * between elements. The child's @c padding_t, @c padding_b and
10387 * @c align_y properties apply for padding/alignment relative to the
10388 * overall height of the box. Finally, there is the @c weight_x
10389 * property, which, if set to a non-zero value, tells the container
10390 * that the child width is @b not pre-defined. If the container can't
10391 * accommodate all its children, it sets the widths of the ones
10392 * <b>with weights</b> to sizes as small as they can all fit into
10393 * it. If the size required by the children is less than the
10394 * available, the box increases its childrens' (which have weights)
10395 * widths as to fit the remaining space. The @c weight_x property,
10396 * besides telling the element is resizable, gives a @b weight for the
10397 * resizing process. The parent box will try to distribute (or take
10398 * off) widths accordingly to the @b normalized list of weigths: most
10399 * weighted children remain/get larger in this process than the least
10400 * ones. @c weight_y does not influence the layout.
10401 *
10402 * If one desires that, besides having weights, child elements must be
10403 * resized bounded to a minimum or maximum size, those size hints must
10404 * be set, by the <c>evas_object_size_hint_{min,max}_set()</c>
10405 * functions.
10406 */
10407EAPI void evas_object_box_layout_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10408
10409/**
10410 * Layout function which sets the box @a o to a (basic) vertical box
10411 *
10412 * This function behaves analogously to
10413 * evas_object_box_layout_horizontal(). The description of its
10414 * behaviour can be derived from that function's documentation.
10415 */
10416EAPI void evas_object_box_layout_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10417
10418/**
10419 * Layout function which sets the box @a o to a @b homogeneous
10420 * vertical box
10421 *
10422 * This function behaves analogously to
10423 * evas_object_box_layout_homogeneous_horizontal(). The description
10424 * of its behaviour can be derived from that function's documentation.
10425 */
10426EAPI void evas_object_box_layout_homogeneous_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10427
10428/**
10429 * Layout function which sets the box @a o to a @b homogeneous
10430 * horizontal box
10431 *
10432 * @param o The box object in question
10433 * @param priv The smart data of the @p o
10434 * @param data The data pointer passed on
10435 * evas_object_box_layout_set(), if any
10436 *
10437 * In a homogeneous horizontal box, its width is divided @b equally
10438 * between the contained objects. The box's overall behavior is
10439 * controlled by its padding/alignment properties, which are set by
10440 * the <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
10441 * functions. The size hints the elements in the box -- set by the
10442 * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
10443 * -- also control the way this function works.
10444 *
10445 * \par Box's properties:
10446 * @c align_h has no influence on the box for this layout.
10447 * @c padding_h tells the box to draw empty spaces of that size, in
10448 * pixels, between the (equal) child objects's cells. The @c align_v
10449 * and @c padding_v properties of the box don't contribute to its
10450 * behaviour when this layout is chosen.
10451 *
10452 * \par Child element's properties:
10453 * @c padding_l and @c padding_r sum up to the required width of the
10454 * child element. The @c align_x property tells the relative position
10455 * of this overall child width in its allocated cell (@r 0.0 to
10456 * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to
10457 * @c align_x makes the box try to resize this child element to the exact
10458 * width of its cell (respecting the minimum and maximum size hints on
10459 * the child's width and accounting for its horizontal padding
10460 * hints). The child's @c padding_t, @c padding_b and @c align_y
10461 * properties apply for padding/alignment relative to the overall
10462 * height of the box. A value of @c -1.0 to @c align_y makes the box
10463 * try to resize this child element to the exact height of its parent
10464 * (respecting the maximum size hint on the child's height).
10465 */
10466EAPI void evas_object_box_layout_homogeneous_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10467
10468/**
10469 * Layout function which sets the box @a o to a <b>maximum size,
10470 * homogeneous</b> horizontal box
10471 *
10472 * @param o The box object in question
10473 * @param priv The smart data of the @p o
10474 * @param data The data pointer passed on
10475 * evas_object_box_layout_set(), if any
10476 *
10477 * In a maximum size, homogeneous horizontal box, besides having cells
10478 * of <b>equal size</b> reserved for the child objects, this size will
10479 * be defined by the size of the @b largest child in the box (in
10480 * width). The box's overall behavior is controlled by its properties,
10481 * which are set by the
10482 * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
10483 * functions. The size hints of the elements in the box -- set by the
10484 * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
10485 * -- also control the way this function works.
10486 *
10487 * \par Box's properties:
10488 * @c padding_h tells the box to draw empty spaces of that size, in
10489 * pixels, between the child objects's cells. @c align_h controls the
10490 * horizontal alignment of the child objects, relative to the
10491 * containing box. When set to @c 0.0, children are aligned to the
10492 * left. A value of @c 1.0 lets them aligned to the right
10493 * border. Values in between align them proportionally. A negative
10494 * value of @c align_h makes the box to @b justify its children
10495 * cells. The padding between them, in this case, is corrected so that
10496 * the leftmost one touches the left border and the rightmost one
10497 * touches the right border (even if they must overlap). The
10498 * @c align_v and @c padding_v properties of the box don't contribute to
10499 * its behaviour when this layout is chosen.
10500 *
10501 * \par Child element's properties:
10502 * @c padding_l and @c padding_r sum up to the required width of the
10503 * child element. The @c align_x property tells the relative position
10504 * of this overall child width in its allocated cell (@c 0.0 to
10505 * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to
10506 * @c align_x makes the box try to resize this child element to the exact
10507 * width of its cell (respecting the minimun and maximum size hints on
10508 * the child's width and accounting for its horizontal padding
10509 * hints). The child's @c padding_t, @c padding_b and @c align_y
10510 * properties apply for padding/alignment relative to the overall
10511 * height of the box. A value of @c -1.0 to @c align_y makes the box
10512 * try to resize this child element to the exact height of its parent
10513 * (respecting the max hint on the child's height).
10514 */
10515EAPI void evas_object_box_layout_homogeneous_max_size_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10516
10517/**
10518 * Layout function which sets the box @a o to a <b>maximum size,
10519 * homogeneous</b> vertical box
10520 *
10521 * This function behaves analogously to
10522 * evas_object_box_layout_homogeneous_max_size_horizontal(). The
10523 * description of its behaviour can be derived from that function's
10524 * documentation.
10525 */
10526EAPI void evas_object_box_layout_homogeneous_max_size_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10527
10528/**
10529 * Layout function which sets the box @a o to a @b flow horizontal
10530 * box.
10531 *
10532 * @param o The box object in question
10533 * @param priv The smart data of the @p o
10534 * @param data The data pointer passed on
10535 * evas_object_box_layout_set(), if any
10536 *
10537 * In a flow horizontal box, the box's child elements are placed in
10538 * @b rows (think of text as an analogy). A row has as much elements as
10539 * can fit into the box's width. The box's overall behavior is
10540 * controlled by its properties, which are set by the
10541 * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
10542 * functions. The size hints of the elements in the box -- set by the
10543 * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
10544 * -- also control the way this function works.
10545 *
10546 * \par Box's properties:
10547 * @c padding_h tells the box to draw empty spaces of that size, in
10548 * pixels, between the child objects's cells. @c align_h dictates the
10549 * horizontal alignment of the rows (@c 0.0 to left align them, @c 1.0
10550 * to right align). A value of @c -1.0 to @c align_h lets the rows
10551 * @b justified horizontally. @c align_v controls the vertical alignment
10552 * of the entire set of rows (@c 0.0 to top, @c 1.0 to bottom). A
10553 * value of @c -1.0 to @c align_v makes the box to @b justify the rows
10554 * vertically. The padding between them, in this case, is corrected so
10555 * that the first row touches the top border and the last one touches
10556 * the bottom border (even if they must overlap). @c padding_v has no
10557 * influence on the layout.
10558 *
10559 * \par Child element's properties:
10560 * @c padding_l and @c padding_r sum up to the required width of the
10561 * child element. The @c align_x property has no influence on the
10562 * layout. The child's @c padding_t and @c padding_b sum up to the
10563 * required height of the child element and is the only means (besides
10564 * row justifying) of setting space between rows. Note, however, that
10565 * @c align_y dictates positioning relative to the <b>largest
10566 * height</b> required by a child object in the actual row.
10567 */
10568EAPI void evas_object_box_layout_flow_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10569
10570/**
10571 * Layout function which sets the box @a o to a @b flow vertical box.
10572 *
10573 * This function behaves analogously to
10574 * evas_object_box_layout_flow_horizontal(). The description of its
10575 * behaviour can be derived from that function's documentation.
10576 */
10577EAPI void evas_object_box_layout_flow_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10578
10579/**
10580 * Layout function which sets the box @a o to a @b stacking box
10581 *
10582 * @param o The box object in question
10583 * @param priv The smart data of the @p o
10584 * @param data The data pointer passed on
10585 * evas_object_box_layout_set(), if any
10586 *
10587 * In a stacking box, all children will be given the same size -- the
10588 * box's own size -- and they will be stacked one above the other, so
10589 * that the first object in @p o's internal list of child elements
10590 * will be the bottommost in the stack.
10591 *
10592 * \par Box's properties:
10593 * No box properties are used.
10594 *
10595 * \par Child element's properties:
10596 * @c padding_l and @c padding_r sum up to the required width of the
10597 * child element. The @c align_x property tells the relative position
10598 * of this overall child width in its allocated cell (@c 0.0 to
10599 * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to @c
10600 * align_x makes the box try to resize this child element to the exact
10601 * width of its cell (respecting the min and max hints on the child's
10602 * width and accounting for its horizontal padding properties). The
10603 * same applies to the vertical axis.
10604 */
10605EAPI void evas_object_box_layout_stack (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
10606
10607/**
10608 * Set the alignment of the whole bounding box of contents, for a
10609 * given box object.
10610 *
10611 * @param o The given box object to set alignment from
10612 * @param horizontal The horizontal alignment, in pixels
10613 * @param vertical the vertical alignment, in pixels
10614 *
10615 * This will influence how a box object is to align its bounding box
10616 * of contents within its own area. The values @b must be in the range
10617 * @c 0.0 - @c 1.0, or undefined behavior is expected. For horizontal
10618 * alignment, @c 0.0 means to the left, with @c 1.0 meaning to the
10619 * right. For vertical alignment, @c 0.0 means to the top, with @c 1.0
10620 * meaning to the bottom.
10621 *
10622 * @note The default values for both alignments is @c 0.5.
10623 *
10624 * @see evas_object_box_align_get()
10625 */
10626EAPI void evas_object_box_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
10627
10628/**
10629 * Get the alignment of the whole bounding box of contents, for a
10630 * given box object.
10631 *
10632 * @param o The given box object to get alignment from
10633 * @param horizontal Pointer to a variable where to store the
10634 * horizontal alignment
10635 * @param vertical Pointer to a variable where to store the vertical
10636 * alignment
10637 *
10638 * @see evas_object_box_align_set() for more information
10639 */
10640EAPI void evas_object_box_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
10641
10642/**
10643 * Set the (space) padding between cells set for a given box object.
10644 *
10645 * @param o The given box object to set padding from
10646 * @param horizontal The horizontal padding, in pixels
10647 * @param vertical the vertical padding, in pixels
10648 *
10649 * @note The default values for both padding components is @c 0.
10650 *
10651 * @see evas_object_box_padding_get()
10652 */
10653EAPI void evas_object_box_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
10654
10655/**
10656 * Get the (space) padding between cells set for a given box object.
10657 *
10658 * @param o The given box object to get padding from
10659 * @param horizontal Pointer to a variable where to store the
10660 * horizontal padding
10661 * @param vertical Pointer to a variable where to store the vertical
10662 * padding
10663 *
10664 * @see evas_object_box_padding_set()
10665 */
10666EAPI void evas_object_box_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
10667
10668/**
10669 * Append a new @a child object to the given box object @a o.
10670 *
10671 * @param o The given box object
10672 * @param child A child Evas object to be made a member of @p o
10673 * @return A box option bound to the recently added box item or @c
10674 * NULL, on errors
10675 *
10676 * On success, the @c "child,added" smart event will take place.
10677 *
10678 * @note The actual placing of the item relative to @p o's area will
10679 * depend on the layout set to it. For example, on horizontal layouts
10680 * an item in the end of the box's list of children will appear on its
10681 * right.
10682 *
10683 * @note This call will trigger the box's _Evas_Object_Box_Api::append
10684 * smart function.
10685 */
10686EAPI Evas_Object_Box_Option *evas_object_box_append (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
10687
10688/**
10689 * Prepend a new @a child object to the given box object @a o.
10690 *
10691 * @param o The given box object
10692 * @param child A child Evas object to be made a member of @p o
10693 * @return A box option bound to the recently added box item or @c
10694 * NULL, on errors
10695 *
10696 * On success, the @c "child,added" smart event will take place.
10697 *
10698 * @note The actual placing of the item relative to @p o's area will
10699 * depend on the layout set to it. For example, on horizontal layouts
10700 * an item in the beginning of the box's list of children will appear
10701 * on its left.
10702 *
10703 * @note This call will trigger the box's
10704 * _Evas_Object_Box_Api::prepend smart function.
10705 */
10706EAPI Evas_Object_Box_Option *evas_object_box_prepend (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
10707
10708/**
10709 * Insert a new @a child object <b>before another existing one</b>, in
10710 * a given box object @a o.
10711 *
10712 * @param o The given box object
10713 * @param child A child Evas object to be made a member of @p o
10714 * @param reference The child object to place this new one before
10715 * @return A box option bound to the recently added box item or @c
10716 * NULL, on errors
10717 *
10718 * On success, the @c "child,added" smart event will take place.
10719 *
10720 * @note This function will fail if @p reference is not a member of @p
10721 * o.
10722 *
10723 * @note The actual placing of the item relative to @p o's area will
10724 * depend on the layout set to it.
10725 *
10726 * @note This call will trigger the box's
10727 * _Evas_Object_Box_Api::insert_before smart function.
10728 */
10729EAPI 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);
10730
10731/**
10732 * Insert a new @a child object <b>after another existing one</b>, in
10733 * a given box object @a o.
10734 *
10735 * @param o The given box object
10736 * @param child A child Evas object to be made a member of @p o
10737 * @param reference The child object to place this new one after
10738 * @return A box option bound to the recently added box item or @c
10739 * NULL, on errors
10740 *
10741 * On success, the @c "child,added" smart event will take place.
10742 *
10743 * @note This function will fail if @p reference is not a member of @p
10744 * o.
10745 *
10746 * @note The actual placing of the item relative to @p o's area will
10747 * depend on the layout set to it.
10748 *
10749 * @note This call will trigger the box's
10750 * _Evas_Object_Box_Api::insert_after smart function.
10751 */
10752EAPI 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);
10753
10754/**
10755 * Insert a new @a child object <b>at a given position</b>, in a given
10756 * box object @a o.
10757 *
10758 * @param o The given box object
10759 * @param child A child Evas object to be made a member of @p o
10760 * @param pos The numeric position (starting from @c 0) to place the
10761 * new child object at
10762 * @return A box option bound to the recently added box item or @c
10763 * NULL, on errors
10764 *
10765 * On success, the @c "child,added" smart event will take place.
10766 *
10767 * @note This function will fail if the given position is invalid,
10768 * given @p o's internal list of elements.
10769 *
10770 * @note The actual placing of the item relative to @p o's area will
10771 * depend on the layout set to it.
10772 *
10773 * @note This call will trigger the box's
10774 * _Evas_Object_Box_Api::insert_at smart function.
10775 */
10776EAPI Evas_Object_Box_Option *evas_object_box_insert_at (Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2);
10777
10778/**
10779 * Remove a given object from a box object, unparenting it again.
10780 *
10781 * @param o The box object to remove a child object from
10782 * @param child The handle to the child object to be removed
10783 * @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
10784 *
10785 * On removal, you'll get an unparented object again, just as it was
10786 * before you inserted it in the box. The
10787 * _Evas_Object_Box_Api::option_free box smart callback will be called
10788 * automatilly for you and, also, the @c "child,removed" smart event
10789 * will take place.
10790 *
10791 * @note This call will trigger the box's _Evas_Object_Box_Api::remove
10792 * smart function.
10793 */
10794EAPI Eina_Bool evas_object_box_remove (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
10795
10796/**
10797 * Remove an object, <b>bound to a given position</b> in a box object,
10798 * unparenting it again.
10799 *
10800 * @param o The box object to remove a child object from
10801 * @param in The numeric position (starting from @c 0) of the child
10802 * object to be removed
10803 * @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
10804 *
10805 * On removal, you'll get an unparented object again, just as it was
10806 * before you inserted it in the box. The @c option_free() box smart
10807 * callback will be called automatilly for you and, also, the
10808 * @c "child,removed" smart event will take place.
10809 *
10810 * @note This function will fail if the given position is invalid,
10811 * given @p o's internal list of elements.
10812 *
10813 * @note This call will trigger the box's
10814 * _Evas_Object_Box_Api::remove_at smart function.
10815 */
10816EAPI Eina_Bool evas_object_box_remove_at (Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1);
10817
10818/**
10819 * Remove @b all child objects from a box object, unparenting them
10820 * again.
10821 *
10822 * @param o The box object to remove a child object from
10823 * @param child The handle to the child object to be removed
10824 * @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
10825 *
10826 * This has the same effect of calling evas_object_box_remove() on
10827 * each of @p o's child objects, in sequence. If, and only if, all
10828 * those calls succeed, so does this one.
10829 */
10830EAPI Eina_Bool evas_object_box_remove_all (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
10831
10832/**
10833 * Get an iterator to walk the list of children of a given box object.
10834 *
10835 * @param o The box to retrieve an items iterator from
10836 * @return An iterator on @p o's child objects, on success, or @c NULL,
10837 * on errors
10838 *
10839 * @note Do @b not remove or delete objects while walking the list.
10840 */
10841EAPI Eina_Iterator *evas_object_box_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
10842
10843/**
10844 * Get an accessor (a structure providing random items access) to the
10845 * list of children of a given box object.
10846 *
10847 * @param o The box to retrieve an items iterator from
10848 * @return An accessor on @p o's child objects, on success, or @c NULL,
10849 * on errors
10850 *
10851 * @note Do not remove or delete objects while walking the list.
10852 */
10853EAPI Eina_Accessor *evas_object_box_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
10854
10855/**
10856 * Get the list of children objects in a given box object.
10857 *
10858 * @param o The box to retrieve an items list from
10859 * @return A list of @p o's child objects, on success, or @c NULL,
10860 * on errors (or if it has no child objects)
10861 *
10862 * The returned list should be freed with @c eina_list_free() when you
10863 * no longer need it.
10864 *
10865 * @note This is a duplicate of the list kept by the box internally.
10866 * It's up to the user to destroy it when it no longer needs it.
10867 * It's possible to remove objects from the box when walking
10868 * this list, but these removals won't be reflected on it.
10869 */
10870EAPI Eina_List *evas_object_box_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
10871
10872/**
10873 * Get the name of the property of the child elements of the box @a o
10874 * which have @a id as identifier
10875 *
10876 * @param o The box to search child options from
10877 * @param id The numerical identifier of the option being searched, for
10878 * its name
10879 * @return The name of the given property or @c NULL, on errors.
10880 *
10881 * @note This call won't do anything for a canonical Evas box. Only
10882 * users which have @b subclassed it, setting custom box items options
10883 * (see #Evas_Object_Box_Option) on it, would benefit from this
10884 * function. They'd have to implement it and set it to be the
10885 * _Evas_Object_Box_Api::property_name_get smart class function of the
10886 * box, which is originally set to @c NULL.
10887 */
10888EAPI const char *evas_object_box_option_property_name_get (Evas_Object *o, int property) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
10889
10890/**
10891 * Get the numerical identifier of the property of the child elements
10892 * of the box @a o which have @a name as name string
10893 *
10894 * @param o The box to search child options from
10895 * @param name The name string of the option being searched, for
10896 * its ID
10897 * @return The numerical ID of the given property or @c -1, on
10898 * errors.
10899 *
10900 * @note This call won't do anything for a canonical Evas box. Only
10901 * users which have @b subclassed it, setting custom box items options
10902 * (see #Evas_Object_Box_Option) on it, would benefit from this
10903 * function. They'd have to implement it and set it to be the
10904 * _Evas_Object_Box_Api::property_id_get smart class function of the
10905 * box, which is originally set to @c NULL.
10906 */
10907EAPI int evas_object_box_option_property_id_get (Evas_Object *o, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
10908
10909/**
10910 * Set a property value (by its given numerical identifier), on a
10911 * given box child element
10912 *
10913 * @param o The box parenting the child element
10914 * @param opt The box option structure bound to the child box element
10915 * to set a property on
10916 * @param id The numerical ID of the given property
10917 * @param ... (List of) actual value(s) to be set for this
10918 * property. It (they) @b must be of the same type the user has
10919 * defined for it (them).
10920 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
10921 *
10922 * @note This call won't do anything for a canonical Evas box. Only
10923 * users which have @b subclassed it, setting custom box items options
10924 * (see #Evas_Object_Box_Option) on it, would benefit from this
10925 * function. They'd have to implement it and set it to be the
10926 * _Evas_Object_Box_Api::property_set smart class function of the box,
10927 * which is originally set to @c NULL.
10928 *
10929 * @note This function will internally create a variable argument
10930 * list, with the values passed after @p property, and call
10931 * evas_object_box_option_property_vset() with this list and the same
10932 * previous arguments.
10933 */
10934EAPI Eina_Bool evas_object_box_option_property_set (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
10935
10936/**
10937 * Set a property value (by its given numerical identifier), on a
10938 * given box child element -- by a variable argument list
10939 *
10940 * @param o The box parenting the child element
10941 * @param opt The box option structure bound to the child box element
10942 * to set a property on
10943 * @param id The numerical ID of the given property
10944 * @param va_list The variable argument list implementing the value to
10945 * be set for this property. It @b must be of the same type the user has
10946 * defined for it.
10947 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
10948 *
10949 * This is a variable argument list variant of the
10950 * evas_object_box_option_property_set(). See its documentation for
10951 * more details.
10952 */
10953EAPI 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);
10954
10955/**
10956 * Get a property's value (by its given numerical identifier), on a
10957 * given box child element
10958 *
10959 * @param o The box parenting the child element
10960 * @param opt The box option structure bound to the child box element
10961 * to get a property from
10962 * @param id The numerical ID of the given property
10963 * @param ... (List of) pointer(s) where to store the value(s) set for
10964 * this property. It (they) @b must point to variable(s) of the same
10965 * type the user has defined for it (them).
10966 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
10967 *
10968 * @note This call won't do anything for a canonical Evas box. Only
10969 * users which have @b subclassed it, getting custom box items options
10970 * (see #Evas_Object_Box_Option) on it, would benefit from this
10971 * function. They'd have to implement it and get it to be the
10972 * _Evas_Object_Box_Api::property_get smart class function of the
10973 * box, which is originally get to @c NULL.
10974 *
10975 * @note This function will internally create a variable argument
10976 * list, with the values passed after @p property, and call
10977 * evas_object_box_option_property_vget() with this list and the same
10978 * previous arguments.
10979 */
10980EAPI Eina_Bool evas_object_box_option_property_get (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
10981
10982/**
10983 * Get a property's value (by its given numerical identifier), on a
10984 * given box child element -- by a variable argument list
10985 *
10986 * @param o The box parenting the child element
10987 * @param opt The box option structure bound to the child box element
10988 * to get a property from
10989 * @param id The numerical ID of the given property
10990 * @param va_list The variable argument list with pointers to where to
10991 * store the values of this property. They @b must point to variables
10992 * of the same type the user has defined for them.
10993 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
10994 *
10995 * This is a variable argument list variant of the
10996 * evas_object_box_option_property_get(). See its documentation for
10997 * more details.
10998 */
10999EAPI 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);
11000
11001/**
11002 * @}
11003 */
11004
11005/**
11006 * @defgroup Evas_Object_Table Table Smart Object.
11007 *
11008 * Convenience smart object that packs children using a tabular
11009 * layout using children size hints to define their size and
11010 * alignment inside their cell space.
11011 *
11012 * @ref tutorial_table shows how to use this Evas_Object.
11013 *
11014 * @see @ref Evas_Object_Group_Size_Hints
11015 *
11016 * @ingroup Evas_Smart_Object_Group
11017 *
11018 * @{
11019 */
11020
11021/**
11022 * @brief Create a new table.
11023 *
11024 * @param evas Canvas in which table will be added.
11025 */
11026EAPI Evas_Object *evas_object_table_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11027
11028/**
11029 * @brief Create a table that is child of a given element @a parent.
11030 *
11031 * @see evas_object_table_add()
11032 */
11033EAPI Evas_Object *evas_object_table_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11034
11035/**
11036 * @brief Set how this table should layout children.
11037 *
11038 * @todo consider aspect hint and respect it.
11039 *
11040 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE
11041 * If table does not use homogeneous mode then columns and rows will
11042 * be calculated based on hints of individual cells. This operation
11043 * mode is more flexible, but more complex and heavy to calculate as
11044 * well. @b Weight properties are handled as a boolean expand. Negative
11045 * alignment will be considered as 0.5. This is the default.
11046 *
11047 * @todo @c EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE should balance weight.
11048 *
11049 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE
11050 * When homogeneous is relative to table the own table size is divided
11051 * equally among children, filling the whole table area. That is, if
11052 * table has @c WIDTH and @c COLUMNS, each cell will get <tt>WIDTH /
11053 * COLUMNS</tt> pixels. If children have minimum size that is larger
11054 * than this amount (including padding), then it will overflow and be
11055 * aligned respecting the alignment hint, possible overlapping sibling
11056 * cells. @b Weight hint is used as a boolean, if greater than zero it
11057 * will make the child expand in that axis, taking as much space as
11058 * possible (bounded to maximum size hint). Negative alignment will be
11059 * considered as 0.5.
11060 *
11061 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM
11062 * When homogeneous is relative to item it means the greatest minimum
11063 * cell size will be used. That is, if no element is set to expand,
11064 * the table will have its contents to a minimum size, the bounding
11065 * box of all these children will be aligned relatively to the table
11066 * object using evas_object_table_align_get(). If the table area is
11067 * too small to hold this minimum bounding box, then the objects will
11068 * keep their size and the bounding box will overflow the box area,
11069 * still respecting the alignment. @b Weight hint is used as a
11070 * boolean, if greater than zero it will make that cell expand in that
11071 * axis, toggling the <b>expand mode</b>, which makes the table behave
11072 * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the
11073 * bounding box will overflow and items will not overlap siblings. If
11074 * no minimum size is provided at all then the table will fallback to
11075 * expand mode as well.
11076 */
11077EAPI void evas_object_table_homogeneous_set (Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1);
11078
11079/**
11080 * Get the current layout homogeneous mode.
11081 *
11082 * @see evas_object_table_homogeneous_set()
11083 */
11084EAPI Evas_Object_Table_Homogeneous_Mode evas_object_table_homogeneous_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
11085
11086/**
11087 * Set padding between cells.
11088 */
11089EAPI void evas_object_table_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
11090
11091/**
11092 * Get padding between cells.
11093 */
11094EAPI void evas_object_table_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
11095
11096/**
11097 * Set the alignment of the whole bounding box of contents.
11098 */
11099EAPI void evas_object_table_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
11100
11101/**
11102 * Get alignment of the whole bounding box of contents.
11103 */
11104EAPI void evas_object_table_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
11105
11106/**
11107 * Sets the mirrored mode of the table. In mirrored mode the table items go
11108 * from right to left instead of left to right. That is, 1,1 is top right, not
11109 * top left.
11110 *
11111 * @param obj The table object.
11112 * @param mirrored the mirrored mode to set
11113 * @since 1.1.0
11114 */
11115EAPI void evas_object_table_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
11116
11117/**
11118 * Gets the mirrored mode of the table.
11119 *
11120 * @param obj The table object.
11121 * @return EINA_TRUE if it's a mirrored table, EINA_FALSE otherwise.
11122 * @since 1.1.0
11123 * @see evas_object_table_mirrored_set()
11124 */
11125EAPI Eina_Bool evas_object_table_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
11126
11127/**
11128 * Get packing location of a child of table
11129 *
11130 * @param o The given table object.
11131 * @param child The child object to add.
11132 * @param col pointer to store relative-horizontal position to place child.
11133 * @param row pointer to store relative-vertical position to place child.
11134 * @param colspan pointer to store how many relative-horizontal position to use for this child.
11135 * @param rowspan pointer to store how many relative-vertical position to use for this child.
11136 *
11137 * @return 1 on success, 0 on failure.
11138 * @since 1.1.0
11139 */
11140EAPI 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);
11141
11142/**
11143 * Add a new child to a table object or set its current packing.
11144 *
11145 * @param o The given table object.
11146 * @param child The child object to add.
11147 * @param col relative-horizontal position to place child.
11148 * @param row relative-vertical position to place child.
11149 * @param colspan how many relative-horizontal position to use for this child.
11150 * @param rowspan how many relative-vertical position to use for this child.
11151 *
11152 * @return 1 on success, 0 on failure.
11153 */
11154EAPI 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);
11155
11156/**
11157 * Remove child from table.
11158 *
11159 * @note removing a child will immediately call a walk over children in order
11160 * to recalculate numbers of columns and rows. If you plan to remove
11161 * all children, use evas_object_table_clear() instead.
11162 *
11163 * @return 1 on success, 0 on failure.
11164 */
11165EAPI Eina_Bool evas_object_table_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
11166
11167/**
11168 * Faster way to remove all child objects from a table object.
11169 *
11170 * @param o The given table object.
11171 * @param clear if true, it will delete just removed children.
11172 */
11173EAPI void evas_object_table_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
11174
11175/**
11176 * Get the number of columns and rows this table takes.
11177 *
11178 * @note columns and rows are virtual entities, one can specify a table
11179 * with a single object that takes 4 columns and 5 rows. The only
11180 * difference for a single cell table is that paddings will be
11181 * accounted proportionally.
11182 */
11183EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1);
11184
11185/**
11186 * Get an iterator to walk the list of children for the table.
11187 *
11188 * @note Do not remove or delete objects while walking the list.
11189 */
11190EAPI Eina_Iterator *evas_object_table_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11191
11192/**
11193 * Get an accessor to get random access to the list of children for the table.
11194 *
11195 * @note Do not remove or delete objects while walking the list.
11196 */
11197EAPI Eina_Accessor *evas_object_table_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11198
11199/**
11200 * Get the list of children for the table.
11201 *
11202 * @note This is a duplicate of the list kept by the table internally.
11203 * It's up to the user to destroy it when it no longer needs it.
11204 * It's possible to remove objects from the table when walking this
11205 * list, but these removals won't be reflected on it.
11206 */
11207EAPI Eina_List *evas_object_table_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11208
11209/**
11210 * Get the child of the table at the given coordinates
11211 *
11212 * @note This does not take into account col/row spanning
11213 */
11214EAPI Evas_Object *evas_object_table_child_get (const Evas_Object *o, unsigned short col, unsigned short row) EINA_ARG_NONNULL(1);
11215/**
11216 * @}
11217 */
11218
11219/**
11220 * @defgroup Evas_Object_Grid Grid Smart Object.
11221 *
11222 * Convenience smart object that packs children under a regular grid
11223 * layout, using their virtual grid location and size to determine
11224 * children's positions inside the grid object's area.
11225 *
11226 * @ingroup Evas_Smart_Object_Group
11227 * @since 1.1.0
11228 */
11229
11230/**
11231 * @addtogroup Evas_Object_Grid
11232 * @{
11233 */
11234
11235/**
11236 * Create a new grid.
11237 *
11238 * It's set to a virtual size of 1x1 by default and add children with
11239 * evas_object_grid_pack().
11240 * @since 1.1.0
11241 */
11242EAPI Evas_Object *evas_object_grid_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11243
11244/**
11245 * Create a grid that is child of a given element @a parent.
11246 *
11247 * @see evas_object_grid_add()
11248 * @since 1.1.0
11249 */
11250EAPI Evas_Object *evas_object_grid_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11251
11252/**
11253 * Set the virtual resolution for the grid
11254 *
11255 * @param o The grid object to modify
11256 * @param w The virtual horizontal size (resolution) in integer units
11257 * @param h The virtual vertical size (resolution) in integer units
11258 * @since 1.1.0
11259 */
11260EAPI void evas_object_grid_size_set (Evas_Object *o, int w, int h) EINA_ARG_NONNULL(1);
11261
11262/**
11263 * Get the current virtual resolution
11264 *
11265 * @param o The grid object to query
11266 * @param w A pointer to an integer to store the virtual width
11267 * @param h A pointer to an integer to store the virtual height
11268 * @see evas_object_grid_size_set()
11269 * @since 1.1.0
11270 */
11271EAPI void evas_object_grid_size_get (const Evas_Object *o, int *w, int *h) EINA_ARG_NONNULL(1);
11272
11273/**
11274 * Sets the mirrored mode of the grid. In mirrored mode the grid items go
11275 * from right to left instead of left to right. That is, 0,0 is top right, not
11276 * to left.
11277 *
11278 * @param obj The grid object.
11279 * @param mirrored the mirrored mode to set
11280 * @since 1.1.0
11281 */
11282EAPI void evas_object_grid_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
11283
11284/**
11285 * Gets the mirrored mode of the grid.
11286 *
11287 * @param obj The grid object.
11288 * @return EINA_TRUE if it's a mirrored grid, EINA_FALSE otherwise.
11289 * @see evas_object_grid_mirrored_set()
11290 * @since 1.1.0
11291 */
11292EAPI Eina_Bool evas_object_grid_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
11293
11294/**
11295 * Add a new child to a grid object.
11296 *
11297 * @param o The given grid object.
11298 * @param child The child object to add.
11299 * @param x The virtual x coordinate of the child
11300 * @param y The virtual y coordinate of the child
11301 * @param w The virtual width of the child
11302 * @param h The virtual height of the child
11303 * @return 1 on success, 0 on failure.
11304 * @since 1.1.0
11305 */
11306EAPI 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);
11307
11308/**
11309 * Remove child from grid.
11310 *
11311 * @note removing a child will immediately call a walk over children in order
11312 * to recalculate numbers of columns and rows. If you plan to remove
11313 * all children, use evas_object_grid_clear() instead.
11314 *
11315 * @return 1 on success, 0 on failure.
11316 * @since 1.1.0
11317 */
11318EAPI Eina_Bool evas_object_grid_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
11319
11320/**
11321 * Faster way to remove all child objects from a grid object.
11322 *
11323 * @param o The given grid object.
11324 * @param clear if true, it will delete just removed children.
11325 * @since 1.1.0
11326 */
11327EAPI void evas_object_grid_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
11328
11329/**
11330 * Get the pack options for a grid child
11331 *
11332 * Get the pack x, y, width and height in virtual coordinates set by
11333 * evas_object_grid_pack()
11334 * @param o The grid object
11335 * @param child The grid child to query for coordinates
11336 * @param x The pointer to where the x coordinate will be returned
11337 * @param y The pointer to where the y coordinate will be returned
11338 * @param w The pointer to where the width will be returned
11339 * @param h The pointer to where the height will be returned
11340 * @return 1 on success, 0 on failure.
11341 * @since 1.1.0
11342 */
11343EAPI Eina_Bool evas_object_grid_pack_get (Evas_Object *o, Evas_Object *child, int *x, int *y, int *w, int *h);
11344
11345/**
11346 * Get an iterator to walk the list of children for the grid.
11347 *
11348 * @note Do not remove or delete objects while walking the list.
11349 * @since 1.1.0
11350 */
11351EAPI Eina_Iterator *evas_object_grid_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11352
11353/**
11354 * Get an accessor to get random access to the list of children for the grid.
11355 *
11356 * @note Do not remove or delete objects while walking the list.
11357 * @since 1.1.0
11358 */
11359EAPI Eina_Accessor *evas_object_grid_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11360
11361/**
11362 * Get the list of children for the grid.
11363 *
11364 * @note This is a duplicate of the list kept by the grid internally.
11365 * It's up to the user to destroy it when it no longer needs it.
11366 * It's possible to remove objects from the grid when walking this
11367 * list, but these removals won't be reflected on it.
11368 * @since 1.1.0
11369 */
11370EAPI Eina_List *evas_object_grid_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
11371
11372/**
11373 * @}
11374 */
11375
11376/**
11377 * @defgroup Evas_Cserve Shared Image Cache Server
11378 *
11379 * Evas has an (optional) module which provides client-server
11380 * infrastructure to <b>share bitmaps across multiple processes</b>,
11381 * saving data and processing power.
11382 *
11383 * Be warned that it @b doesn't work when <b>threaded image
11384 * preloading</b> is enabled for Evas, though.
11385 */
11386 typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
11387 typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
11388 typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
11389 typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
11390
11391/**
11392 * Statistics about the server that shares cached bitmaps.
11393 * @ingroup Evas_Cserve
11394 */
11395 struct _Evas_Cserve_Stats
11396 {
11397 int saved_memory; /**< current amount of saved memory, in bytes */
11398 int wasted_memory; /**< current amount of wasted memory, in bytes */
11399 int saved_memory_peak; /**< peak ammount of saved memory, in bytes */
11400 int wasted_memory_peak; /**< peak ammount of wasted memory, in bytes */
11401 double saved_time_image_header_load; /**< time, in seconds, saved in header loads by sharing cached loads instead */
11402 double saved_time_image_data_load; /**< time, in seconds, saved in data loads by sharing cached loads instead */
11403 };
11404
11405/**
11406 * A handle of a cache of images shared by a server.
11407 * @ingroup Evas_Cserve
11408 */
11409 struct _Evas_Cserve_Image_Cache
11410 {
11411 struct {
11412 int mem_total;
11413 int count;
11414 } active, cached;
11415 Eina_List *images;
11416 };
11417
11418/**
11419 * A handle to an image shared by a server.
11420 * @ingroup Evas_Cserve
11421 */
11422 struct _Evas_Cserve_Image
11423 {
11424 const char *file, *key;
11425 int w, h;
11426 time_t file_mod_time;
11427 time_t file_checked_time;
11428 time_t cached_time;
11429 int refcount;
11430 int data_refcount;
11431 int memory_footprint;
11432 double head_load_time;
11433 double data_load_time;
11434 Eina_Bool alpha : 1;
11435 Eina_Bool data_loaded : 1;
11436 Eina_Bool active : 1;
11437 Eina_Bool dead : 1;
11438 Eina_Bool useless : 1;
11439 };
11440
11441/**
11442 * Configuration that controls the server that shares cached bitmaps.
11443 * @ingroup Evas_Cserve
11444 */
11445 struct _Evas_Cserve_Config
11446 {
11447 int cache_max_usage;
11448 int cache_item_timeout;
11449 int cache_item_timeout_check;
11450 };
11451
11452
11453/**
11454 * Retrieves if the system wants to share bitmaps using the server.
11455 * @return @c EINA_TRUE if it wants, @c EINA_FALSE otherwise.
11456 * @ingroup Evas_Cserve
11457 */
11458EAPI Eina_Bool evas_cserve_want_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE;
11459
11460/**
11461 * Retrieves if the system is connected to the server used to share
11462 * bitmaps.
11463 *
11464 * @return @c EINA_TRUE if it's connected, @c EINA_FALSE otherwise.
11465 * @ingroup Evas_Cserve
11466 */
11467EAPI Eina_Bool evas_cserve_connected_get (void) EINA_WARN_UNUSED_RESULT;
11468
11469/**
11470 * Retrieves statistics from a running bitmap sharing server.
11471 * @param stats pointer to structure to fill with statistics about the
11472 * bitmap cache server.
11473 *
11474 * @return @c EINA_TRUE if @p stats were filled with data,
11475 * @c EINA_FALSE otherwise (when @p stats is untouched)
11476 * @ingroup Evas_Cserve
11477 */
11478EAPI Eina_Bool evas_cserve_stats_get (Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
11479
11480/**
11481 * Completely discard/clean a given images cache, thus re-setting it.
11482 *
11483 * @param cache A handle to the given images cache.
11484 */
11485EAPI void evas_cserve_image_cache_contents_clean (Evas_Cserve_Image_Cache *cache) EINA_PURE;
11486
11487/**
11488 * Retrieves the current configuration of the Evas image caching
11489 * server.
11490 *
11491 * @param config where to store current image caching server's
11492 * configuration.
11493 *
11494 * @return @c EINA_TRUE if @p config was filled with data,
11495 * @c EINA_FALSE otherwise (when @p config is untouched)
11496 *
11497 * The fields of @p config will be altered to reflect the current
11498 * configuration's values.
11499 *
11500 * @see evas_cserve_config_set()
11501 *
11502 * @ingroup Evas_Cserve
11503 */
11504EAPI Eina_Bool evas_cserve_config_get (Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE;
11505
11506/**
11507 * Changes the configurations of the Evas image caching server.
11508 *
11509 * @param config A bitmap cache configuration handle with fields set
11510 * to desired configuration values.
11511 * @return @c EINA_TRUE if @p config was successfully applied,
11512 * @c EINA_FALSE otherwise.
11513 *
11514 * @see evas_cserve_config_get()
11515 *
11516 * @ingroup Evas_Cserve
11517 */
11518EAPI Eina_Bool evas_cserve_config_set (const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE;
11519
11520/**
11521 * Force the system to disconnect from the bitmap caching server.
11522 *
11523 * @ingroup Evas_Cserve
11524 */
11525EAPI void evas_cserve_disconnect (void);
11526
11527/**
11528 * @defgroup Evas_Utils General Utilities
11529 *
11530 * Some functions that are handy but are not specific of canvas or
11531 * objects.
11532 */
11533
11534/**
11535 * Converts the given Evas image load error code into a string
11536 * describing it in english.
11537 *
11538 * @param error the error code, a value in ::Evas_Load_Error.
11539 * @return Always returns a valid string. If the given @p error is not
11540 * supported, <code>"Unknown error"</code> is returned.
11541 *
11542 * Mostly evas_object_image_file_set() would be the function setting
11543 * that error value afterwards, but also evas_object_image_load(),
11544 * evas_object_image_save(), evas_object_image_data_get(),
11545 * evas_object_image_data_convert(), evas_object_image_pixels_import()
11546 * and evas_object_image_is_inside(). This function is meant to be
11547 * used in conjunction with evas_object_image_load_error_get(), as in:
11548 *
11549 * Example code:
11550 * @dontinclude evas-load-error-str.c
11551 * @skip img1 =
11552 * @until ecore_main_loop_begin(
11553 *
11554 * Here, being @c valid_path the path to a valid image and @c
11555 * bogus_path a path to a file which does not exist, the two outputs
11556 * of evas_load_error_str() would be (if no other errors occur):
11557 * <code>"No error on load"</code> and <code>"File (or file path) does
11558 * not exist"</code>, respectively. See the full @ref
11559 * Example_Evas_Images "example".
11560 *
11561 * @ingroup Evas_Utils
11562 */
11563EAPI const char *evas_load_error_str (Evas_Load_Error error);
11564
11565/* Evas utility routines for color space conversions */
11566/* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
11567/* rgb color space has r,g,b in the range 0 to 255 */
11568
11569/**
11570 * Convert a given color from HSV to RGB format.
11571 *
11572 * @param h The Hue component of the color.
11573 * @param s The Saturation component of the color.
11574 * @param v The Value component of the color.
11575 * @param r The Red component of the color.
11576 * @param g The Green component of the color.
11577 * @param b The Blue component of the color.
11578 *
11579 * This function converts a given color in HSV color format to RGB
11580 * color format.
11581 *
11582 * @ingroup Evas_Utils
11583 **/
11584EAPI void evas_color_hsv_to_rgb (float h, float s, float v, int *r, int *g, int *b);
11585
11586/**
11587 * Convert a given color from RGB to HSV format.
11588 *
11589 * @param r The Red component of the color.
11590 * @param g The Green component of the color.
11591 * @param b The Blue component of the color.
11592 * @param h The Hue component of the color.
11593 * @param s The Saturation component of the color.
11594 * @param v The Value component of the color.
11595 *
11596 * This function converts a given color in RGB color format to HSV
11597 * color format.
11598 *
11599 * @ingroup Evas_Utils
11600 **/
11601EAPI void evas_color_rgb_to_hsv (int r, int g, int b, float *h, float *s, float *v);
11602
11603/* argb color space has a,r,g,b in the range 0 to 255 */
11604
11605/**
11606 * Pre-multiplies a rgb triplet by an alpha factor.
11607 *
11608 * @param a The alpha factor.
11609 * @param r The Red component of the color.
11610 * @param g The Green component of the color.
11611 * @param b The Blue component of the color.
11612 *
11613 * This function pre-multiplies a given rbg triplet by an alpha
11614 * factor. Alpha factor is used to define transparency.
11615 *
11616 * @ingroup Evas_Utils
11617 **/
11618EAPI void evas_color_argb_premul (int a, int *r, int *g, int *b);
11619
11620/**
11621 * Undo pre-multiplication of a rgb triplet by an alpha factor.
11622 *
11623 * @param a The alpha factor.
11624 * @param r The Red component of the color.
11625 * @param g The Green component of the color.
11626 * @param b The Blue component of the color.
11627 *
11628 * This function undoes pre-multiplication a given rbg triplet by an
11629 * alpha factor. Alpha factor is used to define transparency.
11630 *
11631 * @see evas_color_argb_premul().
11632 *
11633 * @ingroup Evas_Utils
11634 **/
11635EAPI void evas_color_argb_unpremul (int a, int *r, int *g, int *b);
11636
11637
11638/**
11639 * Pre-multiplies data by an alpha factor.
11640 *
11641 * @param data The data value.
11642 * @param len The length value.
11643 *
11644 * This function pre-multiplies a given data by an alpha
11645 * factor. Alpha factor is used to define transparency.
11646 *
11647 * @ingroup Evas_Utils
11648 **/
11649EAPI void evas_data_argb_premul (unsigned int *data, unsigned int len);
11650
11651/**
11652 * Undo pre-multiplication data by an alpha factor.
11653 *
11654 * @param data The data value.
11655 * @param len The length value.
11656 *
11657 * This function undoes pre-multiplication of a given data by an alpha
11658 * factor. Alpha factor is used to define transparency.
11659 *
11660 * @ingroup Evas_Utils
11661 **/
11662EAPI void evas_data_argb_unpremul (unsigned int *data, unsigned int len);
11663
11664/* string and font handling */
11665
11666/**
11667 * Gets the next character in the string
11668 *
11669 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
11670 * this function will place in @p decoded the decoded code point at @p pos
11671 * and return the byte index for the next character in the string.
11672 *
11673 * The only boundary check done is that @p pos must be >= 0. Other than that,
11674 * no checks are performed, so passing an index value that's not within the
11675 * length of the string will result in undefined behavior.
11676 *
11677 * @param str The UTF-8 string
11678 * @param pos The byte index where to start
11679 * @param decoded Address where to store the decoded code point. Optional.
11680 *
11681 * @return The byte index of the next character
11682 *
11683 * @ingroup Evas_Utils
11684 */
11685EAPI int evas_string_char_next_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
11686
11687/**
11688 * Gets the previous character in the string
11689 *
11690 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
11691 * this function will place in @p decoded the decoded code point at @p pos
11692 * and return the byte index for the previous character in the string.
11693 *
11694 * The only boundary check done is that @p pos must be >= 1. Other than that,
11695 * no checks are performed, so passing an index value that's not within the
11696 * length of the string will result in undefined behavior.
11697 *
11698 * @param str The UTF-8 string
11699 * @param pos The byte index where to start
11700 * @param decoded Address where to store the decoded code point. Optional.
11701 *
11702 * @return The byte index of the previous character
11703 *
11704 * @ingroup Evas_Utils
11705 */
11706EAPI int evas_string_char_prev_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
11707
11708/**
11709 * Get the length in characters of the string.
11710 * @param str The string to get the length of.
11711 * @return The length in characters (not bytes)
11712 * @ingroup Evas_Utils
11713 */
11714EAPI int evas_string_char_len_get (const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
11715
11716/**
11717 * @defgroup Evas_Keys Key Input Functions
11718 *
11719 * Functions which feed key events to the canvas.
11720 *
11721 * As explained in @ref intro_not_evas, Evas is @b not aware of input
11722 * systems at all. Then, the user, if using it crudely (evas_new()),
11723 * will have to feed it with input events, so that it can react
11724 * somehow. If, however, the user creates a canvas by means of the
11725 * Ecore_Evas wrapper, it will automatically bind the chosen display
11726 * engine's input events to the canvas, for you.
11727 *
11728 * This group presents the functions dealing with the feeding of key
11729 * events to the canvas. On most of them, one has to reference a given
11730 * key by a name (<code>keyname</code> argument). Those are
11731 * <b>platform dependent</b> symbolic names for the keys. Sometimes
11732 * you'll get the right <code>keyname</code> by simply using an ASCII
11733 * value of the key name, but it won't be like that always.
11734 *
11735 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
11736 * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
11737 * to your display engine's documentation when using evas through an
11738 * Ecore helper wrapper when you need the <code>keyname</code>s.
11739 *
11740 * Example:
11741 * @dontinclude evas-events.c
11742 * @skip mods = evas_key_modifier_get(evas);
11743 * @until {
11744 *
11745 * All the other @c evas_key functions behave on the same manner. See
11746 * the full @ref Example_Evas_Events "example".
11747 *
11748 * @ingroup Evas_Canvas
11749 */
11750
11751/**
11752 * @addtogroup Evas_Keys
11753 * @{
11754 */
11755
11756/**
11757 * Returns a handle to the list of modifier keys registered in the
11758 * canvas @p e. This is required to check for which modifiers are set
11759 * at a given time with the evas_key_modifier_is_set() function.
11760 *
11761 * @param e The pointer to the Evas canvas
11762 *
11763 * @see evas_key_modifier_add
11764 * @see evas_key_modifier_del
11765 * @see evas_key_modifier_on
11766 * @see evas_key_modifier_off
11767 * @see evas_key_modifier_is_set
11768 *
11769 * @return An ::Evas_Modifier handle to query Evas' keys subsystem
11770 * with evas_key_modifier_is_set(), or @c NULL on error.
11771 */
11772EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
11773
11774/**
11775 * Returns a handle to the list of lock keys registered in the canvas
11776 * @p e. This is required to check for which locks are set at a given
11777 * time with the evas_key_lock_is_set() function.
11778 *
11779 * @param e The pointer to the Evas canvas
11780 *
11781 * @see evas_key_lock_add
11782 * @see evas_key_lock_del
11783 * @see evas_key_lock_on
11784 * @see evas_key_lock_off
11785 * @see evas_key_lock_is_set
11786 *
11787 * @return An ::Evas_Lock handle to query Evas' keys subsystem with
11788 * evas_key_lock_is_set(), or @c NULL on error.
11789 */
11790EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
11791
11792
11793/**
11794 * Checks the state of a given modifier key, at the time of the
11795 * call. If the modifier is set, such as shift being pressed, this
11796 * function returns @c Eina_True.
11797 *
11798 * @param m The current modifiers set, as returned by
11799 * evas_key_modifier_get().
11800 * @param keyname The name of the modifier key to check status for.
11801 *
11802 * @return @c Eina_True if the modifier key named @p keyname is on, @c
11803 * Eina_False otherwise.
11804 *
11805 * @see evas_key_modifier_add
11806 * @see evas_key_modifier_del
11807 * @see evas_key_modifier_get
11808 * @see evas_key_modifier_on
11809 * @see evas_key_modifier_off
11810 */
11811EAPI Eina_Bool evas_key_modifier_is_set (const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
11812
11813
11814/**
11815 * Checks the state of a given lock key, at the time of the call. If
11816 * the lock is set, such as caps lock, this function returns @c
11817 * Eina_True.
11818 *
11819 * @param l The current locks set, as returned by evas_key_lock_get().
11820 * @param keyname The name of the lock key to check status for.
11821 *
11822 * @return @c Eina_True if the @p keyname lock key is set, @c
11823 * Eina_False otherwise.
11824 *
11825 * @see evas_key_lock_get
11826 * @see evas_key_lock_add
11827 * @see evas_key_lock_del
11828 * @see evas_key_lock_on
11829 * @see evas_key_lock_off
11830 */
11831EAPI Eina_Bool evas_key_lock_is_set (const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
11832
11833
11834/**
11835 * Adds the @p keyname key to the current list of modifier keys.
11836 *
11837 * @param e The pointer to the Evas canvas
11838 * @param keyname The name of the modifier key to add to the list of
11839 * Evas modifiers.
11840 *
11841 * Modifiers are keys like shift, alt and ctrl, i.e., keys which are
11842 * meant to be pressed together with others, altering the behavior of
11843 * the secondly pressed keys somehow. Evas is so that these keys can
11844 * be user defined.
11845 *
11846 * This call allows custom modifiers to be added to the Evas system at
11847 * run time. It is then possible to set and unset modifier keys
11848 * programmatically for other parts of the program to check and act
11849 * on. Programmers using Evas would check for modifier keys on key
11850 * event callbacks using evas_key_modifier_is_set().
11851 *
11852 * @see evas_key_modifier_del
11853 * @see evas_key_modifier_get
11854 * @see evas_key_modifier_on
11855 * @see evas_key_modifier_off
11856 * @see evas_key_modifier_is_set
11857 *
11858 * @note If the programmer instantiates the canvas by means of the
11859 * ecore_evas_new() family of helper functions, Ecore will take
11860 * care of registering on it all standard modifiers: "Shift",
11861 * "Control", "Alt", "Meta", "Hyper", "Super".
11862 */
11863EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
11864
11865/**
11866 * Removes the @p keyname key from the current list of modifier keys
11867 * on canvas @e.
11868 *
11869 * @param e The pointer to the Evas canvas
11870 * @param keyname The name of the key to remove from the modifiers list.
11871 *
11872 * @see evas_key_modifier_add
11873 * @see evas_key_modifier_get
11874 * @see evas_key_modifier_on
11875 * @see evas_key_modifier_off
11876 * @see evas_key_modifier_is_set
11877 */
11878EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
11879
11880/**
11881 * Adds the @p keyname key to the current list of lock keys.
11882 *
11883 * @param e The pointer to the Evas canvas
11884 * @param keyname The name of the key to add to the locks list.
11885 *
11886 * Locks are keys like caps lock, num lock or scroll lock, i.e., keys
11887 * which are meant to be pressed once -- toggling a binary state which
11888 * is bound to it -- and thus altering the behavior of all
11889 * subsequently pressed keys somehow, depending on its state. Evas is
11890 * so that these keys can be defined by the user.
11891 *
11892 * This allows custom locks to be added to the evas system at run
11893 * time. It is then possible to set and unset lock keys
11894 * programmatically for other parts of the program to check and act
11895 * on. Programmers using Evas would check for lock keys on key event
11896 * callbacks using evas_key_lock_is_set().
11897 *
11898 * @see evas_key_lock_get
11899 * @see evas_key_lock_del
11900 * @see evas_key_lock_on
11901 * @see evas_key_lock_off
11902 * @see evas_key_lock_is_set
11903 *
11904 * @note If the programmer instantiates the canvas by means of the
11905 * ecore_evas_new() family of helper functions, Ecore will take
11906 * care of registering on it all standard lock keys: "Caps_Lock",
11907 * "Num_Lock", "Scroll_Lock".
11908 */
11909EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
11910
11911/**
11912 * Removes the @p keyname key from the current list of lock keys on
11913 * canvas @e.
11914 *
11915 * @param e The pointer to the Evas canvas
11916 * @param keyname The name of the key to remove from the locks list.
11917 *
11918 * @see evas_key_lock_get
11919 * @see evas_key_lock_add
11920 * @see evas_key_lock_on
11921 * @see evas_key_lock_off
11922 */
11923EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
11924
11925
11926/**
11927 * Enables or turns on programmatically the modifier key with name @p
11928 * keyname.
11929 *
11930 * @param e The pointer to the Evas canvas
11931 * @param keyname The name of the modifier to enable.
11932 *
11933 * The effect will be as if the key was pressed for the whole time
11934 * between this call and a matching evas_key_modifier_off().
11935 *
11936 * @see evas_key_modifier_add
11937 * @see evas_key_modifier_get
11938 * @see evas_key_modifier_off
11939 * @see evas_key_modifier_is_set
11940 */
11941EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
11942
11943/**
11944 * Disables or turns off programmatically the modifier key with name
11945 * @p keyname.
11946 *
11947 * @param e The pointer to the Evas canvas
11948 * @param keyname The name of the modifier to disable.
11949 *
11950 * @see evas_key_modifier_add
11951 * @see evas_key_modifier_get
11952 * @see evas_key_modifier_on
11953 * @see evas_key_modifier_is_set
11954 */
11955EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
11956
11957/**
11958 * Enables or turns on programmatically the lock key with name @p
11959 * keyname.
11960 *
11961 * @param e The pointer to the Evas canvas
11962 * @param keyname The name of the lock to enable.
11963 *
11964 * The effect will be as if the key was put on its active state after
11965 * this call.
11966 *
11967 * @see evas_key_lock_get
11968 * @see evas_key_lock_add
11969 * @see evas_key_lock_del
11970 * @see evas_key_lock_off
11971 */
11972EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
11973
11974/**
11975 * Disables or turns off programmatically the lock key with name @p
11976 * keyname.
11977 *
11978 * @param e The pointer to the Evas canvas
11979 * @param keyname The name of the lock to disable.
11980 *
11981 * The effect will be as if the key was put on its inactive state
11982 * after this call.
11983 *
11984 * @see evas_key_lock_get
11985 * @see evas_key_lock_add
11986 * @see evas_key_lock_del
11987 * @see evas_key_lock_on
11988 */
11989EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
11990
11991
11992/**
11993 * Creates a bit mask from the @p keyname @b modifier key. Values
11994 * returned from different calls to it may be ORed together,
11995 * naturally.
11996 *
11997 * @param e The canvas whom to query the bit mask from.
11998 * @param keyname The name of the modifier key to create the mask for.
11999 *
12000 * @returns the bit mask or 0 if the @p keyname key wasn't registered as a
12001 * modifier for canvas @p e.
12002 *
12003 * This function is meant to be using in conjunction with
12004 * evas_object_key_grab()/evas_object_key_ungrab(). Go check their
12005 * documentation for more information.
12006 *
12007 * @see evas_key_modifier_add
12008 * @see evas_key_modifier_get
12009 * @see evas_key_modifier_on
12010 * @see evas_key_modifier_off
12011 * @see evas_key_modifier_is_set
12012 * @see evas_object_key_grab
12013 * @see evas_object_key_ungrab
12014 */
12015EAPI Evas_Modifier_Mask evas_key_modifier_mask_get (const Evas *e, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
12016
12017
12018/**
12019 * Requests @p keyname key events be directed to @p obj.
12020 *
12021 * @param obj the object to direct @p keyname events to.
12022 * @param keyname the key to request events for.
12023 * @param modifiers a mask of modifiers that must be present to
12024 * trigger the event.
12025 * @param not_modifiers a mask of modifiers that must @b not be present
12026 * to trigger the event.
12027 * @param exclusive request that the @p obj is the only object
12028 * receiving the @p keyname events.
12029 * @return @c EINA_TRUE, if the call succeeded, @c EINA_FALSE otherwise.
12030 *
12031 * Key grabs allow one or more objects to receive key events for
12032 * specific key strokes even if other objects have focus. Whenever a
12033 * key is grabbed, only the objects grabbing it will get the events
12034 * for the given keys.
12035 *
12036 * @p keyname is a platform dependent symbolic name for the key
12037 * pressed (see @ref Evas_Keys for more information).
12038 *
12039 * @p modifiers and @p not_modifiers are bit masks of all the
12040 * modifiers that must and mustn't, respectively, be pressed along
12041 * with @p keyname key in order to trigger this new key
12042 * grab. Modifiers can be things such as Shift and Ctrl as well as
12043 * user defigned types via evas_key_modifier_add(). Retrieve them with
12044 * evas_key_modifier_mask_get() or use @c 0 for empty masks.
12045 *
12046 * @p exclusive will make the given object the only one permitted to
12047 * grab the given key. If given @c EINA_TRUE, subsequent calls on this
12048 * function with different @p obj arguments will fail, unless the key
12049 * is ungrabbed again.
12050 *
12051 * Example code follows.
12052 * @dontinclude evas-events.c
12053 * @skip if (d.focus)
12054 * @until else
12055 *
12056 * See the full example @ref Example_Evas_Events "here".
12057 *
12058 * @see evas_object_key_ungrab
12059 * @see evas_object_focus_set
12060 * @see evas_object_focus_get
12061 * @see evas_focus_get
12062 * @see evas_key_modifier_add
12063 */
12064EAPI 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);
12065
12066/**
12067 * Removes the grab on @p keyname key events by @p obj.
12068 *
12069 * @param obj the object that has an existing key grab.
12070 * @param keyname the key the grab is set for.
12071 * @param modifiers a mask of modifiers that must be present to
12072 * trigger the event.
12073 * @param not_modifiers a mask of modifiers that must not not be
12074 * present to trigger the event.
12075 *
12076 * Removes a key grab on @p obj if @p keyname, @p modifiers, and @p
12077 * not_modifiers match.
12078 *
12079 * Example code follows.
12080 * @dontinclude evas-events.c
12081 * @skip got here by key grabs
12082 * @until }
12083 *
12084 * See the full example @ref Example_Evas_Events "here".
12085 *
12086 * @see evas_object_key_grab
12087 * @see evas_object_focus_set
12088 * @see evas_object_focus_get
12089 * @see evas_focus_get
12090 */
12091EAPI 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);
12092
12093/**
12094 * @}
12095 */
12096
12097/**
12098 * @defgroup Evas_Touch_Point_List Touch Point List Functions
12099 *
12100 * Functions to get information of touched points in the Evas.
12101 *
12102 * Evas maintains list of touched points on the canvas. Each point has
12103 * its co-ordinates, id and state. You can get the number of touched
12104 * points and information of each point using evas_touch_point_list
12105 * functions.
12106 *
12107 * @ingroup Evas_Canvas
12108 */
12109
12110/**
12111 * @addtogroup Evas_Touch_Point_List
12112 * @{
12113 */
12114
12115/**
12116 * Get the number of touched point in the evas.
12117 *
12118 * @param e The pointer to the Evas canvas.
12119 * @return The number of touched point on the evas.
12120 *
12121 * New touched point is added to the list whenever touching the evas
12122 * and point is removed whenever removing touched point from the evas.
12123 *
12124 * Example:
12125 * @code
12126 * extern Evas *evas;
12127 * int count;
12128 *
12129 * count = evas_touch_point_list_count(evas);
12130 * printf("The count of touch points: %i\n", count);
12131 * @endcode
12132 *
12133 * @see evas_touch_point_list_nth_xy_get()
12134 * @see evas_touch_point_list_nth_id_get()
12135 * @see evas_touch_point_list_nth_state_get()
12136 */
12137EAPI unsigned int evas_touch_point_list_count(Evas *e) EINA_ARG_NONNULL(1);
12138
12139/**
12140 * This function returns the nth touch point's co-ordinates.
12141 *
12142 * @param e The pointer to the Evas canvas.
12143 * @param n The number of the touched point (0 being the first).
12144 * @param x The pointer to a Evas_Coord to be filled in.
12145 * @param y The pointer to a Evas_Coord to be filled in.
12146 *
12147 * Touch point's co-ordinates is updated whenever moving that point
12148 * on the canvas.
12149 *
12150 * Example:
12151 * @code
12152 * extern Evas *evas;
12153 * Evas_Coord x, y;
12154 *
12155 * if (evas_touch_point_list_count(evas))
12156 * {
12157 * evas_touch_point_nth_xy_get(evas, 0, &x, &y);
12158 * printf("The first touch point's co-ordinate: (%i, %i)\n", x, y);
12159 * }
12160 * @endcode
12161 *
12162 * @see evas_touch_point_list_count()
12163 * @see evas_touch_point_list_nth_id_get()
12164 * @see evas_touch_point_list_nth_state_get()
12165 */
12166EAPI void evas_touch_point_list_nth_xy_get(Evas *e, unsigned int n, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
12167
12168/**
12169 * This function returns the @p id of nth touch point.
12170 *
12171 * @param e The pointer to the Evas canvas.
12172 * @param n The number of the touched point (0 being the first).
12173 * @return id of nth touch point, if the call succeeded, -1 otherwise.
12174 *
12175 * The point which comes from Mouse Event has @p id 0 and The point
12176 * which comes from Multi Event has @p id that is same as Multi
12177 * Event's device id.
12178 *
12179 * Example:
12180 * @code
12181 * extern Evas *evas;
12182 * int id;
12183 *
12184 * if (evas_touch_point_list_count(evas))
12185 * {
12186 * id = evas_touch_point_nth_id_get(evas, 0);
12187 * printf("The first touch point's id: %i\n", id);
12188 * }
12189 * @endcode
12190 *
12191 * @see evas_touch_point_list_count()
12192 * @see evas_touch_point_list_nth_xy_get()
12193 * @see evas_touch_point_list_nth_state_get()
12194 */
12195EAPI int evas_touch_point_list_nth_id_get(Evas *e, unsigned int n) EINA_ARG_NONNULL(1);
12196
12197/**
12198 * This function returns the @p state of nth touch point.
12199 *
12200 * @param e The pointer to the Evas canvas.
12201 * @param n The number of the touched point (0 being the first).
12202 * @return @p state of nth touch point, if the call succeeded,
12203 * EVAS_TOUCH_POINT_CANCEL otherwise.
12204 *
12205 * The point's @p state is EVAS_TOUCH_POINT_DOWN when pressed,
12206 * EVAS_TOUCH_POINT_STILL when the point is not moved after pressed,
12207 * EVAS_TOUCH_POINT_MOVE when moved at least once after pressed and
12208 * EVAS_TOUCH_POINT_UP when released.
12209 *
12210 * Example:
12211 * @code
12212 * extern Evas *evas;
12213 * Evas_Touch_Point_State state;
12214 *
12215 * if (evas_touch_point_list_count(evas))
12216 * {
12217 * state = evas_touch_point_nth_state_get(evas, 0);
12218 * printf("The first touch point's state: %i\n", state);
12219 * }
12220 * @endcode
12221 *
12222 * @see evas_touch_point_list_count()
12223 * @see evas_touch_point_list_nth_xy_get()
12224 * @see evas_touch_point_list_nth_id_get()
12225 */
12226EAPI Evas_Touch_Point_State evas_touch_point_list_nth_state_get(Evas *e, unsigned int n) EINA_ARG_NONNULL(1);
12227
12228/**
12229 * @}
12230 */
12231
12232#ifdef __cplusplus
12233}
12234#endif
12235
12236#endif