7 @author Carsten Haitzler <raster@@rasterman.com>
8 @author Till Adam <till@@adam-lilienthal.de>
9 @author Steve Ireland <sireland@@pobox.com>
10 @author Brett Nash <nash@@nash.id.au>
11 @author Tilman Sauerbeck <tilman@@code-monkey.de>
12 @author Corey Donohoe <atmos@@atmos.org>
13 @author Yuri Hudobin <glassy_ape@@users.sourceforge.net>
14 @author Nathan Ingersoll <ningerso@@d.umn.edu>
15 @author Willem Monsuwe <willem@@stack.nl>
16 @author Jose O Gonzalez <jose_ogp@@juno.com>
17 @author Bernhard Nemec <Bernhard.Nemec@@viasyshc.com>
18 @author Jorge Luis Zapata Muga <jorgeluis.zapata@@gmail.com>
19 @author Cedric Bail <cedric.bail@@free.fr>
20 @author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
21 @author Vincent Torri <vtorri@@univ-evry.fr>
22 @author Tim Horton <hortont424@@gmail.com>
23 @author Tom Hacohen <tom@@stosb.com>
24 @author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
25 @author Iván Briano <ivan@@profusion.mobi>
26 @author Gustavo Lima Chaves <glima@@profusion.mobi>
27 @author Samsung Electronics <tbd>
28 @author Samsung SAIT <tbd>
29 @author Sung W. Park <sungwoo@@gmail.com>
30 @author Jiyoun Park <jy0703.park@@samsung.com>
31 @author Myoungwoon Roy Kim(roy_kim) <myoungwoon.kim@@samsung.com> <myoungwoon@@gmail.com>
32 @author Thierry el Borgi <thierry@@substantiel.fr>
33 @author ChunEon Park <hermet@@hermet.pe.kr>
36 @section toc Table of Contents
43 @li @ref intro_example
46 @section intro What is Evas?
48 Evas is a clean display canvas API for several target display systems that
49 can draw anti-aliased text, smooth super and sub-sampled scaled images,
50 alpha-blend objects much and more.
52 It abstracts any need to know much about what the characteristics of your
53 display system are or what graphics calls are used to draw them and how. It
54 deals on an object level where all you do is create and manipulate objects
55 in a canvas, set their properties, and the rest is done for you.
57 Evas optimises the rendering pipeline to minimise effort in redrawing changes
58 made to the canvas and so takes this work out of the programmers hand,
59 saving a lot of time and energy.
61 It's small and lean, designed to work on embedded systems all the way to
62 large and powerful multi-cpu workstations. It can be compiled to only have
63 the features you need for your target platform if you so wish, thus keeping
64 it small and lean. It has several display back-ends, letting it display on
65 several display systems, making it portable for cross-device and
66 cross-platform development.
68 @subsection intro_not_evas What Evas is not?
70 Evas is not a widget set or widget toolkit, however it is their
71 base. See Elementary (http://docs.enlightenment.org/auto/elementary/)
72 for a toolkit based on Evas, Edje, Ecore and other Enlightenment
75 It is not dependent or aware of main loops, input or output
76 systems. Input should be polled from various sources and feed them to
77 Evas. Similarly, it will not create windows or report windows updates
78 to your system, rather just drawing the pixels and reporting to the
79 user the areas that were changed. Of course these operations are quite
80 common and thus they are ready to use in Ecore, particularly in
81 Ecore_Evas (http://docs.enlightenment.org/auto/ecore/).
84 @section work How does Evas work?
86 Evas is a canvas display library. This is markedly different from most
87 display and windowing systems as a Canvas is structural and is also a state
88 engine, whereas most display and windowing systems are immediate mode display
89 targets. Evas handles the logic between a structural display via its' state
90 engine, and controls the target windowing system in order to produce
91 rendered results of the current canvases state on the display.
93 Immediate mode display systems retain very little, or no state. A program
94 will execute a series of commands, as in the pseudo code:
97 draw line from position (0, 0) to position (100, 200);
99 draw rectangle from position (10, 30) to position (50, 500);
101 bitmap_handle = create_bitmap();
102 scale bitmap_handle to size 100 x 100;
103 draw image bitmap_handle at position (10, 30);
106 The series of commands is executed by the windowing system and the results
107 are displayed on the screen (normally). Once the commands are executed the
108 display system has little or no idea of how to reproduce this image again,
109 and so has to be instructed by the application how to redraw sections of the
110 screen whenever needed. Each successive command will be executed as
111 instructed by the application and either emulated by software or sent to the
112 graphics hardware on the device to be performed.
114 The advantage of such a system is that it is simple, and gives a program
115 tight control over how something looks and is drawn. Given the increasing
116 complexity of displays and demands by users to have better looking
117 interfaces, more and more work is needing to be done at this level by the
118 internals of widget sets, custom display widgets and other programs. This
119 means more and more logic and display rendering code needs to be written
120 time and time again, each time the application needs to figure out how to
121 minimise redraws so that display is fast and interactive, and keep track of
122 redraw logic. The power comes at a high-price, lots of extra code and work.
123 Programmers not very familiar with graphics programming will often make
124 mistakes at this level and produce code that is sub optimal. Those familiar
125 with this kind of programming will simply get bored by writing the same code
128 For example, if in the above scene, the windowing system requires the
129 application to redraw the area from 0, 0 to 50, 50 (also referred as
130 "expose event"), then the programmer must calculate manually the
131 updates and repaint it again:
134 Redraw from position (0, 0) to position (50, 50):
136 // what was in area (0, 0, 50, 50)?
138 // 1. intersection part of line (0, 0) to (100, 200)?
139 draw line from position (0, 0) to position (25, 50);
141 // 2. intersection part of rectangle (10, 30) to (50, 500)?
142 draw rectangle from position (10, 30) to position (50, 50)
144 // 3. intersection part of image at (10, 30), size 100 x 100?
145 bitmap_subimage = subregion from position (0, 0) to position (40, 20)
146 draw image bitmap_subimage at position (10, 30);
149 The clever reader might have noticed that, if all elements in the
150 above scene are opaque, then the system is doing useless paints: part
151 of the line is behind the rectangle, and part of the rectangle is
152 behind the image. These useless paints tends to be very costly, as
153 pixels tend to be 4 bytes in size, thus an overlapping region of 100 x
154 100 pixels is around 40000 useless writes! The developer could write
155 code to calculate the overlapping areas and avoid painting then, but
156 then it should be mixed with the "expose event" handling mentioned
157 above and quickly one realizes the initially simpler method became
160 Evas is a structural system in which the programmer creates and manages
161 display objects and their properties, and as a result of this higher level
162 state management, the canvas is able to redraw the set of objects when
163 needed to represent the current state of the canvas.
165 For example, the pseudo code:
168 line_handle = create_line();
169 set line_handle from position (0, 0) to position (100, 200);
172 rectangle_handle = create_rectangle();
173 move rectangle_handle to position (10, 30);
174 resize rectangle_handle to size 40 x 470;
175 show rectangle_handle;
177 bitmap_handle = create_bitmap();
178 scale bitmap_handle to size 100 x 100;
179 move bitmap_handle to position (10, 30);
185 This may look longer, but when the display needs to be refreshed or updated,
186 the programmer only moves, resizes, shows, hides etc. the objects that they
187 need to change. The programmer simply thinks at the object logic level, and
188 the canvas software does the rest of the work for them, figuring out what
189 actually changed in the canvas since it was last drawn, how to most
190 efficiently redraw he canvas and its contents to reflect the current state,
191 and then it can go off and do the actual drawing of the canvas.
193 This lets the programmer think in a more natural way when dealing with a
194 display, and saves time and effort of working out how to load and display
195 images, render given the current display system etc. Since Evas also is
196 portable across different display systems, this also gives the programmer
197 the ability to have their code ported and display on different display
198 systems with very little work.
200 Evas can be seen as a display system that stands somewhere between a widget
201 set and an immediate mode display system. It retains basic display logic,
202 but does very little high-level logic such as scrollbars, sliders, push
206 @section compiling How to compile using Evas ?
208 Evas is a library your application links to. The procedure for this is very
209 simple. You simply have to compile your application with the appropriate
210 compiler flags that the @p pkg-config script outputs. For example:
212 Compiling C or C++ files into object files:
215 gcc -c -o main.o main.c `pkg-config --cflags evas`
218 Linking object files into a binary executable:
221 gcc -o my_application main.o `pkg-config --libs evas`
224 You simply have to make sure that pkg-config is in your shell's PATH (see
225 the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig
226 or its path is in the PKG_CONFIG_PATH environment variable. It's that simple
227 to link and use Evas once you have written your code to use it.
229 Since the program is linked to Evas, it is now able to use any advertised
230 API calls to display graphics in a canvas managed by Evas, as well as use
231 the API calls provided to manage data as well.
233 You should make sure you add any extra compile and link flags to your
234 compile commands that your application may need as well. The above example
235 is only guaranteed to make Evas add it's own requirements.
238 @section install How is it installed?
250 @section next_steps Next Steps
252 After you understood what Evas is and installed it in your system you
253 should proceed understanding the programming interface for all
254 objects, then see the specific for the most used elements. We'd
255 recommend you to take a while to learn Ecore
256 (http://docs.enlightenment.org/auto/ecore/) and Edje
257 (http://docs.enlightenment.org/auto/edje/) as they will likely save
258 you tons of work compared to using just Evas directly.
262 @li @ref Evas_Object_Group
263 @li @ref Evas_Object_Rectangle
264 @li @ref Evas_Object_Image
265 @li @ref Evas_Object_Text
266 @li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group to define
267 an object that provides custom functions to handle clipping,
268 hiding, moving, resizing, setting the color and more. These could
269 be as simple as a group of objects that move together (see @ref
270 Evas_Smart_Object_Clipped). These smart objects can implement what
271 ends to be a widget, providing some intelligence (thus the name),
272 like a button or check box.
274 @section intro_example Introductory Example
276 @include evas-buffer-simple.c
291 # ifdef EFL_EVAS_BUILD
293 # define EAPI __declspec(dllexport)
296 # endif /* ! DLL_EXPORT */
298 # define EAPI __declspec(dllimport)
299 # endif /* ! EFL_EVAS_BUILD */
303 # define EAPI __attribute__ ((visibility("default")))
310 #endif /* ! _WIN32 */
316 #define EVAS_VERSION_MAJOR 1
317 #define EVAS_VERSION_MINOR 0
319 typedef struct _Evas_Version
327 EAPI extern Evas_Version *evas_version;
331 * @brief These routines are used for Evas library interaction.
333 * @todo check boolean return values and convert to Eina_Bool
334 * @todo change all api to use EINA_SAFETY_*
335 * @todo finish api documentation
338 /* BiDi exposed stuff */
340 typedef enum _Evas_BiDi_Direction
342 EVAS_BIDI_DIRECTION_NATURAL,
343 EVAS_BIDI_DIRECTION_LTR,
344 EVAS_BIDI_DIRECTION_RTL
345 } Evas_BiDi_Direction;
348 * Identifier of callbacks to be set for Evas canvases or Evas
351 * @see evas_object_event_callback_add()
352 * @see evas_event_callback_add()
354 typedef enum _Evas_Callback_Type
357 * The following events are only for use with Evas objects, with
358 * evas_object_event_callback_add():
360 EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */
361 EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
362 EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
363 EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
364 EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
365 EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
366 EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
367 EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
368 EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
369 EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
370 EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
371 EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
372 EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
373 EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
374 EVAS_CALLBACK_SHOW, /**< Show Event */
375 EVAS_CALLBACK_HIDE, /**< Hide Event */
376 EVAS_CALLBACK_MOVE, /**< Move Event */
377 EVAS_CALLBACK_RESIZE, /**< Resize Event */
378 EVAS_CALLBACK_RESTACK, /**< Restack Event */
379 EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
380 EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
381 EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
382 EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */
385 * The following events are only for use with Evas canvases, with
386 * evas_event_callback_add():
388 EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
389 EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
390 EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */
391 EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
392 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
393 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
396 * More Evas object event types - see evas_object_event_callback_add():
398 EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanims in Evas that throw out original image data) */
400 EVAS_CALLBACK_LAST /**< kept as last element/sentinel -- not really an event */
401 } Evas_Callback_Type; /**< The types of events triggering a callback */
404 * Flags for Mouse Button events
406 typedef enum _Evas_Button_Flags
408 EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
409 EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< This mouse button press was the 2nd press of a double click */
410 EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< This mouse button press was the 3rd press of a triple click */
411 } Evas_Button_Flags; /**< Flags for Mouse Button events */
416 typedef enum _Evas_Event_Flags
418 EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
419 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 */
420 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 */
421 } Evas_Event_Flags; /**< Flags for Events */
424 * Flags for Font Hinting
425 * @ingroup Evas_Font_Group
427 typedef enum _Evas_Font_Hinting_Flags
429 EVAS_FONT_HINTING_NONE, /**< No font hinting */
430 EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
431 EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
432 } Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */
435 * Colorspaces for pixel data supported by Evas
436 * @ingroup Evas_Object_Image
438 typedef enum _Evas_Colorspace
440 EVAS_COLORSPACE_ARGB8888, /**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */
441 /* these are not currently supported - but planned for the future */
442 EVAS_COLORSPACE_YCBCR422P601_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-601 specifications. The data poitned to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */
443 EVAS_COLORSPACE_YCBCR422P709_PL,/**< YCbCr 4:2:2 Planar, ITU.BT-709 specifications. The data poitned to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */
444 EVAS_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */
445 EVAS_COLORSPACE_GRY8 /**< 8bit grayscale */
446 } Evas_Colorspace; /**< Colorspaces for pixel data supported by Evas */
449 * How to pack items into cells in a table.
450 * @ingroup Evas_Object_Table
452 typedef enum _Evas_Object_Table_Homogeneous_Mode
454 EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0,
455 EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1,
456 EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2
457 } Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode. */
459 typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< A generic rectangle handle */
460 typedef struct _Evas_Point Evas_Point; /**< integer point */
462 typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */
463 typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */
465 typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */
466 typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */
469 * @typedef Evas_Smart_Class
470 * A smart object base class
471 * @ingroup Evas_Smart_Group
473 typedef struct _Evas_Smart_Class Evas_Smart_Class;
476 * @typedef Evas_Smart_Cb_Description
477 * A smart object callback description, used to provide introspection
478 * @ingroup Evas_Smart_Group
480 typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
484 * An opaque handle to map points
485 * @see evas_map_new()
486 * @see evas_map_free()
487 * @see evas_map_dup()
488 * @ingroup Evas_Object_Group_Map
490 typedef struct _Evas_Map Evas_Map;
494 * An opaque handle to an Evas canvas.
497 * @ingroup Evas_Canvas
499 typedef struct _Evas Evas;
502 * @typedef Evas_Object
503 * An Evas Object handle.
504 * @ingroup Evas_Object_Group
506 typedef struct _Evas_Object Evas_Object;
508 typedef void Evas_Performance; /**< An Evas Performance handle */
509 typedef struct _Evas_Modifier Evas_Modifier; /**< An opaque type containing information on which modifier keys are registered in an Evas canvas */
510 typedef struct _Evas_Lock Evas_Lock; /**< An opaque type containing information on which lock keys are registered in an Evas canvas */
511 typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
512 typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< A generic datatype for engine specific native surface information */
513 typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */
515 typedef int Evas_Coord;
516 typedef int Evas_Font_Size;
517 typedef int Evas_Angle;
519 struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */
521 Evas_Coord x; /**< top-left x co-ordinate of rectangle */
522 Evas_Coord y; /**< top-left y co-ordinate of rectangle */
523 Evas_Coord w; /**< width of rectangle */
524 Evas_Coord h; /**< height of rectangle */
532 struct _Evas_Coord_Point
537 struct _Evas_Coord_Precision_Point
543 struct _Evas_Position
546 Evas_Coord_Point canvas;
549 struct _Evas_Precision_Position
552 Evas_Coord_Precision_Point canvas;
555 typedef enum _Evas_Aspect_Control
557 EVAS_ASPECT_CONTROL_NONE = 0, /**< Preference on scaling unset */
558 EVAS_ASPECT_CONTROL_NEITHER = 1, /**< Same effect as unset preference on scaling */
559 EVAS_ASPECT_CONTROL_HORIZONTAL = 2, /**< Use all horizontal container space to place an object, using the given aspect */
560 EVAS_ASPECT_CONTROL_VERTICAL = 3, /**< Use all vertical container space to place an object, using the given aspect */
561 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 */
562 } Evas_Aspect_Control; /**< Aspect types/policies for scaling size hints, used for evas_object_size_hint_aspect_set() */
564 typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< A source description of pixels for importing pixels */
565 typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< A generic Evas Engine information structure */
566 typedef struct _Evas_Device Evas_Device; /**< A source device handle - where the event came from */
567 typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
568 typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
569 typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
570 typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
571 typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
572 typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
573 typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
574 typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
575 typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
576 typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
577 typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
578 typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< Event structure for #EVAS_CALLBACK_HOLD event callbacks */
580 typedef enum _Evas_Load_Error
582 EVAS_LOAD_ERROR_NONE = 0, /**< No error on load */
583 EVAS_LOAD_ERROR_GENERIC = 1, /**< A non-specific error occurred */
584 EVAS_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< File (or file path) does not exist */
585 EVAS_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission deinied to an existing file (or path) */
586 EVAS_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Allocation of resources failure prevented load */
587 EVAS_LOAD_ERROR_CORRUPT_FILE = 5, /**< File corrupt (but was detected as a known format) */
588 EVAS_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */
589 } Evas_Load_Error; /**< Evas image load error codes one can get - see evas_load_error_str() too. */
592 typedef enum _Evas_Alloc_Error
594 EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */
595 EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */
596 EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded, but extra memory had to be found by freeing up speculative resources */
597 } Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */
599 typedef enum _Evas_Fill_Spread
601 EVAS_TEXTURE_REFLECT = 0, /**< image fill tiling mode - tiling reflects */
602 EVAS_TEXTURE_REPEAT = 1, /**< tiling repeats */
603 EVAS_TEXTURE_RESTRICT = 2, /**< tiling clamps - range offset ignored */
604 EVAS_TEXTURE_RESTRICT_REFLECT = 3, /**< tiling clamps and any range offset reflects */
605 EVAS_TEXTURE_RESTRICT_REPEAT = 4, /**< tiling clamps and any range offset repeats */
606 EVAS_TEXTURE_PAD = 5 /**< tiling extends with end values */
607 } Evas_Fill_Spread; /**< Fill types used for evas_object_image_fill_spread_set() */
609 typedef enum _Evas_Pixel_Import_Pixel_Format
611 EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
612 EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
613 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 */
614 } Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
616 struct _Evas_Pixel_Import_Source
618 Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
619 int w, h; /**< width and height of source in pixels */
620 void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
623 /* magic version number to know what the native surf struct looks like */
624 #define EVAS_NATIVE_SURFACE_VERSION 2
626 typedef enum _Evas_Native_Surface_Type
628 EVAS_NATIVE_SURFACE_NONE,
629 EVAS_NATIVE_SURFACE_X11,
630 EVAS_NATIVE_SURFACE_OPENGL
631 } Evas_Native_Surface_Type;
633 struct _Evas_Native_Surface
636 Evas_Native_Surface_Type type;
639 void *visual; /**< visual of the pixmap to use (Visual) */
640 unsigned long pixmap; /**< pixmap id to use (Pixmap) */
643 unsigned int texture_id; /**< opengl texture id to use from glGenTextures() */
644 unsigned int framebuffer_id; /**< 0 if not a FBO, FBO id otherwise from glGenFramebuffers() */
645 unsigned int internal_format; /**< same as 'internalFormat' for glTexImage2D() */
646 unsigned int format; /**< same as 'format' for glTexImage2D() */
647 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) */
652 #define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
653 #define EVAS_LAYER_MAX 32767 /**< top-most layer number */
655 #define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
656 #define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
657 #define EVAS_TEXT_INVALID -1 /**< Not used for anything */
658 #define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
660 #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() */
661 #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() */
662 #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) */
663 #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) */
664 #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 */
665 #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 */
668 * How the object should be rendered to output.
669 * @ingroup Evas_Object_Group_Extras
671 typedef enum _Evas_Render_Op
673 EVAS_RENDER_BLEND = 0, /**< default op: d = d*(1-sa) + s */
674 EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
675 EVAS_RENDER_COPY = 2, /**< d = s */
676 EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
677 EVAS_RENDER_ADD = 4, /**< d = d + s */
678 EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
679 EVAS_RENDER_SUB = 6, /**< d = d - s */
680 EVAS_RENDER_SUB_REL = 7, /**< d = d - s*da */
681 EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
682 EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
683 EVAS_RENDER_MASK = 10, /**< d = d*sa */
684 EVAS_RENDER_MUL = 11 /**< d = d*s */
685 } Evas_Render_Op; /**< How the object should be rendered to output. */
687 typedef enum _Evas_Border_Fill_Mode
689 EVAS_BORDER_FILL_NONE = 0,
690 EVAS_BORDER_FILL_DEFAULT = 1,
691 EVAS_BORDER_FILL_SOLID = 2
692 } Evas_Border_Fill_Mode;
694 typedef enum _Evas_Image_Scale_Hint
696 EVAS_IMAGE_SCALE_HINT_NONE = 0,
697 EVAS_IMAGE_SCALE_HINT_DYNAMIC = 1,
698 EVAS_IMAGE_SCALE_HINT_STATIC = 2
699 } Evas_Image_Scale_Hint;
701 typedef enum _Evas_Engine_Render_Mode
703 EVAS_RENDER_MODE_BLOCKING = 0,
704 EVAS_RENDER_MODE_NONBLOCKING = 1,
705 } Evas_Engine_Render_Mode;
707 typedef enum _Evas_Image_Content_Hint
709 EVAS_IMAGE_CONTENT_HINT_NONE = 0,
710 EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1,
711 EVAS_IMAGE_CONTENT_HINT_STATIC = 2
712 } Evas_Image_Content_Hint;
714 struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
716 int magic; /**< Magic number */
719 struct _Evas_Event_Mouse_Down /** Mouse button press event */
721 int button; /**< Mouse button number that went down (1 - 32) */
724 Evas_Coord_Point canvas;
727 Evas_Modifier *modifiers;
730 Evas_Button_Flags flags;
731 unsigned int timestamp;
732 Evas_Event_Flags event_flags;
736 struct _Evas_Event_Mouse_Up /** Mouse button release event */
738 int button; /**< Mouse button number that was raised (1 - 32) */
741 Evas_Coord_Point canvas;
744 Evas_Modifier *modifiers;
747 Evas_Button_Flags flags;
748 unsigned int timestamp;
749 Evas_Event_Flags event_flags;
753 struct _Evas_Event_Mouse_In /** Mouse enter event */
755 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
758 Evas_Coord_Point canvas;
761 Evas_Modifier *modifiers;
763 unsigned int timestamp;
764 Evas_Event_Flags event_flags;
768 struct _Evas_Event_Mouse_Out /** Mouse leave event */
770 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
774 Evas_Coord_Point canvas;
777 Evas_Modifier *modifiers;
779 unsigned int timestamp;
780 Evas_Event_Flags event_flags;
784 struct _Evas_Event_Mouse_Move /** Mouse button down event */
786 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
788 Evas_Position cur, prev;
791 Evas_Modifier *modifiers;
793 unsigned int timestamp;
794 Evas_Event_Flags event_flags;
798 struct _Evas_Event_Mouse_Wheel /** Wheel event */
800 int direction; /* 0 = default up/down wheel FIXME: more wheel types */
801 int z; /* ...,-2,-1 = down, 1,2,... = up */
804 Evas_Coord_Point canvas;
807 Evas_Modifier *modifiers;
809 unsigned int timestamp;
810 Evas_Event_Flags event_flags;
814 struct _Evas_Event_Multi_Down /** Multi button press event */
816 int device; /**< Multi device number that went down (1 or more for extra touches) */
817 double radius, radius_x, radius_y;
818 double pressure, angle;
821 Evas_Coord_Precision_Point canvas;
824 Evas_Modifier *modifiers;
827 Evas_Button_Flags flags;
828 unsigned int timestamp;
829 Evas_Event_Flags event_flags;
833 struct _Evas_Event_Multi_Up /** Multi button release event */
835 int device; /**< Multi device number that went up (1 or more for extra touches) */
836 double radius, radius_x, radius_y;
837 double pressure, angle;
840 Evas_Coord_Precision_Point canvas;
843 Evas_Modifier *modifiers;
846 Evas_Button_Flags flags;
847 unsigned int timestamp;
848 Evas_Event_Flags event_flags;
852 struct _Evas_Event_Multi_Move /** Multi button down event */
854 int device; /**< Multi device number that moved (1 or more for extra touches) */
855 double radius, radius_x, radius_y;
856 double pressure, angle;
858 Evas_Precision_Position cur;
861 Evas_Modifier *modifiers;
863 unsigned int timestamp;
864 Evas_Event_Flags event_flags;
868 struct _Evas_Event_Key_Down /** Key press event */
870 char *keyname; /**< The string name of the key pressed */
872 Evas_Modifier *modifiers;
875 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
876 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
877 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 */
878 unsigned int timestamp;
879 Evas_Event_Flags event_flags;
883 struct _Evas_Event_Key_Up /** Key release event */
885 char *keyname; /**< The string name of the key released */
887 Evas_Modifier *modifiers;
890 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
891 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
892 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 */
893 unsigned int timestamp;
894 Evas_Event_Flags event_flags;
898 struct _Evas_Event_Hold /** Hold change event */
900 int hold; /**< The hold flag */
903 unsigned int timestamp;
904 Evas_Event_Flags event_flags;
909 * How the mouse pointer should be handled by Evas.
911 * In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button
912 * is pressed down over an object and held, with the mouse pointer
913 * being moved outside of it, the pointer still behaves as being bound
914 * to that object, albeit out of its drawing region. When the button
915 * is released, the event will be fed to the object, that may check if
916 * the final position is over it or not and do something about it.
918 * In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will
919 * always be bound to the object right below it.
921 * @ingroup Evas_Object_Group_Extras
923 typedef enum _Evas_Object_Pointer_Mode
925 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
926 EVAS_OBJECT_POINTER_MODE_NOGRAB /**< pointer always bound to the object right below it */
927 } Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
929 typedef void (*Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info);
930 typedef void (*Evas_Event_Cb) (void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
931 typedef Eina_Bool (*Evas_Object_Event_Post_Cb) (void *data, Evas *e);
932 typedef void (*Evas_Object_Event_Cb) (void *data, Evas *e, Evas_Object *obj, void *event_info); /**< Evas object event callback function signature */
933 typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
936 * @defgroup Evas_Group Top Level Functions
938 * Functions that affect Evas as a whole.
944 * @return The init counter value.
946 * This function initializes Evas and increments a counter of the
947 * number of calls to it. It returs the new counter's value.
949 * @see evas_shutdown().
951 * Most EFL users wouldn't be using this function directly, because
952 * they wouldn't access Evas directly by themselves. Instead, they
953 * would be using higher level helpers, like @c ecore_evas_init().
954 * See http://docs.enlightenment.org/auto/ecore/.
956 * You should be using this if your use is something like the
957 * following. The buffer engine is just one of the many ones Evas
960 * @dontinclude evas-buffer-simple.c
963 * And being the canvas creation something like:
964 * @skip static Evas *create_canvas
965 * @until evas_output_viewport_set(canvas,
967 * Note that this is code creating an Evas canvas with no usage of
968 * Ecore helpers at all -- no linkage with Ecore on this scenario,
969 * thus. Again, this wouldn't be on Evas common usage for most
970 * developers. See the full @ref Example_Evas_Buffer_Simple "example".
972 * @ingroup Evas_Group
974 EAPI int evas_init (void);
979 * @return Evas' init counter value.
981 * This function finalizes Evas, decrementing the counter of the
982 * number of calls to the function evas_init(). This new value for the
983 * counter is returned.
987 * If you were the sole user of Evas, by means of evas_init(), you can
988 * check if it's being properly shut down by expecting a return value
991 * Example code follows.
992 * @dontinclude evas-buffer-simple.c
993 * @skip // NOTE: use ecore_evas_buffer_new
994 * @until evas_shutdown
995 * Where that function would contain:
996 * @skip evas_free(canvas)
997 * @until evas_free(canvas)
999 * Most users would be using ecore_evas_shutdown() instead, like told
1000 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
1003 * @ingroup Evas_Group
1005 EAPI int evas_shutdown (void);
1009 * Return if any allocation errors have occurred during the prior function
1010 * @return The allocation error flag
1012 * This function will return if any memory allocation errors occurred during,
1013 * and what kind they were. The return value will be one of
1014 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
1015 * with each meaning something different.
1017 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
1018 * worked as expected.
1020 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
1021 * its job and will have exited as cleanly as possible. The programmer
1022 * should consider this as a sign of very low memory and should try and safely
1023 * recover from the prior functions failure (or try free up memory elsewhere
1024 * and try again after more memory is freed).
1026 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
1027 * recovered from by evas finding memory of its own it has allocated and
1028 * freeing what it sees as not really usefully allocated memory. What is freed
1029 * may vary. Evas may reduce the resolution of images, free cached images or
1030 * fonts, trhow out pre-rendered data, reduce the complexity of change lists
1031 * etc. Evas and the program will function as per normal after this, but this
1032 * is a sign of low memory, and it is suggested that the program try and
1033 * identify memory it doesn't need, and free it.
1037 * extern Evas_Object *object;
1038 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
1040 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
1041 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
1043 * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
1044 * fprintf(stderr, " destroy object now as it cannot be used.\n");
1045 * evas_object_del(object);
1047 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1048 * my_memory_cleanup();
1050 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
1052 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1053 * my_memory_cleanup();
1057 * @ingroup Evas_Group
1059 EAPI Evas_Alloc_Error evas_alloc_error (void);
1063 * @brief Get evas' internal asynchronous events read file descriptor.
1065 * @return The canvas' asynchronous events read file descriptor.
1067 * Evas' asynchronous events are meant to be dealt with internally,
1068 * i. e., when building stuff to be glued together into the EFL
1069 * infrastructure -- a module, for example. The context which demands
1070 * its use is when calculations need to be done out of the main
1071 * thread, asynchronously, and some action must be performed after
1074 * An example of actual use of this API is for image asynchronous
1075 * preload inside evas. If the canvas was instantiated through
1076 * ecore-evas usage, ecore itself will take care of calling those
1077 * events' processing.
1079 * This function returns the read file descriptor where to get the
1080 * asynchronous events of the canvas. Naturally, other mainloops,
1081 * apart from ecore, may make use of it.
1083 * @ingroup Evas_Group
1085 EAPI int evas_async_events_fd_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE;
1088 * @brief Trigger the processing of all events waiting on the file
1089 * descriptor returned by evas_async_events_fd_get().
1091 * @return The number of events processed.
1093 * All asynchronous events queued up by evas_async_events_put() are
1094 * processed here. More precisely, the callback functions, informed
1095 * together with other event parameters, when queued, get called (with
1096 * those parameters), in that order.
1098 * @ingroup Evas_Group
1100 EAPI int evas_async_events_process (void);
1103 * Insert asynchronous events on the canvas.
1105 * @param target The target to be affected by the events.
1106 * @param type The type of callback function.
1107 * @param event_info Information about the event.
1108 * @param func The callback function pointer.
1110 * This is the way, for a routine running outside evas' main thread,
1111 * to report an asynchronous event. A callback function is informed,
1112 * whose call is to happen after evas_async_events_process() is
1115 * @ingroup Evas_Group
1117 EAPI 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);
1120 * @defgroup Evas_Canvas Canvas Functions
1122 * Low level Evas canvas functions. Sub groups will present more high
1123 * level ones, though.
1125 * Most of these functions deal with low level Evas actions, like:
1126 * @li create/destroy raw canvases, not bound to any displaying engine
1127 * @li tell a canvas i got focused (in a windowing context, for example)
1128 * @li tell a canvas a region should not be calculated anymore in rendering
1129 * @li tell a canvas to render its contents, immediately
1131 * Most users will be using Evas by means of the @c Ecore_Evas
1132 * wrapper, which deals with all the above mentioned issues
1133 * automatically for them. Thus, you'll be looking at this section
1134 * only if you're building low level stuff.
1136 * The groups within present you functions that deal with the canvas
1137 * directly, too, and not yet with its @b objects. They are the
1138 * functions you need to use at a minimum to get a working canvas.
1140 * Some of the funcions in this group are exemplified @ref
1141 * Example_Evas_Events "here".
1145 * Creates a new empty evas.
1147 * Note that before you can use the evas, you will to at a minimum:
1148 * @li Set its render method with @ref evas_output_method_set .
1149 * @li Set its viewport size with @ref evas_output_viewport_set .
1150 * @li Set its size of the canvas with @ref evas_output_size_set .
1151 * @li Ensure that the render engine is given the correct settings
1152 * with @ref evas_engine_info_set .
1154 * This function should only fail if the memory allocation fails
1156 * @note this function is very low level. Instead of using it
1157 * directly, consider using the high level functions in
1158 * Ecore_Evas such as @c ecore_evas_new(). See
1159 * http://docs.enlightenment.org/auto/ecore/.
1161 * @attention it is recommended that one calls evas_init() before
1162 * creating new canvas.
1164 * @return A new uninitialised Evas canvas on success. Otherwise, @c
1166 * @ingroup Evas_Canvas
1168 EAPI Evas *evas_new (void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
1171 * Frees the given evas and any objects created on it.
1173 * Any objects with 'free' callbacks will have those callbacks called
1176 * @param e The given evas.
1178 * @ingroup Evas_Canvas
1180 EAPI void evas_free (Evas *e) EINA_ARG_NONNULL(1);
1184 * Inform to the evas that it got the focus.
1186 * @param e The evas to change information.
1187 * @ingroup Evas_Canvas
1189 EAPI void evas_focus_in (Evas *e);
1192 * Inform to the evas that it lost the focus.
1194 * @param e The evas to change information.
1195 * @ingroup Evas_Canvas
1197 EAPI void evas_focus_out (Evas *e);
1200 * Get the focus state known by the given evas
1202 * @param e The evas to query information.
1203 * @ingroup Evas_Canvas
1205 EAPI Eina_Bool evas_focus_state_get (const Evas *e) EINA_PURE;
1208 * Push the nochange flag up 1
1210 * This tells evas, that while the nochange flag is greater than 0, do not
1211 * mark objects as "changed" when making changes.
1213 * @param e The evas to change information.
1214 * @ingroup Evas_Canvas
1216 EAPI void evas_nochange_push (Evas *e);
1219 * Pop the nochange flag down 1
1221 * This tells evas, that while the nochange flag is greater than 0, do not
1222 * mark objects as "changed" when making changes.
1224 * @param e The evas to change information.
1225 * @ingroup Evas_Canvas
1227 EAPI void evas_nochange_pop (Evas *e);
1231 * Attaches a specific pointer to the evas for fetching later
1233 * @param e The canvas to attach the pointer to
1234 * @param data The pointer to attach
1235 * @ingroup Evas_Canvas
1237 EAPI void evas_data_attach_set (Evas *e, void *data) EINA_ARG_NONNULL(1);
1240 * Returns the pointer attached by evas_data_attach_set()
1242 * @param e The canvas to attach the pointer to
1243 * @return The pointer attached
1244 * @ingroup Evas_Canvas
1246 EAPI void *evas_data_attach_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1250 * Add a damage rectangle.
1252 * @param e The given canvas pointer.
1253 * @param x The rectangle's left position.
1254 * @param y The rectangle's top position.
1255 * @param w The rectangle's width.
1256 * @param h The rectangle's height.
1258 * This is the function by which one tells evas that a part of the
1259 * canvas has to be repainted.
1261 * @ingroup Evas_Canvas
1263 EAPI void evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1266 * Add an "obscured region" to an Evas canvas.
1268 * @param e The given canvas pointer.
1269 * @param x The rectangle's top left corner's horizontal coordinate.
1270 * @param y The rectangle's top left corner's vertical coordinate
1271 * @param w The rectangle's width.
1272 * @param h The rectangle's height.
1274 * This is the function by which one tells an Evas canvas that a part
1275 * of it <b>must not</b> be repainted. The region must be
1276 * rectangular and its coordinates inside the canvas viewport are
1277 * passed in the call. After this call, the region specified won't
1278 * participate in any form in Evas' calculations and actions during
1279 * its rendering updates, having its displaying content frozen as it
1280 * was just after this function took place.
1282 * We call it "obscured region" because the most common use case for
1283 * this rendering (partial) freeze is something else (most problaby
1284 * other canvas) being on top of the specified rectangular region,
1285 * thus shading it completely from the user's final scene in a
1286 * display. To avoid unecessary processing, one should indicate to the
1287 * obscured canvas not to bother about the non-important area.
1289 * The majority of users won't have to worry about this funcion, as
1290 * they'll be using just one canvas in their applications, with
1291 * nothing inset or on top of it in any form.
1293 * To make this region one that @b has to be repainted again, call the
1294 * function evas_obscured_clear().
1296 * @note This is a <b>very low level function</b>, which most of
1297 * Evas' users wouldn't care about.
1299 * @note This function does @b not flag the canvas as having its state
1300 * changed. If you want to re-render it afterwards expecting new
1301 * contents, you have to add "damage" regions yourself (see
1302 * evas_damage_rectangle_add()).
1304 * @see evas_obscured_clear()
1305 * @see evas_render_updates()
1307 * Example code follows.
1308 * @dontinclude evas-events.c
1309 * @skip add an obscured
1310 * @until evas_obscured_clear(evas);
1312 * In that example, pressing the "Ctrl" and "o" keys will impose or
1313 * remove an obscured region in the middle of the canvas. You'll get
1314 * the same contents at the time the key was pressed, if toggling it
1315 * on, until you toggle it off again (make sure the animation is
1316 * running on to get the idea better). See the full @ref
1317 * Example_Evas_Events "example".
1319 * @ingroup Evas_Canvas
1321 EAPI void evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1324 * Remove all "obscured regions" from an Evas canvas.
1326 * @param e The given canvas pointer.
1328 * This function removes all the rectangles from the obscured regions
1329 * list of the canvas @p e. It takes obscured areas added with
1330 * evas_obscured_rectangle_add() and make them again a regions that @b
1331 * have to be repainted on rendering updates.
1333 * @note This is a <b>very low level function</b>, which most of
1334 * Evas' users wouldn't care about.
1336 * @note This function does @b not flag the canvas as having its state
1337 * changed. If you want to re-render it afterwards expecting new
1338 * contents, you have to add "damage" regions yourself (see
1339 * evas_damage_rectangle_add()).
1341 * @see evas_obscured_rectangle_add() for an example
1342 * @see evas_render_updates()
1344 * @ingroup Evas_Canvas
1346 EAPI void evas_obscured_clear (Evas *e) EINA_ARG_NONNULL(1);
1349 * Force immediate renderization of the given Evas canvas.
1351 * @param e The given canvas pointer.
1352 * @return A newly allocated list of updated rectangles of the canvas
1353 * (@c Eina_Rectangle structs). Free this list with
1354 * evas_render_updates_free().
1356 * This function forces an immediate renderization update of the given
1359 * @note This is a <b>very low level function</b>, which most of
1360 * Evas' users wouldn't care about. One would use it, for example, to
1361 * grab an Evas' canvas update regions and paint them back, using the
1362 * canvas' pixmap, on a displaying system working below Evas.
1364 * @note Evas is a stateful canvas. If no operations changing its
1365 * state took place since the last rendering action, you won't see no
1366 * changes and this call will be a no-op.
1368 * Example code follows.
1369 * @dontinclude evas-events.c
1370 * @skip add an obscured
1371 * @until d.obscured = !d.obscured;
1373 * See the full @ref Example_Evas_Events "example".
1375 * @ingroup Evas_Canvas
1377 EAPI Eina_List *evas_render_updates (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1380 * Free the rectangles returned by evas_render_updates().
1382 * @param updates The list of updated rectangles of the canvas.
1384 * This function removes the region from the render updates list. It
1385 * makes the region doesn't be render updated anymore.
1387 * @see evas_render_updates() for an example
1389 * @ingroup Evas_Canvas
1391 EAPI void evas_render_updates_free (Eina_List *updates);
1394 * Force renderization of the given canvas.
1396 * @param e The given canvas pointer.
1398 * @ingroup Evas_Canvas
1400 EAPI void evas_render (Evas *e) EINA_ARG_NONNULL(1);
1403 * Update the canvas internal objects but not triggering immediate
1406 * @param e The given canvas pointer.
1408 * This function updates the canvas internal objects not triggering
1409 * renderization. To force renderization function evas_render() should
1414 * @ingroup Evas_Canvas
1416 EAPI void evas_norender (Evas *e) EINA_ARG_NONNULL(1);
1419 * Make the canvas discard internally cached data used for rendering.
1421 * @param e The given canvas pointer.
1423 * This function flushes the arrays of delete, active and render objects.
1424 * Other things it may also discard are: shared memory segments,
1425 * temporary scratch buffers, cached data to avoid re-compute of that data etc.
1427 * @ingroup Evas_Canvas
1429 EAPI void evas_render_idle_flush (Evas *e) EINA_ARG_NONNULL(1);
1432 * Make the canvas discard as much data as possible used by the engine at
1435 * @param e The given canvas pointer.
1437 * This function will unload images, delete textures and much more, where
1438 * possible. You may also want to call evas_render_idle_flush() immediately
1439 * prior to this to perhaps discard a little more, though evas_render_dump()
1440 * should implicitly delete most of what evas_render_idle_flush() might
1443 * @ingroup Evas_Canvas
1445 EAPI void evas_render_dump (Evas *e) EINA_ARG_NONNULL(1);
1448 * @defgroup Evas_Output_Method Render Engine Functions
1450 * Functions that are used to set the render engine for a given
1451 * function, and then get that engine working.
1453 * The following code snippet shows how they can be used to
1454 * initialise an evas that uses the X11 software engine:
1457 * Evas_Engine_Info_Software_X11 *einfo;
1458 * extern Display *display;
1459 * extern Window win;
1463 * evas = evas_new();
1464 * evas_output_method_set(evas, evas_render_method_lookup("software_x11"));
1465 * evas_output_size_set(evas, 640, 480);
1466 * evas_output_viewport_set(evas, 0, 0, 640, 480);
1467 * einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas);
1468 * einfo->info.display = display;
1469 * einfo->info.visual = DefaultVisual(display, DefaultScreen(display));
1470 * einfo->info.colormap = DefaultColormap(display, DefaultScreen(display));
1471 * einfo->info.drawable = win;
1472 * einfo->info.depth = DefaultDepth(display, DefaultScreen(display));
1473 * evas_engine_info_set(evas, (Evas_Engine_Info *)einfo);
1476 * @ingroup Evas_Canvas
1480 * Look up a numeric ID from a string name of a rendering engine.
1482 * @param name The string name of an engine
1483 * @return A numeric (opaque) ID for the rendering engine
1484 * @ingroup Evas_Output_Method
1486 * This function looks up a numeric return value for the named engine
1487 * in the string @p name. This is a normal C string, NUL byte
1488 * terminated. The name is case sensitive. If the rendering engine is
1489 * available, a numeric ID for that engine is returned that is not
1490 * 0. If the engine is not available, 0 is returned, indicating an
1493 * The programmer should NEVER rely on the numeric ID of an engine
1494 * unless it is returned by this function. Programs should NOT be
1495 * written accessing render method ID's directly, without first
1496 * obtaining it from this function.
1498 * @attention it is mandatory that one calls evas_init() before
1499 * looking up the render method.
1508 * evas = evas_new();
1511 * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
1514 * engine_id = evas_render_method_lookup("software_x11");
1517 * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
1520 * evas_output_method_set(evas, engine_id);
1523 EAPI int evas_render_method_lookup (const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1526 * List all the rendering engines compiled into the copy of the Evas library
1528 * @return A linked list whose data members are C strings of engine names
1529 * @ingroup Evas_Output_Method
1531 * Calling this will return a handle (pointer) to an Evas linked
1532 * list. Each node in the linked list will have the data pointer be a
1533 * (char *) pointer to the string name of the rendering engine
1534 * available. The strings should never be modified, neither should the
1535 * list be modified. This list should be cleaned up as soon as the
1536 * program no longer needs it using evas_render_method_list_free(). If
1537 * no engines are available from Evas, NULL will be returned.
1541 * Eina_List *engine_list, *l;
1542 * char *engine_name;
1544 * engine_list = evas_render_method_list();
1547 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1550 * printf("Available Evas Engines:\n");
1551 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1552 * printf("%s\n", engine_name);
1553 * evas_render_method_list_free(engine_list);
1556 EAPI Eina_List *evas_render_method_list (void) EINA_WARN_UNUSED_RESULT;
1559 * This function should be called to free a list of engine names
1561 * @param list The Eina_List base pointer for the engine list to be freed
1562 * @ingroup Evas_Output_Method
1564 * When this function is called it will free the engine list passed in
1565 * as @p list. The list should only be a list of engines generated by
1566 * calling evas_render_method_list(). If @p list is NULL, nothing will
1571 * Eina_List *engine_list, *l;
1572 * char *engine_name;
1574 * engine_list = evas_render_method_list();
1577 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1580 * printf("Available Evas Engines:\n");
1581 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1582 * printf("%s\n", engine_name);
1583 * evas_render_method_list_free(engine_list);
1586 EAPI void evas_render_method_list_free (Eina_List *list);
1590 * Sets the output engine for the given evas.
1592 * Once the output engine for an evas is set, any attempt to change it
1593 * will be ignored. The value for @p render_method can be found using
1594 * @ref evas_render_method_lookup .
1596 * @param e The given evas.
1597 * @param render_method The numeric engine value to use.
1599 * @attention it is mandatory that one calls evas_init() before
1600 * setting the output method.
1602 * @ingroup Evas_Output_Method
1604 EAPI void evas_output_method_set (Evas *e, int render_method) EINA_ARG_NONNULL(1);
1607 * Retrieves the number of the output engine used for the given evas.
1608 * @param e The given evas.
1609 * @return The ID number of the output engine being used. @c 0 is
1610 * returned if there is an error.
1611 * @ingroup Evas_Output_Method
1613 EAPI int evas_output_method_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1617 * Retrieves the current render engine info struct from the given evas.
1619 * The returned structure is publicly modifiable. The contents are
1620 * valid until either @ref evas_engine_info_set or @ref evas_render
1623 * This structure does not need to be freed by the caller.
1625 * @param e The given evas.
1626 * @return A pointer to the Engine Info structure. @c NULL is returned if
1627 * an engine has not yet been assigned.
1628 * @ingroup Evas_Output_Method
1630 EAPI Evas_Engine_Info *evas_engine_info_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1633 * Applies the engine settings for the given evas from the given @c
1634 * Evas_Engine_Info structure.
1636 * To get the Evas_Engine_Info structure to use, call @ref
1637 * evas_engine_info_get . Do not try to obtain a pointer to an
1638 * @c Evas_Engine_Info structure in any other way.
1640 * You will need to call this function at least once before you can
1641 * create objects on an evas or render that evas. Some engines allow
1642 * their settings to be changed more than once.
1644 * Once called, the @p info pointer should be considered invalid.
1646 * @param e The pointer to the Evas Canvas
1647 * @param info The pointer to the Engine Info to use
1648 * @return 1 if no error occurred, 0 otherwise
1649 * @ingroup Evas_Output_Method
1651 EAPI Eina_Bool evas_engine_info_set (Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1);
1654 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1656 * Functions that set and retrieve the output and viewport size of an
1659 * @ingroup Evas_Canvas
1663 * Sets the output size of the render engine of the given evas.
1665 * The evas will render to a rectangle of the given size once this
1666 * function is called. The output size is independent of the viewport
1667 * size. The viewport will be stretched to fill the given rectangle.
1669 * The units used for @p w and @p h depend on the engine used by the
1672 * @param e The given evas.
1673 * @param w The width in output units, usually pixels.
1674 * @param h The height in output units, usually pixels.
1675 * @ingroup Evas_Output_Size
1677 EAPI void evas_output_size_set (Evas *e, int w, int h) EINA_ARG_NONNULL(1);
1680 * Retrieve the output size of the render engine of the given evas.
1682 * The output size is given in whatever the output units are for the
1685 * If either @p w or @p h is @c NULL, then it is ignored. If @p e is
1686 * invalid, the returned results are undefined.
1688 * @param e The given evas.
1689 * @param w The pointer to an integer to store the width in.
1690 * @param h The pointer to an integer to store the height in.
1691 * @ingroup Evas_Output_Size
1693 EAPI void evas_output_size_get (const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1);
1696 * Sets the output viewport of the given evas in evas units.
1698 * The output viewport is the area of the evas that will be visible to
1699 * the viewer. The viewport will be stretched to fit the output
1700 * target of the evas when rendering is performed.
1702 * @note The coordinate values do not have to map 1-to-1 with the output
1703 * target. However, it is generally advised that it is done for ease
1706 * @param e The given evas.
1707 * @param x The top-left corner x value of the viewport.
1708 * @param y The top-left corner y value of the viewport.
1709 * @param w The width of the viewport. Must be greater than 0.
1710 * @param h The height of the viewport. Must be greater than 0.
1711 * @ingroup Evas_Output_Size
1713 EAPI void evas_output_viewport_set (Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
1716 * Get the render engine's output viewport co-ordinates in canvas units.
1717 * @param e The pointer to the Evas Canvas
1718 * @param x The pointer to a x variable to be filled in
1719 * @param y The pointer to a y variable to be filled in
1720 * @param w The pointer to a width variable to be filled in
1721 * @param h The pointer to a height variable to be filled in
1722 * @ingroup Evas_Output_Size
1724 * Calling this function writes the current canvas output viewport
1725 * size and location values into the variables pointed to by @p x, @p
1726 * y, @p w and @p h. On success the variables have the output
1727 * location and size values written to them in canvas units. Any of @p
1728 * x, @p y, @p w or @p h that are NULL will not be written to. If @p e
1729 * is invalid, the results are undefined.
1733 * extern Evas *evas;
1734 * Evas_Coord x, y, width, height;
1736 * evas_output_viewport_get(evas, &x, &y, &w, &h);
1739 EAPI void evas_output_viewport_get (const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
1742 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1744 * Functions that are used to map coordinates from the canvas to the
1745 * screen or the screen to the canvas.
1747 * @ingroup Evas_Canvas
1751 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1753 * @param e The pointer to the Evas Canvas
1754 * @param x The screen/output x co-ordinate
1755 * @return The screen co-ordinate translated to canvas unit co-ordinates
1756 * @ingroup Evas_Coord_Mapping_Group
1758 * This function takes in a horizontal co-ordinate as the @p x
1759 * parameter and converts it into canvas units, accounting for output
1760 * size, viewport size and location, returning it as the function
1761 * return value. If @p e is invalid, the results are undefined.
1765 * extern Evas *evas;
1766 * extern int screen_x;
1767 * Evas_Coord canvas_x;
1769 * canvas_x = evas_coord_screen_x_to_world(evas, screen_x);
1772 EAPI Evas_Coord evas_coord_screen_x_to_world (const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1775 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1777 * @param e The pointer to the Evas Canvas
1778 * @param y The screen/output y co-ordinate
1779 * @return The screen co-ordinate translated to canvas unit co-ordinates
1780 * @ingroup Evas_Coord_Mapping_Group
1782 * This function takes in a vertical co-ordinate as the @p y parameter
1783 * and converts it into canvas units, accounting for output size,
1784 * viewport size and location, returning it as the function return
1785 * value. If @p e is invalid, the results are undefined.
1789 * extern Evas *evas;
1790 * extern int screen_y;
1791 * Evas_Coord canvas_y;
1793 * canvas_y = evas_coord_screen_y_to_world(evas, screen_y);
1796 EAPI Evas_Coord evas_coord_screen_y_to_world (const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1799 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1801 * @param e The pointer to the Evas Canvas
1802 * @param x The canvas x co-ordinate
1803 * @return The output/screen co-ordinate translated to output co-ordinates
1804 * @ingroup Evas_Coord_Mapping_Group
1806 * This function takes in a horizontal co-ordinate as the @p x
1807 * parameter and converts it into output units, accounting for output
1808 * size, viewport size and location, returning it as the function
1809 * return value. If @p e is invalid, the results are undefined.
1813 * extern Evas *evas;
1815 * extern Evas_Coord canvas_x;
1817 * screen_x = evas_coord_world_x_to_screen(evas, canvas_x);
1820 EAPI int evas_coord_world_x_to_screen (const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1823 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1825 * @param e The pointer to the Evas Canvas
1826 * @param y The canvas y co-ordinate
1827 * @return The output/screen co-ordinate translated to output co-ordinates
1828 * @ingroup Evas_Coord_Mapping_Group
1830 * This function takes in a vertical co-ordinate as the @p x parameter
1831 * and converts it into output units, accounting for output size,
1832 * viewport size and location, returning it as the function return
1833 * value. If @p e is invalid, the results are undefined.
1837 * extern Evas *evas;
1839 * extern Evas_Coord canvas_y;
1841 * screen_y = evas_coord_world_y_to_screen(evas, canvas_y);
1844 EAPI int evas_coord_world_y_to_screen (const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1847 * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
1849 * Functions that deal with the status of the pointer (mouse cursor).
1851 * @ingroup Evas_Canvas
1855 * This function returns the current known pointer co-ordinates
1857 * @param e The pointer to the Evas Canvas
1858 * @param x The pointer to an integer to be filled in
1859 * @param y The pointer to an integer to be filled in
1860 * @ingroup Evas_Pointer_Group
1862 * This function returns the current known screen/output co-ordinates
1863 * of the mouse pointer and sets the contents of the integers pointed
1864 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
1865 * valid canvas the results of this function are undefined.
1869 * extern Evas *evas;
1870 * int mouse_x, mouse_y;
1872 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
1873 * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y);
1876 EAPI void evas_pointer_output_xy_get (const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1);
1879 * This function returns the current known pointer co-ordinates
1881 * @param e The pointer to the Evas Canvas
1882 * @param x The pointer to a Evas_Coord to be filled in
1883 * @param y The pointer to a Evas_Coord to be filled in
1884 * @ingroup Evas_Pointer_Group
1886 * This function returns the current known canvas unit co-ordinates of
1887 * the mouse pointer and sets the contents of the Evas_Coords pointed
1888 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
1889 * valid canvas the results of this function are undefined.
1893 * extern Evas *evas;
1894 * Evas_Coord mouse_x, mouse_y;
1896 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
1897 * printf("Mouse is at canvas position %f, %f\n", mouse_x, mouse_y);
1900 EAPI void evas_pointer_canvas_xy_get (const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
1903 * Returns a bitmask with the mouse buttons currently pressed, set to 1
1905 * @param e The pointer to the Evas Canvas
1906 * @return A bitmask of the currently depressed buttons on the cavas
1907 * @ingroup Evas_Pointer_Group
1909 * Calling this function will return a 32-bit integer with the
1910 * appropriate bits set to 1 that correspond to a mouse button being
1911 * depressed. This limits Evas to a mouse devices with a maximum of 32
1912 * buttons, but that is generally in excess of any host system's
1913 * pointing device abilities.
1915 * A canvas by default begins with no mouse buttons being pressed and
1916 * only calls to evas_event_feed_mouse_down(),
1917 * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and
1918 * evas_event_feed_mouse_up_data() will alter that.
1920 * The least significant bit corresponds to the first mouse button
1921 * (button 1) and the most significant bit corresponds to the last
1922 * mouse button (button 32).
1924 * If @p e is not a valid canvas, the return value is undefined.
1928 * extern Evas *evas;
1929 * int button_mask, i;
1931 * button_mask = evas_pointer_button_down_mask_get(evas);
1932 * printf("Buttons currently pressed:\n");
1933 * for (i = 0; i < 32; i++)
1935 * if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1);
1939 EAPI int evas_pointer_button_down_mask_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1942 * Returns whether the mouse pointer is logically inside the canvas
1944 * @param e The pointer to the Evas Canvas
1945 * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise
1946 * @ingroup Evas_Pointer_Group
1948 * When this function is called it will return a value of either 0 or
1949 * 1, depending on if evas_event_feed_mouse_in(),
1950 * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(),
1951 * evas_event_feed_mouse_out_data() have been called to feed in a
1952 * mouse enter event into the canvas.
1954 * A return value of 1 indicates the mouse is logically inside the
1955 * canvas, and 0 implies it is logically outside the canvas.
1957 * A canvas begins with the mouse being assumed outside (0).
1959 * If @p e is not a valid canvas, the return value is undefined.
1963 * extern Evas *evas;
1965 * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n");
1966 * else printf("Mouse is out!\n");
1969 EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1970 EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1);
1973 * @defgroup Evas_Canvas_Events Canvas Events
1975 * Functions relating to canvas events, which are mainly reports on
1976 * its internal states changing (an object got focused, the rendering
1979 * Some of the funcions in this group are exemplified @ref
1980 * Example_Evas_Events "here".
1982 * @ingroup Evas_Canvas
1986 * @addtogroup Evas_Canvas_Events
1991 * Add (register) a callback function to a given canvas event.
1993 * @param e Canvas to attach a callback to
1994 * @param type The type of event that will trigger the callback
1995 * @param func The (callback) function to be called when the event is
1997 * @param data The data pointer to be passed to @p func
1999 * This function adds a function callback to the canvas @p e when the
2000 * event of type @p type occurs on it. The function pointer is @p
2003 * In the event of a memory allocation error during the addition of
2004 * the callback to the canvas, evas_alloc_error() should be used to
2005 * determine the nature of the error, if any, and the program should
2006 * sensibly try and recover.
2008 * A callback function must have the ::Evas_Event_Cb prototype
2009 * definition. The first parameter (@p data) in this definition will
2010 * have the same value passed to evas_event_callback_add() as the @p
2011 * data parameter, at runtime. The second parameter @p e is the canvas
2012 * pointer on which the event occurred. The third parameter @p
2013 * event_info is a pointer to a data structure that may or may not be
2014 * passed to the callback, depending on the event type that triggered
2015 * the callback. This is so because some events don't carry extra
2016 * context with them, but others do.
2018 * The event type @p type to trigger the function may be one of
2019 * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST,
2020 * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT,
2021 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and
2022 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of
2023 * event that will trigger the callback to be called. Only the last
2024 * two of the event types listed here provide useful event information
2025 * data -- a pointer to the recently focused Evas object. For the
2026 * others the @p event_info pointer is going to be @c NULL.
2029 * @dontinclude evas-events.c
2030 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE
2031 * @until two canvas event callbacks
2033 * Looking to the callbacks registered above,
2034 * @dontinclude evas-events.c
2035 * @skip called when our rectangle gets focus
2036 * @until let's have our events back
2038 * we see that the canvas flushes its rendering pipeline
2039 * (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb
2040 * routine takes place: it has to redraw that image at a different
2041 * size. Also, the callback on an object being focused comes just
2042 * after we focus it explicitly, on code.
2044 * See the full @ref Example_Evas_Events "example".
2046 * @note Be careful not to add the same callback multiple times, if
2047 * that's not what you want, because Evas won't check if a callback
2048 * existed before exactly as the one being registered (and thus, call
2049 * it more than once on the event, in this case). This would make
2050 * sense if you passed different functions and/or callback data, only.
2052 EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2055 * Delete a callback function from the canvas.
2057 * @param e Canvas to remove a callback from
2058 * @param type The type of event that was triggering the callback
2059 * @param func The function that was to be called when the event was triggered
2060 * @return The data pointer that was to be passed to the callback
2062 * This function removes the most recently added callback from the
2063 * canvas @p e which was triggered by the event type @p type and was
2064 * calling the function @p func when triggered. If the removal is
2065 * successful it will also return the data pointer that was passed to
2066 * evas_event_callback_add() when the callback was added to the
2067 * canvas. If not successful NULL will be returned.
2073 * void focus_in_callback(void *data, Evas *e, void *event_info);
2075 * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
2078 EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
2081 * Delete (unregister) a callback function registered to a given
2084 * @param e Canvas to remove an event callback from
2085 * @param type The type of event that was triggering the callback
2086 * @param func The function that was to be called when the event was
2088 * @param data The data pointer that was to be passed to the callback
2089 * @return The data pointer that was to be passed to the callback
2091 * This function removes <b>the first</b> added callback from the
2092 * canvas @p e matching the event type @p type, the registered
2093 * function pointer @p func and the callback data pointer @p data. If
2094 * the removal is successful it will also return the data pointer that
2095 * was passed to evas_event_callback_add() (that will be the same as
2096 * the parameter) when the callback(s) was(were) added to the
2097 * canvas. If not successful @c NULL will be returned. A common use
2098 * would be to remove an exact match of a callback.
2101 * @dontinclude evas-events.c
2102 * @skip evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
2103 * @until _object_focus_in_cb, NULL);
2105 * See the full @ref Example_Evas_Events "example".
2107 * @note For deletion of canvas events callbacks filtering by just
2108 * type and function pointer, user evas_event_callback_del().
2110 EAPI void *evas_event_callback_del_full (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2113 * Push a callback on the post-event callback stack
2115 * @param e Canvas to push the callback on
2116 * @param func The function that to be called when the stack is unwound
2117 * @param data The data pointer to be passed to the callback
2119 * Evas has a stack of callbacks that get called after all the callbacks for
2120 * an event have triggered (all the objects it triggers on and al the callbacks
2121 * in each object triggered). When all these have been called, the stack is
2122 * unwond from most recently to least recently pushed item and removed from the
2123 * stack calling the callback set for it.
2125 * This is intended for doing reverse logic-like processing, example - when a
2126 * child object that happens to get the event later is meant to be able to
2127 * "steal" functions from a parent and thus on unwind of this stack hav its
2128 * function called first, thus being able to set flags, or return 0 from the
2129 * post-callback that stops all other post-callbacks in the current stack from
2130 * being called (thus basically allowing a child to take control, if the event
2131 * callback prepares information ready for taking action, but the post callback
2132 * actually does the action).
2135 EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2138 * Remove a callback from the post-event callback stack
2140 * @param e Canvas to push the callback on
2141 * @param func The function that to be called when the stack is unwound
2143 * This removes a callback from the stack added with
2144 * evas_post_event_callback_push(). The first instance of the function in
2145 * the callback stack is removed from being executed when the stack is
2146 * unwound. Further instances may still be run on unwind.
2148 EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func);
2151 * Remove a callback from the post-event callback stack
2153 * @param e Canvas to push the callback on
2154 * @param func The function that to be called when the stack is unwound
2155 * @param data The data pointer to be passed to the callback
2157 * This removes a callback from the stack added with
2158 * evas_post_event_callback_push(). The first instance of the function and data
2159 * in the callback stack is removed from being executed when the stack is
2160 * unwound. Further instances may still be run on unwind.
2162 EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2165 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
2167 * Functions that deal with the freezing of input event processing of
2170 * There might be scenarios during a graphical user interface
2171 * program's use when the developer whishes the users wouldn't be able
2172 * to deliver input events to this application. It may, for example,
2173 * be the time for it to populate a view or to change some
2174 * layout. Assuming proper behavior with user interaction during this
2175 * exact time would be hard, as things are in a changing state. The
2176 * programmer can then tell the canvas to ignore input events,
2177 * bringing it back to normal behavior when he/she wants.
2179 * Some of the funcions in this group are exemplified @ref
2180 * Example_Evas_Events "here".
2182 * @ingroup Evas_Canvas_Events
2186 * @addtogroup Evas_Event_Freezing_Group
2191 * Freeze all input events processing.
2193 * @param e The canvas to freeze input events processing on.
2195 * This function will indicate to Evas that the canvas @p e is to have
2196 * all input event processing frozen until a matching
2197 * evas_event_thaw() function is called on the same canvas. All events
2198 * of this kind during the freeze will get @b discarded. Every freeze
2199 * call must be matched by a thaw call in order to completely thaw out
2200 * a canvas (i.e. these calls may be nested). The most common use is
2201 * when you don't want the user to interect with your user interface
2202 * when you're populating a view or changing the layout.
2205 * @dontinclude evas-events.c
2206 * @skip freeze input for 3 seconds
2208 * @dontinclude evas-events.c
2209 * @skip let's have our events back
2212 * See the full @ref Example_Evas_Events "example".
2214 * If you run that example, you'll see the canvas ignoring all input
2215 * events for 3 seconds, when the "f" key is pressed. In a more
2216 * realistic code we would be freezing while a toolkit or Edje was
2217 * doing some UI changes, thawing it back afterwards.
2219 EAPI void evas_event_freeze (Evas *e) EINA_ARG_NONNULL(1);
2222 * Thaw a canvas out after freezing (for input events).
2224 * @param e The canvas to thaw out.
2226 * This will thaw out a canvas after a matching evas_event_freeze()
2227 * call. If this call completely thaws out a canvas, i.e., there's no
2228 * other unbalanced call to evas_event_freeze(), events will start to
2229 * be processed again, but any "missed" events will @b not be
2232 * See evas_event_freeze() for an example.
2234 EAPI void evas_event_thaw (Evas *e) EINA_ARG_NONNULL(1);
2237 * Return the freeze count on input events of a given canvas.
2239 * @param e The canvas to fetch the freeze count from.
2241 * This returns the number of times the canvas has been told to freeze
2242 * input events. It is possible to call evas_event_freeze() multiple
2243 * times, and these must be matched by evas_event_thaw() calls. This
2244 * call allows the program to discover just how many times things have
2245 * been frozen in case it may want to break out of a deep freeze state
2246 * where the count is high.
2250 * extern Evas *evas;
2252 * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
2256 EAPI int evas_event_freeze_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2259 * After thaw of a canvas, re-evaluate the state of objects and call callbacks
2261 * @param e The canvas to evaluate after a thaw
2263 * This is normally called after evas_event_thaw() to re-evaluate mouse
2264 * containment and other states and thus also call callbacks for mouse in and
2265 * out on new objects if the state change demands it.
2267 EAPI void evas_event_thaw_eval (Evas *e) EINA_ARG_NONNULL(1);
2274 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
2276 * Functions to tell Evas that input events happened and should be
2279 * As explained in @ref intro_not_evas, Evas does not know how to poll
2280 * for input events, so the developer should do it and then feed such
2281 * events to the canvas to be processed. This is only required if
2282 * operating Evas directly. Modules such as Ecore_Evas do that for
2285 * Some of the funcions in this group are exemplified @ref
2286 * Example_Evas_Events "here".
2288 * @ingroup Evas_Canvas_Events
2292 * @addtogroup Evas_Event_Feeding_Group
2297 * Mouse down event feed.
2299 * @param e The given canvas pointer.
2300 * @param b The button number.
2301 * @param flags The evas button flags.
2302 * @param timestamp The timestamp of the mouse down event.
2303 * @param data The data for canvas.
2305 * This function will set some evas properties that is necessary when
2306 * the mouse button is pressed. It prepares information to be treated
2307 * by the callback function.
2310 EAPI void evas_event_feed_mouse_down (Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2313 * Mouse up event feed.
2315 * @param e The given canvas pointer.
2316 * @param b The button number.
2317 * @param flags evas button flags.
2318 * @param timestamp The timestamp of the mouse up event.
2319 * @param data The data for canvas.
2321 * This function will set some evas properties that is necessary when
2322 * the mouse button is released. It prepares information to be treated
2323 * by the callback function.
2326 EAPI void evas_event_feed_mouse_up (Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2329 * Mouse move event feed.
2331 * @param e The given canvas pointer.
2332 * @param x The horizontal position of the mouse pointer.
2333 * @param y The vertical position of the mouse pointer.
2334 * @param timestamp The timestamp of the mouse up event.
2335 * @param data The data for canvas.
2337 * This function will set some evas properties that is necessary when
2338 * the mouse is moved from its last position. It prepares information
2339 * to be treated by the callback function.
2342 EAPI void evas_event_feed_mouse_move (Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2345 * Mouse in event feed.
2347 * @param e The given canvas pointer.
2348 * @param timestamp The timestamp of the mouse up event.
2349 * @param data The data for canvas.
2351 * This function will set some evas properties that is necessary when
2352 * the mouse in event happens. It prepares information to be treated
2353 * by the callback function.
2356 EAPI void evas_event_feed_mouse_in (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2359 * Mouse out event feed.
2361 * @param e The given canvas pointer.
2362 * @param timestamp Timestamp of the mouse up event.
2363 * @param data The data for canvas.
2365 * This function will set some evas properties that is necessary when
2366 * the mouse out event happens. It prepares information to be treated
2367 * by the callback function.
2370 EAPI void evas_event_feed_mouse_out (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2371 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);
2372 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);
2373 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);
2376 * Mouse cancel event feed.
2378 * @param e The given canvas pointer.
2379 * @param timestamp The timestamp of the mouse up event.
2380 * @param data The data for canvas.
2382 * This function will call evas_event_feed_mouse_up() when a
2383 * mouse cancel event happens.
2386 EAPI void evas_event_feed_mouse_cancel (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2389 * Mouse wheel event feed.
2391 * @param e The given canvas pointer.
2392 * @param direction The wheel mouse direction.
2393 * @param z How much mouse wheel was scrolled up or down.
2394 * @param timestamp The timestamp of the mouse up event.
2395 * @param data The data for canvas.
2397 * This function will set some evas properties that is necessary when
2398 * the mouse wheel is scrolled up or down. It prepares information to
2399 * be treated by the callback function.
2402 EAPI void evas_event_feed_mouse_wheel (Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2405 * Key down event feed
2407 * @param e The canvas to thaw out
2408 * @param keyname Name of the key
2409 * @param key The key pressed.
2410 * @param string A String
2411 * @param compose The compose string
2412 * @param timestamp Timestamp of the mouse up event
2413 * @param data Data for canvas.
2415 * This function will set some evas properties that is necessary when
2416 * a key is pressed. It prepares information to be treated by the
2417 * callback function.
2420 EAPI 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);
2425 * @param e The canvas to thaw out
2426 * @param keyname Name of the key
2427 * @param key The key released.
2428 * @param string string
2429 * @param compose compose
2430 * @param timestamp Timestamp of the mouse up event
2431 * @param data Data for canvas.
2433 * This function will set some evas properties that is necessary when
2434 * a key is released. It prepares information to be treated by the
2435 * callback function.
2438 EAPI 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);
2443 * @param e The given canvas pointer.
2444 * @param hold The hold.
2445 * @param timestamp The timestamp of the mouse up event.
2446 * @param data The data for canvas.
2448 * This function makes the object to stop sending events.
2451 EAPI void evas_event_feed_hold (Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2462 * @defgroup Evas_Image_Group Image Functions
2464 * Functions that deals with images at canvas level.
2466 * @ingroup Evas_Canvas
2470 * Flush the image cache of the canvas.
2472 * @param e The given evas pointer.
2474 * This function flushes image cache of canvas.
2477 EAPI void evas_image_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2480 * Reload the image cache
2482 * @param e The given evas pointer.
2484 * This function reloads the image cache of canvas.
2487 EAPI void evas_image_cache_reload (Evas *e) EINA_ARG_NONNULL(1);
2490 * Set the image cache.
2492 * @param e The given evas pointer.
2493 * @param size The cache size.
2495 * This function sets the image cache of canvas.
2498 EAPI void evas_image_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2501 * Set the image cache
2503 * @param e The given evas pointer.
2505 * This function returns the image cache of canvas.
2508 EAPI int evas_image_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2511 * @defgroup Evas_Font_Group Font Functions
2513 * Functions that deals with fonts.
2515 * @ingroup Evas_Canvas
2519 * Changes the font hinting for the given evas.
2521 * @param e The given evas.
2522 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2523 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2524 * @ingroup Evas_Font_Group
2526 EAPI void evas_font_hinting_set (Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1);
2529 * Retrieves the font hinting used by the given evas.
2531 * @param e The given evas to query.
2532 * @return The hinting in use, one of #EVAS_FONT_HINTING_NONE,
2533 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2534 * @ingroup Evas_Font_Group
2536 EAPI Evas_Font_Hinting_Flags evas_font_hinting_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2539 * Checks if the font hinting is supported by the given evas.
2541 * @param e The given evas to query.
2542 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2543 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2544 * @return @c EINA_TRUE if it is supported, @c EINA_FALSE otherwise.
2545 * @ingroup Evas_Font_Group
2547 EAPI 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;
2551 * Force the given evas and associated engine to flush its font cache.
2553 * @param e The given evas to flush font cache.
2554 * @ingroup Evas_Font_Group
2556 EAPI void evas_font_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2559 * Changes the size of font cache of the given evas.
2561 * @param e The given evas to flush font cache.
2562 * @param size The size, in bytes.
2564 * @ingroup Evas_Font_Group
2566 EAPI void evas_font_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2569 * Changes the size of font cache of the given evas.
2571 * @param e The given evas to flush font cache.
2572 * @return The size, in bytes.
2574 * @ingroup Evas_Font_Group
2576 EAPI int evas_font_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2580 * List of available font descriptions known or found by this evas.
2582 * The list depends on Evas compile time configuration, such as
2583 * fontconfig support, and the paths provided at runtime as explained
2584 * in @ref Evas_Font_Path_Group.
2586 * @param e The evas instance to query.
2587 * @return a newly allocated list of strings. Do not change the
2588 * strings. Be sure to call evas_font_available_list_free()
2589 * after you're done.
2591 * @ingroup Evas_Font_Group
2593 EAPI Eina_List *evas_font_available_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2596 * Free list of font descriptions returned by evas_font_dir_available_list().
2598 * @param e The evas instance that returned such list.
2599 * @param available the list returned by evas_font_dir_available_list().
2601 * @ingroup Evas_Font_Group
2603 EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1);
2606 * @defgroup Evas_Font_Path_Group Font Path Functions
2608 * Functions that edit the paths being used to load fonts.
2610 * @ingroup Evas_Font_Group
2614 * Removes all font paths loaded into memory for the given evas.
2615 * @param e The given evas.
2616 * @ingroup Evas_Font_Path_Group
2618 EAPI void evas_font_path_clear (Evas *e) EINA_ARG_NONNULL(1);
2621 * Appends a font path to the list of font paths used by the given evas.
2622 * @param e The given evas.
2623 * @param path The new font path.
2624 * @ingroup Evas_Font_Path_Group
2626 EAPI void evas_font_path_append (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2629 * Prepends a font path to the list of font paths used by the given evas.
2630 * @param e The given evas.
2631 * @param path The new font path.
2632 * @ingroup Evas_Font_Path_Group
2634 EAPI void evas_font_path_prepend (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2637 * Retrieves the list of font paths used by the given evas.
2638 * @param e The given evas.
2639 * @return The list of font paths used.
2640 * @ingroup Evas_Font_Path_Group
2642 EAPI const Eina_List *evas_font_path_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2645 * @defgroup Evas_Object_Group Generic Object Functions
2647 * Functions that manipulate generic Evas objects.
2649 * All Evas displaying units are Evas objects. One handles them all by
2650 * means of the handle ::Evas_Object. Besides Evas treats their
2651 * objects equally, they have @b types, which define their specific
2652 * behavior (and individual API).
2654 * Evas comes with a set of built-in object types:
2662 * These functions apply to @b any Evas object, whichever type thay
2665 * @note The built-in types which are most used are rectangles, text
2666 * and images. In fact, with these ones one can create 2D interfaces
2667 * of arbitrary complexity and EFL makes it easy.
2671 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
2673 * Methods that are broadly used, like those that change the color,
2674 * clippers and geometry of an Evas object.
2676 * An example on the most used functions in this group can be seen @ref
2677 * Example_Evas_Object_Manipulation "here".
2679 * For function dealing with stacking, the examples are gathered @ref
2680 * Example_Evas_Stacking "here".
2682 * @ingroup Evas_Object_Group
2686 * @addtogroup Evas_Object_Group_Basic
2691 * Clip one object to another.
2693 * @param obj The object to be clipped
2694 * @param clip The object to clip @p obj by
2696 * This function will clip the object @p obj to the area occupied by
2697 * the object @p clip. This means the object @p obj will only be
2698 * visible within the area occupied by the clipping object (@p clip).
2700 * The color of the object being clipped will be multiplied by the
2701 * color of the clipping one, so the resulting color for the former
2702 * will be <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color
2703 * element (red, green, blue and alpha).
2705 * Clipping is recursive, so clipping objects may be clipped by
2706 * others, and their color will in term be multiplied. You may @b not
2707 * set up circular clipping lists (i.e. object 1 clips object 2, which
2708 * clips object 1): the behavior of Evas is undefined in this case.
2710 * Objects which do not clip others are visible in the canvas as
2711 * normal; <b>those that clip one or more objects become invisible
2712 * themselves</b>, only affecting what they clip. If an object ceases
2713 * to have other objects being clipped by it, it will become visible
2716 * The visibility of an object affects the objects that are clipped by
2717 * it, so if the object clipping others is not shown (as in
2718 * evas_object_show()), the objects clipped by it will not be shown
2721 * If @p obj was being clipped by another object when this function is
2722 * called, it gets implicitly removed from the old clipper's domain
2723 * and is made now to be clipped by its new clipper.
2725 * @note At the moment the <b>only objects that can validly be used to
2726 * clip other objects are rectangle objects</b>. All other object
2727 * types are invalid and the result of using them is undefined. The
2728 * clip object @p clip must be a valid object, but can also be @c
2729 * NULL, in which case the effect of this function is the same as
2730 * calling evas_object_clip_unset() on the @p obj object.
2733 * @dontinclude evas-object-manipulation.c
2734 * @skip solid white clipper (note that it's the default color for a
2735 * @until evas_object_show(d.clipper);
2737 * See the full @ref Example_Evas_Object_Manipulation "example".
2739 EAPI void evas_object_clip_set (Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2);
2742 * Get the object clipping @p obj (if any).
2744 * @param obj The object to get the clipper from
2746 * This function returns the object clipping @p obj. If @p obj is
2747 * not being clipped at all, @c NULL is returned. The object @p obj
2748 * must be a valid ::Evas_Object.
2750 * See also evas_object_clip_set(), evas_object_clip_unset() and
2751 * evas_object_clipees_get().
2754 * @dontinclude evas-object-manipulation.c
2755 * @skip if (evas_object_clip_get(d.img) == d.clipper)
2758 * See the full @ref Example_Evas_Object_Manipulation "example".
2760 EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2763 * Disable/cease clipping on a clipped @p obj object.
2765 * @param obj The object to cease clipping on
2767 * This function disables clipping for the object @p obj, if it was
2768 * already clipped, i.e., its visibility and color get detached from
2769 * the previous clipper. If it wasn't, this has no effect. The object
2770 * @p obj must be a valid ::Evas_Object.
2772 * See also evas_object_clip_set() (for an example),
2773 * evas_object_clipees_get() and evas_object_clip_get().
2776 EAPI void evas_object_clip_unset (Evas_Object *obj);
2779 * Return a list of objects currently clipped by @p obj.
2781 * @param obj The object to get a list of clippees from
2782 * @return a list of objects being clipped by @p obj
2784 * This returns the internal list handle that contains all objects
2785 * clipped by the object @p obj. If none are clipped by it, the call
2786 * returns @c NULL. This list is only valid until the clip list is
2787 * changed and should be fetched again with another call to
2788 * evas_object_clipees_get() if any objects being clipped by this
2789 * object are unclipped, clipped by a new object, deleted or get the
2790 * clipper deleted. These operations will invalidate the list
2791 * returned, so it should not be used anymore after that point. Any
2792 * use of the list after this may have undefined results, possibly
2793 * leading to crashes. The object @p obj must be a valid
2796 * See also evas_object_clip_set(), evas_object_clip_unset() and
2797 * evas_object_clip_get().
2801 * extern Evas_Object *obj;
2802 * Evas_Object *clipper;
2804 * clipper = evas_object_clip_get(obj);
2807 * Eina_List *clippees, *l;
2808 * Evas_Object *obj_tmp;
2810 * clippees = evas_object_clipees_get(clipper);
2811 * printf("Clipper clips %i objects\n", eina_list_count(clippees));
2812 * EINA_LIST_FOREACH(clippees, l, obj_tmp)
2813 * evas_object_show(obj_tmp);
2817 EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2821 * Sets or unsets a given object as the currently focused one on its
2824 * @param obj The object to be focused or unfocused.
2825 * @param focus @c EINA_TRUE, to set it as focused or @c EINA_FALSE,
2826 * to take away the focus from it.
2828 * Changing focus only affects where (key) input events go. There can
2829 * be only one object focused at any time. If @p focus is @c
2830 * EINA_TRUE, @p obj will be set as the currently focused object and
2831 * it will receive all keyboard events that are not exclusive key
2832 * grabs on other objects.
2835 * @dontinclude evas-events.c
2836 * @skip evas_object_focus_set
2837 * @until evas_object_focus_set
2839 * See the full example @ref Example_Evas_Events "here".
2841 * @see evas_object_focus_get
2842 * @see evas_focus_get
2843 * @see evas_object_key_grab
2844 * @see evas_object_key_ungrab
2846 EAPI void evas_object_focus_set (Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
2849 * Retrieve whether an object has the focus.
2851 * @param obj The object to retrieve focus information from.
2852 * @return @c EINA_TRUE if the object has the focus, @c EINA_FALSE
2855 * If the passed object is the currently focused one, @c EINA_TRUE is
2856 * returned. @c EINA_FALSE is returned, otherwise.
2859 * @dontinclude evas-events.c
2861 * @until something is bad
2863 * See the full example @ref Example_Evas_Events "here".
2865 * @see evas_object_focus_set
2866 * @see evas_focus_get
2867 * @see evas_object_key_grab
2868 * @see evas_object_key_ungrab
2870 EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2874 * Sets the layer of the its canvas that the given object will be part
2877 * @param obj The given Evas object.
2878 * @param l The number of the layer to place the object on.
2879 * Must be between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
2881 * If you don't use this function, you'll be dealing with an @b unique
2882 * layer of objects, the default one. Additional layers are handy when
2883 * you don't want a set of objects to interfere with another set with
2884 * regard to @b stacking. Two layers are completely disjoint in that
2887 * This is a low-level function, which you'd be using when something
2888 * should be always on top, for example.
2890 * @warning Be careful, it doesn't make sense to change the layer of
2891 * smart objects' children. Smart objects have a layer of their own,
2892 * which should contain all their children objects.
2894 * @see evas_object_layer_get()
2896 EAPI void evas_object_layer_set (Evas_Object *obj, short l) EINA_ARG_NONNULL(1);
2899 * Retrieves the layer of its canvas that the given object is part of.
2901 * @param obj The given Evas object to query layer from
2902 * @return Number of the its layer
2904 * @see evas_object_layer_set()
2906 EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2910 * Sets the name of the given Evas object to the given name.
2912 * @param obj The given object.
2913 * @param name The given name.
2915 * There might be ocasions where one would like to name his/her
2919 * @dontinclude evas-events.c
2920 * @skip d.bg = evas_object_rectangle_add(d.canvas);
2921 * @until evas_object_name_set(d.bg, "our dear rectangle");
2923 * See the full @ref Example_Evas_Events "example".
2925 EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
2928 * Retrieves the name of the given Evas object.
2930 * @param obj The given object.
2931 * @return The name of the object or @c NULL, if no name has been given
2935 * @dontinclude evas-events.c
2936 * @skip fprintf(stdout, "An object got focused: %s\n",
2937 * @until evas_focus_get
2939 * See the full @ref Example_Evas_Events "example".
2941 EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2945 * Increments object reference count to defer its deletion.
2947 * @param obj The given Evas object to reference
2949 * This increments the reference count of an object, which if greater
2950 * than 0 will defer deletion by evas_object_del() until all
2951 * references are released back (counter back to 0). References cannot
2952 * go below 0 and unreferencing past that will result in the reference
2953 * count being limited to 0. References are limited to <c>2^32 - 1</c>
2954 * for an object. Referencing it more than this will result in it
2955 * being limited to this value.
2957 * @see evas_object_unref()
2958 * @see evas_object_del()
2960 * @note This is a <b>very simple<b> reference counting mechanism! For
2961 * instance, Evas is not ready to check for pending references on a
2962 * canvas deletion, or things like that. This is useful on scenarios
2963 * where, inside a code block, callbacks exist which would possibly
2964 * delete an object we are operating on afterwards. Then, one would
2965 * evas_object_ref() it on the beginning of the block and
2966 * evas_object_unref() it on the end. I would then be deleted at this
2967 * point, if it should be.
2971 * evas_object_ref(obj);
2974 * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
2975 * // more action here...
2976 * evas_object_unref(obj);
2979 * @ingroup Evas_Object_Group_Basic
2982 EAPI void evas_object_ref (Evas_Object *obj);
2985 * Decrements object reference count.
2987 * @param obj The given Evas object to unreference
2989 * This decrements the reference count of an object. If the object has
2990 * had evas_object_del() called on it while references were more than
2991 * 0, it will be deleted at the time this function is called and puts
2992 * the counter back to 0. See evas_object_ref() for more information.
2994 * @see evas_object_ref() (for an example)
2995 * @see evas_object_del()
2997 * @ingroup Evas_Object_Group_Basic
3000 EAPI void evas_object_unref (Evas_Object *obj);
3004 * Marks the given Evas object for deletion (when Evas will free its
3007 * @param obj The given Evas object.
3009 * This call will mark @p obj for deletion, which will take place
3010 * whenever it has no more references to it (see evas_object_ref() and
3011 * evas_object_unref()).
3013 * At actual deletion time, which may or may not be just after this
3014 * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks will
3015 * be called. If the object currently had the focus, its
3016 * ::EVAS_CALLBACK_FOCUS_OUT callback will also be called.
3018 * @see evas_object_ref()
3019 * @see evas_object_unref()
3021 * @ingroup Evas_Object_Group_Basic
3023 EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
3026 * Move the given Evas object to the given location inside its
3029 * @param obj The given Evas object.
3030 * @param x X position to move the object to, in canvas units.
3031 * @param y Y position to move the object to, in canvas units.
3033 * Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback
3036 * @note Naturally, newly created objects are placed at the canvas'
3037 * origin: <code>0, 0</code>.
3040 * @dontinclude evas-object-manipulation.c
3041 * @skip evas_object_image_border_set(d.clipper_border, 3, 3, 3, 3);
3042 * @until evas_object_show
3044 * See the full @ref Example_Evas_Object_Manipulation "example".
3046 * @ingroup Evas_Object_Group_Basic
3048 EAPI void evas_object_move (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
3051 * Changes the size of the given Evas object.
3053 * @param obj The given Evas object.
3054 * @param w The new width of the Evas object.
3055 * @param h The new height of the Evas object.
3057 * Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback
3060 * @note Newly created objects have zeroed dimensions. Then, you most
3061 * probably want to use evas_object_resize() on them after they are
3064 * @note Be aware that resizing an object changes its drawing area,
3065 * but that does imply the object is rescaled! For instance, images
3066 * are filled inside their drawing area using the specifications of
3067 * evas_object_image_fill_set(). Thus to scale the image to match
3068 * exactly your drawing area, you need to change the
3069 * evas_object_image_fill_set() as well.
3071 * @note This is more evident in images, but text, textblock, lines
3072 * and polygons will behave similarly. Check their specific APIs to
3073 * know how to achieve your desired behavior. Consider the following
3077 * // rescale image to fill exactly its area without tiling:
3078 * evas_object_resize(img, w, h);
3079 * evas_object_image_fill_set(img, 0, 0, w, h);
3082 * @ingroup Evas_Object_Group_Basic
3084 EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
3087 * Retrieves the position and (rectangular) size of the given Evas
3090 * @param obj The given Evas object.
3091 * @param x Pointer to an integer in which to store the X coordinate
3093 * @param y Pointer to an integer in which to store the Y coordinate
3095 * @param w Pointer to an integer in which to store the width of the
3097 * @param h Pointer to an integer in which to store the height of the
3100 * The position, naturally, will be relative to the top left corner of
3101 * the canvas' viewport.
3103 * @note Use @c NULL pointers on the geometry components you're not
3104 * interested in: they'll be ignored by the function.
3107 * @dontinclude evas-events.c
3108 * @skip int w, h, cw, ch;
3111 * See the full @ref Example_Evas_Events "example".
3113 * @ingroup Evas_Object_Group_Basic
3115 EAPI 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);
3119 * Makes the given Evas object visible.
3121 * @param obj The given Evas object.
3123 * Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW
3124 * callback will be called.
3126 * @see evas_object_hide() for more on object visibility.
3127 * @see evas_object_visible_get()
3129 * @ingroup Evas_Object_Group_Basic
3131 EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1);
3134 * Makes the given Evas object invisible.
3136 * @param obj The given Evas object.
3138 * Hidden objects, besides not being shown at all in your canvas,
3139 * won't be checked for changes on the canvas rendering
3140 * process. Furthermore, they will not catch input events. Thus, they
3141 * are much ligher (in processing needs) than an object that is
3142 * invisible due to indirect causes, such as being clipped or out of
3143 * the canvas' viewport.
3145 * Besides becoming hidden, @p obj object's ::EVAS_CALLBACK_SHOW
3146 * callback will be called.
3148 * @note All objects are created in the hidden state! If you want them
3149 * shown, use evas_object_show() after their creation.
3151 * @see evas_object_show()
3152 * @see evas_object_visible_get()
3155 * @dontinclude evas-object-manipulation.c
3156 * @skip if (evas_object_visible_get(d.clipper))
3159 * See the full @ref Example_Evas_Object_Manipulation "example".
3161 * @ingroup Evas_Object_Group_Basic
3163 EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1);
3166 * Retrieves whether or not the given Evas object is visible.
3168 * @param obj The given Evas object.
3169 * @return @c EINA_TRUE if the object is visible, @c EINA_FALSE
3172 * This retrieves an object's visibily as the one enforced by
3173 * evas_object_show() and evas_object_hide().
3175 * @note The value returned isn't, by any means, influenced by
3176 * clippers covering @obj, it being out of its canvas' viewport or
3177 * stacked below other object.
3179 * @see evas_object_show()
3180 * @see evas_object_hide() (for an example)
3182 * @ingroup Evas_Object_Group_Basic
3184 EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3188 * Sets the general/main color of the given Evas object to the given
3191 * @param obj The given Evas object.
3192 * @param r The red component of the given color.
3193 * @param g The green component of the given color.
3194 * @param b The blue component of the given color.
3195 * @param a The alpha component of the given color.
3197 * @see evas_object_color_get() (for an example)
3199 * @ingroup Evas_Object_Group_Basic
3201 EAPI void evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
3204 * Retrieves the general/main color of the given Evas object.
3206 * @param obj The given Evas object to retrieve color from.
3207 * @param r Pointer to an integer in which to store the red component
3209 * @param g Pointer to an integer in which to store the green
3210 * component of the color.
3211 * @param b Pointer to an integer in which to store the blue component
3213 * @param a Pointer to an integer in which to store the alpha
3214 * component of the color.
3216 * Retrieves the “main” color's RGB component (and alpha channel)
3217 * values, <b>which range from 0 to 255</b>. For the alpha channel,
3218 * which defines the object's transparency level, the former value
3219 * means totally trasparent, while the latter means opaque.
3221 * Usually you’ll use this attribute for text and rectangle objects,
3222 * where the “main” color is their unique one. If set for objects
3223 * which themselves have colors, like the images one, those colors get
3224 * modulated by this one.
3226 * @note All newly created Evas rectangles get the default color
3227 * values of <code>255 255 255 255</code> (opaque white).
3229 * @note Use @c NULL pointers on the components you're not interested
3230 * in: they'll be ignored by the function.
3233 * @dontinclude evas-object-manipulation.c
3234 * @skip int alpha, r, g, b;
3237 * See the full @ref Example_Evas_Object_Manipulation "example".
3239 * @ingroup Evas_Object_Group_Basic
3241 EAPI void evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
3245 * Retrieves the Evas canvas that the given object lives on.
3247 * @param obj The given Evas object.
3248 * @return A pointer to the canvas where the object is on.
3250 * This function is most useful at code contexts where you need to
3251 * operate on the canvas but have only the object pointer.
3253 * @ingroup Evas_Object_Group_Basic
3255 EAPI Evas *evas_object_evas_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3258 * Retrieves the type of the given Evas object.
3260 * @param obj The given object.
3261 * @return The type of the object.
3263 * For Evas' builtin types, the return strings will be one of:
3264 * - <c>"rectangle"</c>,
3266 * - <c>"polygon"</c>,
3268 * - <c>"textblock"</c> and
3271 * For Evas smart objects (see @ref Evas_Smart_Group), the name of the
3272 * smart class itself is returned on this call. For the built-in smart
3273 * objects, these names are:
3274 * - <c>"EvasObjectSmartClipped"</c>, for the clipped smart object
3275 * - <c>"Evas_Object_Box"</c>, for the box object and
3276 * - <c>"Evas_Object_Table"</c>, for the table object.
3279 * @dontinclude evas-object-manipulation.c
3280 * @skip d.img = evas_object_image_filled_add(d.canvas);
3281 * @until border on the
3283 * See the full @ref Example_Evas_Object_Manipulation "example".
3285 EAPI const char *evas_object_type_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3288 * Raise @p obj to the bottom of its layer.
3290 * @param obj the object to raise
3292 * @p obj will, then, be the highest one in the layer it belongs
3293 * to. Object on other layers won't get touched.
3295 * @see evas_object_stack_above()
3296 * @see evas_object_stack_below()
3297 * @see evas_object_lower()
3299 EAPI void evas_object_raise (Evas_Object *obj) EINA_ARG_NONNULL(1);
3302 * Lower @p obj to the bottom of its layer.
3304 * @param obj the object to lower
3306 * @p obj will, then, be the lowest one in the layer it belongs
3307 * to. Objects on other layers won't get touched.
3309 * @see evas_object_stack_above()
3310 * @see evas_object_stack_below()
3311 * @see evas_object_raise()
3313 EAPI void evas_object_lower (Evas_Object *obj) EINA_ARG_NONNULL(1);
3316 * Stack @p obj immediately above @p above
3318 * @param obj the object to stack
3319 * @param above the object above which to stack
3321 * Objects, in a given canvas, are stacked in the order they get added
3322 * to it. This means that, if they overlap, the highest ones will
3323 * cover the lowest ones, in that order. This function is a way to
3324 * change the stacking order for the objects.
3326 * This function is intended to be used with <b>objects belonging to
3327 * the same layer</b> in a given canvas, otherwise it will fail (and
3328 * accomplish nothing).
3330 * If you have smart objects on your canvas and @p obj is a member of
3331 * one of them, then @p above must also be a member of the same
3334 * Similarly, if @p obj is not a member of a smart object, @p above
3335 * must not be either.
3337 * @see evas_object_layer_get()
3338 * @see evas_object_layer_set()
3339 * @see evas_object_stack_below()
3341 EAPI void evas_object_stack_above (Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2);
3344 * Stack @p obj immediately below @p below
3346 * @param obj the object to stack
3347 * @param below the object below which to stack
3349 * Objects, in a given canvas, are stacked in the order they get added
3350 * to it. This means that, if they overlap, the highest ones will
3351 * cover the lowest ones, in that order. This function is a way to
3352 * change the stacking order for the objects.
3354 * This function is intended to be used with <b>objects belonging to
3355 * the same layer</b> in a given canvas, otherwise it will fail (and
3356 * accomplish nothing).
3358 * If you have smart objects on your canvas and @p obj is a member of
3359 * one of them, then @p below must also be a member of the same
3362 * Similarly, if @p obj is not a member of a smart object, @p below
3363 * must not be either.
3365 * @see evas_object_layer_get()
3366 * @see evas_object_layer_set()
3367 * @see evas_object_stack_below()
3369 EAPI void evas_object_stack_below (Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2);
3372 * Get the Evas object stacked right above @p obj
3374 * @param obj an #Evas_Object
3375 * @return the #Evas_Object directly above @p obj, if any, or @c NULL,
3378 * This function will traverse layers in its search, if there are
3379 * objects on layers above the one @p obj is placed at.
3381 * @see evas_object_layer_get()
3382 * @see evas_object_layer_set()
3383 * @see evas_object_below_get()
3386 EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3389 * Get the Evas object stacked right below @p obj
3391 * @param obj an #Evas_Object
3392 * @return the #Evas_Object directly below @p obj, if any, or @c NULL,
3395 * This function will traverse layers in its search, if there are
3396 * objects on layers below the one @p obj is placed at.
3398 * @see evas_object_layer_get()
3399 * @see evas_object_layer_set()
3400 * @see evas_object_below_set()
3402 EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3409 * @defgroup Evas_Object_Group_Events Object Events
3411 * Objects generate events when they are moved, resized, when their
3412 * visibility change, when they are deleted and so on. These methods
3413 * allow one to be notified about and to handle such events.
3415 * Objects also generate events on input (keyboard and mouse), if they
3416 * accept them (are visible, focused, etc).
3418 * Examples on this group of functions can be found @ref
3419 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
3421 * @ingroup Evas_Object_Group
3425 * @addtogroup Evas_Object_Group_Events
3430 * Add (register) a callback function to a given Evas object event.
3432 * @param obj Object to attach a callback to
3433 * @param type The type of event that will trigger the callback
3434 * @param func The function to be called when the event is triggered
3435 * @param data The data pointer to be passed to @p func
3437 * This function adds a function callback to an object when the event
3438 * of type @p type occurs on object @p obj. The function is @p func.
3440 * In the event of a memory allocation error during addition of the
3441 * callback to the object, evas_alloc_error() should be used to
3442 * determine the nature of the error, if any, and the program should
3443 * sensibly try and recover.
3445 * A callback function must have the ::Evas_Object_Event_Cb prototype
3446 * definition. The first parameter (@p data) in this definition will
3447 * have the same value passed to evas_object_event_callback_add() as
3448 * the @p data parameter, at runtime. The second parameter @p e is the
3449 * canvas pointer on which the event occurred. The third parameter is
3450 * a pointer to the object on which event occurred. Finally, the
3451 * fourth parameter @p event_info is a pointer to a data structure
3452 * that may or may not be passed to the callback, depending on the
3453 * event type that triggered the callback. This is so because some
3454 * events don't carry extra context with them, but others do.
3456 * The event type @p type to trigger the function may be one of
3457 * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT,
3458 * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP,
3459 * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL,
3460 * #EVAS_CALLBACK_MULTI_DOWN, #EVAS_CALLBACK_MULTI_UP,
3461 * #EVAS_CALLBACK_MULTI_MOVE, #EVAS_CALLBACK_FREE,
3462 * #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP,
3463 * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT,
3464 * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE,
3465 * #EVAS_CALLBACK_RESIZE, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL,
3466 * #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS,
3467 * #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED.
3469 * This determines the kind of event that will trigger the callback.
3470 * What follows is a list explaining better the nature of each type of
3471 * event, along with their associated @p event_info pointers:
3473 * - #EVAS_CALLBACK_MOUSE_IN: @p event_info is a pointer to an
3474 * #Evas_Event_Mouse_In struct\n\n
3475 * This event is triggered when the mouse pointer enters the area
3476 * (not shaded by other objects) of the object @p obj. This may
3477 * occur by the mouse pointer being moved by
3478 * evas_event_feed_mouse_move() calls, or by the object being shown,
3479 * raised, moved, resized, or other objects being moved out of the
3480 * way, hidden or lowered, whatever may cause the mouse pointer to
3481 * get on top of @p obj, having been on top of another object
3484 * - #EVAS_CALLBACK_MOUSE_OUT: @p event_info is a pointer to an
3485 * #Evas_Event_Mouse_Out struct\n\n
3486 * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is,
3487 * but it occurs when the mouse pointer exits an object's area. Note
3488 * that no mouse out events will be reported if the mouse pointer is
3489 * implicitly grabbed to an object (mouse buttons are down, having
3490 * been pressed while the pointer was over that object). In these
3491 * cases, mouse out events will be reported once all buttons are
3492 * released, if the mouse pointer has left the object's area. The
3493 * indirect ways of taking off the mouse pointer from an object,
3494 * like cited above, for #EVAS_CALLBACK_MOUSE_IN, also apply here,
3497 * - #EVAS_CALLBACK_MOUSE_DOWN: @p event_info is a pointer to an
3498 * #Evas_Event_Mouse_Down struct\n\n
3499 * This event is triggered by a mouse button being pressed while the
3500 * mouse pointer is over an object. If the pointer mode for Evas is
3501 * #EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this
3502 * object to <b>passively grab the mouse</b> until all mouse buttons
3503 * have been released: all future mouse events will be reported to
3504 * only this object until no buttons are down. That includes mouse
3505 * move events, mouse in and mouse out events, and further button
3506 * presses. When all buttons are released, event propagation will
3507 * occur as normal (see #Evas_Object_Pointer_Mode).
3509 * - #EVAS_CALLBACK_MOUSE_UP: @p event_info is a pointer to an
3510 * #Evas_Event_Mouse_Up struct\n\n
3511 * This event is triggered by a mouse button being released while
3512 * the mouse pointer is over an object's area (or when passively
3513 * grabbed to an object).
3515 * - #EVAS_CALLBACK_MOUSE_MOVE: @p event_info is a pointer to an
3516 * #Evas_Event_Mouse_Move struct\n\n
3517 * This event is triggered by the mouse pointer being moved while
3518 * over an object's area (or while passively grabbed to an object).
3520 * - #EVAS_CALLBACK_MOUSE_WHEEL: @p event_info is a pointer to an
3521 * #Evas_Event_Mouse_Wheel struct\n\n
3522 * This event is triggered by the mouse wheel being rolled while the
3523 * mouse pointer is over an object (or passively grabbed to an
3526 * - #EVAS_CALLBACK_MULTI_DOWN: @p event_info is a pointer to an
3527 * #Evas_Event_Multi_Down struct
3529 * - #EVAS_CALLBACK_MULTI_UP: @p event_info is a pointer to an
3530 * #Evas_Event_Multi_Up struct
3532 * - #EVAS_CALLBACK_MULTI_MOVE: @p event_info is a pointer to an
3533 * #Evas_Event_Multi_Move struct
3535 * - #EVAS_CALLBACK_FREE: @p event_info is @c NULL \n\n
3536 * This event is triggered just before Evas is about to free all
3537 * memory used by an object and remove all references to it. This is
3538 * useful for programs to use if they attached data to an object and
3539 * want to free it when the object is deleted. The object is still
3540 * valid when this callback is called, but after it returns, there
3541 * is no guarantee on the object's validity.
3543 * - #EVAS_CALLBACK_KEY_DOWN: @p event_info is a pointer to an
3544 * #Evas_Event_Key_Down struct\n\n
3545 * This callback is called when a key is pressed and the focus is on
3546 * the object, or a key has been grabbed to a particular object
3547 * which wants to intercept the key press regardless of what object
3550 * - #EVAS_CALLBACK_KEY_UP: @p event_info is a pointer to an
3551 * #Evas_Event_Key_Up struct \n\n
3552 * This callback is called when a key is released and the focus is
3553 * on the object, or a key has been grabbed to a particular object
3554 * which wants to intercept the key release regardless of what
3555 * object has the focus.
3557 * - #EVAS_CALLBACK_FOCUS_IN: @p event_info is @c NULL \n\n
3558 * This event is called when an object gains the focus. When it is
3559 * called the object has already gained the focus.
3561 * - #EVAS_CALLBACK_FOCUS_OUT: @p event_info is @c NULL \n\n
3562 * This event is triggered when an object loses the focus. When it
3563 * is called the object has already lost the focus.
3565 * - #EVAS_CALLBACK_SHOW: @p event_info is @c NULL \n\n
3566 * This event is triggered by the object being shown by
3567 * evas_object_show().
3569 * - #EVAS_CALLBACK_HIDE: @p event_info is @c NULL \n\n
3570 * This event is triggered by an object being hidden by
3571 * evas_object_hide().
3573 * - #EVAS_CALLBACK_MOVE: @p event_info is @c NULL \n\n
3574 * This event is triggered by an object being
3575 * moved. evas_object_move() can trigger this, as can any
3576 * object-specific manipulations that would mean the object's origin
3579 * - #EVAS_CALLBACK_RESIZE: @p event_info is @c NULL \n\n
3580 * This event is triggered by an object being resized. Resizes can
3581 * be triggered by evas_object_resize() or by any object-specific
3582 * calls that may cause the object to resize.
3584 * - #EVAS_CALLBACK_RESTACK: @p event_info is @c NULL \n\n
3585 * This event is triggered by an object being re-stacked. Stacking
3586 * changes can be triggered by
3587 * evas_object_stack_below()/evas_object_stack_above() and others.
3589 * - #EVAS_CALLBACK_DEL: @p event_info is @c NULL.
3591 * - #EVAS_CALLBACK_HOLD: @p event_info is a pointer to an
3592 * #Evas_Event_Hold struct
3594 * - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @p event_info is @c NULL.
3596 * - #EVAS_CALLBACK_IMAGE_PRELOADED: @p event_info is @c NULL.
3598 * - #EVAS_CALLBACK_IMAGE_UNLOADED: @p event_info is @c NULL.
3600 * @note Be careful not to add the same callback multiple times, if
3601 * that's not what you want, because Evas won't check if a callback
3602 * existed before exactly as the one being registered (and thus, call
3603 * it more than once on the event, in this case). This would make
3604 * sense if you passed different functions and/or callback data, only.
3607 * @dontinclude evas-events.c
3608 * @skip evas_object_event_callback_add(
3611 * See the full example @ref Example_Evas_Events "here".
3614 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);
3617 * Delete a callback function from an object
3619 * @param obj Object to remove a callback from
3620 * @param type The type of event that was triggering the callback
3621 * @param func The function that was to be called when the event was triggered
3622 * @return The data pointer that was to be passed to the callback
3624 * This function removes the most recently added callback from the
3625 * object @p obj which was triggered by the event type @p type and was
3626 * calling the function @p func when triggered. If the removal is
3627 * successful it will also return the data pointer that was passed to
3628 * evas_object_event_callback_add() when the callback was added to the
3629 * object. If not successful NULL will be returned.
3633 * extern Evas_Object *object;
3635 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3637 * my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
3640 EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3);
3643 * Delete (unregister) a callback function registered to a given
3644 * Evas object event.
3646 * @param obj Object to remove a callback from
3647 * @param type The type of event that was triggering the callback
3648 * @param func The function that was to be called when the event was
3650 * @param data The data pointer that was to be passed to the callback
3651 * @return The data pointer that was to be passed to the callback
3653 * This function removes the most recently added callback from the
3654 * object @p obj, which was triggered by the event type @p type and was
3655 * calling the function @p func with data @p data, when triggered. If
3656 * the removal is successful it will also return the data pointer that
3657 * was passed to evas_object_event_callback_add() (that will be the
3658 * same as the parameter) when the callback was added to the
3659 * object. In errors, @c NULL will be returned.
3661 * @note For deletion of Evas object events callbacks filtering by
3662 * just type and function pointer, user
3663 * evas_object_event_callback_del().
3667 * extern Evas_Object *object;
3669 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3671 * my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
3674 EAPI 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);
3678 * Set whether an Evas object is to pass (ignore) events.
3680 * @param obj the Evas object to operate on
3681 * @param pass whether @p obj is to pass events (@c EINA_TRUE) or not
3684 * If @p pass is @c EINA_TRUE, it will make events on @p obj to be @b
3685 * ignored. They will be triggered on the @b next lower object (that
3686 * is not set to pass events), instead (see evas_object_below_get()).
3688 * If @p pass is @c EINA_FALSE, events will be processed on that
3691 * @see evas_object_pass_events_get() for an example
3692 * @see evas_object_repeat_events_set()
3693 * @see evas_object_propagate_events_set()
3695 EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1);
3698 * Determine whether an object is set to pass (ignore) events.
3700 * @param obj the Evas object to get information from.
3701 * @return pass whether @p obj is set to pass events (@c EINA_TRUE) or not
3705 * @dontinclude evas-stacking.c
3706 * @skip if (strcmp(ev->keyname, "p") == 0)
3709 * See the full @ref Example_Evas_Stacking "example".
3711 * @see evas_object_pass_events_set()
3712 * @see evas_object_repeat_events_get()
3713 * @see evas_object_propagate_events_get()
3715 EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3718 * Set whether an Evas object is to repeat events.
3720 * @param obj the Evas object to operate on
3721 * @param repeat whether @p obj is to repeat events (@c EINA_TRUE) or not
3724 * If @p repeat is @c EINA_TRUE, it will make events on @p obj to also
3725 * be repeated for the @b next lower object in the objects' stack (see
3726 * see evas_object_below_get()).
3728 * If @p repeat is @c EINA_FALSE, events occurring on @p obj will be
3729 * processed only on it.
3732 * @dontinclude evas-stacking.c
3733 * @skip if (strcmp(ev->keyname, "r") == 0)
3736 * See the full @ref Example_Evas_Stacking "example".
3738 * @see evas_object_repeat_events_get()
3739 * @see evas_object_pass_events_get()
3740 * @see evas_object_propagate_events_get()
3742 EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
3745 * Determine whether an object is set to repeat events.
3747 * @param obj the given Evas object pointer
3748 * @retrieve whether @p obj is set to repeat events (@c EINA_TRUE)
3749 * or not (@c EINA_FALSE)
3751 * @see evas_object_repeat_events_set() for an example
3752 * @see evas_object_pass_events_set()
3753 * @see evas_object_propagate_events_set()
3755 EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3758 * Set whether events on a smart object's member should get propagated
3761 * @param obj the smart object's child to operate on
3762 * @param prop whether to propagate events (@c EINA_TRUE) or not (@c
3765 * This function has @b no effect if @p obj is not a member of a smart
3768 * If @p prop is @c EINA_TRUE, events occurring on this object will be
3769 * propagated on to the smart object of which @p obj is a member. If
3770 * @p prop is @c EINA_FALSE, events occurring on this object will @b
3771 * not be propagated on to the smart object of which @p obj is a
3772 * member. The default value is @c EINA_TRUE.
3774 * @see evas_object_event_callback_add()
3775 * @see evas_object_propagate_events_get()
3776 * @see evas_object_repeat_events_get()
3777 * @see evas_object_pass_events_get()
3779 EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1);
3782 * Retrieve whether an Evas object is set to propagate events.
3784 * @param obj the given Evas object pointer
3785 * @return whether @p obj is set to propagate events (@c EINA_TRUE)
3786 * or not (@c EINA_FALSE)
3788 * @see evas_object_event_callback_add()
3789 * @see evas_object_propagate_events_set()
3790 * @see evas_object_repeat_events_set()
3791 * @see evas_object_pass_events_set()
3793 EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3800 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspecitve, 3D...)
3802 * Evas allows different transformations to be applied to all kinds of
3803 * objects. These are applied by means of UV mapping.
3805 * With UV mapping, one maps points in the source object to a 3D space
3806 * positioning at target. This allows rotation, perspective, scale and
3807 * lots of other effects, depending on the map that is used.
3809 * Each map point may carry a multiplier color. If properly
3810 * calculated, these can do shading effects on the object, producing
3813 * As usual, Evas provides both the raw and easy to use methods. The
3814 * raw methods allow developer to create its maps somewhere else,
3815 * maybe load them from some file format. The easy to use methods,
3816 * calculate the points given some high-level parameters, such as
3817 * rotation angle, ambient light and so on.
3819 * @note applying mapping will reduce performance, so use with
3820 * care. The impact on performance depends on engine in
3821 * use. Software is quite optimized, but not as fast as OpenGL.
3823 * @ingroup Evas_Object_Group
3827 * Enable or disable the map that is set.
3829 * This enables the map that is set or disables it. On enable, the object
3830 * geometry will be saved, and the new geometry will change (position and
3831 * size) to reflect the map geometry set. If none is set yet, this may be
3832 * an undefined geometry, unless you have already set the map with
3833 * evas_object_map_set(). It is suggested you first set a map with
3834 * evas_object_map_set() with valid useful coordinates then enable and
3835 * disable the map with evas_object_map_enable_set() as needed.
3837 * @param obj object to enable the map on
3838 * @param enabled enabled state
3840 EAPI void evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled);
3843 * Get the map enabled state
3845 * This returns the currently enabled state of the map on the object indicated.
3846 * The default map enable state is off. You can enable and disable it with
3847 * evas_object_map_enable_set().
3849 * @param obj object to get the map enabled state from
3850 * @return the map enabled state
3852 EAPI Eina_Bool evas_object_map_enable_get (const Evas_Object *obj);
3855 * Set the map source object
3857 * This sets the object from which the map is taken - can be any object that
3858 * has map enabled on it.
3860 * Currently not implemented. for future use.
3862 * @param obj object to set the map source of
3863 * @param src the source object from which the map is taken
3865 EAPI void evas_object_map_source_set (Evas_Object *obj, Evas_Object *src);
3868 * Get the map source object
3870 * See evas_object_map_source_set()
3872 * @param obj object to set the map source of
3873 * @return the object set as the source
3875 EAPI Evas_Object *evas_object_map_source_get (const Evas_Object *obj);
3878 * Set current object transformation map.
3880 * This sets the map on a given object. It is copied from the @p map pointer,
3881 * so there is no need to keep the @p map object if you don't need it anymore.
3883 * A map is a set of 4 points which have canvas x, y coordinates per point,
3884 * with an optional z point value as a hint for perspective correction, if it
3885 * is available. As well each point has u and v coordinates. These are like
3886 * "texture coordinates" in OpenGL in that they define a point in the source
3887 * image that is mapped to that map vertex/point. The u corresponds to the x
3888 * coordinate of this mapped point and v, the y coordinate. Note that these
3889 * coordinates describe a bounding region to sample. If you have a 200x100
3890 * source image and want to display it at 200x100 with proper pixel
3891 * precision, then do:
3894 * Evas_Map *m = evas_map_new(4);
3895 * evas_map_point_coord_set(m, 0, 0, 0, 0);
3896 * evas_map_point_coord_set(m, 1, 200, 0, 0);
3897 * evas_map_point_coord_set(m, 2, 200, 100, 0);
3898 * evas_map_point_coord_set(m, 3, 0, 100, 0);
3899 * evas_map_point_image_uv_set(m, 0, 0, 0);
3900 * evas_map_point_image_uv_set(m, 1, 200, 0);
3901 * evas_map_point_image_uv_set(m, 2, 200, 100);
3902 * evas_map_point_image_uv_set(m, 3, 0, 100);
3903 * evas_object_map_set(obj, m);
3907 * Note that the map points a uv coordinates match the image geometry. If
3908 * the @p map parameter is NULL, the stored map will be freed and geometry
3909 * prior to enabling/setting a map will be restored.
3911 * @param obj object to change transformation map
3912 * @param map new map to use
3914 * @see evas_map_new()
3916 EAPI void evas_object_map_set (Evas_Object *obj, const Evas_Map *map);
3919 * Get current object transformation map.
3921 * This returns the current internal map set on the indicated object. It is
3922 * intended for read-only acces and is only valid as long as the object is
3923 * not deleted or the map on the object is not changed. If you wish to modify
3924 * the map and set it back do the following:
3927 * const Evas_Map *m = evas_object_map_get(obj);
3928 * Evas_Map *m2 = evas_map_dup(m);
3929 * evas_map_util_rotate(m2, 30.0, 0, 0);
3930 * evas_object_map_set(obj);
3931 * evas_map_free(m2);
3934 * @param obj object to query transformation map.
3935 * @return map reference to map in use. This is an internal data structure, so
3938 * @see evas_object_map_set()
3940 EAPI const Evas_Map *evas_object_map_get (const Evas_Object *obj);
3944 * Populate source and destination map points to match exactly object.
3946 * Usually one initialize map of an object to match it's original
3947 * position and size, then transform these with evas_map_util_*
3948 * functions, such as evas_map_util_rotate() or
3949 * evas_map_util_3d_rotate(). The original set is done by this
3950 * function, avoiding code duplication all around.
3952 * @param m map to change all 4 points (must be of size 4).
3953 * @param obj object to use unmapped geometry to populate map coordinates.
3954 * @param z Point Z Coordinate hint (pre-perspective transform). This value
3955 * will be used for all four points.
3957 * @see evas_map_util_points_populate_from_object()
3958 * @see evas_map_point_coord_set()
3959 * @see evas_map_point_image_uv_set()
3961 EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
3964 * Populate source and destination map points to match exactly object.
3966 * Usually one initialize map of an object to match it's original
3967 * position and size, then transform these with evas_map_util_*
3968 * functions, such as evas_map_util_rotate() or
3969 * evas_map_util_3d_rotate(). The original set is done by this
3970 * function, avoiding code duplication all around.
3972 * Z Point coordinate is assumed as 0 (zero).
3974 * @param m map to change all 4 points (must be of size 4).
3975 * @param obj object to use unmapped geometry to populate map coordinates.
3977 * @see evas_map_util_points_populate_from_object_full()
3978 * @see evas_map_util_points_populate_from_geometry()
3979 * @see evas_map_point_coord_set()
3980 * @see evas_map_point_image_uv_set()
3982 EAPI void evas_map_util_points_populate_from_object (Evas_Map *m, const Evas_Object *obj);
3985 * Populate source and destination map points to match given geometry.
3987 * Similar to evas_map_util_points_populate_from_object_full(), this
3988 * call takes raw values instead of querying object's unmapped
3989 * geometry. The given width will be used to calculate destination
3990 * points (evas_map_point_coord_set()) and set the image uv
3991 * (evas_map_point_image_uv_set()).
3993 * @param m map to change all 4 points (must be of size 4).
3994 * @param x Point X Coordinate
3995 * @param y Point Y Coordinate
3996 * @param w width to use to calculate second and third points.
3997 * @param h height to use to calculate third and fourth points.
3998 * @param z Point Z Coordinate hint (pre-perspective transform). This value
3999 * will be used for all four points.
4001 * @see evas_map_util_points_populate_from_object()
4002 * @see evas_map_point_coord_set()
4003 * @see evas_map_point_image_uv_set()
4005 EAPI 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);
4008 * Set color of all points to given color.
4010 * This call is useful to reuse maps after they had 3d lightning or
4011 * any other colorization applied before.
4013 * @param m map to change the color of.
4014 * @param r red (0 - 255)
4015 * @param g green (0 - 255)
4016 * @param b blue (0 - 255)
4017 * @param a alpha (0 - 255)
4019 * @see evas_map_point_color_set()
4021 EAPI void evas_map_util_points_color_set (Evas_Map *m, int r, int g, int b, int a);
4024 * Change the map to apply the given rotation.
4026 * This rotates the indicated map's coordinates around the center coordinate
4027 * given by @p cx and @p cy as the rotation center. The points will have their
4028 * X and Y coordinates rotated clockwise by @p degrees degress (360.0 is a
4029 * full rotation). Negative values for degrees will rotate counter-clockwise
4030 * by that amount. All coordinates are canvas global coordinates.
4032 * @param m map to change.
4033 * @param degrees amount of degrees from 0.0 to 360.0 to rotate.
4034 * @param cx rotation's center horizontal position.
4035 * @param cy rotation's center vertical position.
4037 * @see evas_map_point_coord_set()
4038 * @see evas_map_util_zoom()
4040 EAPI void evas_map_util_rotate (Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
4043 * Change the map to apply the given zooming.
4045 * Like evas_map_util_rotate(), this zooms the points of the map from a center
4046 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
4047 * parameters specific how much to zoom in the X and Y direction respectively.
4048 * A value of 1.0 means "don't zoom". 2.0 means "dobule the size". 0.5 is
4049 * "half the size" etc. All coordinates are canvas global coordinates.
4051 * @param m map to change.
4052 * @param zoomx horizontal zoom to use.
4053 * @param zoomy vertical zoom to use.
4054 * @param cx zooming center horizontal position.
4055 * @param cy zooming center vertical position.
4057 * @see evas_map_point_coord_set()
4058 * @see evas_map_util_rotate()
4060 EAPI void evas_map_util_zoom (Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
4063 * Rotate the map around 3 axes in 3D
4065 * This will rotate not just around the "Z" axis as in evas_map_util_rotate()
4066 * (which is a convenience call for those only wanting 2D). This will rotate
4067 * around the X, Y and Z axes. The Z axis points "into" the screen with low
4068 * values at the screen and higher values further away. The X axis runs from
4069 * left to right on the screen and the Y axis from top to bottom. Like with
4070 * evas_map_util_rotate(0 you provide a center point to rotate around (in 3D).
4072 * @param m map to change.
4073 * @param dx amount of degrees from 0.0 to 360.0 to rotate arount X axis.
4074 * @param dy amount of degrees from 0.0 to 360.0 to rotate arount Y axis.
4075 * @param dz amount of degrees from 0.0 to 360.0 to rotate arount Z axis.
4076 * @param cx rotation's center horizontal position.
4077 * @param cy rotation's center vertical position.
4078 * @param cz rotation's center vertical position.
4080 EAPI void evas_map_util_3d_rotate (Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz);
4083 * Perform lighting calculations on the given Map
4085 * This is used to apply lighting calculations (from a single light source)
4086 * to a given map. The R, G and B values of each vertex will be modified to
4087 * reflect the lighting based on the lixth point coordinates, the light
4088 * color and the ambient color, and at what angle the map is facing the
4089 * light source. A surface should have its points be declared in a
4090 * clockwise fashion if the face is "facing" towards you (as opposed to
4091 * away from you) as faces have a "logical" side for lighting.
4093 * @param m map to change.
4094 * @param lx X coordinate in space of light point
4095 * @param ly Y coordinate in space of light point
4096 * @param lz Z coordinate in space of light point
4097 * @param lr light red value (0 - 255)
4098 * @param lg light green value (0 - 255)
4099 * @param lb light blue value (0 - 255)
4100 * @param ar ambient color red value (0 - 255)
4101 * @param ag ambient color green value (0 - 255)
4102 * @param ab ambient color blue value (0 - 255)
4104 EAPI 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);
4107 * Apply a perspective transform to the map
4109 * This applies a given perspective (3D) to the map coordinates. X, Y and Z
4110 * values are used. The px and py points specify the "infinite distance" point
4111 * in the 3D conversion (where all lines converge to like when artists draw
4112 * 3D by hand). The @p z0 value specifis the z value at which there is a 1:1
4113 * mapping between spatial coorinates and screen coordinates. Any points
4114 * on this z value will not have their X and Y values modified in the transform.
4115 * Those further away (Z value higher) will shrink into the distance, and
4116 * those less than this value will expand and become bigger. The @p foc value
4117 * determines the "focal length" of the camera. This is in reality the distance
4118 * between the camera lens plane itself (at or closer than this rendering
4119 * results are undefined) and the "z0" z value. This allows for some "depth"
4120 * control and @p foc must be greater than 0.
4122 * @param m map to change.
4123 * @param px The pespective distance X coordinate
4124 * @param py The pespective distance Y coordinate
4125 * @param z0 The "0" z plane value
4126 * @param foc The focal distance
4128 EAPI void evas_map_util_3d_perspective (Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
4131 * Get the clockwise state of a map
4133 * This determines if the output points (X and Y. Z is not used) are
4134 * clockwise or anti-clockwise. This can be used for "back-face culling". This
4135 * is where you hide objects that "face away" from you. In this case objects
4136 * that are not clockwise.
4138 * @param m map to query.
4139 * @return 1 if clockwise, 0 otherwise
4141 EAPI Eina_Bool evas_map_util_clockwise_get (Evas_Map *m);
4145 * Create map of transformation points to be later used with an Evas object.
4147 * This creates a set of points (currently only 4 is supported. no other
4148 * number for @p count will work). That is empty and ready to be modified
4149 * with evas_map calls.
4151 * @param count number of points in the map. *
4152 * @return a newly allocated map or @c NULL on errors.
4154 * @see evas_map_free()
4155 * @see evas_map_dup()
4156 * @see evas_map_point_coord_set()
4157 * @see evas_map_point_image_uv_set()
4158 * @see evas_map_util_points_populate_from_object_full()
4159 * @see evas_map_util_points_populate_from_object()
4161 * @see evas_object_map_set()
4163 EAPI Evas_Map *evas_map_new (int count);
4166 * Set the smoothing for map rendering
4168 * This sets smoothing for map rendering. If the object is a type that has
4169 * its own smoothing settings, then both the smooth settings for this object
4170 * and the map must be turned off. By default smooth maps are enabled.
4172 * @param m map to modify. Must not be NULL.
4173 * @param enabled enable or disable smooth map rendering
4175 EAPI void evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled);
4178 * get the smoothing for map rendering
4180 * This gets smoothing for map rendering.
4182 * @param m map to get the smooth from. Must not be NULL.
4184 EAPI Eina_Bool evas_map_smooth_get (const Evas_Map *m);
4187 * Set the alpha flag for map rendering
4189 * This sets alpha flag for map rendering. If the object is a type that has
4190 * its own alpha settings, then this will take precedence. Only image objects
4191 * have this currently. Fits stops alpha blending of the map area, and is
4192 * useful if you know the object and/or all sub-objects is 100% solid.
4194 * @param m map to modify. Must not be NULL.
4195 * @param enabled enable or disable alpha map rendering
4197 EAPI void evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled);
4200 * get the alpha flag for map rendering
4202 * This gets the alph flag for map rendering.
4204 * @param m map to get the alpha from. Must not be NULL.
4206 EAPI Eina_Bool evas_map_alpha_get (const Evas_Map *m);
4209 * Copy a previously allocated map.
4211 * This makes a duplicate of the @p m object and returns it.
4213 * @param m map to copy. Must not be NULL.
4214 * @return newly allocated map with the same count and contents as @p m.
4216 EAPI Evas_Map *evas_map_dup (const Evas_Map *m);
4219 * Free a previously allocated map.
4221 * This frees a givem map @p m and all memory associated with it. You must NOT
4222 * free a map returned by evas_object_map_get() as this is internal.
4224 * @param m map to free.
4226 EAPI void evas_map_free (Evas_Map *m);
4231 * Returns the number of points in a map. Should be at least 4.
4233 * @param m map to get size.
4234 * @return -1 on error, points otherwise.
4236 EAPI int evas_map_count_get (const Evas_Map *m) EINA_CONST;
4239 * Change the map point's coordinate.
4241 * This sets the fixen point's coordinate in the map. Note that points
4242 * describe the outline of a quadrangle and are ordered either clockwise
4243 * or anit-clock-wise. It is suggested to keep your quadrangles concave and
4244 * non-complex, though these polygon modes may work, they may not render
4245 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
4246 * 2 and 3, and 3 and 0 to describe the edges of the quandrangle.
4248 * The X and Y and Z coordinates are in canvas units. Z is optional and may
4249 * or may not be honored in drawing. Z is a hint and does not affect the
4250 * X and Y rendered coordinates. It may be used for calculating fills with
4251 * perspective correct rendering.
4253 * Remember all coordinates are canvas global ones like with move and reize
4256 * @param m map to change point. Must not be @c NULL.
4257 * @param idx index of point to change. Must be smaller than map size.
4258 * @param x Point X Coordinate
4259 * @param y Point Y Coordinate
4260 * @param z Point Z Coordinate hint (pre-perspective transform)
4262 * @see evas_map_util_rotate()
4263 * @see evas_map_util_zoom()
4264 * @see evas_map_util_points_populate_from_object_full()
4265 * @see evas_map_util_points_populate_from_object()
4267 EAPI void evas_map_point_coord_set (Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
4270 * Get the map point's coordinate.
4272 * This returns the coordinates of the given point in the map.
4274 * @param m map to query point.
4275 * @param idx index of point to query. Must be smaller than map size.
4276 * @param x where to return the X coordinate.
4277 * @param y where to return the Y coordinate.
4278 * @param z where to return the Z coordinate.
4280 EAPI void evas_map_point_coord_get (const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
4283 * Change the map point's U and V texture source point
4285 * This sets the U and V coordinates for the point. This determines which
4286 * coordinate in the source image is mapped to the given point, much like
4287 * OpenGL and textures. Notes that these points do select the pixel, but
4288 * are double floating point values to allow for accuracy and sub-pixel
4291 * @param m map to change the point of.
4292 * @param idx index of point to change. Must be smaller than map size.
4293 * @param u the X coordinate within the image/texture source
4294 * @param v the Y coordinate within the image/texture source
4296 * @see evas_map_point_coord_set()
4297 * @see evas_object_map_set()
4298 * @see evas_map_util_points_populate_from_object_full()
4299 * @see evas_map_util_points_populate_from_object()
4301 EAPI void evas_map_point_image_uv_set (Evas_Map *m, int idx, double u, double v);
4304 * Get the map point's U and V texture source points
4306 * This returns the texture points set by evas_map_point_image_uv_set().
4308 * @param m map to query point.
4309 * @param idx index of point to query. Must be smaller than map size.
4310 * @param u where to write the X coordinate within the image/texture source
4311 * @param v where to write the Y coordinate within the image/texture source
4313 EAPI void evas_map_point_image_uv_get (const Evas_Map *m, int idx, double *u, double *v);
4316 * Set the color of a vertex in the map
4318 * This sets the color of the vertex in the map. Colors will be linearly
4319 * interpolated between vertex points through the map. Color will multiply
4320 * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
4321 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
4322 * have no affect on modifying the texture pixels.
4324 * @param m map to change the color of.
4325 * @param idx index of point to change. Must be smaller than map size.
4326 * @param r red (0 - 255)
4327 * @param g green (0 - 255)
4328 * @param b blue (0 - 255)
4329 * @param a alpha (0 - 255)
4331 * @see evas_map_util_points_color_set()
4332 * @see evas_map_point_coord_set()
4333 * @see evas_object_map_set()
4335 EAPI void evas_map_point_color_set (Evas_Map *m, int idx, int r, int g, int b, int a);
4338 * Get the color set on a vertex in the map
4340 * This gets the color set by evas_map_point_color_set() on the given vertex
4343 * @param m map to get the color of the vertex from.
4344 * @param idx index of point get. Must be smaller than map size.
4345 * @param r pointer to red return
4346 * @param g pointer to green return
4347 * @param b pointer to blue return
4348 * @param a pointer to alpha return (0 - 255)
4350 * @see evas_map_point_coord_set()
4351 * @see evas_object_map_set()
4353 EAPI void evas_map_point_color_get (const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
4356 * @defgroup Evas_Object_Group_Size_Hints Size Hints
4358 * Objects may carry hints, so that another object that acts as a
4359 * manager (see @ref Evas_Smart_Object_Group) may know how to properly
4360 * position and resize its subordinate objects. The Size Hints provide
4361 * a common interface that is recommended as the protocol for such
4364 * For example, box objects use alignment hints to align its
4365 * lines/columns inside its container, padding hints to set the
4366 * padding between each individual child, etc.
4368 * Examples on their usage:
4369 * - @ref Example_Evas_Size_Hints "evas-hints.c"
4370 * - @ref Example_Evas_Aspect_Hints "evas-aspect-hints.c"
4372 * @ingroup Evas_Object_Group
4376 * @addtogroup Evas_Object_Group_Size_Hints
4381 * Retrieves the hints for an object's minimum size.
4383 * @param obj The given Evas object to query hints from.
4384 * @param w Pointer to an integer in which to store the minimum width.
4385 * @param h Pointer to an integer in which to store the minimum height.
4387 * These are hints on the minimim sizes @p obj should have. This is
4388 * not a size enforcement in any way, it's just a hint that should be
4389 * used whenever appropriate.
4391 * @note Use @c NULL pointers on the hint components you're not
4392 * interested in: they'll be ignored by the function.
4394 * @see evas_object_size_hint_min_set() for an example
4396 EAPI void evas_object_size_hint_min_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4399 * Sets the hints for an object's minimum size.
4401 * @param obj The given Evas object to query hints from.
4402 * @param w Integer to use as the minimum width hint.
4403 * @param h Integer to use as the minimum height hint.
4405 * This is not a size enforcement in any way, it's just a hint that
4406 * should be used whenever appropriate.
4408 * Values @c 0 will be treated as unset hint components, when queried
4412 * @dontinclude evas-hints.c
4413 * @skip evas_object_size_hint_min_set
4416 * In this example the minimum size hints change de behavior of an
4417 * Evas box when layouting its children. See the full @ref
4418 * Example_Evas_Size_Hints "example".
4420 * @see evas_object_size_hint_min_get()
4422 EAPI void evas_object_size_hint_min_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4425 * Retrieves the hints for an object's maximum size.
4427 * @param obj The given Evas object to query hints from.
4428 * @param w Pointer to an integer in which to store the maximum width.
4429 * @param h Pointer to an integer in which to store the maximum height.
4431 * These are hints on the maximum sizes @p obj should have. This is
4432 * not a size enforcement in any way, it's just a hint that should be
4433 * used whenever appropriate.
4435 * @note Use @c NULL pointers on the hint components you're not
4436 * interested in: they'll be ignored by the function.
4438 * @see evas_object_size_hint_max_set()
4440 EAPI void evas_object_size_hint_max_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4443 * Sets the hints for an object's maximum size.
4445 * @param obj The given Evas object to query hints from.
4446 * @param w Integer to use as the maximum width hint.
4447 * @param h Integer to use as the maximum height hint.
4449 * This is not a size enforcement in any way, it's just a hint that
4450 * should be used whenever appropriate.
4452 * Values @c -1 will be treated as unset hint components, when queried
4456 * @dontinclude evas-hints.c
4457 * @skip evas_object_size_hint_max_set
4460 * In this example the maximum size hints change de behavior of an
4461 * Evas box when layouting its children. See the full @ref
4462 * Example_Evas_Size_Hints "example".
4464 * @see evas_object_size_hint_max_get()
4466 EAPI void evas_object_size_hint_max_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4469 * Retrieves the hints for an object's optimum size.
4471 * @param obj The given Evas object to query hints from.
4472 * @param w Pointer to an integer in which to store the requested width.
4473 * @param h Pointer to an integer in which to store the requested height.
4475 * These are hints on the optimum sizes @p obj should have. This is
4476 * not a size enforcement in any way, it's just a hint that should be
4477 * used whenever appropriate.
4479 * @note Use @c NULL pointers on the hint components you're not
4480 * interested in: they'll be ignored by the function.
4482 * @see evas_object_size_hint_request_set()
4484 EAPI void evas_object_size_hint_request_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4487 * Sets the hints for an object's optimum size.
4489 * @param obj The given Evas object to query hints from.
4490 * @param w Integer to use as the preferred width hint.
4491 * @param h Integer to use as the preferred height hint.
4493 * This is not a size enforcement in any way, it's just a hint that
4494 * should be used whenever appropriate.
4496 * Values @c 0 will be treated as unset hint components, when queried
4499 * @see evas_object_size_hint_request_get()
4501 EAPI void evas_object_size_hint_request_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4504 * Retrieves the hints for an object's aspect ratio.
4506 * @param obj The given Evas object to query hints from.
4507 * @param aspect Returns the policy/type of aspect ratio applied to @p obj.
4508 * @param w Pointer to an integer in which to store the aspect's width
4510 * @param h Pointer to an integer in which to store the aspect's
4511 * height ratio term.
4513 * The different aspect ratio policies are documented in the
4514 * #Evas_Aspect_Control type. A container respecting these size hints
4515 * would @b scale its children accordingly to those policies.
4517 * For any policy, if any of the given aspect ratio terms are @c 0,
4518 * the object's container should ignore the aspect and scale @p obj to
4519 * occupy the whole available area. If they are both positive
4520 * integers, that proportion will be respected, under each scaling
4523 * These images illustrate some of the #Evas_Aspect_Control policies:
4525 * @image html any-policy.png
4526 * @image rtf any-policy.png
4527 * @image latex any-policy.eps
4529 * @image html aspect-control-none-neither.png
4530 * @image rtf aspect-control-none-neither.png
4531 * @image latex aspect-control-none-neither.eps
4533 * @image html aspect-control-both.png
4534 * @image rtf aspect-control-both.png
4535 * @image latex aspect-control-both.eps
4537 * @image html aspect-control-horizontal.png
4538 * @image rtf aspect-control-horizontal.png
4539 * @image latex aspect-control-horizontal.eps
4541 * This is not a size enforcement in any way, it's just a hint that
4542 * should be used whenever appropriate.
4544 * @note Use @c NULL pointers on the hint components you're not
4545 * interested in: they'll be ignored by the function.
4548 * @dontinclude evas-aspect-hints.c
4549 * @skip if (strcmp(ev->keyname, "c") == 0)
4552 * See the full @ref Example_Evas_Aspect_Hints "example".
4554 * @see evas_object_size_hint_aspect_set()
4556 EAPI 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);
4559 * Sets the hints for an object's aspect ratio.
4561 * @param obj The given Evas object to query hints from.
4562 * @param aspect The policy/type of aspect ratio to apply to @p obj.
4563 * @param w Integer to use as aspect width ratio term.
4564 * @param h Integer to use as aspect height ratio term.
4566 * This is not a size enforcement in any way, it's just a hint that should
4567 * be used whenever appropriate.
4569 * If any of the given aspect ratio terms are @c 0,
4570 * the object's container will ignore the aspect and scale @p obj to
4571 * occupy the whole available area, for any given policy.
4573 * @see evas_object_size_hint_aspect_get() for more information.
4575 EAPI void evas_object_size_hint_aspect_set (Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4578 * Retrieves the hints for on object's alignment.
4580 * @param obj The given Evas object to query hints from.
4581 * @param x Pointer to a double in which to store the horizontal
4583 * @param y Pointer to a double in which to store the vertical
4586 * This is not a size enforcement in any way, it's just a hint that
4587 * should be used whenever appropriate.
4589 * @note Use @c NULL pointers on the hint components you're not
4590 * interested in: they'll be ignored by the function.
4592 * @see evas_object_size_hint_align_set() for more information
4594 EAPI void evas_object_size_hint_align_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
4597 * Sets the hints for an object's alignment.
4599 * @param obj The given Evas object to query hints from.
4600 * @param x Double, ranging from @c 0.0 to @c 1.0 or with the
4601 * special value #EVAS_HINT_FILL, to use as horizontal alignment hint.
4602 * @param y Double, ranging from @c 0.0 to @c 1.0 or with the
4603 * special value #EVAS_HINT_FILL, to use as vertical alignment hint.
4605 * These are hints on how to align an object <b>inside the boundaries
4606 * of a container/manager</b>. Accepted values are in the @c 0.0 to @c
4607 * 1.0 range, with the special value #EVAS_HINT_FILL used to specify
4608 * "justify" or "fill" by some users. See documentation of possible
4609 * users: in Evas, they are the @ref Evas_Object_Box "box" and @ref
4610 * Evas_Object_Table "table" smart objects.
4612 * For the horizontal component, @c 0.0 means to the left, @c 1.0
4613 * means to the right. Analogously, for the vertical component, @c 0.0
4614 * to the top, @c 1.0 means to the bottom.
4616 * See the following figure:
4617 * @image html alignment-hints.png
4618 * @image rtf alignment-hints.png
4619 * @image latex alignment-hints.eps
4621 * This is not a size enforcement in any way, it's just a hint that
4622 * should be used whenever appropriate.
4625 * @dontinclude evas-hints.c
4626 * @skip evas_object_size_hint_align_set
4629 * In this example the alignment hints change de behavior of an Evas
4630 * box when layouting its children. See the full @ref
4631 * Example_Evas_Size_Hints "example".
4633 * @see evas_object_size_hint_align_get()
4635 EAPI void evas_object_size_hint_align_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
4638 * Retrieves the hints for an object's weight.
4640 * @param obj The given Evas object to query hints from.
4641 * @param x Pointer to a double in which to store the horizontal weight.
4642 * @param y Pointer to a double in which to store the vertical weight.
4644 * Accepted values are zero or positive values. Some users might use
4645 * this hint as a boolean, but some might consider it as a @b
4646 * proportion, see documentation of possible users, which in Evas are
4647 * the @ref Evas_Object_Box "box" and @ref Evas_Object_Table "table"
4650 * This is not a size enforcement in any way, it's just a hint that
4651 * should be used whenever appropriate.
4653 * @note Use @c NULL pointers on the hint components you're not
4654 * interested in: they'll be ignored by the function.
4656 * @see evas_object_size_hint_weight_set() for an example
4658 EAPI void evas_object_size_hint_weight_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
4661 * Sets the hints for an object's weight.
4663 * @param obj The given Evas object to query hints from.
4664 * @param x Double (@c 0.0-1.0) to use as horizontal weight hint.
4665 * @param y Double (@c 0.0-1.0) to use as vertical weight hint.
4667 * This is not a size enforcement in any way, it's just a hint that should
4668 * be used whenever appropriate.
4671 * @dontinclude evas-hints.c
4672 * @skip evas_object_size_hint_weight_set
4675 * In this example the weight hints change de behavior of an Evas box
4676 * when layouting its children. See the full @ref
4677 * Example_Evas_Size_Hints "example".
4679 * @see evas_object_size_hint_weight_get() for more information
4681 EAPI void evas_object_size_hint_weight_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
4684 * Retrieves the hints for an object's padding space.
4686 * @param obj The given Evas object to query hints from.
4687 * @param l Pointer to an integer in which to store left padding.
4688 * @param r Pointer to an integer in which to store right padding.
4689 * @param t Pointer to an integer in which to store top padding.
4690 * @param b Pointer to an integer in which to store bottom padding.
4692 * Padding is extra space an object takes on each of its delimiting
4693 * rectangle sides, in canvas units. This space will be rendered
4694 * transparent, naturally.
4696 * This is not a size enforcement in any way, it's just a hint that
4697 * should be used whenever appropriate.
4699 * @note Use @c NULL pointers on the hint components you're not
4700 * interested in: they'll be ignored by the function.
4703 * @dontinclude evas-hints.c
4704 * @skip evas_object_size_hint_padding_set
4707 * In this example the padding hints change de behavior of an Evas box
4708 * when layouting its children. See the full @ref
4709 * Example_Evas_Size_Hints "example".
4711 * @see evas_object_size_hint_padding_set()
4713 EAPI 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);
4716 * Sets the hints for an object's padding space.
4718 * @param obj The given Evas object to query hints from.
4719 * @param l Integer to specify left padding.
4720 * @param r Integer to specify right padding.
4721 * @param t Integer to specify top padding.
4722 * @param b Integer to specify bottom padding.
4724 * This is not a size enforcement in any way, it's just a hint that
4725 * should be used whenever appropriate.
4727 * @see evas_object_size_hint_padding_get() for more information
4729 EAPI 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);
4736 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
4738 * Miscellaneous functions that also apply to any object, but are less
4739 * used or not implemented by all objects.
4741 * Examples on this group of functions can be found @ref
4742 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
4744 * @ingroup Evas_Object_Group
4748 * @addtogroup Evas_Object_Group_Extras
4753 * Set an attached data pointer to an object with a given string key.
4755 * @param obj The object to attach the data pointer to
4756 * @param key The string key for the data to access it
4757 * @param data The ponter to the data to be attached
4759 * This attaches the pointer @p data to the object @p obj, given the
4760 * access string @p key. This pointer will stay "hooked" to the object
4761 * until a new pointer with the same string key is attached with
4762 * evas_object_data_set() or it is deleted with
4763 * evas_object_data_del(). On deletion of the object @p obj, the
4764 * pointers will not be accessible from the object anymore.
4766 * You can find the pointer attached under a string key using
4767 * evas_object_data_get(). It is the job of the calling application to
4768 * free any data pointed to by @p data when it is no longer required.
4770 * If @p data is @c NULL, the old value stored at @p key will be
4771 * removed but no new value will be stored. This is synonymous with
4772 * calling evas_object_data_del() with @p obj and @p key.
4774 * @note This function is very handy when you have data associated
4775 * specifically to an Evas object, being of use only when dealing with
4776 * it. Than you don't have the burden to a pointer to it elsewhere,
4777 * using this family of functions.
4783 * extern Evas_Object *obj;
4785 * my_data = malloc(500);
4786 * evas_object_data_set(obj, "name_of_data", my_data);
4787 * printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data"));
4790 EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2);
4793 * Return an attached data pointer on an Evas object by its given
4796 * @param obj The object to which the data was attached
4797 * @param key The string key the data was stored under
4798 * @return The data pointer stored, or @c NULL if none was stored
4800 * This function will return the data pointer attached to the object
4801 * @p obj, stored using the string key @p key. If the object is valid
4802 * and a data pointer was stored under the given key, that pointer
4803 * will be returned. If this is not the case, @c NULL will be
4804 * returned, signifying an invalid object or a non-existent key. It is
4805 * possible that a @c NULL pointer was stored given that key, but this
4806 * situation is non-sensical and thus can be considered an error as
4807 * well. @c NULL pointers are never stored as this is the return value
4808 * if an error occurs.
4814 * extern Evas_Object *obj;
4816 * my_data = evas_object_data_get(obj, "name_of_my_data");
4817 * if (my_data) printf("Data stored was %p\n", my_data);
4818 * else printf("No data was stored on the object\n");
4821 EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
4824 * Delete an attached data pointer from an object.
4826 * @param obj The object to delete the data pointer from
4827 * @param key The string key the data was stored under
4828 * @return The original data pointer stored at @p key on @p obj
4830 * This will remove the stored data pointer from @p obj stored under
4831 * @p key and return this same pointer, if actually there was data
4832 * there, or @c NULL, if nothing was stored under that key.
4838 * extern Evas_Object *obj;
4840 * my_data = evas_object_data_del(obj, "name_of_my_data");
4843 EAPI void *evas_object_data_del (Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
4847 * Set pointer behavior.
4850 * @param setting desired behavior.
4852 * This function has direct effect on event callbacks related to
4855 * If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse
4856 * is down at this object, events will be restricted to it as source,
4857 * mouse moves, for example, will be emitted even if outside this
4860 * If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will
4861 * be emitted just when inside this object area.
4863 * The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB.
4865 * @ingroup Evas_Object_Group_Extras
4867 EAPI void evas_object_pointer_mode_set (Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1);
4870 * Determine how pointer will behave.
4872 * @return pointer behavior.
4873 * @ingroup Evas_Object_Group_Extras
4875 EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4879 * Sets whether or not the given Evas object is to be drawn anti-aliased.
4881 * @param obj The given Evas object.
4882 * @param anti_alias 1 if the object is to be anti_aliased, 0 otherwise.
4883 * @ingroup Evas_Object_Group_Extras
4885 EAPI void evas_object_anti_alias_set (Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1);
4888 * Retrieves whether or not the given Evas object is to be drawn anti_aliased.
4889 * @param obj The given Evas object.
4890 * @return @c 1 if the object is to be anti_aliased. @c 0 otherwise.
4891 * @ingroup Evas_Object_Group_Extras
4893 EAPI Eina_Bool evas_object_anti_alias_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4897 * Sets the scaling factor for an Evas object. Does not affect all
4900 * @param obj The given Evas object.
4901 * @param scale The scaling factor. <c>1.0</c> means no scaling,
4904 * This will multiply the object's dimension by the given factor, thus
4905 * altering its geometry (width and height). Useful when you want
4906 * scalable UI elements, possibly at run time.
4908 * @note Only text and textblock objects have scaling change
4909 * handlers. Other objects won't change visually on this call.
4911 * @see evas_object_scale_get()
4913 * @ingroup Evas_Object_Group_Extras
4915 EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
4918 * Retrieves the scaling factor for the given Evas object.
4920 * @param obj The given Evas object.
4921 * @return The scaling factor.
4923 * @ingroup Evas_Object_Group_Extras
4925 * @see evas_object_scale_set()
4927 EAPI double evas_object_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4931 * Sets the render_op to be used for rendering the Evas object.
4932 * @param obj The given Evas object.
4933 * @param render_op one of the Evas_Render_Op values.
4934 * @ingroup Evas_Object_Group_Extras
4936 EAPI void evas_object_render_op_set (Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1);
4939 * Retrieves the current value of the operation used for rendering the Evas object.
4940 * @param obj The given Evas object.
4941 * @return one of the enumerated values in Evas_Render_Op.
4942 * @ingroup Evas_Object_Group_Extras
4944 EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4947 * Set whether to use precise (usually expensive) point collision
4948 * detection for a given Evas object.
4950 * @param obj The given object.
4951 * @param precise whether to use precise point collision detection or
4952 * not The default value is false.
4954 * Use this function to make Evas treat objects' transparent areas as
4955 * @b not belonging to it with regard to mouse pointer events. By
4956 * default, all of the object's boundary rectangle will be taken in
4959 * @warning By using precise point collision detection you'll be
4960 * making Evas more resource intensive.
4962 * Example code follows.
4963 * @dontinclude evas-events.c
4964 * @skip if (strcmp(ev->keyname, "p") == 0)
4967 * See the full example @ref Example_Evas_Events "here".
4969 * @see evas_object_precise_is_inside_get()
4970 * @ingroup Evas_Object_Group_Extras
4972 EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1);
4975 * Determine whether an object is set to use precise point collision
4978 * @param obj The given object.
4979 * @return whether @p obj is set to use precise point collision
4980 * detection or not The default value is false.
4982 * @see evas_object_precise_is_inside_set() for an example
4984 * @ingroup Evas_Object_Group_Extras
4986 EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4988 EAPI void evas_object_static_clip_set (Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1);
4989 EAPI Eina_Bool evas_object_static_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4996 * @defgroup Evas_Object_Group_Find Finding Objects
4998 * Functions that allows finding objects by their position, name or
5001 * @ingroup Evas_Object_Group
5005 * @addtogroup Evas_Object_Group_Find
5010 * Retrieve the object that currently has focus.
5012 * @param e The Evas canvas to query for focused object on.
5013 * @return The object that has focus or @c NULL if there is not one.
5015 * Evas can have (at most) one of its objects focused at a time.
5016 * Focused objects will be the ones having <b>key events</b> delivered
5017 * to, which the programmer can act upon by means of
5018 * evas_object_event_callback_add() usage.
5020 * @note Most users wouldn't be dealing directly with Evas' focused
5021 * objects. Instead, they would be using a higher level library for
5022 * that (like a toolkit, as Elementary) to handle focus and who's
5023 * receiving input for them.
5025 * This call returns the object that currently has focus on the canvas
5026 * @p e or @c NULL, if none.
5028 * @see evas_object_focus_set
5029 * @see evas_object_focus_get
5030 * @see evas_object_key_grab
5031 * @see evas_object_key_ungrab
5034 * @dontinclude evas-events.c
5035 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
5036 * @until evas_object_focus_set(d.bg, EINA_TRUE);
5037 * @dontinclude evas-events.c
5038 * @skip called when our rectangle gets focus
5041 * In this example the @c event_info is exactly a pointer to that
5042 * focused rectangle. See the full @ref Example_Evas_Events "example".
5044 * @ingroup Evas_Object_Group_Find
5046 EAPI Evas_Object *evas_focus_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5050 * Retrieves the object on the given evas with the given name.
5051 * @param e The given evas.
5052 * @param name The given name.
5053 * @return If successful, the Evas object with the given name. Otherwise,
5055 * @ingroup Evas_Object_Group_Find
5057 EAPI Evas_Object *evas_object_name_find (const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5061 * Retrieves the top object at the given position (x,y)
5062 * @param e The given Evas object.
5063 * @param x The horizontal coordinate
5064 * @param y The vertical coordinate
5065 * @param include_pass_events_objects Boolean Flag to include or not
5066 * pass events objects
5067 * @param include_hidden_objects Boolean Flag to include or not hidden objects
5068 * @return The Evas object that is over all others objects at the given position.
5070 EAPI 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;
5073 * Retrieves the top object at mouse pointer position
5074 * @param e The given Evas object.
5075 * @return The Evas object that is over all others objects at the
5078 EAPI Evas_Object *evas_object_top_at_pointer_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5081 * Retrieves the top object in the given rectangle region
5082 * @param e The given Evas object.
5083 * @param x The horizontal coordinate.
5084 * @param y The vertical coordinate.
5085 * @param w The width size.
5086 * @param h The height size.
5087 * @param include_pass_events_objects Boolean Flag to include or not pass events objects
5088 * @param include_hidden_objects Boolean Flag to include or not hidden objects
5089 * @return The Evas object that is over all others objects at the pointer position.
5092 EAPI 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;
5096 * Retrieves the objects at the given position
5097 * @param e The given Evas object.
5098 * @param x The horizontal coordinate.
5099 * @param y The vertical coordinate.
5100 * @param include_pass_events_objects Boolean Flag to include or not
5101 * pass events objects
5102 * @param include_hidden_objects Boolean Flag to include or not hidden objects
5103 * @return The list of Evas objects at the pointer position.
5106 EAPI 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;
5107 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;
5110 * Get the lowest (stacked) Evas object on the canvas @p
5112 * @param e a valid canvas pointer
5113 * @return a pointer to the lowest object on it, if any, or @c NULL,
5116 * This function will take all populated layers in the canvas into
5117 * account, getting the lowest object for the lowest layer, naturally.
5119 * @see evas_object_layer_get()
5120 * @see evas_object_layer_set()
5121 * @see evas_object_below_set()
5122 * @see evas_object_above_set()
5124 EAPI Evas_Object *evas_object_bottom_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5127 * Get the highest (stacked) Evas object on the canvas @p
5129 * @param e a valid canvas pointer
5130 * @return a pointer to the highest object on it, if any, or @c NULL,
5133 * This function will take all populated layers in the canvas into
5134 * account, getting the highest object for the highest layer,
5137 * @see evas_object_layer_get()
5138 * @see evas_object_layer_set()
5139 * @see evas_object_below_set()
5140 * @see evas_object_above_set()
5142 EAPI Evas_Object *evas_object_top_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5149 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
5151 * Evas provides a way to intercept method calls. The interceptor
5152 * callback may opt to completely deny the call, or may check and
5153 * change the parameters before continuing. The continuation of an
5154 * intercepted call is done by calling the intercepted call again,
5155 * from inside the interceptor callback.
5157 * @ingroup Evas_Object_Group
5159 typedef void (*Evas_Object_Intercept_Show_Cb) (void *data, Evas_Object *obj);
5160 typedef void (*Evas_Object_Intercept_Hide_Cb) (void *data, Evas_Object *obj);
5161 typedef void (*Evas_Object_Intercept_Move_Cb) (void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
5162 typedef void (*Evas_Object_Intercept_Resize_Cb) (void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
5163 typedef void (*Evas_Object_Intercept_Raise_Cb) (void *data, Evas_Object *obj);
5164 typedef void (*Evas_Object_Intercept_Lower_Cb) (void *data, Evas_Object *obj);
5165 typedef void (*Evas_Object_Intercept_Stack_Above_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
5166 typedef void (*Evas_Object_Intercept_Stack_Below_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
5167 typedef void (*Evas_Object_Intercept_Layer_Set_Cb) (void *data, Evas_Object *obj, int l);
5168 typedef void (*Evas_Object_Intercept_Color_Set_Cb) (void *data, Evas_Object *obj, int r, int g, int b, int a);
5169 typedef void (*Evas_Object_Intercept_Clip_Set_Cb) (void *data, Evas_Object *obj, Evas_Object *clip);
5170 typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *obj);
5174 * Set the callback function that intercepts a show event of a object.
5176 * @param obj The given canvas object pointer.
5177 * @param func The given function to be the callback function.
5178 * @param data The data passed to the callback function.
5180 * This function sets a callback function to intercepts a show event
5181 * of a canvas object.
5183 * @see evas_object_intercept_show_callback_del().
5186 EAPI void evas_object_intercept_show_callback_add (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
5189 * Unset the callback function that intercepts a show event of a
5192 * @param obj The given canvas object pointer.
5193 * @param func The given callback function.
5195 * This function sets a callback function to intercepts a show event
5196 * of a canvas object.
5198 * @see evas_object_intercept_show_callback_add().
5201 EAPI void *evas_object_intercept_show_callback_del (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2);
5204 * Set the callback function that intercepts a hide event of a object.
5206 * @param obj The given canvas object pointer.
5207 * @param func The given function to be the callback function.
5208 * @param data The data passed to the callback function.
5210 * This function sets a callback function to intercepts a hide event
5211 * of a canvas object.
5213 * @see evas_object_intercept_hide_callback_del().
5216 EAPI void evas_object_intercept_hide_callback_add (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
5219 * Unset the callback function that intercepts a hide event of a
5222 * @param obj The given canvas object pointer.
5223 * @param func The given callback function.
5225 * This function sets a callback function to intercepts a hide event
5226 * of a canvas object.
5228 * @see evas_object_intercept_hide_callback_add().
5231 EAPI void *evas_object_intercept_hide_callback_del (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2);
5234 * Set the callback function that intercepts a move event of a object.
5236 * @param obj The given canvas object pointer.
5237 * @param func The given function to be the callback function.
5238 * @param data The data passed to the callback function.
5240 * This function sets a callback function to intercepts a move event
5241 * of a canvas object.
5243 * @see evas_object_intercept_move_callback_del().
5246 EAPI void evas_object_intercept_move_callback_add (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
5249 * Unset the callback function that intercepts a move event of a
5252 * @param obj The given canvas object pointer.
5253 * @param func The given callback function.
5255 * This function sets a callback function to intercepts a move event
5256 * of a canvas object.
5258 * @see evas_object_intercept_move_callback_add().
5261 EAPI void *evas_object_intercept_move_callback_del (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2);
5263 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);
5264 EAPI void *evas_object_intercept_resize_callback_del (Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2);
5265 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);
5266 EAPI void *evas_object_intercept_raise_callback_del (Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2);
5267 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);
5268 EAPI void *evas_object_intercept_lower_callback_del (Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2);
5269 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);
5270 EAPI void *evas_object_intercept_stack_above_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2);
5271 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);
5272 EAPI void *evas_object_intercept_stack_below_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2);
5273 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);
5274 EAPI void *evas_object_intercept_layer_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2);
5275 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);
5276 EAPI void *evas_object_intercept_color_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2);
5277 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);
5278 EAPI void *evas_object_intercept_clip_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2);
5279 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);
5280 EAPI void *evas_object_intercept_clip_unset_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2);
5283 * @defgroup Evas_Object_Specific Specific Object Functions
5285 * Functions that work on specific objects.
5290 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
5292 * @brief Function to create evas rectangle objects.
5294 * This function may seem useless given there are no functions to manipulate
5295 * the created rectangle, however the rectangle is actually very useful and can
5296 * be manipulate using the generic @ref Evas_Object_Group
5297 * "evas object functions".
5299 * For an example of use of an evas_object_rectangle see @ref
5300 * Example_Evas_Object_Manipulation "here".
5302 * @ingroup Evas_Object_Specific
5306 * Adds a rectangle to the given evas.
5307 * @param e The given evas.
5308 * @return The new rectangle object.
5310 * @ingroup Evas_Object_Rectangle
5312 EAPI Evas_Object *evas_object_rectangle_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5315 * @defgroup Evas_Object_Image Image Object Functions
5317 * Functions used to create and manipulate image objects.
5319 * Note - Image objects may return or accept "image data" in multiple
5320 * formats. This is based on the colorspace of an object. Here is a
5321 * rundown on formats:
5323 * EVAS_COLORSPACE_ARGB8888:
5325 * This pixel format is a linear block of pixels, starting at the
5326 * top-left row by row until the bottom right of the image or pixel
5327 * region. All pixels are 32-bit unsigned int's with the high-byte
5328 * being alpha and the low byte being blue in the format ARGB. Alpha
5329 * may or may not be used by evas depending on the alpha flag of the
5330 * image, but if not used, should be set to 0xff anyway.
5332 * This colorspace uses premultiplied alpha. That means that R, G and
5333 * B cannot exceed A in value. The conversion from non-premultiplied
5336 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
5338 * So 50% transparent blue will be: 0x80000080. This will not be
5339 * "dark" - just 50% transparent. Values are 0 == black, 255 == solid
5340 * or full red, green or blue.
5342 * EVAS_COLORSPACE_YCBCR422P601_PL:
5344 * This is a pointer-list indirected set of YUV (YCbCr) pixel
5345 * data. This means that the data returned or set is not actual pixel
5346 * data, but pointers TO lines of pixel data. The list of pointers
5347 * will first be N rows of pointers to the Y plane - pointing to the
5348 * first pixel at the start of each row in the Y plane. N is the
5349 * height of the image data in pixels. Each pixel in the Y, U and V
5350 * planes is 1 byte exactly, packed. The next N / 2 pointers will
5351 * point to rows in the U plane, and the next N / 2 pointers will
5352 * point to the V plane rows. U and V planes are half the horizontal
5353 * and vertical resolution of the Y plane.
5355 * Row order is top to bottom and row pixels are stored left to right.
5357 * There is a limitation that these images MUST be a multiple of 2
5358 * pixels in size horizontally or vertically. This is due to the U and
5359 * V planes being half resolution. Also note that this assumes the
5360 * itu601 YUV colorspace specification. This is defined for standard
5361 * television and mpeg streams. HDTV may use the itu709
5364 * Values are 0 to 255, indicating full or no signal in that plane
5367 * EVAS_COLORSPACE_YCBCR422P709_PL:
5369 * Not implemented yet.
5371 * EVAS_COLORSPACE_RGB565_A5P:
5373 * In the process of being implemented in 1 engine only. This may change.
5375 * This is a pointer to image data for 16-bit half-word pixel data in
5376 * 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue), with
5377 * the high-byte containing red and the low byte containing blue, per
5378 * pixel. This data is packed row by row from the top-left to the
5381 * If the image has an alpha channel enabled there will be an extra
5382 * alpha plane after the color pixel plane. If not, then this data
5383 * will not exist and should not be accessed in any way. This plane is
5384 * a set of pixels with 1 byte per pixel defining the alpha values of
5385 * all pixels in the image from the top-left to the bottom right of
5386 * the image, row by row. Even though the values of the alpha pixels
5387 * can be 0 to 255, only values 0 through to 32 are used, 32 being
5388 * solid and 0 being transparent.
5390 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
5391 * with 0 being black and 31 or 63 being full red, green or blue
5392 * respectively. This colorspace is also pre-multiplied like
5393 * EVAS_COLORSPACE_ARGB8888 so:
5395 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
5397 * EVAS_COLORSPACE_A8:
5399 * The image is just a alpha mask (8 bit's per pixel). This is used for alpha
5402 * @ingroup Evas_Object_Specific
5404 typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o);
5408 * Creates a new image object on the given evas.
5410 * @param e The given evas.
5411 * @return The created image object.
5413 EAPI Evas_Object *evas_object_image_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5416 * Creates a new image object that automatically scales on the given evas.
5418 * This is a helper around evas_object_image_add() and
5419 * evas_object_image_filled_set(), it will track object resizes and apply
5420 * evas_object_image_fill_set() with the new geometry.
5422 * @see evas_object_image_add()
5423 * @see evas_object_image_filled_set()
5424 * @see evas_object_image_fill_set()
5426 EAPI Evas_Object *evas_object_image_filled_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5430 * Sets the data for an image from memory to be loaded
5432 * This is the same as evas_object_image_file_set() but the file to be loaded
5433 * may exist at an address in memory (the data for the file, not the filename
5434 * itself). The @p data at the address is copied and stored for future use, so
5435 * no @p data needs to be kept after this call is made. It will be managed and
5436 * freed for you when no longer needed. The @p size is limited to 2 gigabytes
5437 * in size, and must be greater than 0. A NULL @p data pointer is also invalid.
5438 * Set the filename to NULL to reset to empty state and have the image file
5439 * data freed from memory using evas_object_image_file_set().
5441 * The @p format is optional (pass NULL if you don't need/use it). It is used
5442 * to help Evas guess better which loader to use for the data. It may simply
5443 * be the "extension" of the file as it would normally be on disk such as
5444 * "jpg" or "png" or "gif" etc.
5446 * @param obj The given image object.
5447 * @param data The image file data address
5448 * @param size The size of the image file data in bytes
5449 * @param format The format of the file (optional), or @c NULL if not needed
5450 * @param key The image key in file, or @c NULL.
5452 EAPI void evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2);
5455 * Sets the filename and key of the given image object.
5457 * If the file supports multiple data stored in it as eet, you can
5458 * specify the key to be used as the index of the image in this file.
5460 * @param obj The given image object.
5461 * @param file The image filename.
5462 * @param key The image key in file, or @c NULL.
5464 EAPI void evas_object_image_file_set (Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
5467 * Retrieves the filename and key of the given image object.
5469 * @param obj The given image object.
5470 * @param file Location to store the image filename, or @c NULL.
5471 * @param key Location to store the image key, or @c NULL.
5473 EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2);
5476 * Sets how much of each border of the given image object is not
5479 * When rendering, the image may be scaled to fit the size of the
5480 * image object. This function sets what area around the border of the
5481 * image is not to be scaled. This sort of function is useful for
5482 * widget theming, where, for example, buttons may be of varying
5483 * sizes, but the border size must remain constant.
5485 * The units used for @p l, @p r, @p t and @p b are output units.
5487 * @param obj The given image object.
5488 * @param l Distance of the left border that is not to be stretched.
5489 * @param r Distance of the right border that is not to be stretched.
5490 * @param t Distance of the top border that is not to be stretched.
5491 * @param b Distance of the bottom border that is not to be stretched.
5493 EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1);
5496 * Retrieves how much of each border of the given image object is not
5499 * See @ref evas_object_image_border_set for more details.
5501 * @param obj The given image object.
5502 * @param l Location to store the left border width in, or @c NULL.
5503 * @param r Location to store the right border width in, or @c NULL.
5504 * @param t Location to store the top border width in, or @c NULL.
5505 * @param b Location to store the bottom border width in, or @c NULL.
5507 EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
5510 * Sets if the center part of the given image object (not the border)
5513 * When rendering, the image may be scaled to fit the size of the
5514 * image object. This function sets if the center part of the scaled
5515 * image is to be drawn or left completely blank, or forced to be
5516 * solid. Very useful for frames and decorations.
5518 * @param obj The given image object.
5519 * @param fill Fill mode of the middle.
5521 EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1);
5524 * Retrieves if the center of the given image object is to be drawn or
5527 * See @ref evas_object_image_fill_set for more details.
5529 * @param obj The given image object.
5530 * @return Fill mode of the center.
5532 EAPI 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;
5535 * Sets if image fill property should track object size.
5537 * If set to true, then every evas_object_resize() will automatically
5538 * trigger call to evas_object_image_fill_set() with the new size so
5539 * image will fill the whole object area.
5541 * @param obj The given image object.
5542 * @param setting whether to follow object size.
5544 * @see evas_object_image_filled_add()
5545 * @see evas_object_image_fill_set()
5547 EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
5550 * Retrieves if image fill property is tracking object size.
5552 * @param obj The given image object.
5553 * @return 1 if it is tracking, 0 if not and evas_object_fill_set()
5554 * must be called manually.
5556 EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5559 * Sets a scale factor (multiplier) for the borders of an image
5561 * @param obj The given image object.
5562 * @param scale The scale factor (default is 1.0 - i.e. no scale)
5564 EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale);
5567 * Retrieves the border scale factor
5569 * See evas_object_image_border_scale_set()
5571 * @param obj The given image object.
5572 * @return The scale factor
5574 EAPI double evas_object_image_border_scale_get (const Evas_Object *obj);
5577 * Sets the rectangle of the given image object that the image will be
5580 * Note that the image will be tiled around this one rectangle. To
5581 * have only one copy of the image drawn, @p x and @p y must be 0 and
5582 * @p w and @p h need to be the width and height of the image object
5585 * The default values for the fill parameters is @p x = 0, @p y = 0,
5586 * @p w = 32 and @p h = 32.
5588 * @param obj The given image object.
5589 * @param x The X coordinate for the top left corner of the image.
5590 * @param y The Y coordinate for the top left corner of the image.
5591 * @param w The width of the image.
5592 * @param h The height of the image.
5594 EAPI 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);
5597 * Retrieves the dimensions of the rectangle of the given image object
5598 * that the image will be drawn to.
5600 * See @ref evas_object_image_fill_set for more details.
5602 * @param obj The given image object.
5603 * @param x Location to store the X coordinate for the top left corner of the image in, or @c NULL.
5604 * @param y Location to store the Y coordinate for the top left corner of the image in, or @c NULL.
5605 * @param w Location to store the width of the image in, or @c NULL.
5606 * @param h Location to store the height of the image in, or @c NULL.
5608 EAPI 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);
5611 * Sets the tiling mode for the given evas image object's fill.
5612 * @param obj The given evas image object.
5613 * @param spread One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT,
5614 * EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.
5616 EAPI void evas_object_image_fill_spread_set (Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1);
5619 * Retrieves the spread (tiling mode) for the given image object's
5622 * @param obj The given evas image object.
5623 * @return The current spread mode of the image object.
5625 EAPI Evas_Fill_Spread evas_object_image_fill_spread_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5628 * Sets the size of the given image object.
5630 * This function will scale down or crop the image so that it is
5631 * treated as if it were at the given size. If the size given is
5632 * smaller than the image, it will be cropped. If the size given is
5633 * larger, then the image will be treated as if it were in the upper
5634 * left hand corner of a larger image that is otherwise transparent.
5636 * @param obj The given image object.
5637 * @param w The new width of the image.
5638 * @param h The new height of the image.
5640 EAPI void evas_object_image_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
5643 * Retrieves the size of the given image object.
5645 * See @ref evas_object_image_size_set for more details.
5647 * @param obj The given image object.
5648 * @param w Location to store the width of the image in, or @c NULL.
5649 * @param h Location to store the height of the image in, or @c NULL.
5651 EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
5654 * Retrieves the row stride of the given image object,
5656 * The row stride is the number of units between the start of a
5657 * row and the start of the next row.
5659 * @param obj The given image object.
5660 * @return The stride of the image.
5662 EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5665 * Retrieves a number representing any error that occurred during the last
5666 * load of the given image object.
5668 * @param obj The given image object.
5669 * @return A value giving the last error that occurred. It should be one of
5670 * the @c EVAS_LOAD_ERROR_* values. @c EVAS_LOAD_ERROR_NONE is
5671 * returned if there was no error.
5673 EAPI Evas_Load_Error evas_object_image_load_error_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5676 * Sets the raw image data of the given image object.
5678 * Note that the raw data must be of the same size and colorspace of
5679 * the image. If data is NULL the current image data will be freed.
5681 * @param obj The given image object.
5682 * @param data The raw data, or @c NULL.
5684 EAPI void evas_object_image_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
5687 * Converts the raw image data of the given image object to the
5688 * specified colorspace.
5690 * Note that this function does not modify the raw image data. If the
5691 * requested colorspace is the same as the image colorspace nothing is
5692 * done and NULL is returned. You should use
5693 * evas_object_image_colorspace_get() to check the current image
5696 * See @ref evas_object_image_colorspace_get.
5698 * @param obj The given image object.
5699 * @param to_cspace The colorspace to which the image raw data will be converted.
5700 * @return data A newly allocated data in the format specified by to_cspace.
5702 EAPI void *evas_object_image_data_convert (Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5705 * Get a pointer to the raw image data of the given image object.
5707 * This function returns a pointer to an image object's internal pixel
5708 * buffer, for reading only or read/write. If you request it for
5709 * writing, the image will be marked dirty so that it gets redrawn at
5712 * This is best suited when you want to modify an existing image,
5713 * without changing its dimensions.
5715 * @param obj The given image object.
5716 * @param for_writing Whether the data being retrieved will be modified.
5717 * @return The raw image data.
5719 EAPI void *evas_object_image_data_get (const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5722 * Replaces the raw image data of the given image object.
5724 * This function lets the application replace an image object's
5725 * internal pixel buffer with a user-allocated one. For best results,
5726 * you should generally first call evas_object_image_size_set() with
5727 * the width and height for the new buffer.
5729 * This call is best suited for when you will be using image data with
5730 * different dimensions than the existing image data, if any. If you
5731 * only need to modify the existing image in some fashion, then using
5732 * evas_object_image_data_get() is probably what you are after.
5734 * Note that the caller is responsible for freeing the buffer when
5735 * finished with it, as user-set image data will not be automatically
5736 * freed when the image object is deleted.
5738 * See @ref evas_object_image_data_get for more details.
5740 * @param obj The given image object.
5741 * @param data The raw data.
5743 EAPI void evas_object_image_data_copy_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
5746 * Mark a sub-region of the given image object to be redrawn.
5748 * This function schedules a particular rectangular region of an image
5749 * object to be updated (redrawn) at the next render.
5751 * @param obj The given image object.
5752 * @param x X-offset of the region to be updated.
5753 * @param y Y-offset of the region to be updated.
5754 * @param w Width of the region to be updated.
5755 * @param h Height of the region to be updated.
5757 EAPI void evas_object_image_data_update_add (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
5760 * Enable or disable alpha channel of the given image object.
5762 * This function sets a flag on an image object indicating whether or
5763 * not to use alpha channel data. A value of 1 indicates to use alpha
5764 * channel data, and 0 indicates to ignore any alpha channel
5765 * data. Note that this has nothing to do with an object's color as
5766 * manipulated by evas_object_color_set().
5768 * @param obj The given image object.
5769 * @param has_alpha Whether to use alpha channel data or not.
5771 EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1);
5774 * @brief Retrieves the alpha channel setting of the given image object.
5776 * @param obj The given image object.
5777 * @return Whether the alpha channel data is being used.
5779 * This function returns 1 if the image object's alpha channel is
5780 * being used, or 0 otherwise.
5782 * See @ref evas_object_image_alpha_set for more details.
5784 EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5787 * Sets whether to use of high-quality image scaling algorithm
5788 * of the given image object.
5790 * When enabled, a higher quality image scaling algorithm is used when
5791 * scaling images to sizes other than the source image. This gives
5792 * better results but is more computationally expensive.
5794 * @param obj The given image object.
5795 * @param smooth_scale Whether to use smooth scale or not.
5797 EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1);
5800 * Retrieves whether the given image object is using use a
5801 * high-quality image scaling algorithm.
5803 * See @ref evas_object_image_smooth_scale_set for more details.
5805 * @param obj The given image object.
5806 * @return Whether smooth scale is being used.
5808 EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5811 * Preload image in the background
5813 * This function request the preload of the data image in the
5814 * background. The worked is queued before being processed.
5816 * If image data is already loaded, it will callback
5817 * EVAS_CALLBACK_IMAGE_PRELOADED immediately and do nothing else.
5819 * If cancel is set, it will remove the image from the workqueue.
5821 * @param obj The given image object.
5822 * @param cancel 0 means add to the workqueue, 1 remove it.
5824 EAPI void evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1);
5827 * Reload a image of the canvas.
5829 * @param obj The given image object pointer.
5831 * This function reloads a image of the given canvas.
5834 EAPI void evas_object_image_reload (Evas_Object *obj) EINA_ARG_NONNULL(1);
5837 * Save the given image object to a file.
5839 * Note that you should pass the filename extension when saving. If
5840 * the file supports multiple data stored in it as eet, you can
5841 * specify the key to be used as the index of the image in this file.
5843 * You can specify some flags when saving the image. Currently
5844 * acceptable flags are quality and compress. Eg.: "quality=100
5847 * @param obj The given image object.
5848 * @param file The filename to be used to save the image.
5849 * @param key The image key in file, or @c NULL.
5850 * @param flags String containing the flags to be used.
5852 EAPI Eina_Bool evas_object_image_save (const Evas_Object *obj, const char *file, const char *key, const char *flags) EINA_ARG_NONNULL(1, 2);
5855 * Import pixels from given source to a given canvas image object.
5857 * @param obj The given canvas object.
5858 * @param pixels The pixel's source to be imported.
5860 * This function imports pixels from a given source to a given canvas image.
5863 EAPI Eina_Bool evas_object_image_pixels_import (Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2);
5866 * Set the callback function to get pixels from a canva's image.
5868 * @param obj The given canvas pointer.
5869 * @param func The callback function.
5870 * @param data The data pointer to be passed to @a func.
5872 * This functions sets a function to be the callback function that get
5873 * pixes from a image of the canvas.
5876 EAPI 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);
5879 * Mark whether the given image object is dirty (needs to be redrawn).
5881 * @param obj The given image object.
5882 * @param dirty Whether the image is dirty.
5884 EAPI void evas_object_image_pixels_dirty_set (Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1);
5887 * Retrieves whether the given image object is dirty (needs to be redrawn).
5889 * @param obj The given image object.
5890 * @return Whether the image is dirty.
5892 EAPI Eina_Bool evas_object_image_pixels_dirty_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5895 * Set the dpi resolution of a loaded image of the canvas.
5897 * @param obj The given canvas pointer.
5898 * @param dpi The new dpi resolution.
5900 * This function set the dpi resolution of a given loaded canvas image.
5903 EAPI void evas_object_image_load_dpi_set (Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1);
5906 * Get the dpi resolution of a loaded image of the canvas.
5908 * @param obj The given canvas pointer.
5909 * @return The dpi resolution of the given canvas image.
5911 * This function returns the dpi resolution of given canvas image.
5914 EAPI double evas_object_image_load_dpi_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5917 * Set the size of a loaded image of the canvas.
5919 * @param obj The given canvas object.
5920 * @param w The new width of the canvas image given.
5921 * @param h The new height of the canvas image given.
5923 * This function sets a new size for the given canvas image.
5926 EAPI void evas_object_image_load_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
5929 * Get the size of a loaded image of the canvas.
5931 * @param obj The given image object.
5932 * @param w The width of the canvas image given.
5933 * @param h The height of the canvas image given.
5935 * This function get the size of the given canvas image.
5938 EAPI void evas_object_image_load_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
5941 * Set the scale down of a loaded image of the canvas.
5943 * @param obj The given image object pointer.
5944 * @param scale_down The scale to down value.
5946 * This function sets the scale down of a given canvas image.
5949 EAPI void evas_object_image_load_scale_down_set (Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1);
5952 * Get the scale down value of given image of the canvas.
5954 * @param obj The given image object pointer.
5956 * This function returns the scale down value of a given canvas image.
5959 EAPI int evas_object_image_load_scale_down_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5960 EAPI void evas_object_image_load_region_set (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
5961 EAPI void evas_object_image_load_region_get (const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
5964 * Define if the orientation information in the image file should be honored.
5966 * @param obj The given image object pointer.
5967 * @param enable @p EINA_TRUE means that it should honor the orientation information
5970 EAPI void evas_object_image_load_orientation_set (Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
5973 * Get if the orientation information in the image file should be honored.
5975 * @param obj The given image object pointer.
5978 EAPI Eina_Bool evas_object_image_load_orientation_get (const Evas_Object *obj) EINA_ARG_NONNULL(1);
5981 * Set the colorspace of a given image of the canvas.
5983 * @param obj The given image object pointer.
5984 * @param cspace The new color space.
5986 * This function sets the colorspace of given canvas image.
5989 EAPI void evas_object_image_colorspace_set (Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1);
5992 * Get the colorspace of a given image of the canvas.
5994 * @param obj The given image object pointer.
5995 * @return The colorspace of the image.
5997 * This function returns the colorspace of given canvas image.
6000 EAPI Evas_Colorspace evas_object_image_colorspace_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6003 * Set the native surface of a given image of the canvas
6005 * @param obj The given canvas pointer.
6006 * @param surf The new native surface.
6008 * This function sets a native surface of a given canvas image.
6011 EAPI void evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2);
6014 * Get the native surface of a given image of the canvas
6016 * @param obj The given canvas pointer.
6017 * @return The native surface of the given canvas image.
6019 * This function returns the native surface of a given canvas image.
6022 EAPI Evas_Native_Surface *evas_object_image_native_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6025 * Set the scale hint of a given image of the canvas.
6027 * @param obj The given canvas pointer.
6028 * @param hint The scale hint value.
6030 * This function sets the scale hint value of the given image of the canvas.
6033 EAPI void evas_object_image_scale_hint_set (Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1);
6036 * Get the scale hint of a given image of the canvas.
6038 * @param obj The given canvas pointer.
6040 * This function returns the scale hint value of the given image of the canvas.
6043 EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6046 * Set the content hint of a given image of the canvas.
6048 * @param obj The given canvas pointer.
6049 * @param hint The content hint value.
6051 * This function sets the content hint value of the given image of the canvas.
6054 EAPI void evas_object_image_content_hint_set (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1);
6057 * Get the content hint of a given image of the canvas.
6059 * @param obj The given canvas pointer.
6061 * This function returns the content hint value of the given image of the canvas.
6064 EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6068 * Enable an image to be used as an alpha mask.
6070 * This will set any flags, and discard any excess image data not used as an
6073 * Note there is little point in using a image as alpha mask unless it has an
6076 * @param obj Object to use as an alpha mask.
6077 * @param ismask Use image as alphamask, must be true.
6079 EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1);
6082 * Set the source object on a proxy object.
6084 * The source must be another object. The proxy will have the same base
6085 * appearance of the source object. Obviously other effects may be applied to
6086 * the proxy, such as a map to create a reflection of the original object.
6088 * Any existing source object will be removed. Setting the src to NULL clears
6091 * You cannot set a proxy on a proxy.
6093 * @param obj Proxy object.
6094 * @param src Source of the proxy.
6095 * @return EINA_TRUE on success, EINA_FALSE on error.
6097 EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1);
6100 * Get the current source object of an image.
6102 * @param obj Image object
6103 * @return Source object, or @c NULL on error.
6105 EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1);
6108 * Clear the source on a proxy image.
6110 * This is equivalent to calling evas_object_image_source_set with a NULL
6113 * @param obj Image object to clear source of.
6114 * @return EINA_TRUE on success, EINA_FALSE on error.
6116 EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1);
6119 * Check if a file extention may be supported by @ref Evas_Object_Image.
6121 * @param file The file to check
6122 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
6125 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
6127 * This functions is threadsafe.
6129 EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
6132 * Check if a file extention may be supported by @ref Evas_Object_Image.
6134 * @param file The file to check, it should be an Eina_Stringshare.
6135 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
6138 * This functions is threadsafe.
6140 EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
6143 * @defgroup Evas_Object_Text Text Object Functions
6145 * Functions that operate on single line, single style text objects.
6147 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
6149 * @ingroup Evas_Object_Specific
6151 typedef enum _Evas_Text_Style_Type
6153 /* basic styles (4 bits allocatedm use 0->10 now, 5 left) */
6154 #define EVAS_TEXT_STYLE_MASK_BASIC 0xf
6155 #define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
6156 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
6157 EVAS_TEXT_STYLE_PLAIN,
6158 EVAS_TEXT_STYLE_SHADOW,
6159 EVAS_TEXT_STYLE_OUTLINE,
6160 EVAS_TEXT_STYLE_SOFT_OUTLINE,
6161 EVAS_TEXT_STYLE_GLOW,
6162 EVAS_TEXT_STYLE_OUTLINE_SHADOW,
6163 EVAS_TEXT_STYLE_FAR_SHADOW,
6164 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW,
6165 EVAS_TEXT_STYLE_SOFT_SHADOW,
6166 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW,
6168 #define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
6169 #define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
6170 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
6171 /* OR these to modify shadow direction (3 bits needed) */
6172 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4),
6173 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4),
6174 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4),
6175 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4),
6176 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4),
6177 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4),
6178 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4),
6179 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4)
6180 } Evas_Text_Style_Type;
6183 * Creates a new text @c Evas_Object on the provided @c Evas canvas.
6185 * @param e The @c Evas canvas to create the text object upon.
6187 * @see evas_object_text_font_source_set
6188 * @see evas_object_text_font_set
6189 * @see evas_object_text_text_set
6191 * @returns NULL on error, A pointer to a new @c Evas_Object on success.
6193 EAPI Evas_Object *evas_object_text_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6195 EAPI void evas_object_text_font_source_set (Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1);
6196 EAPI const char *evas_object_text_font_source_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6197 EAPI void evas_object_text_font_set (Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1);
6200 * Query evas for font information of a text @c Evas_Object.
6202 * This function allows the font name and size of a text @c Evas_Object as
6203 * created with evas_object_text_add() to be queried. Be aware that the font
6204 * name string is still owned by Evas and should NOT have free() called on
6205 * it by the caller of the function.
6207 * @param obj The evas text object to query for font information.
6208 * @param font A pointer to the location to store the font name in (may be NULL).
6209 * @param size A pointer to the location to store the font size in (may be NULL).
6211 EAPI void evas_object_text_font_get (const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1, 2);
6214 * Sets the text to be displayed by the given evas text object.
6215 * @param obj Evas text object.
6216 * @param text Text to display.
6218 EAPI void evas_object_text_text_set (Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
6221 * @brief Sets the BiDi delimiters used in the textblock.
6223 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
6224 * is useful for example in recipients fields of e-mail clients where bidi
6225 * oddities can occur when mixing rtl and ltr.
6227 * @param obj The given text object.
6228 * @param delim A null terminated string of delimiters, e.g ",|".
6231 EAPI void evas_object_text_bidi_delimiters_set(Evas_Object *obj, const char *delim);
6234 * @brief Gets the BiDi delimiters used in the textblock.
6236 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
6237 * is useful for example in recipients fields of e-mail clients where bidi
6238 * oddities can occur when mixing rtl and ltr.
6240 * @param obj The given text object.
6241 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
6244 EAPI const char *evas_object_text_bidi_delimiters_get(const Evas_Object *obj);
6247 * Retrieves the text currently being displayed by the given evas text object.
6248 * @param obj The given evas text object.
6249 * @return The text currently being displayed. Do not free it.
6251 EAPI const char *evas_object_text_text_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6252 EAPI Evas_Coord evas_object_text_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6253 EAPI Evas_Coord evas_object_text_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6254 EAPI Evas_Coord evas_object_text_max_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6255 EAPI Evas_Coord evas_object_text_max_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6256 EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6257 EAPI Evas_Coord evas_object_text_vert_advance_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6258 EAPI Evas_Coord evas_object_text_inset_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6261 * Retrieve position and dimension information of a character within a text @c Evas_Object.
6263 * This function is used to obtain the X, Y, width and height of a the character
6264 * located at @p pos within the @c Evas_Object @p obj. @p obj must be a text object
6265 * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx,
6266 * @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to that
6269 * @param obj The text object to retrieve position information for.
6270 * @param pos The character position to request co-ordinates for.
6271 * @param cx A pointer to an @c Evas_Coord to store the X value in (can be NULL).
6272 * @param cy A pointer to an @c Evas_Coord to store the Y value in (can be NULL).
6273 * @param cw A pointer to an @c Evas_Coord to store the Width value in (can be NULL).
6274 * @param ch A pointer to an @c Evas_Coord to store the Height value in (can be NULL).
6276 * @returns EINA_FALSE on error, EINA_TRUE on success.
6278 EAPI 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);
6279 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);
6282 * Returns the logical position of the last char in the text
6283 * up to the pos given. this is NOT the position of the last char
6284 * because of the possibility of RTL in the text.
6286 EAPI int evas_object_text_last_up_to_pos (const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
6287 EAPI Evas_Text_Style_Type evas_object_text_style_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6288 EAPI void evas_object_text_style_set (Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1);
6289 EAPI void evas_object_text_shadow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
6290 EAPI void evas_object_text_shadow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
6291 EAPI void evas_object_text_glow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
6292 EAPI void evas_object_text_glow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
6293 EAPI void evas_object_text_glow2_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
6294 EAPI void evas_object_text_glow2_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
6295 EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
6296 EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
6299 * Gets the text style pad of a text object.
6301 * @param obj The given text object.
6302 * @param l The left pad (or @c NULL).
6303 * @param r The right pad (or @c NULL).
6304 * @param t The top pad (or @c NULL).
6305 * @param b The bottom pad (or @c NULL).
6308 EAPI void evas_object_text_style_pad_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
6311 * Retrieves the direction of the text currently being displayed in the
6313 * @param obj The given evas text object.
6314 * @return the direction of the text
6316 EAPI Evas_BiDi_Direction evas_object_text_direction_get (const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
6319 * @defgroup Evas_Object_Textblock Textblock Object Functions
6321 * Functions used to create and manipulate textblock objects. Unlike
6322 * @ref Evas_Object_Text, these handle complex text, doing multiple
6323 * styles and multiline text based on HTML-like tags. Of these extra
6324 * features will be heavier on memory and processing cost.
6326 * @todo put here some usage examples
6328 * @ingroup Evas_Object_Specific
6332 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
6334 * This part explains about the textblock object's API and proper usage.
6335 * If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal.
6336 * The main user of the textblock object is the edje entry object in Edje, so
6337 * that's a good place to learn from, but I think this document is more than
6338 * enough, if it's not, please request for me info and I'll update it.
6340 * @subsection textblock_intro Introduction
6341 * The textblock objects is, as implied, an object that can show big chunks of
6342 * text. Textblock supports many features including: Text formatting, automatic
6343 * and manual text alignment, embedding items (for example icons) and more.
6344 * Textblock has three important parts, the text paragraphs, the format nodes
6347 * @subsection textblock_cursors Textblock Object Cursors
6348 * A textblock Cursor @ref Evas_Textblock_Cursor is data type that represents
6349 * a position in a textblock. Each cursor contains information about the
6350 * paragraph it points to, the position in that paragraph and the object itself.
6351 * Cursors register to textblock objects upon creation, this means that once
6352 * you created a cursor, it belongs to a specific obj and you can't for example
6353 * copy a cursor "into" a cursor of a different object. Registered cursors
6354 * also have the added benefit of updating automatically upon textblock changes,
6355 * this means that if you have a cursor pointing to a specific character, it'll
6356 * still point to it even after you change the whole object completely (as long
6357 * as the char was not deleted), this is not possible without updating, because
6358 * as mentioned, each cursor holds a character position. There are many
6359 * functions that handle cursors, just check out the evas_textblock_cursor*
6360 * functions. For creation and deletion of cursors check out:
6361 * @see evas_object_textblock_cursor_new()
6362 * @see evas_textblock_cursor_free()
6363 * @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).
6365 * @subsection textblock_paragraphs Textblock Object Paragraphs
6366 * The textblock object is made out of text splitted to paragraphs (delimited
6367 * by the paragraph separation character). Each paragraph has many (or none)
6368 * format nodes associated with it which are responsible for the formatting
6369 * of that paragraph.
6371 * @subsection textblock_format_nodes Textblock Object Format Nodes
6372 * As explained in @ref textblock_paragraphs each one of the format nodes
6373 * is associated with a paragraph.
6374 * There are two types of format nodes, visible and invisible:
6375 * Visible: formats that a cursor can point to, i.e formats that
6376 * occupy space, for example: newlines, tabs, items and etc. Some visible items
6377 * are made of two parts, in this case, only the opening tag is visible.
6378 * A closing tag (i.e a </tag> tag) should NEVER be visible.
6379 * Invisible: formats that don't occupy space, for example: bold and underline.
6380 * Being able to access format nodes is very important for some uses. For
6381 * example, edje uses the "<a>" format to create links in the text (and pop
6382 * popups above them when clicked). For the textblock object a is just a
6383 * formatting instruction (how to color the text), but edje utilizes the access
6384 * to the format nodes to make it do more.
6385 * For more information, take a look at all the evas_textblock_node_format_*
6387 * The translation of "<tag>" tags to actual format is done according to the
6388 * tags defined in the style, see @ref evas_textblock_style_set
6390 * @subsection textblock_special_formats Special Formats
6391 * This section is not yet written. If you want some info about styles/formats
6392 * and how to use them, expedite's textblock_basic test is a great start.
6393 * @todo Write @textblock_special_formats
6395 typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
6396 typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
6398 * @typedef Evas_Object_Textblock_Node_Format
6401 typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
6402 typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
6404 struct _Evas_Textblock_Rectangle
6406 Evas_Coord x, y, w, h;
6409 typedef enum _Evas_Textblock_Text_Type
6411 EVAS_TEXTBLOCK_TEXT_RAW,
6412 EVAS_TEXTBLOCK_TEXT_PLAIN,
6413 EVAS_TEXTBLOCK_TEXT_MARKUP
6414 } Evas_Textblock_Text_Type;
6416 typedef enum _Evas_Textblock_Cursor_Type
6418 EVAS_TEXTBLOCK_CURSOR_UNDER,
6419 EVAS_TEXTBLOCK_CURSOR_BEFORE
6420 } Evas_Textblock_Cursor_Type;
6424 * Adds a textblock to the given evas.
6425 * @param e The given evas.
6426 * @return The new textblock object.
6428 EAPI Evas_Object *evas_object_textblock_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6432 * Returns the unescaped version of escape.
6433 * @param escape the string to be escaped
6434 * @return the unescaped version of escape
6436 EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6439 * Returns the escaped version of the string.
6440 * @param string to escape
6441 * @param len_ret the len of the new escape
6442 * @return the escaped string.
6444 EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6447 * Return the unescaped version of the string between start and end.
6449 * @param escape_start the start of the string.
6450 * @param escape_end the end of the string.
6451 * @return the unescaped version of the range
6453 EAPI 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;
6457 * Creates a new textblock style.
6458 * @return The new textblock style.
6460 EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
6463 * Destroys a textblock style.
6464 * @param ts The textblock style to free.
6466 EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
6469 * Sets the style ts to the style passed as text by text.
6470 * Expected a string consisting of many (or none) tag='format' pairs.
6472 * @param ts the style to set.
6473 * @param text the text to parse - NOT NULL.
6474 * @return Returns no value.
6476 EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
6479 * Return the text of the style ts.
6480 * @param ts the style to get it's text.
6481 * @return the text of the style or null on error.
6483 EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6487 * Set the objects style to ts.
6488 * @param obj the Evas object to set the style to.
6489 * @param ts the style to set.
6490 * @return Returns no value.
6492 EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
6495 * Return the style of an object.
6496 * @param obj the object to get the style from.
6497 * @return the style of the object.
6499 EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6502 * @brief Set the "replacement character" to use for the given textblock object.
6504 * @param obj The given textblock object.
6505 * @param ch The charset name.
6507 EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1);
6510 * @brief Get the "replacement character" for given textblock object. Returns
6511 * NULL if no replacement character is in use.
6513 * @param obj The given textblock object
6514 * @return replacement character or @c NULL
6516 EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6519 * @brief Sets the vertical alignment of text within the textblock object
6522 * Normally alignment is 0.0 (top of object). Values given should be
6523 * between 0.0 and 1.0 (1.0 bottom of object, 0.5 being vertically centered
6526 * @param obj The given textblock object.
6527 * @param align A value between 0.0 and 1.0
6530 EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align);
6533 * @brief Gets the vertical alignment of a textblock
6535 * @param obj The given textblock object.
6536 * @return The elignment set for the object
6539 EAPI double evas_object_textblock_valign_get(const Evas_Object *obj);
6542 * @brief Sets the BiDi delimiters used in the textblock.
6544 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
6545 * is useful for example in recipients fields of e-mail clients where bidi
6546 * oddities can occur when mixing rtl and ltr.
6548 * @param obj The given textblock object.
6549 * @param delim A null terminated string of delimiters, e.g ",|".
6552 EAPI void evas_object_textblock_bidi_delimiters_set(Evas_Object *obj, const char *delim);
6555 * @brief Gets the BiDi delimiters used in the textblock.
6557 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
6558 * is useful for example in recipients fields of e-mail clients where bidi
6559 * oddities can occur when mixing rtl and ltr.
6561 * @param obj The given textblock object.
6562 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
6565 EAPI const char *evas_object_textblock_bidi_delimiters_get(const Evas_Object *obj);
6568 * @brief Sets newline mode. When true, newline character will behave
6569 * as a paragraph separator.
6571 * @param obj The given textblock object.
6572 * @param mode EINA_TRUE for PS mode, EINA_FALSE otherwise.
6575 EAPI void evas_object_textblock_newline_mode_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1);
6578 * @brief Gets newline mode. When true, newline character behaves
6579 * as a paragraph separator.
6581 * @param obj The given textblock object.
6582 * @return EINA_TRUE if in PS mode, EINA_FALSE otherwise.
6585 EAPI Eina_Bool evas_object_textblock_newline_mode_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6589 * Sets the tetxblock's text to the markup text.
6591 * @note assumes text does not include the unicode object replacement char (0xFFFC)
6593 * @param obj the textblock object.
6594 * @param text the markup text to use.
6595 * @return Return no value.
6597 EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
6600 * Prepends markup to the cursor cur.
6602 * @note assumes text does not include the unicode object replacement char (0xFFFC)
6604 * @param cur the cursor to prepend to.
6605 * @param text the markup text to prepend.
6606 * @return Return no value.
6608 EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6611 * Return the markup of the object.
6613 * @param obj the Evas object.
6614 * @return the markup text of the object.
6616 EAPI const char *evas_object_textblock_text_markup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6620 * Return the object's main cursor.
6622 * @param obj the object.
6623 * @return the obj's main cursor.
6625 EAPI const Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6628 * Create a new cursor, associate it to the obj and init it to point
6629 * to the start of the textblock. Association to the object means the cursor
6630 * will be updated when the object will change.
6632 * @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).
6634 * @param obj the object to associate to.
6635 * @return the new cursor.
6637 EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6641 * Free the cursor and unassociate it from the object.
6642 * @note do not use it to free unassociated cursors.
6644 * @param cur the cursor to free.
6645 * @return Returns no value.
6647 EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6651 * Sets the cursor to the start of the first text node.
6653 * @param cur the cursor to update.
6654 * @return Returns no value.
6656 EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6659 * sets the cursor to the end of the last text node.
6661 * @param cur the cursor to set.
6662 * @return Returns no value.
6664 EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6667 * Advances to the start of the next text node
6669 * @param cur the cursor to update
6670 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
6672 EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6675 * Advances to the end of the previous text node
6677 * @param cur the cursor to update
6678 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
6680 EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6685 * @param obj The evas, must not be NULL.
6686 * @param anchor the anchor name to get
6687 * @return Returns the list format node corresponding to the anchor, may be null if there are none.
6689 EAPI const Eina_List *evas_textblock_node_format_list_get(const Evas_Object *obj, const char *anchor) EINA_ARG_NONNULL(1, 2);
6692 * Returns the first format node.
6694 * @param obj The evas, must not be NULL.
6695 * @return Returns the first format node, may be null if there are none.
6697 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6700 * Returns the last format node.
6702 * @param obj The evas textblock, must not be NULL.
6703 * @return Returns the first format node, may be null if there are none.
6705 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6708 * Returns the next format node (after n)
6710 * @param n the current format node - not null.
6711 * @return Returns the next format node, may be null.
6713 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
6716 * Returns the prev format node (after n)
6718 * @param n the current format node - not null.
6719 * @return Returns the prev format node, may be null.
6721 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
6724 * Remove a format node and it's match. i.e, removes a <tag> </tag> pair.
6725 * Assumes the node is the first part of <tag> i.e, this won't work if
6726 * n is a closing tag.
6728 * @param obj the Evas object of the textblock - not null.
6729 * @param n the current format node - not null.
6731 EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
6734 * Sets the cursor to point to the place where format points to.
6736 * @param cur the cursor to update.
6737 * @param n the format node to update according.
6739 EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
6742 * Return the format node at the position pointed by cur.
6744 * @param cur the position to look at.
6745 * @return the format node if found, NULL otherwise.
6746 * @see evas_textblock_cursor_format_is_visible_get()
6748 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6751 * Get the text format representation of the format node.
6753 * @param fmt the format node.
6754 * @return the textual format of the format node.
6756 EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6759 * Set the cursor to point to the position of fmt.
6761 * @param cur the cursor to update
6762 * @param fmt the format to update according to.
6764 EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
6767 * Check if the current cursor position is a visible format. This way is more
6768 * efficient than evas_textblock_cursor_format_get() to check for the existence
6769 * of a visible format.
6771 * @param cur the cursor to look at.
6772 * @return #EINA_TRUE if the cursor points to a visible format, #EINA_FALSE otherwise.
6773 * @see evas_textblock_cursor_format_get()
6775 EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6778 * Advances to the next format node
6780 * @param cur the cursor to be updated.
6781 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6783 EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6786 * Advances to the previous format node.
6788 * @param cur the cursor to update.
6789 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6791 EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6794 * Returns true if the cursor points to a format.
6796 * @param cur the cursor to check.
6797 * @return Returns #EINA_TRUE if a cursor points to a format #EINA_FALSE otherwise.
6799 EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6802 * Advances 1 char forward.
6804 * @param cur the cursor to advance.
6805 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6807 EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6810 * Advances 1 char backward.
6812 * @param cur the cursor to advance.
6813 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6815 EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6818 * Go to the first char in the node the cursor is pointing on.
6820 * @param cur the cursor to update.
6821 * @return Returns no value.
6823 EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6826 * Go to the last char in a text node.
6828 * @param cur the cursor to update.
6829 * @return Returns no value.
6831 EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6834 * Go to the start of the current line
6836 * @param cur the cursor to update.
6837 * @return Returns no value.
6839 EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6842 * Go to the end of the current line.
6844 * @param cur the cursor to update.
6845 * @return Returns no value.
6847 EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6850 * Return the current cursor pos.
6852 * @param cur the cursor to take the position from.
6853 * @return the position or -1 on error
6855 EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6858 * Set the cursor pos.
6860 * @param cur the cursor to be set.
6861 * @param pos the pos to set.
6863 EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
6866 * Go to the start of the line passed
6868 * @param cur cursor to update.
6869 * @param line numer to set.
6870 * @return #EINA_TRUE on success, #EINA_FALSE on error.
6872 EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
6875 * Compare two cursors.
6877 * @param cur1 the first cursor.
6878 * @param cur2 the second cursor.
6879 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
6881 EAPI 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;
6884 * Make cur_dest point to the same place as cur. Does not work if they don't
6885 * point to the same object.
6887 * @param cur the source cursor.
6888 * @param cur_dest destination cursor.
6889 * @return Returns no value.
6891 EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
6895 * Adds text to the current cursor position and set the cursor to *before*
6896 * the start of the text just added.
6898 * @param cur the cursor to where to add text at.
6899 * @param _text the text to add.
6900 * @return Returns the len of the text added.
6901 * @see evas_textblock_cursor_text_prepend()
6903 EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6906 * Adds text to the current cursor position and set the cursor to *after*
6907 * the start of the text just added.
6909 * @param cur the cursor to where to add text at.
6910 * @param _text the text to add.
6911 * @return Returns the len of the text added.
6912 * @see evas_textblock_cursor_text_append()
6914 EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6918 * Adds format to the current cursor position. If the format being added is a
6919 * visible format, add it *before* the cursor position, otherwise, add it after.
6920 * This behavior is because visible formats are like characters and invisible
6921 * should be stacked in a way that the last one is added last.
6923 * This function works with native formats, that means that style defined
6924 * tags like <br> won't work here. For those kind of things use markup prepend.
6926 * @param cur the cursor to where to add format at.
6927 * @param format the format to add.
6928 * @return Returns true if a visible format was added, false otherwise.
6929 * @see evas_textblock_cursor_format_prepend()
6933 * Check if the current cursor position points to the terminating null of the
6934 * last paragraph. (shouldn't be allowed to point to the terminating null of
6935 * any previous paragraph anyway.
6937 * @param cur the cursor to look at.
6938 * @return #EINA_TRUE if the cursor points to the terminating null, #EINA_FALSE otherwise.
6940 EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
6943 * Adds format to the current cursor position. If the format being added is a
6944 * visible format, add it *before* the cursor position, otherwise, add it after.
6945 * This behavior is because visible formats are like characters and invisible
6946 * should be stacked in a way that the last one is added last.
6947 * If the format is visible the cursor is advanced after it.
6949 * This function works with native formats, that means that style defined
6950 * tags like <br> won't work here. For those kind of things use markup prepend.
6952 * @param cur the cursor to where to add format at.
6953 * @param format the format to add.
6954 * @return Returns true if a visible format was added, false otherwise.
6955 * @see evas_textblock_cursor_format_prepend()
6957 EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
6960 * Delete the character at the location of the cursor. If there's a format
6961 * pointing to this position, delete it as well.
6963 * @param cur the cursor pointing to the current location.
6964 * @return Returns no value.
6966 EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6969 * Delete the range between cur1 and cur2.
6971 * @param cur1 one side of the range.
6972 * @param cur2 the second side of the range
6973 * @return Returns no value.
6975 EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
6979 * Return the text of the paragraph cur points to - returns the text in markup..
6981 * @param cur the cursor pointing to the paragraph.
6982 * @return the text on success, NULL otherwise.
6984 EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6987 * Return the length of the paragraph, cheaper the eina_unicode_strlen()
6989 * @param cur the position of the paragraph.
6990 * @return the length of the paragraph on success, -1 otehrwise.
6992 EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6995 * Return the text in the range between cur1 and cur2
6997 * FIXME: format is currently unused, you always get markup back.
6999 * @param cur1 one side of the range.
7000 * @param cur2 the other side of the range
7001 * @param format to be documented
7002 * @return the text in the range
7003 * @see elm_entry_markup_to_utf8()
7005 EAPI 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;
7008 * Return the content of the cursor.
7010 * @param cur the cursor
7011 * @return the text in the range
7013 EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7017 * Returns the geometry of the cursor. Depends on the type of cursor requested.
7018 * This should be used instead of char_geometry_get because there are weird
7019 * special cases with BiDi text.
7020 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
7021 * get, except for the case of the last char of a line which depends on the
7022 * paragraph direction.
7024 * in '|' cursor mode (i.e a line between two chars) it is very varyable.
7025 * For example consider the following visual string:
7026 * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
7027 * a '|' between the c and the C.
7029 * @param cur the cursor.
7030 * @param cx the x of the cursor
7031 * @param cy the y of the cursor
7032 * @param cw the width of the cursor
7033 * @param ch the height of the cursor
7034 * @param dir the direction of the cursor, can be NULL.
7035 * @param ctype the type of the cursor.
7036 * @return line number of the char on success, -1 on error.
7038 EAPI 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);
7041 * Returns the geometry of the char at cur.
7043 * @param cur the position of the char.
7044 * @param cx the x of the char.
7045 * @param cy the y of the char.
7046 * @param cw the w of the char.
7047 * @param ch the h of the char.
7048 * @return line number of the char on success, -1 on error.
7050 EAPI 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);
7053 * Returns the geometry of the pen at cur.
7055 * @param cur the position of the char.
7056 * @param cpen_x the pen_x of the char.
7057 * @param cy the y of the char.
7058 * @param cadv the adv of the char.
7059 * @param ch the h of the char.
7060 * @return line number of the char on success, -1 on error.
7062 EAPI 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);
7065 * Returns the geometry of the line at cur.
7067 * @param cur the position of the line.
7068 * @param cx the x of the line.
7069 * @param cy the y of the line.
7070 * @param cw the width of the line.
7071 * @param ch the height of the line.
7072 * @return line number of the line on success, -1 on error.
7074 EAPI 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);
7077 * Set the position of the cursor according to the X and Y coordinates.
7079 * @param cur the cursor to set.
7080 * @param x coord to set by.
7081 * @param y coord to set by.
7082 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
7084 EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
7087 * Set the cursor position according to the y coord.
7089 * @param cur the cur to be set.
7090 * @param y the coord to set by.
7091 * @return the line number found, -1 on error.
7093 EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
7096 * Get the geometry of a range.
7098 * @param cur1 one side of the range.
7099 * @param cur2 other side of the range.
7100 * @return a list of Rectangles representing the geometry of the range.
7102 EAPI 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;
7103 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);
7107 * Checks if the cursor points to the end of the line.
7109 * @param cur the cursor to check.
7110 * @return #EINA_TRUE if true, #EINA_FALSE otherwise.
7112 EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7116 * Get the geometry of a line number.
7118 * @param obj the object.
7119 * @param line the line number.
7120 * @param cx x coord of the line.
7121 * @param cy y coord of the line.
7122 * @param cw w coord of the line.
7123 * @param ch h coord of the line.
7124 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
7126 EAPI 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);
7129 * Clear the textblock object.
7130 * @note Does *NOT* free the Evas object itself.
7132 * @param obj the object to clear.
7135 EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
7138 * Get the formatted width and height. This calculates the actual size after restricting
7139 * the textblock to the current size of the object.
7140 * The main difference between this and @ref evas_object_textblock_size_native_get
7141 * is that the "native" function does not wrapping into account
7142 * it just calculates the real width of the object if it was placed on an
7143 * infinite canvas, while this function gives the size after wrapping
7144 * according to the size restrictions of the object.
7146 * For example for a textblock containing the text: "You shall not pass!"
7147 * with no margins or padding and assuming a monospace font and a size of
7148 * 7x10 char widths (for simplicity) has a native size of 19x1
7149 * and a formatted size of 5x4.
7152 * @param obj the Evas object.
7153 * @param w[out] the width of the object.
7154 * @param h[out] the height of the object
7155 * @return Returns no value.
7156 * @see evas_object_textblock_size_native_get
7158 EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
7161 * Get the native width and height. This calculates the actual size without taking account
7162 * the current size of the object.
7163 * The main difference between this and @ref evas_object_textblock_size_formatted_get
7164 * is that the "native" function does not take wrapping into account
7165 * it just calculates the real width of the object if it was placed on an
7166 * infinite canvas, while the "formatted" function gives the size after
7167 * wrapping text according to the size restrictions of the object.
7169 * For example for a textblock containing the text: "You shall not pass!"
7170 * with no margins or padding and assuming a monospace font and a size of
7171 * 7x10 char widths (for simplicity) has a native size of 19x1
7172 * and a formatted size of 5x4.
7174 * @param obj the Evas object of the textblock
7175 * @param w[out] the width returned
7176 * @param h[out] the height returned
7177 * @return Returns no value.
7179 EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
7180 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);
7183 * @defgroup Evas_Line_Group Line Object Functions
7185 * Functions used to deal with evas line objects.
7187 * @ingroup Evas_Object_Specific
7191 * Adds a new evas line object to the given evas.
7192 * @param e The given evas.
7193 * @return The new evas line object.
7195 EAPI Evas_Object *evas_object_line_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7198 * Sets the coordinates of the end points of the given evas line object.
7199 * @param obj The given evas line object.
7200 * @param x1 The X coordinate of the first point.
7201 * @param y1 The Y coordinate of the first point.
7202 * @param x2 The X coordinate of the second point.
7203 * @param y2 The Y coordinate of the second point.
7205 EAPI void evas_object_line_xy_set (Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2);
7208 * Retrieves the coordinates of the end points of the given evas line object.
7209 * @param obj The given line object.
7210 * @param x1 Pointer to an integer in which to store the X coordinate of the
7212 * @param y1 Pointer to an integer in which to store the Y coordinate of the
7214 * @param x2 Pointer to an integer in which to store the X coordinate of the
7216 * @param y2 Pointer to an integer in which to store the Y coordinate of the
7219 EAPI void evas_object_line_xy_get (const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2);
7222 * @defgroup Evas_Object_Polygon Polygon Object Functions
7224 * Functions that operate on evas polygon objects.
7226 * Hint: as evas does not provide ellipse, smooth paths or circle, one
7227 * can calculate points and convert these to a polygon.
7229 * @ingroup Evas_Object_Specific
7233 * Adds a new evas polygon object to the given evas.
7234 * @param e The given evas.
7235 * @return A new evas polygon object.
7237 EAPI Evas_Object *evas_object_polygon_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7240 * Adds the given point to the given evas polygon object.
7241 * @param obj The given evas polygon object.
7242 * @param x The X coordinate of the given point.
7243 * @param y The Y coordinate of the given point.
7244 * @ingroup Evas_Polygon_Group
7246 EAPI void evas_object_polygon_point_add (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
7249 * Removes all of the points from the given evas polygon object.
7250 * @param obj The given polygon object.
7252 EAPI void evas_object_polygon_points_clear (Evas_Object *obj) EINA_ARG_NONNULL(1);
7255 * @defgroup Evas_Smart_Group Smart Functions
7257 * Functions that deal with Evas_Smart's, creating definition
7258 * (classes) of objects that will have customized behavior for methods
7259 * like evas_object_move(), evas_object_resize(),
7260 * evas_object_clip_set() and others.
7262 * These objects will accept the generic methods defined in @ref
7263 * Evas_Object_Group and the extensions defined in @ref
7264 * Evas_Smart_Object_Group. There are couple of existent smart objects
7265 * in Evas itself, see @ref Evas_Object_Box, @ref Evas_Object_Table
7266 * and @ref Evas_Smart_Object_Clipped.
7270 * @def EVAS_SMART_CLASS_VERSION
7271 * The version you have to put into the version field in the smart
7273 * @ingroup Evas_Smart_Group
7275 #define EVAS_SMART_CLASS_VERSION 4
7277 * @struct _Evas_Smart_Class
7278 * a smart object class
7279 * @ingroup Evas_Smart_Group
7281 struct _Evas_Smart_Class
7283 const char *name; /**< the string name of the class */
7285 void (*add) (Evas_Object *o);
7286 void (*del) (Evas_Object *o);
7287 void (*move) (Evas_Object *o, Evas_Coord x, Evas_Coord y);
7288 void (*resize) (Evas_Object *o, Evas_Coord w, Evas_Coord h);
7289 void (*show) (Evas_Object *o);
7290 void (*hide) (Evas_Object *o);
7291 void (*color_set) (Evas_Object *o, int r, int g, int b, int a);
7292 void (*clip_set) (Evas_Object *o, Evas_Object *clip);
7293 void (*clip_unset) (Evas_Object *o);
7294 void (*calculate) (Evas_Object *o);
7295 void (*member_add) (Evas_Object *o, Evas_Object *child);
7296 void (*member_del) (Evas_Object *o, Evas_Object *child);
7298 const Evas_Smart_Class *parent; /**< this class inherits from this parent */
7299 const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, NULL terminated */
7300 void *interfaces; /**< to be used in a future near you */
7305 * @struct _Evas_Smart_Cb_Description
7307 * Describes a callback used by a smart class
7308 * evas_object_smart_callback_call(), particularly useful to explain
7309 * to user and its code (ie: introspection) what the parameter @c
7310 * event_info will contain.
7312 * @ingroup Evas_Smart_Group
7314 struct _Evas_Smart_Cb_Description
7316 const char *name; /**< callback name, ie: "changed" */
7319 * @brief Hint type of @c event_info parameter of Evas_Smart_Cb.
7321 * The type string uses the pattern similar to
7323 * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures
7325 * but extended to optionally include variable names within
7326 * brackets preceding types. Example:
7328 * @li Structure with two integers:
7331 * @li Structure called 'x' with two integers named 'a' and 'b':
7332 * @c "[x]([a]i[b]i)"
7334 * @li Array of integers:
7337 * @li Array called 'x' of struct with two integers:
7340 * @note This type string is used as a hint and is @b not validated
7341 * or enforced anyhow. Implementors should make the best use
7342 * of it to help bindings, documentation and other users of
7343 * introspection features.
7349 * @def EVAS_SMART_CLASS_INIT_NULL
7350 * Initializer to zero a whole Evas_Smart_Class structure.
7352 * @see EVAS_SMART_CLASS_INIT_VERSION
7353 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
7354 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
7355 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
7356 * @ingroup Evas_Smart_Group
7358 #define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
7361 * @def EVAS_SMART_CLASS_INIT_VERSION
7362 * Initializer to zero a whole Evas_Smart_Class structure and set version.
7364 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
7365 * latest EVAS_SMART_CLASS_VERSION.
7367 * @see EVAS_SMART_CLASS_INIT_NULL
7368 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
7369 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
7370 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
7371 * @ingroup Evas_Smart_Group
7373 #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}
7376 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
7377 * Initializer to zero a whole Evas_Smart_Class structure and set name
7380 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
7381 * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
7383 * It will keep a reference to name field as a "const char *", that is,
7384 * name must be available while the structure is used (hint: static or global!)
7385 * and will not be modified.
7387 * @see EVAS_SMART_CLASS_INIT_NULL
7388 * @see EVAS_SMART_CLASS_INIT_VERSION
7389 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
7390 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
7391 * @ingroup Evas_Smart_Group
7393 #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}
7396 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
7397 * Initializer to zero a whole Evas_Smart_Class structure and set name,
7398 * version and parent class.
7400 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
7401 * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
7404 * It will keep a reference to name field as a "const char *", that is,
7405 * name must be available while the structure is used (hint: static or global!)
7406 * and will not be modified. Similarly, parent reference will be kept.
7408 * @see EVAS_SMART_CLASS_INIT_NULL
7409 * @see EVAS_SMART_CLASS_INIT_VERSION
7410 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
7411 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
7412 * @ingroup Evas_Smart_Group
7414 #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}
7417 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
7418 * Initializer to zero a whole Evas_Smart_Class structure and set name,
7419 * version, parent class and callbacks definition.
7421 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
7422 * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
7423 * class and callbacks at this level.
7425 * It will keep a reference to name field as a "const char *", that is,
7426 * name must be available while the structure is used (hint: static or global!)
7427 * and will not be modified. Similarly, parent and callbacks reference
7430 * @see EVAS_SMART_CLASS_INIT_NULL
7431 * @see EVAS_SMART_CLASS_INIT_VERSION
7432 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
7433 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
7434 * @ingroup Evas_Smart_Group
7436 #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}
7439 * @def EVAS_SMART_SUBCLASS_NEW
7441 * Convenience macro to subclass a Smart Class.
7443 * This macro saves some typing when writing a Smart Class derived from
7444 * another one. In order to work, the user needs to provide some functions
7445 * adhering to the following guidelines.
7446 * - @<prefix@>_smart_set_user(): the internal _smart_set function will call
7447 * this one provided by the user after inheriting everything from the
7448 * parent, which should take care of setting the right member functions
7450 * - @<prefix@>_parent_sc: pointer to the smart class of the parent. When calling
7451 * parent functions from overloaded ones, use this global variable.
7452 * - @<prefix@>_smart_class_new(): this function returns the Evas_Smart needed
7453 * to create smart objects with this class, should be called by the public
7455 * - If this new class should be subclassable as well, a public _smart_set()
7456 * function is desirable to fill the class used as parent by the children.
7457 * It's up to the user to provide this interface, which will most likely
7458 * call @<prefix@>_smart_set() to get the job done.
7460 * @param smart_name The name used for the Smart Class. e.g: "Evas_Object_Box".
7461 * @param prefix Prefix used for all variables and functions defined.
7462 * @param api_type Type of the structure used as API for the Smart Class. Either Evas_Smart_Class or something derived from it.
7463 * @param parent_type Type of the parent class API.
7464 * @param parent_func Function that gets the parent class. e.g: evas_object_box_smart_class_get().
7465 * @param cb_desc Array of callback descriptions for this Smart Class.
7467 * @ingroup Evas_Smart_Group
7469 #define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
7470 static const parent_type * prefix##_parent_sc = NULL; \
7471 static void prefix##_smart_set_user(api_type *api); \
7472 static void prefix##_smart_set(api_type *api) \
7474 Evas_Smart_Class *sc; \
7475 if (!(sc = (Evas_Smart_Class *)api)) \
7477 if (!prefix##_parent_sc) \
7478 prefix##_parent_sc = parent_func(); \
7479 evas_smart_class_inherit(sc, (const Evas_Smart_Class *)prefix##_parent_sc); \
7480 prefix##_smart_set_user(api); \
7482 static Evas_Smart * prefix##_smart_class_new(void) \
7484 static Evas_Smart *smart = NULL; \
7485 static api_type api; \
7488 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
7489 memset(&api, 0, sizeof(api_type)); \
7490 sc->version = EVAS_SMART_CLASS_VERSION; \
7491 sc->name = smart_name; \
7492 sc->callbacks = cb_desc; \
7493 prefix##_smart_set(&api); \
7494 smart = evas_smart_class_new(sc); \
7500 * @def EVAS_SMART_DATA_ALLOC
7501 * Convenience macro to allocate smart data only if needed.
7503 * When writing a subclassable smart object, the .add function will need
7504 * to check if the smart private data was already allocated by some child
7505 * object or not. This macro makes it easier to do it.
7507 * @param o Evas object passed to the .add function
7508 * @param priv_type The type of the data to allocate
7509 * @ingroup Evas_Smart_Group
7511 #define EVAS_SMART_DATA_ALLOC(o, priv_type) \
7513 priv = evas_object_smart_data_get(o); \
7515 priv = (priv_type *)calloc(1, sizeof(priv_type)); \
7516 if (!priv) return; \
7517 evas_object_smart_data_set(o, priv); \
7522 * Free an Evas_Smart
7524 * If this smart was created using evas_smart_class_new(), the associated
7525 * Evas_Smart_Class will not be freed.
7527 * @param s the Evas_Smart to free
7530 EAPI void evas_smart_free (Evas_Smart *s) EINA_ARG_NONNULL(1);
7533 * Creates an Evas_Smart from an Evas_Smart_Class.
7535 * @param sc the smart class definition
7536 * @return an Evas_Smart
7538 EAPI Evas_Smart *evas_smart_class_new (const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7541 * Get the Evas_Smart_Class of an Evas_Smart
7543 * @param s the Evas_Smart
7544 * @return the Evas_Smart_Class
7546 EAPI const Evas_Smart_Class *evas_smart_class_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7550 * @brief Get the data pointer set on an Evas_Smart.
7552 * @param s Evas_Smart
7554 * This data pointer is set either as the final parameter to
7555 * evas_smart_new or as the data field in the Evas_Smart_Class passed
7556 * in to evas_smart_class_new
7558 EAPI void *evas_smart_data_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7561 * Get the callbacks known by this Evas_Smart.
7563 * This is likely different from Evas_Smart_Class::callbacks as it
7564 * will contain the callbacks of all class hierarchy sorted, while the
7565 * direct smart class member refers only to that specific class and
7566 * should not include parent's.
7568 * If no callbacks are known, this function returns @c NULL.
7570 * The array elements and thus their contents will be reference to
7571 * original values given to evas_smart_new() as
7572 * Evas_Smart_Class::callbacks.
7574 * The array is sorted by name. The last array element is the @c NULL
7575 * pointer and is not counted in @a count. Loop iterations can check
7576 * any of these cases.
7578 * @param s the Evas_Smart.
7579 * @param count returns the number of elements in returned array.
7580 * @return the array with callback descriptions known by this class,
7581 * its size is returned in @a count parameter. It should not
7582 * be modified anyhow. If no callbacks are known, @c NULL is
7583 * returned. The array is sorted by name and elements refer to
7584 * the original value given to evas_smart_new().
7586 * @note objects may provide per-instance callbacks, use
7587 * evas_object_smart_callbacks_descriptions_get() to get those
7589 * @see evas_object_smart_callbacks_descriptions_get()
7591 EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
7595 * Find callback description for callback called @a name.
7597 * @param s the Evas_Smart.
7598 * @param name name of desired callback, must @b not be @c NULL. The
7599 * search have a special case for @a name being the same
7600 * pointer as registered with Evas_Smart_Cb_Description, one
7601 * can use it to avoid excessive use of strcmp().
7602 * @return reference to description if found, @c NULL if not found.
7604 EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2) EINA_PURE;
7608 * Sets one class to inherit from the other.
7610 * Copy all function pointers, set @c parent to @a parent_sc and copy
7611 * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
7612 * using @a parent_sc_size as reference.
7614 * This is recommended instead of a single memcpy() since it will take
7615 * care to not modify @a sc name, version, callbacks and possible
7618 * @param sc child class.
7619 * @param parent_sc parent class, will provide attributes.
7620 * @param parent_sc_size size of parent_sc structure, child should be at least
7621 * this size. Everything after @c Evas_Smart_Class size is copied
7622 * using regular memcpy().
7624 EAPI 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);
7627 * Get the number of users of the smart instance
7629 * @param s The Evas_Smart to get the usage count of
7630 * @return The number of uses of the smart instance
7632 * This function tells you how many more uses of the smart instance are in
7633 * existence. This should be used before freeing/clearing any of the
7634 * Evas_Smart_Class that was used to create the smart instance. The smart
7635 * instance will refer to data in the Evas_Smart_Class used to create it and
7636 * thus you cannot remove the original data until all users of it are gone.
7637 * When the usage count goes to 0, you can evas_smart_free() the smart
7638 * instance @p s and remove from memory any of the Evas_Smart_Class that
7639 * was used to create the smart instance, if you desire. Removing it from
7640 * memory without doing this will cause problems (crashes, undefined
7641 * behavior etc. etc.), so either never remove the original
7642 * Evas_Smart_Class data from memory (have it be a constant structure and
7643 * data), or use this API call and be very careful.
7645 EAPI int evas_smart_usage_get(const Evas_Smart *s);
7648 * @def evas_smart_class_inherit
7649 * Easy to use version of evas_smart_class_inherit_full().
7651 * This version will use sizeof(parent_sc), copying everything.
7653 * @param sc child class, will have methods copied from @a parent_sc
7654 * @param parent_sc parent class, will provide contents to be copied.
7655 * @return 1 on success, 0 on failure.
7656 * @ingroup Evas_Smart_Group
7658 #define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, parent_sc, sizeof(*parent_sc))
7661 * @defgroup Evas_Smart_Object_Group Smart Object Functions
7663 * Functions dealing with evas smart objects (instances).
7665 * Smart objects are groupings of primitive Evas objects that behave as a
7666 * cohesive group. For instance, a file manager icon may be a smart object
7667 * composed of an image object, a text label and two rectangles that appear
7668 * behind the image and text when the icon is selected. As a smart object,
7669 * the normal evas api could be used on the icon object.
7671 * @see @ref Evas_Smart_Group for class definitions.
7675 * Instantiates a new smart object described by @p s.
7677 * @param e the evas on which to add the object
7678 * @param s the Evas_Smart describing the smart object
7679 * @return a new Evas_Object
7680 * @ingroup Evas_Smart_Object_Group
7682 EAPI Evas_Object *evas_object_smart_add (Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC;
7685 * Set an Evas object as a member of a smart object.
7687 * @param obj The member object
7688 * @param smart_obj The smart object
7690 * Members will automatically be stacked and layered with the smart object.
7691 * The various stacking function will operate on members relative to the
7692 * other members instead of the entire canvas.
7694 * Non-member objects can not interleave a smart object's members.
7696 * @ingroup Evas_Smart_Object_Group
7698 EAPI void evas_object_smart_member_add (Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2);
7701 * Removes a member object from a smart object.
7703 * @param obj the member object
7704 * @ingroup Evas_Smart_Object_Group
7706 * This removes a member object from a smart object. The object will still
7707 * be on the canvas, but no longer associated with whichever smart object
7708 * it was associated with.
7711 EAPI void evas_object_smart_member_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
7714 * Gets the smart parent of an Evas_Object
7715 * @param obj the Evas_Object you want to get the parent
7716 * @return Returns the smart parent of @a obj, or @c NULL if @a obj is not a smart member of another Evas_Object
7717 * @ingroup Evas_Smart_Object_Group
7719 EAPI Evas_Object *evas_object_smart_parent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7722 * Checks the Smart type of the object and its parents
7723 * @param obj the Evas_Object to check the type of
7724 * @param type the type to check for
7725 * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise
7726 * @ingroup Evas_Smart_Object_Group
7728 EAPI 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;
7731 * Checks the Smart type of the object and its parents using pointer comparison
7732 * @param obj the Evas_Object to check the type of
7733 * @param type the type to check for. Must be the name pointer in the smart class used to create the object
7734 * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise
7735 * @ingroup Evas_Smart_Object_Group
7737 EAPI 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;
7740 * Gets the list of the member objects of an Evas_Object
7741 * @param obj the Evas_Object you want to get the list of member objects
7742 * @return Returns the list of the member objects of @a obj.
7743 * The returned list should be freed with eina_list_free() when you no longer need it
7745 EAPI Eina_List *evas_object_smart_members_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7748 * Get the Evas_Smart from which @p obj was created.
7750 * @param obj a smart object
7751 * @return the Evas_Smart
7752 * @ingroup Evas_Smart_Object_Group
7754 EAPI Evas_Smart *evas_object_smart_smart_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7757 * Retrieve user data stored on a smart object.
7759 * @param obj The smart object
7760 * @return A pointer to data stored using evas_object_smart_data_set(), or
7761 * NULL if none has been set.
7762 * @ingroup Evas_Smart_Object_Group
7764 EAPI void *evas_object_smart_data_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7767 * Store a pointer to user data for a smart object.
7769 * @param obj The smart object
7770 * @param data A pointer to user data
7771 * @ingroup Evas_Smart_Object_Group
7773 EAPI void evas_object_smart_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
7776 * Add a callback for the smart event specified by @p event.
7778 * @param obj a smart object
7779 * @param event the event name
7780 * @param func the callback function
7781 * @param data user data to be passed to the callback function
7782 * @ingroup Evas_Smart_Object_Group
7784 EAPI 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);
7787 * Remove a smart callback
7789 * Removes a callback that was added by evas_object_smart_callback_add()
7791 * @param obj a smart object
7792 * @param event the event name
7793 * @param func the callback function
7794 * @return the data pointer
7795 * @ingroup Evas_Smart_Object_Group
7797 EAPI void *evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3);
7800 * Call any smart callbacks on @p obj for @p event.
7802 * @param obj the smart object
7803 * @param event the event name
7804 * @param event_info an event specific struct of info to pass to the callback
7806 * This should be called internally in the smart object when some specific
7807 * event has occurred. The documentation for the smart object should include
7808 * a list of possible events and what type of @p event_info to expect.
7810 * @ingroup Evas_Smart_Object_Group
7812 EAPI void evas_object_smart_callback_call (Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2);
7816 * Set smart object instance callbacks descriptions.
7818 * These descriptions are hints to be used by introspection and are
7819 * not enforced in any way.
7821 * It will not be checked if instance callbacks descriptions have the
7822 * same name as another in class. Both are kept in different arrays
7823 * and users of evas_object_smart_callbacks_descriptions_get() should
7824 * handle this case as they wish.
7826 * @param obj The smart object
7827 * @param descriptions NULL terminated (name != NULL) array with
7828 * descriptions. Array elements will not be modified, but
7829 * reference to them and their contents will be made, so this
7830 * array should be kept alive during object lifetime.
7831 * @return 1 on success, 0 on failure.
7832 * @ingroup Evas_Smart_Object_Group
7834 * @note while instance callbacks descriptions are possible, they are
7835 * not recommended. Use class callbacks descriptions instead as they
7836 * make user's life simpler and will use less memory as descriptions
7837 * and arrays will be shared among all instances.
7839 EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1);
7842 * Get the callbacks descriptions known by this smart object.
7844 * This call retrieves processed callbacks descriptions for both
7845 * instance and class. These arrays are sorted by description's name
7846 * and are @c NULL terminated, so both @a class_count and
7847 * @a instance_count can be ignored, the terminator @c NULL is not
7848 * counted in these values.
7850 * @param obj the smart object.
7851 * @param class_descriptions where to store class callbacks
7852 * descriptions array, if any is known. If no descriptions are
7853 * known, @c NULL is returned. This parameter may be @c NULL if
7854 * it is not of interest.
7855 * @param class_count returns how many class callbacks descriptions
7857 * @param instance_descriptions where to store instance callbacks
7858 * descriptions array, if any is known. If no descriptions are
7859 * known, @c NULL is returned. This parameter may be @c NULL if
7860 * it is not of interest.
7861 * @param instance_count returns how many instance callbacks
7862 * descriptions are known.
7864 * @note if just class descriptions are of interest, try
7865 * evas_smart_callbacks_descriptions_get() instead.
7867 * @see evas_smart_callbacks_descriptions_get()
7868 * @ingroup Evas_Smart_Object_Group
7870 EAPI 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);
7873 * Find callback description for callback called @a name.
7875 * @param obj the smart object.
7876 * @param name name of desired callback, must @b not be @c NULL. The
7877 * search have a special case for @a name being the same
7878 * pointer as registered with Evas_Smart_Cb_Description, one
7879 * can use it to avoid excessive use of strcmp().
7880 * @param class_description pointer to return class description or @c
7881 * NULL if not found. If parameter is @c NULL, no search will
7882 * be done on class descriptions.
7883 * @param instance_description pointer to return instance description
7884 * or @c NULL if not found. If parameter is @c NULL, no search
7885 * will be done on instance descriptions.
7886 * @return reference to description if found, @c NULL if not found.
7888 EAPI 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);
7892 * Mark smart object as changed, dirty.
7894 * This will inform the scene that it changed and needs to be redraw, also
7895 * setting need_recalculate on the given object.
7897 * @see evas_object_smart_need_recalculate_set().
7899 * @ingroup Evas_Smart_Object_Group
7901 EAPI void evas_object_smart_changed (Evas_Object *obj) EINA_ARG_NONNULL(1);
7904 * Set the need_recalculate flag of given smart object.
7906 * If this flag is set then calculate() callback (method) of the given
7907 * smart object will be called, if one is provided, during render phase
7908 * usually evas_render(). After this step, this flag will be automatically
7911 * If no calculate() is provided, this flag will be left unchanged.
7913 * @note just setting this flag will not make scene dirty and evas_render()
7914 * will have no effect. To do that, use evas_object_smart_changed(),
7915 * that will automatically call this function with 1 as parameter.
7917 * @param obj the smart object
7918 * @param value if one want to set or unset the need_recalculate flag.
7920 * @ingroup Evas_Smart_Object_Group
7922 EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
7925 * Get the current value of need_recalculate flag.
7927 * @note this flag will be unset during the render phase, after calculate()
7928 * is called if one is provided. If no calculate() is provided, then
7929 * the flag will be left unchanged after render phase.
7931 * @param obj the smart object
7932 * @return if flag is set or not.
7934 * @ingroup Evas_Smart_Object_Group
7936 EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7939 * Call user provided calculate() and unset need_calculate.
7941 * @param obj the smart object
7943 * @ingroup Evas_Smart_Object_Group
7945 EAPI void evas_object_smart_calculate (Evas_Object *obj) EINA_ARG_NONNULL(1);
7949 * Call user provided calculate() and unset need_calculate on all objects.
7951 * @param e The canvas to calculate all objects in
7953 * @ingroup Evas_Smart_Object_Group
7955 EAPI void evas_smart_objects_calculate (Evas *e);
7958 * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
7960 * Clipped smart object is a base to construct other smart objects
7961 * that based on the concept of having an internal clipper that is
7962 * applied to all its other children. This clipper will control the
7963 * visibility, clipping and color of sibling objects (remember that
7964 * the clipping is recursive, and clipper color modulates the color of
7965 * its clippees). By default, this base will also move children
7966 * relatively to the parent, and delete them when parent is
7967 * deleted. In other words, it is the base for simple object grouping.
7969 * @see evas_object_smart_clipped_smart_set()
7971 * @ingroup Evas_Smart_Object_Group
7975 * Every subclass should provide this at the beginning of their own
7976 * data set with evas_object_smart_data_set().
7978 typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
7979 struct _Evas_Object_Smart_Clipped_Data
7981 Evas_Object *clipper;
7987 * Get the clipper object for the given clipped smart object.
7989 * @param obj the clipped smart object to retrieve the associated clipper.
7990 * @return the clipper object.
7992 * @see evas_object_smart_clipped_smart_add()
7994 EAPI Evas_Object *evas_object_smart_clipped_clipper_get (Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7997 * Set smart class callbacks so it implements the "Clipped Smart Object".
7999 * This call will assign all the required methods of Evas_Smart_Class,
8000 * if one wants to "subclass" it, call this function and later
8001 * override values, if one wants to call the original method, save it
8002 * somewhere, example:
8005 * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
8007 * static void my_class_smart_add(Evas_Object *o)
8010 * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
8014 * Evas_Smart_Class *my_class_new(void)
8016 * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
8017 * if (!parent_sc.name)
8019 * evas_object_smart_clipped_smart_set(&sc);
8021 * sc.add = my_class_smart_add;
8027 * Default behavior is:
8028 * - add: creates a hidden clipper with "infinite" size;
8029 * - del: delete all children objects;
8030 * - move: move all objects relative relatively;
8031 * - resize: not defined;
8032 * - show: if there are children objects, show clipper;
8033 * - hide: hides clipper;
8034 * - color_set: set the color of clipper;
8035 * - clip_set: set clipper of clipper;
8036 * - clip_unset: unset the clipper of clipper;
8038 EAPI void evas_object_smart_clipped_smart_set (Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
8041 * Get a pointer to the Clipped Smart Class to use for proper inheritance
8043 EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get (void) EINA_CONST;
8047 * Moves all children objects relative to given offset.
8049 * @param obj the smart Evas object to use.
8050 * @param dx horizontal offset.
8051 * @param dy vertical offset.
8053 EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1);
8056 * @defgroup Evas_Object_Box Box (Sequence) Smart Object.
8058 * Convenience smart object that packs children as a sequence using
8059 * a layout function specified by user. There are a couple of helper
8060 * layout functions, all of them using children size hints to define
8061 * their size and alignment inside their cell space.
8063 * @see @ref Evas_Object_Group_Size_Hints
8065 * @ingroup Evas_Smart_Object_Group
8068 * @typedef Evas_Object_Box_Api
8069 * Smart Class extension providing extra box requirements.
8070 * @ingroup Evas_Object_Box
8072 typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
8074 * @typedef Evas_Object_Box_Data
8075 * Smart instance data providing box requirements.
8076 * @ingroup Evas_Object_Box
8078 typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
8080 * @typedef Evas_Object_Box_Option
8081 * The base structure for a box option.
8082 * @ingroup Evas_Object_Box
8084 typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
8085 typedef void (*Evas_Object_Box_Layout) (Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
8088 * @def EVAS_OBJECT_BOX_API_VERSION
8089 * @ingroup Evas_Object_Box
8091 #define EVAS_OBJECT_BOX_API_VERSION 1
8093 * @struct _Evas_Object_Box_Api
8095 * This structure should be used by any class that wants to inherit
8096 * from box to provide custom behavior not allowed only by providing a
8097 * layout function with evas_object_box_layout_set().
8099 * @extends Evas_Smart_Class
8100 * @ingroup Evas_Object_Box
8102 struct _Evas_Object_Box_Api
8104 Evas_Smart_Class base;
8106 Evas_Object_Box_Option *(*append) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
8107 Evas_Object_Box_Option *(*prepend) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
8108 Evas_Object_Box_Option *(*insert_before) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, const Evas_Object *reference);
8109 Evas_Object_Box_Option *(*insert_after) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, const Evas_Object *reference);
8110 Evas_Object_Box_Option *(*insert_at) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, unsigned int pos);
8111 Evas_Object *(*remove) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
8112 Evas_Object *(*remove_at) (Evas_Object *o, Evas_Object_Box_Data *priv, unsigned int pos);
8113 Eina_Bool (*property_set) (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args);
8114 Eina_Bool (*property_get) (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args);
8115 const char *(*property_name_get)(Evas_Object *o, int property);
8116 int (*property_id_get) (Evas_Object *o, const char *name);
8117 Evas_Object_Box_Option *(*option_new) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
8118 void (*option_free) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt);
8122 * @def EVAS_OBJECT_BOX_API_INIT
8123 * Initializer for whole Evas_Object_Box_Api structure.
8125 * @param smart_class_init initializer to use for the "base" field
8126 * (Evas_Smart_Class).
8128 * @see EVAS_SMART_CLASS_INIT_NULL
8129 * @see EVAS_SMART_CLASS_INIT_VERSION
8130 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
8131 * @see EVAS_OBJECT_BOX_API_INIT_NULL
8132 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
8133 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
8134 * @ingroup Evas_Object_Box
8136 #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}
8139 * @def EVAS_OBJECT_BOX_API_INIT_NULL
8140 * Initializer to zero a whole Evas_Object_Box_Api structure.
8142 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
8143 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
8144 * @see EVAS_OBJECT_BOX_API_INIT
8145 * @ingroup Evas_Object_Box
8147 #define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
8150 * @def EVAS_OBJECT_BOX_API_INIT_VERSION
8151 * Initializer to zero a whole Evas_Object_Box_Api structure and set version.
8153 * Similar to EVAS_OBJECT_BOX_API_INIT_NULL, but will set version field of
8154 * Evas_Smart_Class (base field) to latest EVAS_SMART_CLASS_VERSION
8156 * @see EVAS_OBJECT_BOX_API_INIT_NULL
8157 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
8158 * @see EVAS_OBJECT_BOX_API_INIT
8159 * @ingroup Evas_Object_Box
8161 #define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
8164 * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
8165 * Initializer to zero a whole Evas_Object_Box_Api structure and set
8168 * Similar to EVAS_OBJECT_BOX_API_INIT_NULL, but will set version field of
8169 * Evas_Smart_Class (base field) to latest EVAS_SMART_CLASS_VERSION and name
8170 * to the specific value.
8172 * It will keep a reference to name field as a "const char *", that is,
8173 * name must be available while the structure is used (hint: static or global!)
8174 * and will not be modified.
8176 * @see EVAS_OBJECT_BOX_API_INIT_NULL
8177 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
8178 * @see EVAS_OBJECT_BOX_API_INIT
8179 * @ingroup Evas_Object_Box
8181 #define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
8184 * @struct _Evas_Object_Box_Data
8186 * This structure augments clipped smart object's instance data,
8187 * providing extra members required by generic box implementation. If
8188 * a subclass inherits from #Evas_Object_Box_Api then it may augment
8189 * #Evas_Object_Box_Data to fit its own needs.
8191 * @extends Evas_Object_Smart_Clipped_Data
8192 * @ingroup Evas_Object_Box
8194 struct _Evas_Object_Box_Data
8196 Evas_Object_Smart_Clipped_Data base;
8197 const Evas_Object_Box_Api *api;
8204 Eina_List *children;
8206 Evas_Object_Box_Layout cb;
8208 void (*free_data)(void *data);
8210 Eina_Bool layouting : 1;
8211 Eina_Bool children_changed : 1;
8214 struct _Evas_Object_Box_Option
8217 Eina_Bool max_reached:1;
8218 Eina_Bool min_reached:1;
8219 Evas_Coord alloc_size;
8224 * Set the default box @a api struct (Evas_Object_Box_Api)
8225 * with the default values. May be used to extend that API.
8227 EAPI void evas_object_box_smart_set (Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
8230 * Get Box Smart Class for inheritance purposes
8232 EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get (void) EINA_CONST;
8235 * Set a 'calculate' callback (@a cb) to the @a o box's smart class,
8236 * which here defines its genre (horizontal, vertical, homogeneous,
8239 EAPI 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);
8245 * Its layout function must be set via evas_object_box_layout_set()
8246 * (defaults to evas_object_box_layout_horizontal()). The other
8247 * properties of the box must be set/retrieved via
8248 * evas_object_box_{h,v}_{align,padding}_{get,set)().
8250 EAPI Evas_Object *evas_object_box_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8253 * Create a box that is child of a given element @a parent.
8255 * @see evas_object_box_add()
8257 EAPI Evas_Object *evas_object_box_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8261 * Layout function which sets the box @a o to a (basic) horizontal
8262 * box. @a priv must be the smart data of the box.
8264 * The object's overall behavior is controlled by its properties,
8265 * which are set by the evas_object_box_{h,v}_{align,padding}_set()
8266 * family of functions. The properties of the elements in the box --
8267 * set by evas_object_size_hint_{align,padding,weight}_set() functions
8268 * -- also control the way this function works.
8270 * \par box's properties:
8271 * @c align_h controls the horizontal alignment of the child objects
8272 * relative to the containing box. When set to 0, children are aligned
8273 * to the left. A value of 1 lets them aligned to the right border.
8274 * Values in between align them proportionally. Note that if the size
8275 * required by the children, which is given by their widths and the @c
8276 * padding_h property of the box, is bigger than the container width,
8277 * the children will be displayed out of its bounds. A negative value
8278 * of @c align_h makes the box to *justify* its children. The padding
8279 * between them, in this case, is corrected so that the leftmost one
8280 * touches the left border and the rightmost one touches the right
8281 * border (even if they must overlap). The @c align_v and @c
8282 * padding_v properties of the box don't contribute to its behaviour
8283 * when this layout is chosen.
8285 * \par Child element's properties:
8286 * @c align_x does not influence the box's behavior. @c padding_l and
8287 * @c padding_r sum up to the container's horizontal padding between
8288 * elements. The child's @c padding_t, @c padding_b and @c align_y
8289 * properties apply for padding/positioning relative to the overall
8290 * height of the box. Finally, there is the @c weight_x property,
8291 * which, if set to a non-zero value, tells the container that the
8292 * child width is not pre-defined. If the container can't accommodate
8293 * all its children, it sets the widths of the children *with weights*
8294 * to sizes as small as they can all fit into it. If the size
8295 * required by the children is less than the available, the box
8296 * increases its children's (which have weights) widths as to fit the
8297 * remaining space. The @c weight_x property, besides telling the
8298 * element is resizable, gives a *weight* for the resizing process.
8299 * The parent box will try to distribute (or take off) widths
8300 * accordingly to the *normalized* list of weigths: most weighted
8301 * children remain/get larger in this process than the least ones.
8302 * @c weight_y does not influence the layout.
8304 * If one desires that, besides having weights, child elements must be
8305 * resized bounded to a minimum or maximum size, their size hint
8306 * properties must be set (by the
8307 * evas_object_size_hint_{min,max}_set() functions.
8309 EAPI void evas_object_box_layout_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8312 * Layout function which sets the box @a o to a (basic) vertical box.
8313 * @a priv must be the smart data of the box.
8315 * This function behaves analogously to
8316 * evas_object_box_layout_horizontal(). The description of its
8317 * behaviour can be derived from that function's documentation.
8319 EAPI void evas_object_box_layout_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8322 * Layout function which sets the box @a o to a *homogeneous* vertical
8323 * box. @a priv must be the smart data of the box.
8325 * This function behaves analogously to
8326 * evas_object_box_layout_homogeneous_horizontal(). The description
8327 * of its behaviour can be derived from that function's documentation.
8329 EAPI void evas_object_box_layout_homogeneous_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8332 * Layout function which sets the box @a o to a *homogeneous*
8333 * horizontal box. @a priv must be the smart data of the box.
8335 * In a homogeneous horizontal box, its width is divided equally
8336 * between the contained objects. The box's overall behavior is
8337 * controlled by its properties, which are set by the
8338 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
8339 * The properties of the elements in the box -- set by
8340 * evas_object_size_hint_{align,padding,weight}_set() functions --
8341 * also control the way this function works.
8343 * \par box's properties:
8344 * @c align_h has no influence on the box for this layout. @c
8345 * padding_h tells the box to draw empty spaces of that size, in
8346 * pixels, between the (still equal) child objects's cells. The @c
8347 * align_v and @c padding_v properties of the box don't contribute to
8348 * its behaviour when this layout is chosen.
8350 * \par Child element's properties:
8351 * @c padding_l and @c padding_r sum up to the required width of the
8352 * child element. The @c align_x property tells the relative position
8353 * of this overall child width in its allocated cell (0 to extreme
8354 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
8355 * box try to resize this child element to the exact width of its cell
8356 * (respecting the min and max hints on the child's width *and*
8357 * accounting its horizontal padding properties). The child's @c
8358 * padding_t, @c padding_b and @c align_y properties apply for
8359 * padding/positioning relative to the overall height of the box. A
8360 * value of -1.0 to @c align_y makes the box try to resize this child
8361 * element to the exact height of its parent (respecting the max hint
8362 * on the child's height).
8364 EAPI void evas_object_box_layout_homogeneous_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8367 * Layout function which sets the box @a o to a *max size-homogeneous*
8368 * horizontal box. @a priv must be the smart data of the box.
8370 * In a max size-homogeneous horizontal box, the equal sized cells
8371 * reserved for the child objects have the width of the space required
8372 * by the largest child (in width). The box's overall behavior is
8373 * controlled by its properties, which are set by the
8374 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
8375 * The properties of the elements in the box -- set by
8376 * evas_object_size_hint_{align,padding,weight}_set() functions --
8377 * also control the way this function works.
8379 * \par box's properties:
8380 * @c padding_h tells the box to draw empty spaces of that size, in
8381 * pixels, between the child objects's cells. @c align_h controls the
8382 * horizontal alignment of the child objects relative to the
8383 * containing box. When set to 0, children are aligned to the left. A
8384 * value of 1 lets them aligned to the right border. Values in
8385 * between align them proportionally. A negative value of @c align_h
8386 * makes the box to *justify* its children cells. The padding between
8387 * them, in this case, is corrected so that the leftmost one touches
8388 * the left border and the rightmost one touches the right border
8389 * (even if they must overlap). The @c align_v and @c padding_v
8390 * properties of the box don't contribute to its behaviour when this
8393 * \par Child element's properties:
8394 * @c padding_l and @c padding_r sum up to the required width of the
8395 * child element. The @c align_x property tells the relative position
8396 * of this overall child width in its allocated cell (0 to extreme
8397 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
8398 * box try to resize this child element to the exact width of its cell
8399 * (respecting the min and max hints on the child's width *and*
8400 * accounting its horizontal padding properties). The child's @c
8401 * padding_t, @c padding_b and @c align_y properties apply for
8402 * padding/positioning relative to the overall height of the box. A
8403 * value of -1.0 to @c align_y makes the box try to resize this child
8404 * element to the exact height of its parent (respecting the max hint
8405 * on the child's height).
8407 EAPI void evas_object_box_layout_homogeneous_max_size_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8410 * Layout function which sets the box @a o to a *max size-homogeneous*
8411 * vertical box. @a priv must be the smart data of the box.
8413 * This function behaves analogously to
8414 * evas_object_box_layout_homogeneous_max_size_horizontal(). The
8415 * description of its behaviour can be derived from that function's
8418 EAPI void evas_object_box_layout_homogeneous_max_size_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8421 * Layout function which sets the box @a o to a *flow* horizontal box.
8422 * @a priv must be the smart data of the box.
8424 * In a flow horizontal box, the box's child elements are placed in
8425 * rows (think of text as an analogy). A row has as much elements as
8426 * can fit into the box's width. The box's overall behavior is
8427 * controlled by its properties, which are set by the
8428 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
8429 * The properties of the elements in the box -- set by
8430 * evas_object_size_hint_{align,padding,weight}_set() functions --
8431 * also control the way this function works.
8433 * \par box's properties:
8434 * @c padding_h tells the box to draw empty spaces of that size, in
8435 * pixels, between the child objects's cells. @c align_h dictates the
8436 * horizontal alignment of the rows (0 to left align them, 1 to right
8437 * align). A value of -1.0 to @c align_h lets the rows *justified*
8438 * horizontally. @c align_v controls the vertical alignment of the
8439 * entire set of rows (0 to top, 1 to bottom). A value of -1.0 to @c
8440 * align_v makes the box to *justify* the rows vertically. The padding
8441 * between them, in this case, is corrected so that the first row
8442 * touches the top border and the last one touches the bottom border
8443 * (even if they must overlap). @c padding_v has no influence on the
8446 * \par Child element's properties:
8447 * @c padding_l and @c padding_r sum up to the required width of the
8448 * child element. The @c align_x property has no influence on the
8449 * layout. The child's @c padding_t and @c padding_b sum up to the
8450 * required height of the child element and is the only means (besides
8451 * row justifying) of setting space between rows. Note, however, that
8452 * @c align_y dictates positioning relative to the *largest height*
8453 * required by a child object in the actual row.
8455 EAPI void evas_object_box_layout_flow_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8458 * Layout function which sets the box @a o to a *flow* vertical box.
8459 * @a priv must be the smart data of the box.
8461 * This function behaves analogously to
8462 * evas_object_box_layout_flow_horizontal(). The description of its
8463 * behaviour can be derived from that function's documentation.
8465 EAPI void evas_object_box_layout_flow_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8468 * Layout function which sets the box @a o to set all children to the
8469 * size of the object. @a priv must be the smart data of the box.
8471 * In a stack box, all children will be given the same size and they
8472 * will be stacked on above the other, so the first object will be the
8475 * \par box's properties:
8476 * No box option is used.
8478 * \par Child element's properties:
8479 * @c padding_l and @c padding_r sum up to the required width of the
8480 * child element. The @c align_x property tells the relative position
8481 * of this overall child width in its allocated cell (0 to extreme
8482 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
8483 * box try to resize this child element to the exact width of its cell
8484 * (respecting the min and max hints on the child's width *and*
8485 * accounting its horizontal padding properties). Same applies to
8488 EAPI void evas_object_box_layout_stack (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8492 * Set the alignment of the whole bounding box of contents.
8494 EAPI void evas_object_box_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
8497 * Get alignment of the whole bounding box of contents.
8499 EAPI void evas_object_box_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
8502 * Set the space (padding) between cells.
8504 EAPI void evas_object_box_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
8507 * Get the (space) padding between cells.
8509 EAPI void evas_object_box_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
8513 * Append a new object @a child to the box @a o. On error, @c NULL is
8516 EAPI Evas_Object_Box_Option *evas_object_box_append (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8519 * Prepend a new object @a child to the box @a o. On error, @c NULL is
8522 EAPI Evas_Object_Box_Option *evas_object_box_prepend (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8525 * Prepend a new object @a child to the box @c o relative to element @a
8526 * reference. If @a reference is not contained in the box or any other
8527 * error occurs, @c NULL is returned.
8529 EAPI 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);
8532 * Append a new object @a child to the box @c o relative to element @a
8533 * reference. If @a reference is not contained in the box or any other
8534 * error occurs, @c NULL is returend.
8536 EAPI 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);
8539 * Insert a new object @a child to the box @a o at position @a pos. On
8540 * error, @c NULL is returned.
8542 EAPI Evas_Object_Box_Option *evas_object_box_insert_at (Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2);
8545 * Remove an object @a child from the box @a o. On error, @c 0 is
8548 EAPI Eina_Bool evas_object_box_remove (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8551 * Remove an object from the box @a o which occupies position @a
8552 * pos. On error, @c 0 is returned.
8554 EAPI Eina_Bool evas_object_box_remove_at (Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1);
8557 * Remove all child objects.
8558 * @return 0 on errors
8560 EAPI Eina_Bool evas_object_box_remove_all (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8563 * Get an iterator to walk the list of children for the box.
8565 * @note Do not remove or delete objects while walking the list.
8567 EAPI Eina_Iterator *evas_object_box_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8570 * Get an accessor to get random access to the list of children for the box.
8572 * @note Do not remove or delete objects while walking the list.
8574 EAPI Eina_Accessor *evas_object_box_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8577 * Get the list of children for the box.
8579 * @note This is a duplicate of the list kept by the box internally.
8580 * It's up to the user to destroy it when it no longer needs it.
8581 * It's possible to remove objects from the box when walking this
8582 * list, but these removals won't be reflected on it.
8584 EAPI Eina_List *evas_object_box_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8588 * Get the name of the property of the child elements of the box @a o
8589 * whose id is @a property. On error, @c NULL is returned.
8591 EAPI const char *evas_object_box_option_property_name_get (Evas_Object *o, int property) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8594 * Get the id of the property of the child elements of the box @a o
8595 * whose name is @a name. On error, @c -1 is returned.
8597 EAPI 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;
8600 * Set the property (with id @a property) of the child element of the
8601 * box @a o whose property struct is @a opt. The property's values
8602 * must be the last arguments and their type *must* match that of the
8603 * property itself. On error, @c 0 is returned.
8605 EAPI Eina_Bool evas_object_box_option_property_set (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
8608 * Set the property (with id @a property) of the child element of the
8609 * box @a o whose property struct is @a opt. The property's values
8610 * must be the args which the va_list @a args is initialized with and
8611 * their type *must* match that of the property itself. On error, @c 0
8614 EAPI 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);
8617 * Get the property (with id @a property) of the child element of the
8618 * box @a o whose property struct is @a opt. The last arguments must
8619 * be addresses of variables with the same type of that property. On
8620 * error, @c 0 is returned.
8622 EAPI Eina_Bool evas_object_box_option_property_get (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
8625 * Get the property (with id @a property) of the child element of the
8626 * box @a o whose property struct is @a opt. The args which the
8627 * va_list @a args is initialized with must be addresses of variables
8628 * with the same type of that property. On error, @c 0 is returned.
8630 EAPI 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);
8633 * @defgroup Evas_Object_Table Table Smart Object.
8635 * Convenience smart object that packs children using a tabular
8636 * layout using children size hints to define their size and
8637 * alignment inside their cell space.
8639 * @see @ref Evas_Object_Group_Size_Hints
8641 * @ingroup Evas_Smart_Object_Group
8645 * Create a new table.
8647 * It's set to non-homogeneous by default, add children with
8648 * evas_object_table_pack().
8650 EAPI Evas_Object *evas_object_table_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8653 * Create a table that is child of a given element @a parent.
8655 * @see evas_object_table_add()
8657 EAPI Evas_Object *evas_object_table_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8660 * Set how this table should layout children.
8662 * @todo consider aspect hint and respect it.
8664 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE
8665 * If table does not use homogeneous mode then columns and rows will
8666 * be calculated based on hints of individual cells. This operation
8667 * mode is more flexible, but more complex and heavy to calculate as
8668 * well. @b Weight properties are handled as a boolean
8669 * expand. Negative alignment will be considered as 0.5.
8671 * @todo @c EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE should balance weight.
8673 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE
8674 * When homogeneous is relative to table the own table size is divided
8675 * equally among children, filling the whole table area. That is, if
8676 * table has @c WIDTH and @c COLUMNS, each cell will get <tt>WIDTH /
8677 * COLUMNS</tt> pixels. If children have minimum size that is larger
8678 * than this amount (including padding), then it will overflow and be
8679 * aligned respecting the alignment hint, possible overlapping sibling
8680 * cells. @b Weight hint is used as a boolean, if greater than zero it
8681 * will make the child expand in that axis, taking as much space as
8682 * possible (bounded to maximum size hint). Negative alignment will be
8683 * considered as 0.5.
8685 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM
8686 * When homogeneous is relative to item it means the greatest minimum
8687 * cell size will be used. That is, if no element is set to expand,
8688 * the table will have its contents to a minimum size, the bounding
8689 * box of all these children will be aligned relatively to the table
8690 * object using evas_object_table_align_get(). If the table area is
8691 * too small to hold this minimum bounding box, then the objects will
8692 * keep their size and the bounding box will overflow the box area,
8693 * still respecting the alignment. @b Weight hint is used as a
8694 * boolean, if greater than zero it will make that cell expand in that
8695 * axis, toggling the <b>expand mode</b>, which makes the table behave
8696 * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the
8697 * bounding box will overflow and items will not overlap siblings. If
8698 * no minimum size is provided at all then the table will fallback to
8699 * expand mode as well.
8701 EAPI void evas_object_table_homogeneous_set (Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1);
8704 * Get the current layout homogeneous mode.
8706 * @see evas_object_table_homogeneous_set()
8708 EAPI Evas_Object_Table_Homogeneous_Mode evas_object_table_homogeneous_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8711 * Set padding between cells.
8713 EAPI void evas_object_table_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
8716 * Get padding between cells.
8718 EAPI void evas_object_table_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
8721 * Set the alignment of the whole bounding box of contents.
8723 EAPI void evas_object_table_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
8726 * Get alignment of the whole bounding box of contents.
8728 EAPI void evas_object_table_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
8731 * Sets the mirrored mode of the table. In mirrored mode the table items go
8732 * from right to left instead of left to right. That is, 1,1 is top right, not
8735 * @param obj The table object.
8736 * @param mirrored the mirrored mode to set
8739 EAPI void evas_object_table_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
8742 * Gets the mirrored mode of the table. In mirrored mode the table items go
8743 * from right to left instead of left to right. That is, 1,1 is top right, not
8746 * @param obj The table object.
8747 * @return EINA_TRUE if it's a mirrored table, EINA_FALSE otherwise.
8752 * Get a child from the table using its coordinates
8754 * @note This does not take into account col/row spanning
8756 EAPI Eina_Bool evas_object_table_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
8760 * Get packing location of a child of table
8762 * @param o The given table object.
8763 * @param child The child object to add.
8764 * @param col pointer to store relative-horizontal position to place child.
8765 * @param row pointer to store relative-vertical position to place child.
8766 * @param colspan pointer to store how many relative-horizontal position to use for this child.
8767 * @param rowspan pointer to store how many relative-vertical position to use for this child.
8769 * @return 1 on success, 0 on failure.
8772 EAPI 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);
8775 * Add a new child to a table object or set its current packing.
8777 * @param o The given table object.
8778 * @param child The child object to add.
8779 * @param col relative-horizontal position to place child.
8780 * @param row relative-vertical position to place child.
8781 * @param colspan how many relative-horizontal position to use for this child.
8782 * @param rowspan how many relative-vertical position to use for this child.
8784 * @return 1 on success, 0 on failure.
8786 EAPI 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);
8789 * Remove child from table.
8791 * @note removing a child will immediately call a walk over children in order
8792 * to recalculate numbers of columns and rows. If you plan to remove
8793 * all children, use evas_object_table_clear() instead.
8795 * @return 1 on success, 0 on failure.
8797 EAPI Eina_Bool evas_object_table_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8800 * Faster way to remove all child objects from a table object.
8802 * @param o The given table object.
8803 * @param clear if true, it will delete just removed children.
8805 EAPI void evas_object_table_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8809 * Get the number of columns and rows this table takes.
8811 * @note columns and rows are virtual entities, one can specify a table
8812 * with a single object that takes 4 columns and 5 rows. The only
8813 * difference for a single cell table is that paddings will be
8814 * accounted proportionally.
8816 EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1);
8819 * Get an iterator to walk the list of children for the table.
8821 * @note Do not remove or delete objects while walking the list.
8823 EAPI Eina_Iterator *evas_object_table_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8826 * Get an accessor to get random access to the list of children for the table.
8828 * @note Do not remove or delete objects while walking the list.
8830 EAPI Eina_Accessor *evas_object_table_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8833 * Get the list of children for the table.
8835 * @note This is a duplicate of the list kept by the table internally.
8836 * It's up to the user to destroy it when it no longer needs it.
8837 * It's possible to remove objects from the table when walking this
8838 * list, but these removals won't be reflected on it.
8840 EAPI Eina_List *evas_object_table_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8841 EAPI Evas_Object *evas_object_table_child_get (const Evas_Object *o, unsigned short col, unsigned short row) EINA_ARG_NONNULL(1);
8844 * @defgroup Evas_Object_Grid Grid Smart Object.
8846 * Convenience smart object that packs children using a regular grid
8847 * layout using Their virtual grid location and size to determine
8848 * position inside the grid object
8850 * @ingroup Evas_Smart_Object_Group
8855 * Create a new grid.
8857 * It's set to a virtual size of 1x1 by default and add children with
8858 * evas_object_grid_pack().
8861 EAPI Evas_Object *evas_object_grid_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8864 * Create a grid that is child of a given element @a parent.
8866 * @see evas_object_grid_add()
8869 EAPI Evas_Object *evas_object_grid_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8872 * Set the virtual resolution for the grid
8874 * @param o The grid object to modify
8875 * @param w The virtual horizontal size (resolution) in integer units
8876 * @param h The virtual vertical size (resolution) in integer units
8879 EAPI void evas_object_grid_size_set (Evas_Object *o, int w, int h) EINA_ARG_NONNULL(1);
8882 * Get the current virtual resolution
8884 * @param o The grid object to query
8885 * @param w A pointer to an integer to store the virtual width
8886 * @param h A pointer to an integer to store the virtual height
8887 * @see evas_object_grid_size_set()
8890 EAPI void evas_object_grid_size_get (const Evas_Object *o, int *w, int *h) EINA_ARG_NONNULL(1) EINA_PURE;
8893 * Sets the mirrored mode of the grid. In mirrored mode the grid items go
8894 * from right to left instead of left to right. That is, 0,0 is top right, not
8897 * @param obj The grid object.
8898 * @param mirrored the mirrored mode to set
8901 EAPI void evas_object_grid_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
8904 * Gets the mirrored mode of the grid.
8906 * @param obj The grid object.
8907 * @return EINA_TRUE if it's a mirrored grid, EINA_FALSE otherwise.
8908 * @see evas_object_grid_mirrored_set()
8911 EAPI Eina_Bool evas_object_grid_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
8914 * Add a new child to a grid object.
8916 * @param o The given grid object.
8917 * @param child The child object to add.
8918 * @param x The virtual x coordinate of the child
8919 * @param y The virtual y coordinate of the child
8920 * @param w The virtual width of the child
8921 * @param h The virtual height of the child
8922 * @return 1 on success, 0 on failure.
8925 EAPI 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);
8928 * Remove child from grid.
8930 * @note removing a child will immediately call a walk over children in order
8931 * to recalculate numbers of columns and rows. If you plan to remove
8932 * all children, use evas_object_grid_clear() instead.
8934 * @return 1 on success, 0 on failure.
8937 EAPI Eina_Bool evas_object_grid_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8940 * Faster way to remove all child objects from a grid object.
8942 * @param o The given grid object.
8943 * @param clear if true, it will delete just removed children.
8946 EAPI void evas_object_grid_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8949 * Get the pack options for a grid child
8951 * Get the pack x, y, width and height in virtual coordinates set by
8952 * evas_object_grid_pack()
8953 * @param o The grid object
8954 * @param child The grid child to query for coordinates
8955 * @param x The pointer to where the x coordinate will be returned
8956 * @param y The pointer to where the y coordinate will be returned
8957 * @param w The pointer to where the width will be returned
8958 * @param h The pointer to where the height will be returned
8959 * @return 1 on success, 0 on failure.
8962 EAPI Eina_Bool evas_object_grid_pack_get (Evas_Object *o, Evas_Object *child, int *x, int *y, int *w, int *h);
8965 * Get an iterator to walk the list of children for the grid.
8967 * @note Do not remove or delete objects while walking the list.
8970 EAPI Eina_Iterator *evas_object_grid_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8973 * Get an accessor to get random access to the list of children for the grid.
8975 * @note Do not remove or delete objects while walking the list.
8978 EAPI Eina_Accessor *evas_object_grid_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8981 * Get the list of children for the grid.
8983 * @note This is a duplicate of the list kept by the grid internally.
8984 * It's up to the user to destroy it when it no longer needs it.
8985 * It's possible to remove objects from the grid when walking this
8986 * list, but these removals won't be reflected on it.
8989 EAPI Eina_List *evas_object_grid_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8992 * @defgroup Evas_Cserve Shared Image Cache Server
8994 * Provides client-server infrastructure to share bitmaps across
8995 * multiple processes, saving data and processing power.
8997 typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
8998 typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
8999 typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
9000 typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
9003 * Statistics about server that shares cached bitmaps.
9004 * @ingroup Evas_Cserve
9006 struct _Evas_Cserve_Stats
9008 int saved_memory; /**< current saved memory, in bytes */
9009 int wasted_memory; /**< current wasted memory, in bytes */
9010 int saved_memory_peak; /**< peak of saved memory, in bytes */
9011 int wasted_memory_peak; /**< peak of wasted memory, in bytes */
9012 double saved_time_image_header_load; /**< time, in seconds, saved in header loads by sharing cached loads instead */
9013 double saved_time_image_data_load; /**< time, in seconds, saved in data loads by sharing cached loads instead */
9017 * Cache of images shared by server.
9018 * @ingroup Evas_Cserve
9020 struct _Evas_Cserve_Image_Cache
9030 * An image shared by the server.
9031 * @ingroup Evas_Cserve
9033 struct _Evas_Cserve_Image
9035 const char *file, *key;
9037 time_t file_mod_time;
9038 time_t file_checked_time;
9042 int memory_footprint;
9043 double head_load_time;
9044 double data_load_time;
9045 Eina_Bool alpha : 1;
9046 Eina_Bool data_loaded : 1;
9047 Eina_Bool active : 1;
9049 Eina_Bool useless : 1;
9053 * Configuration that controls the server that shares cached bitmaps.
9054 * @ingroup Evas_Cserve
9056 struct _Evas_Cserve_Config
9058 int cache_max_usage;
9059 int cache_item_timeout;
9060 int cache_item_timeout_check;
9065 * Retrieves if the system wants to share bitmaps using the server.
9066 * @return @c EINA_TRUE if wants, @c EINA_FALSE otherwise.
9067 * @ingroup Evas_Cserve
9069 EAPI Eina_Bool evas_cserve_want_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE;
9072 * Retrieves if the system is connected to the server used to shae bitmaps.
9073 * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise.
9074 * @ingroup Evas_Cserve
9076 EAPI Eina_Bool evas_cserve_connected_get (void) EINA_WARN_UNUSED_RESULT;
9079 * Retrieves if the system wants to share bitmaps using the server.
9080 * @param stats pointer to structure to fill with statistics about
9082 * @return @c EINA_TRUE if @p stats were filled with data,
9083 * @c EINA_FALSE otherwise and @p stats is untouched.
9084 * @ingroup Evas_Cserve
9086 EAPI Eina_Bool evas_cserve_stats_get (Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
9087 EAPI void evas_cserve_image_cache_contents_clean (Evas_Cserve_Image_Cache *cache) EINA_PURE;
9090 * Retrieves the current configuration of the server.
9091 * @param config where to store current server configuration.
9092 * @return @c EINA_TRUE if @p config were filled with data,
9093 * @c EINA_FALSE otherwise and @p config is untouched.
9094 * @ingroup Evas_Cserve
9096 EAPI Eina_Bool evas_cserve_config_get (Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE;
9099 * Changes the configuration of the server.
9100 * @param config where to store current server configuration.
9101 * @return @c EINA_TRUE if @p config were successfully applied,
9102 * @c EINA_FALSE otherwise.
9103 * @ingroup Evas_Cserve
9105 EAPI Eina_Bool evas_cserve_config_set (const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE;
9108 * Force system to disconnect from cache server.
9109 * @ingroup Evas_Cserve
9111 EAPI void evas_cserve_disconnect (void);
9114 * @defgroup Evas_Utils General Utilities
9116 * Some functions that are handy but are not specific of canvas or
9121 * Converts the given Evas image load error code into a string
9122 * describing it in english.
9124 * @param error the error code, a value in ::Evas_Load_Error.
9125 * @return Always returns a valid string. If the given @p error is not
9126 * supported, <code>"Unknown error"</code> is returned.
9128 * Mostly evas_object_image_file_set() would be the function setting
9129 * that error value afterwards, but also evas_object_image_load(),
9130 * evas_object_image_save(), evas_object_image_data_get(),
9131 * evas_object_image_data_convert(), evas_object_image_pixels_import()
9132 * and evas_object_image_is_inside(). This function is meant to be
9133 * used in conjunction with evas_object_image_load_error_get(), as in:
9136 * @dontinclude evas-load-error-str.c
9138 * @until ecore_main_loop_begin(
9140 * Here, being @c valid_path the path to a valid image and @c
9141 * bogus_path a path to a file which does not exist, the two outputs
9142 * of evas_load_error_str() would be (if no other errors occur):
9143 * <code>"No error on load"</code> and <code>"File (or file path) does
9144 * not exist"</code>, respectively. See the full @ref
9145 * Example_Evas_Load_Error_Str "example".
9147 * @ingroup Evas_Utils
9149 EAPI const char *evas_load_error_str (Evas_Load_Error error);
9151 /* Evas utility routines for color space conversions */
9152 /* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
9153 /* rgb color space has r,g,b in the range 0 to 255 */
9156 * Convert a given color from HSV to RGB format.
9158 * @param h The Hue component of the color.
9159 * @param s The Saturation component of the color.
9160 * @param v The Value component of the color.
9161 * @param r The Red component of the color.
9162 * @param g The Green component of the color.
9163 * @param b The Blue component of the color.
9165 * This function converts a given color in HSV color format to RGB
9168 * @ingroup Evas_Utils
9170 EAPI void evas_color_hsv_to_rgb (float h, float s, float v, int *r, int *g, int *b);
9173 * Convert a given color from RGB to HSV format.
9175 * @param r The Red component of the color.
9176 * @param g The Green component of the color.
9177 * @param b The Blue component of the color.
9178 * @param h The Hue component of the color.
9179 * @param s The Saturation component of the color.
9180 * @param v The Value component of the color.
9182 * This function converts a given color in RGB color format to HSV
9185 * @ingroup Evas_Utils
9187 EAPI void evas_color_rgb_to_hsv (int r, int g, int b, float *h, float *s, float *v);
9189 /* argb color space has a,r,g,b in the range 0 to 255 */
9192 * Pre-multiplies a rgb triplet by an alpha factor.
9194 * @param a The alpha factor.
9195 * @param r The Red component of the color.
9196 * @param g The Green component of the color.
9197 * @param b The Blue component of the color.
9199 * This function pre-multiplies a given rbg triplet by an alpha
9200 * factor. Alpha factor is used to define transparency.
9202 * @ingroup Evas_Utils
9204 EAPI void evas_color_argb_premul (int a, int *r, int *g, int *b);
9207 * Undo pre-multiplication of a rgb triplet by an alpha factor.
9209 * @param a The alpha factor.
9210 * @param r The Red component of the color.
9211 * @param g The Green component of the color.
9212 * @param b The Blue component of the color.
9214 * This function undoes pre-multiplication a given rbg triplet by an
9215 * alpha factor. Alpha factor is used to define transparency.
9217 * @see evas_color_argb_premul().
9219 * @ingroup Evas_Utils
9221 EAPI void evas_color_argb_unpremul (int a, int *r, int *g, int *b);
9225 * Pre-multiplies data by an alpha factor.
9227 * @param data The data value.
9228 * @param len The length value.
9230 * This function pre-multiplies a given data by an alpha
9231 * factor. Alpha factor is used to define transparency.
9233 * @ingroup Evas_Utils
9235 EAPI void evas_data_argb_premul (unsigned int *data, unsigned int len);
9238 * Undo pre-multiplication data by an alpha factor.
9240 * @param data The data value.
9241 * @param len The length value.
9243 * This function undoes pre-multiplication of a given data by an alpha
9244 * factor. Alpha factor is used to define transparency.
9246 * @ingroup Evas_Utils
9248 EAPI void evas_data_argb_unpremul (unsigned int *data, unsigned int len);
9250 /* string and font handling */
9253 * Gets the next character in the string
9255 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
9256 * this function will place in @p decoded the decoded code point at @p pos
9257 * and return the byte index for the next character in the string.
9259 * The only boundary check done is that @p pos must be >= 0. Other than that,
9260 * no checks are performed, so passing an index value that's not within the
9261 * length of the string will result in undefined behavior.
9263 * @param str The UTF-8 string
9264 * @param pos The byte index where to start
9265 * @param decoded Address where to store the decoded code point. Optional.
9267 * @return The byte index of the next character
9269 * @ingroup Evas_Utils
9271 EAPI int evas_string_char_next_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
9274 * Gets the previous character in the string
9276 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
9277 * this function will place in @p decoded the decoded code point at @p pos
9278 * and return the byte index for the previous character in the string.
9280 * The only boundary check done is that @p pos must be >= 1. Other than that,
9281 * no checks are performed, so passing an index value that's not within the
9282 * length of the string will result in undefined behavior.
9284 * @param str The UTF-8 string
9285 * @param pos The byte index where to start
9286 * @param decoded Address where to store the decoded code point. Optional.
9288 * @return The byte index of the previous character
9290 * @ingroup Evas_Utils
9292 EAPI int evas_string_char_prev_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
9295 * Get the length in characters of the string.
9296 * @param str The string to get the length of.
9297 * @return The length in characters (not bytes)
9298 * @ingroup Evas_Utils
9300 EAPI int evas_string_char_len_get (const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9303 * @defgroup Evas_Keys Key Input Functions
9305 * Functions which feed key events to the canvas.
9307 * As explained in @ref intro_not_evas, Evas is @b not aware of input
9308 * systems at all. Then, the user, if using it crudely (evas_new()),
9309 * will have to feed it with input events, so that it can react
9310 * somehow. If, however, the user creates a canvas by means of the
9311 * Ecore_Evas wrapper, it will automatically bind the chosen display
9312 * engine's input events to the canvas, for you.
9314 * This group presents the functions dealing with the feeding of key
9315 * events to the canvas. On most of them, one has to reference a given
9316 * key by a name (<code>keyname</code> argument). Those are
9317 * <b>platform dependent</b> symbolic names for the keys. Sometimes
9318 * you'll get the right <code>keyname</code> by simply using an ASCII
9319 * value of the key name, but it won't be like that always.
9321 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
9322 * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
9323 * to your display engine's documentation when using evas through an
9324 * Ecore helper wrapper when you need the <code>keyname</code>s.
9327 * @dontinclude evas-events.c
9328 * @skip mods = evas_key_modifier_get(evas);
9331 * All the other @c evas_key functions behave on the same manner. See
9332 * the full @ref Example_Evas_Events "example".
9334 * @ingroup Evas_Canvas
9338 * @addtogroup Evas_Keys
9343 * Returns a handle to the list of modifier keys registered in the
9344 * canvas @p e. This is required to check for which modifiers are set
9345 * at a given time with the evas_key_modifier_is_set() function.
9347 * @param e The pointer to the Evas canvas
9349 * @see evas_key_modifier_add
9350 * @see evas_key_modifier_del
9351 * @see evas_key_modifier_on
9352 * @see evas_key_modifier_off
9353 * @see evas_key_modifier_is_set
9355 * @return An ::Evas_Modifier handle to query Evas' keys subsystem
9356 * with evas_key_modifier_is_set(), or @c NULL on error.
9358 EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9361 * Returns a handle to the list of lock keys registered in the canvas
9362 * @p e. This is required to check for which locks are set at a given
9363 * time with the evas_key_lock_is_set() function.
9365 * @param e The pointer to the Evas canvas
9367 * @see evas_key_lock_add
9368 * @see evas_key_lock_del
9369 * @see evas_key_lock_on
9370 * @see evas_key_lock_off
9371 * @see evas_key_lock_is_set
9373 * @return An ::Evas_Lock handle to query Evas' keys subsystem with
9374 * evas_key_lock_is_set(), or @c NULL on error.
9376 EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
9380 * Checks the state of a given modifier key, at the time of the
9381 * call. If the modifier is set, such as shift being pressed, this
9382 * function returns @c Eina_True.
9384 * @param m The current modifiers set, as returned by
9385 * evas_key_modifier_get().
9386 * @param keyname The name of the modifier key to check status for.
9388 * @return @c Eina_True if the modifier key named @p keyname is on, @c
9389 * Eina_False otherwise.
9391 * @see evas_key_modifier_add
9392 * @see evas_key_modifier_del
9393 * @see evas_key_modifier_get
9394 * @see evas_key_modifier_on
9395 * @see evas_key_modifier_off
9397 EAPI 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;
9401 * Checks the state of a given lock key, at the time of the call. If
9402 * the lock is set, such as caps lock, this function returns @c
9405 * @param l The current locks set, as returned by evas_key_lock_get().
9406 * @param keyname The name of the lock key to check status for.
9408 * @return @c Eina_True if the @p keyname lock key is set, @c
9409 * Eina_False otherwise.
9411 * @see evas_key_lock_get
9412 * @see evas_key_lock_add
9413 * @see evas_key_lock_del
9414 * @see evas_key_lock_on
9415 * @see evas_key_lock_off
9417 EAPI 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;
9421 * Adds the @p keyname key to the current list of modifier keys.
9423 * @param e The pointer to the Evas canvas
9424 * @param keyname The name of the modifier key to add to the list of
9427 * Modifiers are keys like shift, alt and ctrl, i.e., keys which are
9428 * meant to be pressed together with others, altering the behavior of
9429 * the secondly pressed keys somehow. Evas is so that these keys can
9432 * This call allows custom modifiers to be added to the Evas system at
9433 * run time. It is then possible to set and unset modifier keys
9434 * programmatically for other parts of the program to check and act
9435 * on. Programmers using Evas would check for modifier keys on key
9436 * event callbacks using evas_key_modifier_is_set().
9438 * @see evas_key_modifier_del
9439 * @see evas_key_modifier_get
9440 * @see evas_key_modifier_on
9441 * @see evas_key_modifier_off
9442 * @see evas_key_modifier_is_set
9444 * @note If the programmer instantiates the canvas by means of the
9445 * ecore_evas_new() family of helper functions, Ecore will take
9446 * care of registering on it all standard modifiers: "Shift",
9447 * "Control", "Alt", "Meta", "Hyper", "Super".
9449 EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9452 * Removes the @p keyname key from the current list of modifier keys
9455 * @param e The pointer to the Evas canvas
9456 * @param keyname The name of the key to remove from the modifiers list.
9458 * @see evas_key_modifier_add
9459 * @see evas_key_modifier_get
9460 * @see evas_key_modifier_on
9461 * @see evas_key_modifier_off
9462 * @see evas_key_modifier_is_set
9464 EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9467 * Adds the @p keyname key to the current list of lock keys.
9469 * @param e The pointer to the Evas canvas
9470 * @param keyname The name of the key to add to the locks list.
9472 * Locks are keys like caps lock, num lock or scroll lock, i.e., keys
9473 * which are meant to be pressed once -- toggling a binary state which
9474 * is bound to it -- and thus altering the behavior of all
9475 * subsequently pressed keys somehow, depending on its state. Evas is
9476 * so that these keys can be defined by the user.
9478 * This allows custom locks to be added to the evas system at run
9479 * time. It is then possible to set and unset lock keys
9480 * programmatically for other parts of the program to check and act
9481 * on. Programmers using Evas would check for lock keys on key event
9482 * callbacks using evas_key_lock_is_set().
9484 * @see evas_key_lock_get
9485 * @see evas_key_lock_del
9486 * @see evas_key_lock_on
9487 * @see evas_key_lock_off
9488 * @see evas_key_lock_is_set
9490 * @note If the programmer instantiates the canvas by means of the
9491 * ecore_evas_new() family of helper functions, Ecore will take
9492 * care of registering on it all standard lock keys: "Caps_Lock",
9493 * "Num_Lock", "Scroll_Lock".
9495 EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9498 * Removes the @p keyname key from the current list of lock keys on
9501 * @param e The pointer to the Evas canvas
9502 * @param keyname The name of the key to remove from the locks list.
9504 * @see evas_key_lock_get
9505 * @see evas_key_lock_add
9506 * @see evas_key_lock_on
9507 * @see evas_key_lock_off
9509 EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9513 * Enables or turns on programmatically the modifier key with name @p
9516 * @param e The pointer to the Evas canvas
9517 * @param keyname The name of the modifier to enable.
9519 * The effect will be as if the key was pressed for the whole time
9520 * between this call and a matching evas_key_modifier_off().
9522 * @see evas_key_modifier_add
9523 * @see evas_key_modifier_get
9524 * @see evas_key_modifier_off
9525 * @see evas_key_modifier_is_set
9527 EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9530 * Disables or turns off programmatically the modifier key with name
9533 * @param e The pointer to the Evas canvas
9534 * @param keyname The name of the modifier to disable.
9536 * @see evas_key_modifier_add
9537 * @see evas_key_modifier_get
9538 * @see evas_key_modifier_on
9539 * @see evas_key_modifier_is_set
9541 EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9544 * Enables or turns on programmatically the lock key with name @p
9547 * @param e The pointer to the Evas canvas
9548 * @param keyname The name of the lock to enable.
9550 * The effect will be as if the key was put on its active state after
9553 * @see evas_key_lock_get
9554 * @see evas_key_lock_add
9555 * @see evas_key_lock_del
9556 * @see evas_key_lock_off
9558 EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9561 * Disables or turns off programmatically the lock key with name @p
9564 * @param e The pointer to the Evas canvas
9565 * @param keyname The name of the lock to disable.
9567 * The effect will be as if the key was put on its inactive state
9570 * @see evas_key_lock_get
9571 * @see evas_key_lock_add
9572 * @see evas_key_lock_del
9573 * @see evas_key_lock_on
9575 EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9579 * Creates a bit mask from the @p keyname @b modifier key. Values
9580 * returned from different calls to it may be ORed together,
9583 * @param e The canvas whom to query the bit mask from.
9584 * @param keyname The name of the modifier key to create the mask for.
9586 * @returns the bit mask or 0 if the @p keyname key wasn't registered as a
9587 * modifier for canvas @p e.
9589 * This function is meant to be using in conjunction with
9590 * evas_object_key_grab()/evas_object_key_ungrab(). Go check their
9591 * documentation for more information.
9593 * @see evas_key_modifier_add
9594 * @see evas_key_modifier_get
9595 * @see evas_key_modifier_on
9596 * @see evas_key_modifier_off
9597 * @see evas_key_modifier_is_set
9598 * @see evas_object_key_grab
9599 * @see evas_object_key_ungrab
9601 EAPI 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;
9605 * Requests @p keyname key events be directed to @p obj.
9607 * @param obj the object to direct @p keyname events to.
9608 * @param keyname the key to request events for.
9609 * @param modifiers a mask of modifiers that must be present to
9610 * trigger the event.
9611 * @param not_modifiers a mask of modifiers that must @b not be present
9612 * to trigger the event.
9613 * @param exclusive request that the @p obj is the only object
9614 * receiving the @p keyname events.
9615 * @return @c EINA_TRUE, if the call succeeded, @c EINA_FALSE otherwise.
9617 * Key grabs allow one or more objects to receive key events for
9618 * specific key strokes even if other objects have focus. Whenever a
9619 * key is grabbed, only the objects grabbing it will get the events
9620 * for the given keys.
9622 * @p keyname is a platform dependent symbolic name for the key
9623 * pressed (see @ref Evas_Keys for more information).
9625 * @p modifiers and @p not_modifiers are bit masks of all the
9626 * modifiers that must and mustn't, respectively, be pressed along
9627 * with @p keyname key in order to trigger this new key
9628 * grab. Modifiers can be things such as Shift and Ctrl as well as
9629 * user defigned types via evas_key_modifier_add(). Retrieve them with
9630 * evas_key_modifier_mask_get() or use @c 0 for empty masks.
9632 * @p exclusive will make the given object the only one permitted to
9633 * grab the given key. If given @c EINA_TRUE, subsequent calls on this
9634 * function with different @p obj arguments will fail, unless the key
9635 * is ungrabbed again.
9637 * Example code follows.
9638 * @dontinclude evas-events.c
9639 * @skip if (d.focus)
9642 * See the full example @ref Example_Evas_Events "here".
9644 * @see evas_object_key_ungrab
9645 * @see evas_object_focus_set
9646 * @see evas_object_focus_get
9647 * @see evas_focus_get
9648 * @see evas_key_modifier_add
9650 EAPI 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);
9653 * Removes the grab on @p keyname key events by @p obj.
9655 * @param obj the object that has an existing key grab.
9656 * @param keyname the key the grab is set for.
9657 * @param modifiers a mask of modifiers that must be present to
9658 * trigger the event.
9659 * @param not_modifiers a mask of modifiers that must not not be
9660 * present to trigger the event.
9662 * Removes a key grab on @p obj if @p keyname, @p modifiers, and @p
9663 * not_modifiers match.
9665 * Example code follows.
9666 * @dontinclude evas-events.c
9667 * @skip got here by key grabs
9670 * See the full example @ref Example_Evas_Events "here".
9672 * @see evas_object_key_grab
9673 * @see evas_object_focus_set
9674 * @see evas_object_focus_get
9675 * @see evas_focus_get
9677 EAPI 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);