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@@naver.com>
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 used with object or canvas.
350 * @see evas_object_event_callback_add()
351 * @see evas_event_callback_add()
353 typedef enum _Evas_Callback_Type
356 * The following events are only for use with objects
357 * evas_object_event_callback_add():
359 EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */
360 EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
361 EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
362 EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
363 EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
364 EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
365 EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
366 EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
367 EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
368 EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
369 EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
370 EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
371 EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
372 EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
373 EVAS_CALLBACK_SHOW, /**< Show Event */
374 EVAS_CALLBACK_HIDE, /**< Hide Event */
375 EVAS_CALLBACK_MOVE, /**< Move Event */
376 EVAS_CALLBACK_RESIZE, /**< Resize Event */
377 EVAS_CALLBACK_RESTACK, /**< Restack Event */
378 EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
379 EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
380 EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
381 EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image as been preloaded */
384 * The following events are only for use with canvas
385 * evas_event_callback_add():
387 EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
388 EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
389 EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */
390 EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
391 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
392 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
395 * More object event types - see evas_object_event_callback_add():
397 EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanims in evas that throws out original image data) */
399 /* the following id no event number, but a sentinel: */
400 EVAS_CALLBACK_LAST /**< keep as last element/sentinel -- not really an event */
401 } Evas_Callback_Type; /**< The type of event to trigger the 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,
558 EVAS_ASPECT_CONTROL_NEITHER = 1,
559 EVAS_ASPECT_CONTROL_HORIZONTAL = 2,
560 EVAS_ASPECT_CONTROL_VERTICAL = 3,
561 EVAS_ASPECT_CONTROL_BOTH = 4
562 } Evas_Aspect_Control;
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 mouse pointer should be handled by Evas.
911 * If #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse is down an
912 * object, then moves outside of it, the pointer still behaves as
913 * being bound to the object, albeit out of its drawing region. On
914 * mouse up, the event will be feed to the object, that may check if
915 * the final position is over or not and do something about it.
917 * @ingroup Evas_Object_Group_Extras
919 typedef enum _Evas_Object_Pointer_Mode
921 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
922 EVAS_OBJECT_POINTER_MODE_NOGRAB
923 } Evas_Object_Pointer_Mode; /**< How mouse pointer should be handled by Evas. */
925 typedef void (*Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info);
926 typedef void (*Evas_Event_Cb) (void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
927 typedef Eina_Bool (*Evas_Object_Event_Post_Cb) (void *data, Evas *e);
928 typedef void (*Evas_Object_Event_Cb) (void *data, Evas *e, Evas_Object *obj, void *event_info);
929 typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
932 * @defgroup Evas_Group Top Level Functions
934 * Functions that affect Evas as a whole.
940 * @return The init counter value.
942 * This function initializes Evas and increments a counter of the
943 * number of calls to it. It returs the new counter's value.
945 * @see evas_shutdown().
947 * Most EFL users wouldn't be using this function directly, because
948 * they wouldn't access Evas directly by themselves. Instead, they
949 * would be using higher level helpers, like @c ecore_evas_init().
950 * See http://docs.enlightenment.org/auto/ecore/.
952 * You should be using this if your use is something like the
953 * following. The buffer engine is just one of the many ones Evas
956 * @dontinclude evas-buffer-simple.c
959 * And being the canvas creation something like:
960 * @skip static Evas *create_canvas
961 * @until evas_output_viewport_set(canvas,
963 * Note that this is code creating an Evas canvas with no usage of
964 * Ecore helpers at all -- no linkage with Ecore on this scenario,
965 * thus. Again, this wouldn't be on Evas common usage for most
966 * developers. See the full @ref Example_Evas_Buffer_Simple "example".
968 * @ingroup Evas_Group
970 EAPI int evas_init (void);
975 * @return Evas' init counter value.
977 * This function finalizes Evas, decrementing the counter of the
978 * number of calls to the function evas_init(). This new value for the
979 * counter is returned.
983 * If you were the sole user of Evas, by means of evas_init(), you can
984 * check if it's being properly shut down by expecting a return value
987 * Example code follows.
988 * @dontinclude evas-buffer-simple.c
989 * @skip // NOTE: use ecore_evas_buffer_new
990 * @until evas_shutdown
991 * Where that function would contain:
992 * @skip evas_free(canvas)
993 * @until evas_free(canvas)
995 * Most users would be using ecore_evas_shutdown() instead, like told
996 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
999 * @ingroup Evas_Group
1001 EAPI int evas_shutdown (void);
1005 * Return if any allocation errors have occurred during the prior function
1006 * @return The allocation error flag
1008 * This function will return if any memory allocation errors occurred during,
1009 * and what kind they were. The return value will be one of
1010 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
1011 * with each meaning something different.
1013 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
1014 * worked as expected.
1016 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
1017 * its job and will have exited as cleanly as possible. The programmer
1018 * should consider this as a sign of very low memory and should try and safely
1019 * recover from the prior functions failure (or try free up memory elsewhere
1020 * and try again after more memory is freed).
1022 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
1023 * recovered from by evas finding memory of its own it has allocated and
1024 * freeing what it sees as not really usefully allocated memory. What is freed
1025 * may vary. Evas may reduce the resolution of images, free cached images or
1026 * fonts, trhow out pre-rendered data, reduce the complexity of change lists
1027 * etc. Evas and the program will function as per normal after this, but this
1028 * is a sign of low memory, and it is suggested that the program try and
1029 * identify memory it doesn't need, and free it.
1033 * extern Evas_Object *object;
1034 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
1036 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
1037 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
1039 * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
1040 * fprintf(stderr, " destroy object now as it cannot be used.\n");
1041 * evas_object_del(object);
1043 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1044 * my_memory_cleanup();
1046 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
1048 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1049 * my_memory_cleanup();
1053 * @ingroup Evas_Group
1055 EAPI Evas_Alloc_Error evas_alloc_error (void);
1059 * @brief Get evas' internal asynchronous events read file descriptor.
1061 * @return The canvas' asynchronous events read file descriptor.
1063 * Evas' asynchronous events are meant to be dealt with internally,
1064 * i. e., when building stuff to be glued together into the EFL
1065 * infrastructure -- a module, for example. The context which demands
1066 * its use is when calculations need to be done out of the main
1067 * thread, asynchronously, and some action must be performed after
1070 * An example of actual use of this API is for image asynchronous
1071 * preload inside evas. If the canvas was instantiated through
1072 * ecore-evas usage, ecore itself will take care of calling those
1073 * events' processing.
1075 * This function returns the read file descriptor where to get the
1076 * asynchronous events of the canvas. Naturally, other mainloops,
1077 * apart from ecore, may make use of it.
1079 * @ingroup Evas_Group
1081 EAPI int evas_async_events_fd_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE;
1084 * @brief Trigger the processing of all events waiting on the file
1085 * descriptor returned by evas_async_events_fd_get().
1087 * @return The number of events processed.
1089 * All asynchronous events queued up by evas_async_events_put() are
1090 * processed here. More precisely, the callback functions, informed
1091 * together with other event parameters, when queued, get called (with
1092 * those parameters), in that order.
1094 * @ingroup Evas_Group
1096 EAPI int evas_async_events_process (void);
1099 * Insert asynchronous events on the canvas.
1101 * @param target The target to be affected by the events.
1102 * @param type The type of callback function.
1103 * @param event_info Information about the event.
1104 * @param func The callback function pointer.
1106 * This is the way, for a routine running outside evas' main thread,
1107 * to report an asynchronous event. A callback function is informed,
1108 * whose call is to happen after evas_async_events_process() is
1111 * @ingroup Evas_Group
1113 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);
1116 * @defgroup Evas_Canvas Canvas Functions
1118 * Low level Evas canvas functions. Sub groups will present more high
1119 * level ones, though.
1121 * Most of these functions deal with low level Evas actions, like:
1122 * @li create/destroy raw canvases, not bound to any displaying engine
1123 * @li tell a canvas i got focused (in a windowing context, for example)
1124 * @li tell a canvas a region should not be calculated anymore in rendering
1125 * @li tell a canvas to render its contents, immediately
1127 * Most users will be using Evas by means of the @c Ecore_Evas
1128 * wrapper, which deals with all the above mentioned issues
1129 * automatically for them. Thus, you'll be looking at this section
1130 * only if you're building low level stuff.
1132 * The groups within present you functions that deal with the canvas
1133 * directly, too, and not yet with its @b objects. They are the
1134 * functions you need to use at a minimum to get a working canvas.
1138 * Creates a new empty evas.
1140 * Note that before you can use the evas, you will to at a minimum:
1141 * @li Set its render method with @ref evas_output_method_set .
1142 * @li Set its viewport size with @ref evas_output_viewport_set .
1143 * @li Set its size of the canvas with @ref evas_output_size_set .
1144 * @li Ensure that the render engine is given the correct settings
1145 * with @ref evas_engine_info_set .
1147 * This function should only fail if the memory allocation fails
1149 * @note this function is very low level. Instead of using it
1150 * directly, consider using the high level functions in
1151 * Ecore_Evas such as @c ecore_evas_new(). See
1152 * http://docs.enlightenment.org/auto/ecore/.
1154 * @attention it is recommended that one calls evas_init() before
1155 * creating new canvas.
1157 * @return A new uninitialised Evas canvas on success. Otherwise, @c
1159 * @ingroup Evas_Canvas
1161 EAPI Evas *evas_new (void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
1164 * Frees the given evas and any objects created on it.
1166 * Any objects with 'free' callbacks will have those callbacks called
1169 * @param e The given evas.
1171 * @ingroup Evas_Canvas
1173 EAPI void evas_free (Evas *e) EINA_ARG_NONNULL(1);
1177 * Inform to the evas that it got the focus.
1179 * @param e The evas to change information.
1180 * @ingroup Evas_Canvas
1182 EAPI void evas_focus_in (Evas *e);
1185 * Inform to the evas that it lost the focus.
1187 * @param e The evas to change information.
1188 * @ingroup Evas_Canvas
1190 EAPI void evas_focus_out (Evas *e);
1193 * Get the focus state known by the given evas
1195 * @param e The evas to query information.
1196 * @ingroup Evas_Canvas
1198 EAPI Eina_Bool evas_focus_state_get (const Evas *e) EINA_PURE;
1201 * Push the nochange flag up 1
1203 * This tells evas, that while the nochange flag is greater than 0, do not
1204 * mark objects as "changed" when making changes.
1206 * @param e The evas to change information.
1207 * @ingroup Evas_Canvas
1209 EAPI void evas_nochange_push (Evas *e);
1212 * Pop the nochange flag down 1
1214 * This tells evas, that while the nochange flag is greater than 0, do not
1215 * mark objects as "changed" when making changes.
1217 * @param e The evas to change information.
1218 * @ingroup Evas_Canvas
1220 EAPI void evas_nochange_pop (Evas *e);
1224 * Attaches a specific pointer to the evas for fetching later
1226 * @param e The canvas to attach the pointer to
1227 * @param data The pointer to attach
1228 * @ingroup Evas_Canvas
1230 EAPI void evas_data_attach_set (Evas *e, void *data) EINA_ARG_NONNULL(1);
1233 * Returns the pointer attached by evas_data_attach_set()
1235 * @param e The canvas to attach the pointer to
1236 * @return The pointer attached
1237 * @ingroup Evas_Canvas
1239 EAPI void *evas_data_attach_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1243 * Add a damage rectangle.
1245 * @param e The given canvas pointer.
1246 * @param x The rectangle's left position.
1247 * @param y The rectangle's top position.
1248 * @param w The rectangle's width.
1249 * @param h The rectangle's height.
1251 * This is the function by which one tells evas that a part of the
1252 * canvas has to be repainted.
1254 * @ingroup Evas_Canvas
1256 EAPI void evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1259 * Add an "obscured region" to an Evas canvas.
1261 * @param e The given canvas pointer.
1262 * @param x The rectangle's top left corner's horizontal coordinate.
1263 * @param y The rectangle's top left corner's vertical coordinate
1264 * @param w The rectangle's width.
1265 * @param h The rectangle's height.
1267 * This is the function by which one tells an Evas canvas that a part
1268 * of it <b>must not</b> be repainted. The region must be
1269 * rectangular and its coordinates inside the canvas viewport are
1270 * passed in the call. After this call, the region specified won't
1271 * participate in any form in Evas' calculations and actions during
1272 * its rendering updates, having its displaying content frozen as it
1273 * was just after this function took place.
1275 * We call it "obscured region" because the most common use case for
1276 * this rendering (partial) freeze is something else (most problaby
1277 * other canvas) being on top of the specified rectangular region,
1278 * thus shading it completely from the user's final scene in a
1279 * display. To avoid unecessary processing, one should indicate to the
1280 * obscured canvas not to bother about the non-important area.
1282 * The majority of users won't have to worry about this funcion, as
1283 * they'll be using just one canvas in their applications, with
1284 * nothing inset or on top of it in any form.
1286 * To make this region one that @b has to be repainted again, call the
1287 * function evas_obscured_clear().
1289 * @note This is a <b>very low level function</b>, which most of
1290 * Evas' users wouldn't care about.
1292 * @note This function does @b not flag the canvas as having its state
1293 * changed. If you want to re-render it afterwards expecting new
1294 * contents, you have to add "damage" regions yourself (see
1295 * evas_damage_rectangle_add()).
1297 * @see evas_obscured_clear()
1298 * @see evas_render_updates()
1300 * Example code follows.
1301 * @dontinclude evas-events.c
1302 * @skip add an obscured
1303 * @until evas_obscured_clear(evas);
1305 * In that example, pressing the "Ctrl" and "o" keys will impose or
1306 * remove an obscured region in the middle of the canvas. You'll get
1307 * the same contents at the time the key was pressed, if toggling it
1308 * on, until you toggle it off again (make sure the animation is
1309 * running on to get the idea better). See the full @ref
1310 * Example_Evas_Events "example".
1312 * @ingroup Evas_Canvas
1314 EAPI void evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1317 * Remove all "obscured regions" from an Evas canvas.
1319 * @param e The given canvas pointer.
1321 * This function removes all the rectangles from the obscured regions
1322 * list of the canvas @p e. It takes obscured areas added with
1323 * evas_obscured_rectangle_add() and make them again a regions that @b
1324 * have to be repainted on rendering updates.
1326 * @note This is a <b>very low level function</b>, which most of
1327 * Evas' users wouldn't care about.
1329 * @note This function does @b not flag the canvas as having its state
1330 * changed. If you want to re-render it afterwards expecting new
1331 * contents, you have to add "damage" regions yourself (see
1332 * evas_damage_rectangle_add()).
1334 * @see evas_obscured_rectangle_add() for an example
1335 * @see evas_render_updates()
1337 * @ingroup Evas_Canvas
1339 EAPI void evas_obscured_clear (Evas *e) EINA_ARG_NONNULL(1);
1342 * Force immediate renderization of the given Evas canvas.
1344 * @param e The given canvas pointer.
1345 * @return A newly allocated list of updated rectangles of the canvas
1346 * (@c Eina_Rectangle structs). Free this list with
1347 * evas_render_updates_free().
1349 * This function forces an immediate renderization update of the given
1352 * @note This is a <b>very low level function</b>, which most of
1353 * Evas' users wouldn't care about. One would use it, for example, to
1354 * grab an Evas' canvas update regions and paint them back, using the
1355 * canvas' pixmap, on a displaying system working below Evas.
1357 * @note Evas is a stateful canvas. If no operations changing its
1358 * state took place since the last rendering action, you won't see no
1359 * changes and this call will be a no-op.
1361 * Example code follows.
1362 * @dontinclude evas-events.c
1363 * @skip add an obscured
1364 * @until d.obscured = !d.obscured;
1366 * See the full @ref Example_Evas_Events "example".
1368 * @ingroup Evas_Canvas
1370 EAPI Eina_List *evas_render_updates (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1373 * Free the rectangles returned by evas_render_updates().
1375 * @param updates The list of updated rectangles of the canvas.
1377 * This function removes the region from the render updates list. It
1378 * makes the region doesn't be render updated anymore.
1380 * @see evas_render_updates() for an example
1382 * @ingroup Evas_Canvas
1384 EAPI void evas_render_updates_free (Eina_List *updates);
1387 * Force renderization of the given canvas.
1389 * @param e The given canvas pointer.
1391 * @ingroup Evas_Canvas
1393 EAPI void evas_render (Evas *e) EINA_ARG_NONNULL(1);
1396 * Update the canvas internal objects but not triggering immediate
1399 * @param e The given canvas pointer.
1401 * This function updates the canvas internal objects not triggering
1402 * renderization. To force renderization function evas_render() should
1407 * @ingroup Evas_Canvas
1409 EAPI void evas_norender (Evas *e) EINA_ARG_NONNULL(1);
1412 * Make the canvas discard internally cached data used for rendering.
1414 * @param e The given canvas pointer.
1416 * This function flushes the arrays of delete, active and render objects.
1417 * Other things it may also discard are: shared memory segments,
1418 * temporary scratch buffers, cached data to avoid re-compute of that data etc.
1420 * @ingroup Evas_Canvas
1422 EAPI void evas_render_idle_flush (Evas *e) EINA_ARG_NONNULL(1);
1425 * Make the canvas discard as much data as possible used by the engine at
1428 * @param e The given canvas pointer.
1430 * This function will unload images, delete textures and much more, where
1431 * possible. You may also want to call evas_render_idle_flush() immediately
1432 * prior to this to perhaps discard a little more, though evas_render_dump()
1433 * should implicitly delete most of what evas_render_idle_flush() might
1436 * @ingroup Evas_Canvas
1438 EAPI void evas_render_dump (Evas *e) EINA_ARG_NONNULL(1);
1441 * @defgroup Evas_Output_Method Render Engine Functions
1443 * Functions that are used to set the render engine for a given
1444 * function, and then get that engine working.
1446 * The following code snippet shows how they can be used to
1447 * initialise an evas that uses the X11 software engine:
1450 * Evas_Engine_Info_Software_X11 *einfo;
1451 * extern Display *display;
1452 * extern Window win;
1456 * evas = evas_new();
1457 * evas_output_method_set(evas, evas_render_method_lookup("software_x11"));
1458 * evas_output_size_set(evas, 640, 480);
1459 * evas_output_viewport_set(evas, 0, 0, 640, 480);
1460 * einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas);
1461 * einfo->info.display = display;
1462 * einfo->info.visual = DefaultVisual(display, DefaultScreen(display));
1463 * einfo->info.colormap = DefaultColormap(display, DefaultScreen(display));
1464 * einfo->info.drawable = win;
1465 * einfo->info.depth = DefaultDepth(display, DefaultScreen(display));
1466 * evas_engine_info_set(evas, (Evas_Engine_Info *)einfo);
1469 * @ingroup Evas_Canvas
1473 * Look up a numeric ID from a string name of a rendering engine.
1475 * @param name The string name of an engine
1476 * @return A numeric (opaque) ID for the rendering engine
1477 * @ingroup Evas_Output_Method
1479 * This function looks up a numeric return value for the named engine
1480 * in the string @p name. This is a normal C string, NUL byte
1481 * terminated. The name is case sensitive. If the rendering engine is
1482 * available, a numeric ID for that engine is returned that is not
1483 * 0. If the engine is not available, 0 is returned, indicating an
1486 * The programmer should NEVER rely on the numeric ID of an engine
1487 * unless it is returned by this function. Programs should NOT be
1488 * written accessing render method ID's directly, without first
1489 * obtaining it from this function.
1491 * @attention it is mandatory that one calls evas_init() before
1492 * looking up the render method.
1501 * evas = evas_new();
1504 * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
1507 * engine_id = evas_render_method_lookup("software_x11");
1510 * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
1513 * evas_output_method_set(evas, engine_id);
1516 EAPI int evas_render_method_lookup (const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1519 * List all the rendering engines compiled into the copy of the Evas library
1521 * @return A linked list whose data members are C strings of engine names
1522 * @ingroup Evas_Output_Method
1524 * Calling this will return a handle (pointer) to an Evas linked
1525 * list. Each node in the linked list will have the data pointer be a
1526 * (char *) pointer to the string name of the rendering engine
1527 * available. The strings should never be modified, neither should the
1528 * list be modified. This list should be cleaned up as soon as the
1529 * program no longer needs it using evas_render_method_list_free(). If
1530 * no engines are available from Evas, NULL will be returned.
1534 * Eina_List *engine_list, *l;
1535 * char *engine_name;
1537 * engine_list = evas_render_method_list();
1540 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1543 * printf("Available Evas Engines:\n");
1544 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1545 * printf("%s\n", engine_name);
1546 * evas_render_method_list_free(engine_list);
1549 EAPI Eina_List *evas_render_method_list (void) EINA_WARN_UNUSED_RESULT;
1552 * This function should be called to free a list of engine names
1554 * @param list The Eina_List base pointer for the engine list to be freed
1555 * @ingroup Evas_Output_Method
1557 * When this function is called it will free the engine list passed in
1558 * as @p list. The list should only be a list of engines generated by
1559 * calling evas_render_method_list(). If @p list is NULL, nothing will
1564 * Eina_List *engine_list, *l;
1565 * char *engine_name;
1567 * engine_list = evas_render_method_list();
1570 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1573 * printf("Available Evas Engines:\n");
1574 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1575 * printf("%s\n", engine_name);
1576 * evas_render_method_list_free(engine_list);
1579 EAPI void evas_render_method_list_free (Eina_List *list);
1583 * Sets the output engine for the given evas.
1585 * Once the output engine for an evas is set, any attempt to change it
1586 * will be ignored. The value for @p render_method can be found using
1587 * @ref evas_render_method_lookup .
1589 * @param e The given evas.
1590 * @param render_method The numeric engine value to use.
1592 * @attention it is mandatory that one calls evas_init() before
1593 * setting the output method.
1595 * @ingroup Evas_Output_Method
1597 EAPI void evas_output_method_set (Evas *e, int render_method) EINA_ARG_NONNULL(1);
1600 * Retrieves the number of the output engine used for the given evas.
1601 * @param e The given evas.
1602 * @return The ID number of the output engine being used. @c 0 is
1603 * returned if there is an error.
1604 * @ingroup Evas_Output_Method
1606 EAPI int evas_output_method_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1610 * Retrieves the current render engine info struct from the given evas.
1612 * The returned structure is publicly modifiable. The contents are
1613 * valid until either @ref evas_engine_info_set or @ref evas_render
1616 * This structure does not need to be freed by the caller.
1618 * @param e The given evas.
1619 * @return A pointer to the Engine Info structure. @c NULL is returned if
1620 * an engine has not yet been assigned.
1621 * @ingroup Evas_Output_Method
1623 EAPI Evas_Engine_Info *evas_engine_info_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1626 * Applies the engine settings for the given evas from the given @c
1627 * Evas_Engine_Info structure.
1629 * To get the Evas_Engine_Info structure to use, call @ref
1630 * evas_engine_info_get . Do not try to obtain a pointer to an
1631 * @c Evas_Engine_Info structure in any other way.
1633 * You will need to call this function at least once before you can
1634 * create objects on an evas or render that evas. Some engines allow
1635 * their settings to be changed more than once.
1637 * Once called, the @p info pointer should be considered invalid.
1639 * @param e The pointer to the Evas Canvas
1640 * @param info The pointer to the Engine Info to use
1641 * @return 1 if no error occurred, 0 otherwise
1642 * @ingroup Evas_Output_Method
1644 EAPI Eina_Bool evas_engine_info_set (Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1);
1647 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1649 * Functions that set and retrieve the output and viewport size of an
1652 * @ingroup Evas_Canvas
1656 * Sets the output size of the render engine of the given evas.
1658 * The evas will render to a rectangle of the given size once this
1659 * function is called. The output size is independent of the viewport
1660 * size. The viewport will be stretched to fill the given rectangle.
1662 * The units used for @p w and @p h depend on the engine used by the
1665 * @param e The given evas.
1666 * @param w The width in output units, usually pixels.
1667 * @param h The height in output units, usually pixels.
1668 * @ingroup Evas_Output_Size
1670 EAPI void evas_output_size_set (Evas *e, int w, int h) EINA_ARG_NONNULL(1);
1673 * Retrieve the output size of the render engine of the given evas.
1675 * The output size is given in whatever the output units are for the
1678 * If either @p w or @p h is @c NULL, then it is ignored. If @p e is
1679 * invalid, the returned results are undefined.
1681 * @param e The given evas.
1682 * @param w The pointer to an integer to store the width in.
1683 * @param h The pointer to an integer to store the height in.
1684 * @ingroup Evas_Output_Size
1686 EAPI void evas_output_size_get (const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1);
1689 * Sets the output viewport of the given evas in evas units.
1691 * The output viewport is the area of the evas that will be visible to
1692 * the viewer. The viewport will be stretched to fit the output
1693 * target of the evas when rendering is performed.
1695 * @note The coordinate values do not have to map 1-to-1 with the output
1696 * target. However, it is generally advised that it is done for ease
1699 * @param e The given evas.
1700 * @param x The top-left corner x value of the viewport.
1701 * @param y The top-left corner y value of the viewport.
1702 * @param w The width of the viewport. Must be greater than 0.
1703 * @param h The height of the viewport. Must be greater than 0.
1704 * @ingroup Evas_Output_Size
1706 EAPI void evas_output_viewport_set (Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
1709 * Get the render engine's output viewport co-ordinates in canvas units.
1710 * @param e The pointer to the Evas Canvas
1711 * @param x The pointer to a x variable to be filled in
1712 * @param y The pointer to a y variable to be filled in
1713 * @param w The pointer to a width variable to be filled in
1714 * @param h The pointer to a height variable to be filled in
1715 * @ingroup Evas_Output_Size
1717 * Calling this function writes the current canvas output viewport
1718 * size and location values into the variables pointed to by @p x, @p
1719 * y, @p w and @p h. On success the variables have the output
1720 * location and size values written to them in canvas units. Any of @p
1721 * x, @p y, @p w or @p h that are NULL will not be written to. If @p e
1722 * is invalid, the results are undefined.
1726 * extern Evas *evas;
1727 * Evas_Coord x, y, width, height;
1729 * evas_output_viewport_get(evas, &x, &y, &w, &h);
1732 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);
1735 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1737 * Functions that are used to map coordinates from the canvas to the
1738 * screen or the screen to the canvas.
1740 * @ingroup Evas_Canvas
1744 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1746 * @param e The pointer to the Evas Canvas
1747 * @param x The screen/output x co-ordinate
1748 * @return The screen co-ordinate translated to canvas unit co-ordinates
1749 * @ingroup Evas_Coord_Mapping_Group
1751 * This function takes in a horizontal co-ordinate as the @p x
1752 * parameter and converts it into canvas units, accounting for output
1753 * size, viewport size and location, returning it as the function
1754 * return value. If @p e is invalid, the results are undefined.
1758 * extern Evas *evas;
1759 * extern int screen_x;
1760 * Evas_Coord canvas_x;
1762 * canvas_x = evas_coord_screen_x_to_world(evas, screen_x);
1765 EAPI Evas_Coord evas_coord_screen_x_to_world (const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1768 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1770 * @param e The pointer to the Evas Canvas
1771 * @param y The screen/output y co-ordinate
1772 * @return The screen co-ordinate translated to canvas unit co-ordinates
1773 * @ingroup Evas_Coord_Mapping_Group
1775 * This function takes in a vertical co-ordinate as the @p y parameter
1776 * and converts it into canvas units, accounting for output size,
1777 * viewport size and location, returning it as the function return
1778 * value. If @p e is invalid, the results are undefined.
1782 * extern Evas *evas;
1783 * extern int screen_y;
1784 * Evas_Coord canvas_y;
1786 * canvas_y = evas_coord_screen_y_to_world(evas, screen_y);
1789 EAPI Evas_Coord evas_coord_screen_y_to_world (const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1792 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1794 * @param e The pointer to the Evas Canvas
1795 * @param x The canvas x co-ordinate
1796 * @return The output/screen co-ordinate translated to output co-ordinates
1797 * @ingroup Evas_Coord_Mapping_Group
1799 * This function takes in a horizontal co-ordinate as the @p x
1800 * parameter and converts it into output units, accounting for output
1801 * size, viewport size and location, returning it as the function
1802 * return value. If @p e is invalid, the results are undefined.
1806 * extern Evas *evas;
1808 * extern Evas_Coord canvas_x;
1810 * screen_x = evas_coord_world_x_to_screen(evas, canvas_x);
1813 EAPI int evas_coord_world_x_to_screen (const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1816 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1818 * @param e The pointer to the Evas Canvas
1819 * @param y The canvas y co-ordinate
1820 * @return The output/screen co-ordinate translated to output co-ordinates
1821 * @ingroup Evas_Coord_Mapping_Group
1823 * This function takes in a vertical co-ordinate as the @p x parameter
1824 * and converts it into output units, accounting for output size,
1825 * viewport size and location, returning it as the function return
1826 * value. If @p e is invalid, the results are undefined.
1830 * extern Evas *evas;
1832 * extern Evas_Coord canvas_y;
1834 * screen_y = evas_coord_world_y_to_screen(evas, canvas_y);
1837 EAPI int evas_coord_world_y_to_screen (const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1840 * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
1842 * Functions that deal with the status of the pointer (mouse cursor).
1844 * @ingroup Evas_Canvas
1848 * This function returns the current known pointer co-ordinates
1850 * @param e The pointer to the Evas Canvas
1851 * @param x The pointer to an integer to be filled in
1852 * @param y The pointer to an integer to be filled in
1853 * @ingroup Evas_Pointer_Group
1855 * This function returns the current known screen/output co-ordinates
1856 * of the mouse pointer and sets the contents of the integers pointed
1857 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
1858 * valid canvas the results of this function are undefined.
1862 * extern Evas *evas;
1863 * int mouse_x, mouse_y;
1865 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
1866 * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y);
1869 EAPI void evas_pointer_output_xy_get (const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1);
1872 * This function returns the current known pointer co-ordinates
1874 * @param e The pointer to the Evas Canvas
1875 * @param x The pointer to a Evas_Coord to be filled in
1876 * @param y The pointer to a Evas_Coord to be filled in
1877 * @ingroup Evas_Pointer_Group
1879 * This function returns the current known canvas unit co-ordinates of
1880 * the mouse pointer and sets the contents of the Evas_Coords pointed
1881 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
1882 * valid canvas the results of this function are undefined.
1886 * extern Evas *evas;
1887 * Evas_Coord mouse_x, mouse_y;
1889 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
1890 * printf("Mouse is at canvas position %f, %f\n", mouse_x, mouse_y);
1893 EAPI void evas_pointer_canvas_xy_get (const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
1896 * Returns a bitmask with the mouse buttons currently pressed, set to 1
1898 * @param e The pointer to the Evas Canvas
1899 * @return A bitmask of the currently depressed buttons on the cavas
1900 * @ingroup Evas_Pointer_Group
1902 * Calling this function will return a 32-bit integer with the
1903 * appropriate bits set to 1 that correspond to a mouse button being
1904 * depressed. This limits Evas to a mouse devices with a maximum of 32
1905 * buttons, but that is generally in excess of any host system's
1906 * pointing device abilities.
1908 * A canvas by default begins with no mouse buttons being pressed and
1909 * only calls to evas_event_feed_mouse_down(),
1910 * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and
1911 * evas_event_feed_mouse_up_data() will alter that.
1913 * The least significant bit corresponds to the first mouse button
1914 * (button 1) and the most significant bit corresponds to the last
1915 * mouse button (button 32).
1917 * If @p e is not a valid canvas, the return value is undefined.
1921 * extern Evas *evas;
1922 * int button_mask, i;
1924 * button_mask = evas_pointer_button_down_mask_get(evas);
1925 * printf("Buttons currently pressed:\n");
1926 * for (i = 0; i < 32; i++)
1928 * if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1);
1932 EAPI int evas_pointer_button_down_mask_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1935 * Returns whether the mouse pointer is logically inside the canvas
1937 * @param e The pointer to the Evas Canvas
1938 * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise
1939 * @ingroup Evas_Pointer_Group
1941 * When this function is called it will return a value of either 0 or
1942 * 1, depending on if evas_event_feed_mouse_in(),
1943 * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(),
1944 * evas_event_feed_mouse_out_data() have been called to feed in a
1945 * mouse enter event into the canvas.
1947 * A return value of 1 indicates the mouse is logically inside the
1948 * canvas, and 0 implies it is logically outside the canvas.
1950 * A canvas begins with the mouse being assumed outside (0).
1952 * If @p e is not a valid canvas, the return value is undefined.
1956 * extern Evas *evas;
1958 * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n");
1959 * else printf("Mouse is out!\n");
1962 EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1963 EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1);
1966 * @defgroup Evas_Canvas_Events Canvas Events
1968 * Functions relating to canvas events, be they input (mice,
1969 * keyboards, etc) or output ones (internal states changing, etc).
1971 * @ingroup Evas_Canvas
1975 * @addtogroup Evas_Canvas_Events
1980 * Add (register) a callback function to a given canvas event.
1982 * @param e Canvas to attach a callback to
1983 * @param type The type of event that will trigger the callback
1984 * @param func The (callback) function to be called when the event is
1986 * @param data The data pointer to be passed to @p func
1988 * This function adds a function callback to the canvas @p e when the
1989 * event of type @p type occurs on it. The function pointer is @p
1992 * In the event of a memory allocation error during the addition of
1993 * the callback to the canvas, evas_alloc_error() should be used to
1994 * determine the nature of the error, if any, and the program should
1995 * sensibly try and recover.
1997 * A callback function must have the ::Evas_Event_Cb prototype
1998 * definition. The first parameter (@p data) in this definition will
1999 * have the same value passed to evas_event_callback_add() as the @p
2000 * data parameter, at runtime. The second parameter @p e is the canvas
2001 * pointer on which the event occurred. The third parameter @p
2002 * event_info is a pointer to a data structure that may or may not be
2003 * passed to the callback, depending on the event type that triggered
2004 * the callback. This is so because some events don't carry extra
2005 * context with them, but others do.
2007 * The event type @p type to trigger the function may be one of
2008 * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST,
2009 * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT,
2010 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and
2011 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of
2012 * event that will trigger the callback to be called. Only the last
2013 * two of the event types listed here provide useful event information
2014 * data -- a pointer to the recently focused Evas object. For the
2015 * others the @p event_info pointer is going to be @c NULL.
2018 * @dontinclude evas-events.c
2019 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE
2020 * @until two canvas event callbacks
2022 * Looking to the callbacks registered above,
2023 * @dontinclude evas-events.c
2024 * @skip called when our rectangle gets focus
2025 * @until let's have our events back
2027 * we see that the canvas flushes its rendering pipeline
2028 * (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb
2029 * routine takes place: it has to redraw that image at a different
2030 * size. Also, the callback on an object being focused comes just
2031 * after we focus it explicitly, on code.
2033 * See the full @ref Example_Evas_Events "example".
2035 * @note Be careful not to add the same callback multiple times, if
2036 * that's not what you want, because Evas won't check if a callback
2037 * existed before exactly as the one being registered (and thus, call
2038 * it more than once on the event, in this case). This would make
2039 * sense if you passed different functions and/or callback data, only.
2041 EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2044 * Delete a callback function from the canvas.
2046 * @param e Canvas to remove a callback from
2047 * @param type The type of event that was triggering the callback
2048 * @param func The function that was to be called when the event was triggered
2049 * @return The data pointer that was to be passed to the callback
2051 * This function removes the most recently added callback from the
2052 * canvas @p e which was triggered by the event type @p type and was
2053 * calling the function @p func when triggered. If the removal is
2054 * successful it will also return the data pointer that was passed to
2055 * evas_event_callback_add() when the callback was added to the
2056 * canvas. If not successful NULL will be returned.
2062 * void focus_in_callback(void *data, Evas *e, void *event_info);
2064 * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
2067 EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
2070 * Delete (unregister) a callback function registered to a given
2073 * @param e Canvas to remove an event callback from
2074 * @param type The type of event that was triggering the callback
2075 * @param func The function that was to be called when the event was
2077 * @param data The data pointer that was to be passed to the callback
2078 * @return The data pointer that was to be passed to the callback
2080 * This function removes <b>the first</b> added callback from the
2081 * canvas @p e matching the event type @p type, the registered
2082 * function pointer @p func and the callback data pointer @p data. If
2083 * the removal is successful it will also return the data pointer that
2084 * was passed to evas_event_callback_add() (that will be the same as
2085 * the parameter) when the callback(s) was(were) added to the
2086 * canvas. If not successful @c NULL will be returned. A common use
2087 * would be to remove an exact match of a callback.
2090 * @dontinclude evas-events.c
2091 * @skip evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
2092 * @until _object_focus_in_cb, NULL);
2094 * See the full @ref Example_Evas_Events "example".
2096 * @note For deletion of canvas events callbacks filtering by just
2097 * type and function pointer, user evas_event_callback_del().
2099 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);
2102 * Push a callback on the post-event callback stack
2104 * @param e Canvas to push the callback on
2105 * @param func The function that to be called when the stack is unwound
2106 * @param data The data pointer to be passed to the callback
2108 * Evas has a stack of callbacks that get called after all the callbacks for
2109 * an event have triggered (all the objects it triggers on and al the callbacks
2110 * in each object triggered). When all these have been called, the stack is
2111 * unwond from most recently to least recently pushed item and removed from the
2112 * stack calling the callback set for it.
2114 * This is intended for doing reverse logic-like processing, example - when a
2115 * child object that happens to get the event later is meant to be able to
2116 * "steal" functions from a parent and thus on unwind of this stack hav its
2117 * function called first, thus being able to set flags, or return 0 from the
2118 * post-callback that stops all other post-callbacks in the current stack from
2119 * being called (thus basically allowing a child to take control, if the event
2120 * callback prepares information ready for taking action, but the post callback
2121 * actually does the action).
2124 EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2127 * Remove a callback from the post-event callback stack
2129 * @param e Canvas to push the callback on
2130 * @param func The function that to be called when the stack is unwound
2132 * This removes a callback from the stack added with
2133 * evas_post_event_callback_push(). The first instance of the function in
2134 * the callback stack is removed from being executed when the stack is
2135 * unwound. Further instances may still be run on unwind.
2137 EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func);
2140 * Remove a callback from the post-event callback stack
2142 * @param e Canvas to push the callback on
2143 * @param func The function that to be called when the stack is unwound
2144 * @param data The data pointer to be passed to the callback
2146 * This removes a callback from the stack added with
2147 * evas_post_event_callback_push(). The first instance of the function and data
2148 * in the callback stack is removed from being executed when the stack is
2149 * unwound. Further instances may still be run on unwind.
2151 EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2154 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
2156 * Functions that deal with the freezing of input event processing of
2159 * There might be scenarios during a graphical user interface
2160 * program's use when the developer whishes the users wouldn't be able
2161 * to deliver input events to this application. It may, for example,
2162 * be the time for it to populate a view or to change some
2163 * layout. Assuming proper behavior with user interaction during this
2164 * exact time would be hard, as things are in a changing state. The
2165 * programmer can then tell the canvas to ignore input events,
2166 * bringing it back to normal behavior when he/she wants.
2168 * @ingroup Evas_Canvas_Events
2172 * @addtogroup Evas_Event_Freezing_Group
2177 * Freeze all input events processing.
2179 * @param e The canvas to freeze input events processing on.
2181 * This function will indicate to Evas that the canvas @p e is to have
2182 * all input event processing frozen until a matching
2183 * evas_event_thaw() function is called on the same canvas. All events
2184 * of this kind during the freeze will get @b discarded. Every freeze
2185 * call must be matched by a thaw call in order to completely thaw out
2186 * a canvas (i.e. these calls may be nested). The most common use is
2187 * when you don't want the user to interect with your user interface
2188 * when you're populating a view or changing the layout.
2191 * @dontinclude evas-events.c
2192 * @skip freeze input for 3 seconds
2194 * @dontinclude evas-events.c
2195 * @skip let's have our events back
2198 * See the full @ref Example_Evas_Events "example".
2200 * If you run that example, you'll see the canvas ignoring all input
2201 * events for 3 seconds, when the "f" key is pressed. In a more
2202 * realistic code we would be freezing while a toolkit or Edje was
2203 * doing some UI changes, thawing it back afterwards.
2205 EAPI void evas_event_freeze (Evas *e) EINA_ARG_NONNULL(1);
2208 * Thaw a canvas out after freezing (for input events).
2210 * @param e The canvas to thaw out.
2212 * This will thaw out a canvas after a matching evas_event_freeze()
2213 * call. If this call completely thaws out a canvas, i.e., there's no
2214 * other unbalanced call to evas_event_freeze(), events will start to
2215 * be processed again, but any "missed" events will @b not be
2218 * See evas_event_freeze() for an example.
2220 EAPI void evas_event_thaw (Evas *e) EINA_ARG_NONNULL(1);
2223 * Return the freeze count on input events of a given canvas.
2225 * @param e The canvas to fetch the freeze count from.
2227 * This returns the number of times the canvas has been told to freeze
2228 * input events. It is possible to call evas_event_freeze() multiple
2229 * times, and these must be matched by evas_event_thaw() calls. This
2230 * call allows the program to discover just how many times things have
2231 * been frozen in case it may want to break out of a deep freeze state
2232 * where the count is high.
2236 * extern Evas *evas;
2238 * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
2242 EAPI int evas_event_freeze_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2245 * After thaw of a canvas, re-evaluate the state of objects and call callbacks
2247 * @param e The canvas to evaluate after a thaw
2249 * This is normally called after evas_event_thaw() to re-evaluate mouse
2250 * containment and other states and thus also call callbacks for mouse in and
2251 * out on new objects if the state change demands it.
2253 EAPI void evas_event_thaw_eval (Evas *e) EINA_ARG_NONNULL(1);
2260 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
2262 * Functions to tell Evas that input events happened and should be
2265 * As explained in @ref intro_not_evas, Evas does not know how to poll
2266 * for input events, so the developer should do it and then feed such
2267 * events to the canvas to be processed. This is only required if
2268 * operating Evas directly. Modules such as Ecore_Evas do that for
2271 * @ingroup Evas_Canvas_Events
2275 * @addtogroup Evas_Event_Feeding_Group
2280 * Mouse down event feed.
2282 * @param e The given canvas pointer.
2283 * @param b The button number.
2284 * @param flags The evas button flags.
2285 * @param timestamp The timestamp of the mouse down event.
2286 * @param data The data for canvas.
2288 * This function will set some evas properties that is necessary when
2289 * the mouse button is pressed. It prepares information to be treated
2290 * by the callback function.
2293 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);
2296 * Mouse up event feed.
2298 * @param e The given canvas pointer.
2299 * @param b The button number.
2300 * @param flags evas button flags.
2301 * @param timestamp The timestamp of the mouse up event.
2302 * @param data The data for canvas.
2304 * This function will set some evas properties that is necessary when
2305 * the mouse button is released. It prepares information to be treated
2306 * by the callback function.
2309 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);
2312 * Mouse move event feed.
2314 * @param e The given canvas pointer.
2315 * @param x The horizontal position of the mouse pointer.
2316 * @param y The vertical position of the mouse pointer.
2317 * @param timestamp The timestamp of the mouse up event.
2318 * @param data The data for canvas.
2320 * This function will set some evas properties that is necessary when
2321 * the mouse is moved from its last position. It prepares information
2322 * to be treated by the callback function.
2325 EAPI void evas_event_feed_mouse_move (Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2328 * Mouse in event feed.
2330 * @param e The given canvas pointer.
2331 * @param timestamp The timestamp of the mouse up event.
2332 * @param data The data for canvas.
2334 * This function will set some evas properties that is necessary when
2335 * the mouse in event happens. It prepares information to be treated
2336 * by the callback function.
2339 EAPI void evas_event_feed_mouse_in (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2342 * Mouse out event feed.
2344 * @param e The given canvas pointer.
2345 * @param timestamp Timestamp of the mouse up event.
2346 * @param data The data for canvas.
2348 * This function will set some evas properties that is necessary when
2349 * the mouse out event happens. It prepares information to be treated
2350 * by the callback function.
2353 EAPI void evas_event_feed_mouse_out (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2354 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);
2355 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);
2356 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);
2359 * Mouse cancel event feed.
2361 * @param e The given canvas pointer.
2362 * @param timestamp The timestamp of the mouse up event.
2363 * @param data The data for canvas.
2365 * This function will call evas_event_feed_mouse_up() when a
2366 * mouse cancel event happens.
2369 EAPI void evas_event_feed_mouse_cancel (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2372 * Mouse wheel event feed.
2374 * @param e The given canvas pointer.
2375 * @param direction The wheel mouse direction.
2376 * @param z How much mouse wheel was scrolled up or down.
2377 * @param timestamp The timestamp of the mouse up event.
2378 * @param data The data for canvas.
2380 * This function will set some evas properties that is necessary when
2381 * the mouse wheel is scrolled up or down. It prepares information to
2382 * be treated by the callback function.
2385 EAPI void evas_event_feed_mouse_wheel (Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2388 * Key down event feed
2390 * @param e The canvas to thaw out
2391 * @param keyname Name of the key
2392 * @param key The key pressed.
2393 * @param string A String
2394 * @param compose The compose string
2395 * @param timestamp Timestamp of the mouse up event
2396 * @param data Data for canvas.
2398 * This function will set some evas properties that is necessary when
2399 * a key is pressed. It prepares information to be treated by the
2400 * callback function.
2403 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);
2408 * @param e The canvas to thaw out
2409 * @param keyname Name of the key
2410 * @param key The key released.
2411 * @param string string
2412 * @param compose compose
2413 * @param timestamp Timestamp of the mouse up event
2414 * @param data Data for canvas.
2416 * This function will set some evas properties that is necessary when
2417 * a key is released. It prepares information to be treated by the
2418 * callback function.
2421 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);
2426 * @param e The given canvas pointer.
2427 * @param hold The hold.
2428 * @param timestamp The timestamp of the mouse up event.
2429 * @param data The data for canvas.
2431 * This function makes the object to stop sending events.
2434 EAPI void evas_event_feed_hold (Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2445 * @defgroup Evas_Image_Group Image Functions
2447 * Functions that deals with images at canvas level.
2449 * @ingroup Evas_Canvas
2453 * Flush the image cache of the canvas.
2455 * @param e The given evas pointer.
2457 * This function flushes image cache of canvas.
2460 EAPI void evas_image_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2463 * Reload the image cache
2465 * @param e The given evas pointer.
2467 * This function reloads the image cache of canvas.
2470 EAPI void evas_image_cache_reload (Evas *e) EINA_ARG_NONNULL(1);
2473 * Set the image cache.
2475 * @param e The given evas pointer.
2476 * @param size The cache size.
2478 * This function sets the image cache of canvas.
2481 EAPI void evas_image_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2484 * Set the image cache
2486 * @param e The given evas pointer.
2488 * This function returns the image cache of canvas.
2491 EAPI int evas_image_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2494 * @defgroup Evas_Font_Group Font Functions
2496 * Functions that deals with fonts.
2498 * @ingroup Evas_Canvas
2502 * Changes the font hinting for the given evas.
2504 * @param e The given evas.
2505 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2506 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2507 * @ingroup Evas_Font_Group
2509 EAPI void evas_font_hinting_set (Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1);
2512 * Retrieves the font hinting used by the given evas.
2514 * @param e The given evas to query.
2515 * @return The hinting in use, one of #EVAS_FONT_HINTING_NONE,
2516 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2517 * @ingroup Evas_Font_Group
2519 EAPI Evas_Font_Hinting_Flags evas_font_hinting_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2522 * Checks if the font hinting is supported by the given evas.
2524 * @param e The given evas to query.
2525 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2526 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2527 * @return @c EINA_TRUE if it is supported, @c EINA_FALSE otherwise.
2528 * @ingroup Evas_Font_Group
2530 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;
2534 * Force the given evas and associated engine to flush its font cache.
2536 * @param e The given evas to flush font cache.
2537 * @ingroup Evas_Font_Group
2539 EAPI void evas_font_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2542 * Changes the size of font cache of the given evas.
2544 * @param e The given evas to flush font cache.
2545 * @param size The size, in bytes.
2547 * @ingroup Evas_Font_Group
2549 EAPI void evas_font_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2552 * Changes the size of font cache of the given evas.
2554 * @param e The given evas to flush font cache.
2555 * @return The size, in bytes.
2557 * @ingroup Evas_Font_Group
2559 EAPI int evas_font_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2563 * List of available font descriptions known or found by this evas.
2565 * The list depends on Evas compile time configuration, such as
2566 * fontconfig support, and the paths provided at runtime as explained
2567 * in @ref Evas_Font_Path_Group.
2569 * @param e The evas instance to query.
2570 * @return a newly allocated list of strings. Do not change the
2571 * strings. Be sure to call evas_font_available_list_free()
2572 * after you're done.
2574 * @ingroup Evas_Font_Group
2576 EAPI Eina_List *evas_font_available_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2579 * Free list of font descriptions returned by evas_font_dir_available_list().
2581 * @param e The evas instance that returned such list.
2582 * @param available the list returned by evas_font_dir_available_list().
2584 * @ingroup Evas_Font_Group
2586 EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1);
2589 * @defgroup Evas_Font_Path_Group Font Path Functions
2591 * Functions that edit the paths being used to load fonts.
2593 * @ingroup Evas_Font_Group
2597 * Removes all font paths loaded into memory for the given evas.
2598 * @param e The given evas.
2599 * @ingroup Evas_Font_Path_Group
2601 EAPI void evas_font_path_clear (Evas *e) EINA_ARG_NONNULL(1);
2604 * Appends a font path to the list of font paths used by the given evas.
2605 * @param e The given evas.
2606 * @param path The new font path.
2607 * @ingroup Evas_Font_Path_Group
2609 EAPI void evas_font_path_append (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2612 * Prepends a font path to the list of font paths used by the given evas.
2613 * @param e The given evas.
2614 * @param path The new font path.
2615 * @ingroup Evas_Font_Path_Group
2617 EAPI void evas_font_path_prepend (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2620 * Retrieves the list of font paths used by the given evas.
2621 * @param e The given evas.
2622 * @return The list of font paths used.
2623 * @ingroup Evas_Font_Path_Group
2625 EAPI const Eina_List *evas_font_path_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2628 * @defgroup Evas_Object_Group Generic Object Functions
2630 * Functions that manipulate generic Evas objects.
2632 * All Evas displaying units are Evas objects. One handles them all by
2633 * means of the handle ::Evas_Object. Besides Evas treats their
2634 * objects equally, they have @b types, which define their specific
2635 * behavior (and individual API).
2637 * Evas comes with a set of built-in object types:
2645 * These functions apply to @b any Evas object, whichever type thay
2648 * @note The built-in types which are most used are rectangles, text
2649 * and images. In fact, with these ones one can create 2D interfaces
2650 * of arbitrary complexity and EFL makes it easy.
2654 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
2656 * Methods that are broadly used, like those that change the color,
2657 * clippers and geometry of an Evas object.
2659 * @ingroup Evas_Object_Group
2663 * @addtogroup Evas_Object_Group_Basic
2668 * Clip one object to another.
2670 * @param obj The object to be clipped
2671 * @param clip The object to clip @p obj by
2673 * This function will clip the object @p obj to the area occupied by
2674 * the object @p clip. This means the object @p obj will only be
2675 * visible within the area occupied by the clipping object (@p clip).
2677 * The color of the object being clipped will be multiplied by the
2678 * color of the clipping one, so the resulting color for the former
2679 * will be <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color
2680 * element (red, green, blue and alpha).
2682 * Clipping is recursive, so clipping objects may be clipped by
2683 * others, and their color will in term be multiplied. You may @b not
2684 * set up circular clipping lists (i.e. object 1 clips object 2, which
2685 * clips object 1): the behavior of Evas is undefined in this case.
2687 * Objects which do not clip others are visible in the canvas as
2688 * normal; <b>those that clip one or more objects become invisible
2689 * themselves</b>, only affecting what they clip. If an object ceases
2690 * to have other objects being clipped by it, it will become visible
2693 * The visibility of an object affects the objects that are clipped by
2694 * it, so if the object clipping others is not shown (as in
2695 * evas_object_show()), the objects clipped by it will not be shown
2698 * If @p obj was being clipped by another object when this function is
2699 * called, it gets implicitly removed from the old clipper's domain
2700 * and is made now to be clipped by its new clipper.
2702 * @note At the moment the <b>only objects that can validly be used to
2703 * clip other objects are rectangle objects</b>. All other object
2704 * types are invalid and the result of using them is undefined. The
2705 * clip object @p clip must be a valid object, but can also be @c
2706 * NULL, in which case the effect of this function is the same as
2707 * calling evas_object_clip_unset() on the @p obj object.
2710 * @dontinclude evas-object-manipulation.c
2711 * @skip solid white clipper (note that it's the default color for a
2712 * @until evas_object_show(d.clipper);
2714 * See the full @ref Example_Evas_Object_Manipulation "example".
2716 EAPI void evas_object_clip_set (Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2);
2719 * Get the object clipping @p obj (if any).
2721 * @param obj The object to get the clipper from
2723 * This function returns the object clipping @p obj. If @p obj is
2724 * not being clipped at all, @c NULL is returned. The object @p obj
2725 * must be a valid ::Evas_Object.
2727 * See also evas_object_clip_set(), evas_object_clip_unset() and
2728 * evas_object_clipees_get().
2731 * @dontinclude evas-object-manipulation.c
2732 * @skip if (evas_object_clip_get(d.img) == d.clipper)
2735 * See the full @ref Example_Evas_Object_Manipulation "example".
2737 EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2740 * Disable/cease clipping on a clipped @p obj object.
2742 * @param obj The object to cease clipping on
2744 * This function disables clipping for the object @p obj, if it was
2745 * already clipped, i.e., its visibility and color get detached from
2746 * the previous clipper. If it wasn't, this has no effect. The object
2747 * @p obj must be a valid ::Evas_Object.
2749 * See also evas_object_clip_set() (for an example),
2750 * evas_object_clipees_get() and evas_object_clip_get().
2753 EAPI void evas_object_clip_unset (Evas_Object *obj);
2756 * Return a list of objects currently clipped by @p obj.
2758 * @param obj The object to get a list of clippees from
2759 * @return a list of objects being clipped by @p obj
2761 * This returns the internal list handle that contains all objects
2762 * clipped by the object @p obj. If none are clipped by it, the call
2763 * returns @c NULL. This list is only valid until the clip list is
2764 * changed and should be fetched again with another call to
2765 * evas_object_clipees_get() if any objects being clipped by this
2766 * object are unclipped, clipped by a new object, deleted or get the
2767 * clipper deleted. These operations will invalidate the list
2768 * returned, so it should not be used anymore after that point. Any
2769 * use of the list after this may have undefined results, possibly
2770 * leading to crashes. The object @p obj must be a valid
2773 * See also evas_object_clip_set(), evas_object_clip_unset() and
2774 * evas_object_clip_get().
2778 * extern Evas_Object *obj;
2779 * Evas_Object *clipper;
2781 * clipper = evas_object_clip_get(obj);
2784 * Eina_List *clippees, *l;
2785 * Evas_Object *obj_tmp;
2787 * clippees = evas_object_clipees_get(clipper);
2788 * printf("Clipper clips %i objects\n", eina_list_count(clippees));
2789 * EINA_LIST_FOREACH(clippees, l, obj_tmp)
2790 * evas_object_show(obj_tmp);
2794 EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2798 * Sets focus to the given object.
2800 * @param obj The object to be focused or unfocused.
2801 * @param focus set or remove focus to the object.
2803 * Changing focus only affects where key events go. There can be only
2804 * one object focused at any time. <p> If the parameter (@p focus) is
2805 * set, the passed object will be set as the currently focused object.
2806 * It will receive all keyboard events that are not exclusive key
2807 * grabs on other objects.
2809 * @see evas_object_focus_get
2810 * @see evas_focus_get
2811 * @see evas_object_key_grab
2812 * @see evas_object_key_ungrab
2814 EAPI void evas_object_focus_set (Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
2817 * Test if the object has focus.
2819 * @param obj The object to be tested.
2821 * If the passed object is the currently focused object 1 is returned,
2824 * @see evas_object_focus_set
2825 * @see evas_focus_get
2826 * @see evas_object_key_grab
2827 * @see evas_object_key_ungrab
2829 * @return 1 if the object has the focus, 0 otherwise.
2831 EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2835 * Sets the layer of the evas that the given object will be part of.
2837 * It is not possible to change the layer of a smart object's child.
2839 * @param obj The given Evas object.
2840 * @param l The number of the layer to place the object on.
2841 * Between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
2843 EAPI void evas_object_layer_set (Evas_Object *obj, short l) EINA_ARG_NONNULL(1);
2846 * Retrieves the layer of the evas that the given object is part of.
2848 * Be careful, it doesn't make sense to change the layer of smart object's
2849 * child. So the returned value could be wrong in some case. Don't rely on
2852 * @param obj The given Evas object.
2853 * @return Number of the layer.
2855 EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2859 * Sets the name of the given Evas object to the given name.
2861 * @param obj The given object.
2862 * @param name The given name.
2864 * There might be ocasions where one would like to name his/her
2868 * @dontinclude evas-events.c
2869 * @skip d.bg = evas_object_rectangle_add(d.canvas);
2870 * @until evas_object_name_set(d.bg, "our dear rectangle");
2872 * See the full @ref Example_Evas_Events "example".
2874 EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
2877 * Retrieves the name of the given Evas object.
2879 * @param obj The given object.
2880 * @return The name of the object or @c NULL, if no name has been given
2884 * @dontinclude evas-events.c
2885 * @skip fprintf(stdout, "An object got focused: %s\n",
2886 * @until evas_focus_get
2888 * See the full @ref Example_Evas_Events "example".
2890 EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2894 * Increments object reference count to defer its deletion.
2896 * @param obj The given Evas object to reference
2898 * This increments the reference count of an object, which if greater
2899 * than 0 will defer deletion by evas_object_del() until all
2900 * references are released back (counter back to 0). References cannot
2901 * go below 0 and unreferencing past that will result in the reference
2902 * count being limited to 0. References are limited to <c>2^32 - 1</c>
2903 * for an object. Referencing it more than this will result in it
2904 * being limited to this value.
2906 * @see evas_object_unref()
2907 * @see evas_object_del()
2909 * @note This is a <b>very simple<b> reference counting mechanism! For
2910 * instance, Evas is not ready to check for pending references on a
2911 * canvas deletion, or things like that. This is useful on scenarios
2912 * where, inside a code block, callbacks exist which would possibly
2913 * delete an object we are operating on afterwards. Then, one would
2914 * evas_object_ref() it on the beginning of the block and
2915 * evas_object_unref() it on the end. I would then be deleted at this
2916 * point, if it should be.
2920 * evas_object_ref(obj);
2923 * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
2924 * // more action here...
2925 * evas_object_unref(obj);
2928 * @ingroup Evas_Object_Group_Basic
2931 EAPI void evas_object_ref (Evas_Object *obj);
2934 * Decrements object reference count.
2936 * @param obj The given Evas object to unreference
2938 * This decrements the reference count of an object. If the object has
2939 * had evas_object_del() called on it while references were more than
2940 * 0, it will be deleted at the time this function is called and puts
2941 * the counter back to 0. See evas_object_ref() for more information.
2943 * @see evas_object_ref() (for an example)
2944 * @see evas_object_del()
2946 * @ingroup Evas_Object_Group_Basic
2949 EAPI void evas_object_unref (Evas_Object *obj);
2953 * Marks the given Evas object for deletion (when Evas will free its
2956 * @param obj The given Evas object.
2958 * This call will mark @p obj for deletion, which will take place
2959 * whenever it has no more references to it (see evas_object_ref() and
2960 * evas_object_unref()).
2962 * At actual deletion time, which may or may not be just after this
2963 * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks will
2964 * be called. If the object currently had the focus, its
2965 * ::EVAS_CALLBACK_FOCUS_OUT callback will also be called.
2967 * @see evas_object_ref()
2968 * @see evas_object_unref()
2970 * @ingroup Evas_Object_Group_Basic
2972 EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
2975 * Move the given Evas object to the given location inside its
2978 * @param obj The given Evas object.
2979 * @param x X position to move the object to, in canvas units.
2980 * @param y Y position to move the object to, in canvas units.
2982 * Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback
2985 * @note Naturally, newly created objects are placed at the canvas'
2986 * origin: <code>0, 0</code>.
2989 * @dontinclude evas-object-manipulation.c
2990 * @skip evas_object_image_border_set(d.clipper_border, 3, 3, 3, 3);
2991 * @until evas_object_show
2993 * See the full @ref Example_Evas_Object_Manipulation "example".
2995 * @ingroup Evas_Object_Group_Basic
2997 EAPI void evas_object_move (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
3000 * Changes the size of the given Evas object.
3002 * @param obj The given Evas object.
3003 * @param w The new width of the Evas object.
3004 * @param h The new height of the Evas object.
3006 * Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback
3009 * @note Newly created objects have zeroed dimensions. Then, you most
3010 * probably want to use evas_object_resize() on them after they are
3013 * @note Be aware that resizing an object changes its drawing area,
3014 * but that does imply the object is rescaled! For instance, images
3015 * are filled inside their drawing area using the specifications of
3016 * evas_object_image_fill_set(). Thus to scale the image to match
3017 * exactly your drawing area, you need to change the
3018 * evas_object_image_fill_set() as well.
3020 * @note This is more evident in images, but text, textblock, lines
3021 * and polygons will behave similarly. Check their specific APIs to
3022 * know how to achieve your desired behavior. Consider the following
3026 * // rescale image to fill exactly its area without tiling:
3027 * evas_object_resize(img, w, h);
3028 * evas_object_image_fill_set(img, 0, 0, w, h);
3031 * @ingroup Evas_Object_Group_Basic
3033 EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
3036 * Retrieves the position and (rectangular) size of the given Evas
3039 * @param obj The given Evas object.
3040 * @param x Pointer to an integer in which to store the X coordinate
3042 * @param y Pointer to an integer in which to store the Y coordinate
3044 * @param w Pointer to an integer in which to store the width of the
3046 * @param h Pointer to an integer in which to store the height of the
3049 * The position, naturally, will be relative to the top left corner of
3050 * the canvas' viewport.
3052 * @note Use @c NULL pointers on the geometry components you're not
3053 * interested in: they'll be ignored by the function.
3056 * @dontinclude evas-events.c
3057 * @skip int w, h, cw, ch;
3060 * See the full @ref Example_Evas_Events "example".
3062 * @ingroup Evas_Object_Group_Basic
3064 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);
3068 * Makes the given Evas object visible.
3070 * @param obj The given Evas object.
3072 * Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW
3073 * callback will be called.
3075 * @see evas_object_hide() for more on object visibility.
3076 * @see evas_object_visible_get()
3078 * @ingroup Evas_Object_Group_Basic
3080 EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1);
3083 * Makes the given Evas object invisible.
3085 * @param obj The given Evas object.
3087 * Hidden objects, besides not being shown at all in your canvas,
3088 * won't be checked for changes on the canvas rendering
3089 * process. Furthermore, they will not catch input events. Thus, they
3090 * are much ligher (in processing needs) than an object that is
3091 * invisible due to indirect causes, such as being clipped or out of
3092 * the canvas' viewport.
3094 * Besides becoming hidden, @p obj object's ::EVAS_CALLBACK_SHOW
3095 * callback will be called.
3097 * @note All objects are created in the hidden state! If you want them
3098 * shown, use evas_object_show() after their creation.
3100 * @see evas_object_show()
3101 * @see evas_object_visible_get()
3104 * @dontinclude evas-object-manipulation.c
3105 * @skip if (evas_object_visible_get(d.clipper))
3108 * See the full @ref Example_Evas_Object_Manipulation "example".
3110 * @ingroup Evas_Object_Group_Basic
3112 EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1);
3115 * Retrieves whether or not the given Evas object is visible.
3117 * @param obj The given Evas object.
3118 * @return @c EINA_TRUE if the object is visible, @c EINA_FALSE
3121 * This retrieves an object's visibily as the one enforced by
3122 * evas_object_show() and evas_object_hide().
3124 * @note The value returned isn't, by any means, influenced by
3125 * clippers covering @obj, it being out of its canvas' viewport or
3126 * stacked below other object.
3128 * @see evas_object_show()
3129 * @see evas_object_hide() (for an example)
3131 * @ingroup Evas_Object_Group_Basic
3133 EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3137 * Sets the general/main color of the given Evas object to the given
3140 * @param obj The given Evas object.
3141 * @param r The red component of the given color.
3142 * @param g The green component of the given color.
3143 * @param b The blue component of the given color.
3144 * @param a The alpha component of the given color.
3146 * @see evas_object_color_get() (for an example)
3148 * @ingroup Evas_Object_Group_Basic
3150 EAPI void evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
3153 * Retrieves the general/main color of the given Evas object.
3155 * @param obj The given Evas object to retrieve color from.
3156 * @param r Pointer to an integer in which to store the red component
3158 * @param g Pointer to an integer in which to store the green
3159 * component of the color.
3160 * @param b Pointer to an integer in which to store the blue component
3162 * @param a Pointer to an integer in which to store the alpha
3163 * component of the color.
3165 * Retrieves the “main” color's RGB component (and alpha channel)
3166 * values, <b>which range from 0 to 255</b>. For the alpha channel,
3167 * which defines the object's transparency level, the former value
3168 * means totally trasparent, while the latter means opaque.
3170 * Usually you’ll use this attribute for text and rectangle objects,
3171 * where the “main” color is their unique one. If set for objects
3172 * which themselves have colors, like the images one, those colors get
3173 * modulated by this one.
3175 * @note All newly created Evas rectangles get the default color
3176 * values of <code>255 255 255 255</code> (opaque white).
3178 * @note Use @c NULL pointers on the components you're not interested
3179 * in: they'll be ignored by the function.
3182 * @dontinclude evas-object-manipulation.c
3183 * @skip int alpha, r, g, b;
3186 * See the full @ref Example_Evas_Object_Manipulation "example".
3188 * @ingroup Evas_Object_Group_Basic
3190 EAPI void evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
3194 * Retrieves the Evas canvas that the given object lives on.
3196 * @param obj The given Evas object.
3197 * @return A pointer to the canvas where the object is on.
3199 * This function is most useful at code contexts where you need to
3200 * operate on the canvas but have only the object pointer.
3202 * @ingroup Evas_Object_Group_Basic
3204 EAPI Evas *evas_object_evas_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3207 * Retrieves the type of the given Evas object.
3209 * @param obj The given object.
3210 * @return The type of the object.
3212 * For Evas' builtin types, the return strings will be one of:
3213 * - <c>"rectangle"</c>,
3215 * - <c>"polygon"</c>,
3217 * - <c>"textblock"</c> and
3220 * For Evas smart objects (see @ref Evas_Smart_Group), the name of the
3221 * smart class itself is returned on this call. For the built-in
3222 * clipped smart object, it is <c>"EvasObjectSmartClipped"</c>.
3225 * @dontinclude evas-object-manipulation.c
3226 * @skip d.img = evas_object_image_filled_add(d.canvas);
3227 * @until border on the
3229 * See the full @ref Example_Evas_Object_Manipulation "example".
3231 EAPI const char *evas_object_type_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3234 * Raise @p obj to the top of its layer.
3236 * @param obj the object to raise
3238 EAPI void evas_object_raise (Evas_Object *obj) EINA_ARG_NONNULL(1);
3241 * Lower @p obj to the bottom of its layer.
3243 * @param obj the object to lower
3245 EAPI void evas_object_lower (Evas_Object *obj) EINA_ARG_NONNULL(1);
3248 * Stack @p obj immediately above @p above
3250 * If @p obj is a member of a smart object, then @p above must also be
3251 * a member of the same smart object.
3253 * Similarly, if @p obj is not a member of smart object, @p above may
3256 * @param obj the object to stack
3257 * @param above the object above which to stack
3259 EAPI void evas_object_stack_above (Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2);
3262 * Stack @p obj immediately below @p below
3264 * If @p obj is a member of a smart object, then @p below must also be
3265 * a member of the same smart object.
3267 * Similarly, if @p obj is not a member of smart object, @p below may
3270 * @param obj the object to stack
3271 * @param below the object below which to stack
3273 EAPI void evas_object_stack_below (Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2);
3276 * Get the Evas object above @p obj
3278 * @param obj an Evas_Object
3279 * @return the Evas_Object directly above
3281 EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3284 * Get the Evas object below @p obj
3286 * @param obj an Evas_Object
3287 * @return the Evas_Object directly below
3289 EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3296 * @defgroup Evas_Object_Group_Events Object Events
3298 * Objects generates events when they are moved, resized, when their
3299 * visibility change, when they are deleted and so on. These methods
3300 * will allow one to handle such events.
3302 * The events can be those from keyboard and mouse, if the object
3303 * accepts these events.
3305 * @ingroup Evas_Object_Group
3309 * @addtogroup Evas_Object_Group_Events
3314 * Add a callback function to an object
3316 * @param obj Object to attach a callback to
3317 * @param type The type of event that will trigger the callback
3318 * @param func The function to be called when the event is triggered
3319 * @param data The data pointer to be passed to @p func
3321 * This function adds a function callback to an object when the event
3322 * of type @p type occurs on object @p obj. The function is @p func.
3324 * In the event of a memory allocation error during addition of the
3325 * callback to the object, evas_alloc_error() should be used to
3326 * determine the nature of the error, if any, and the program should
3327 * sensibly try and recover.
3329 * The function will be passed the pointer @p data when it is
3330 * called. A callback function must look like this:
3333 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
3336 * The first parameter @p data in this function will be the same value
3337 * passed to evas_object_event_callback_add() as the @p data
3338 * parameter. The second parameter is a convenience for the programmer
3339 * to know what evas canvas the event occurred on. The third parameter
3340 * @p obj is the Object handle on which the event occurred. The foruth
3341 * parameter @p event_info is a pointer to a data structure that may
3342 * or may not be passed to the callback, depending on the event type
3343 * that triggered the callback.
3345 * The event type @p type to trigger the function may be one of
3346 * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT,
3347 * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP,
3348 * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL,
3349 * #EVAS_CALLBACK_FREE, #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP,
3350 * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT,
3351 * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE,
3352 * #EVAS_CALLBACK_RESIZE or #EVAS_CALLBACK_RESTACK.
3353 * This determines the kind of event that will trigger the callback to
3354 * be called. The @p event_info pointer passed to the callback will
3355 * be one of the following, depending on the event triggering it:
3357 * #EVAS_CALLBACK_MOUSE_IN: event_info = pointer to Evas_Event_Mouse_In
3359 * This event is triggered when the mouse pointer enters the region of
3360 * the object @p obj. This may occur by the mouse pointer being moved
3361 * by evas_event_feed_mouse_move() or
3362 * evas_event_feed_mouse_move_data() calls, or by the object being
3363 * shown, raised, moved, resized, or other objects being moved out of
3364 * the way, hidden, lowered or moved out of the way.
3366 * #EVAS_CALLBACK_MOUSE_OUT: event_info = pointer to Evas_Event_Mouse_Out
3368 * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is, but
3369 * occurs when the mouse pointer exits an object. Note that no out
3370 * events will be reported if the mouse pointer is implicitly grabbed
3371 * to an object (the mouse buttons are down at all and any were
3372 * pressed on that object). An out event will be reported as soon as
3373 * the mouse is no longer grabbed (no mouse buttons are
3374 * depressed). Out events will be reported once all buttons are
3375 * released, if the mouse has left the object.
3377 * #EVAS_CALLBACK_MOUSE_DOWN: event_info = pointer to
3378 * Evas_Event_Mouse_Down
3380 * This event is triggered by a mouse button being depressed while
3381 * over an object. If pointermode is EVAS_OBJECT_POINTER_MODE_AUTOGRAB
3382 * (default) this causes this object to passively grab the mouse until
3383 * all mouse buttons have been released. That means if this mouse
3384 * button is the first to be pressed, all future mouse events will be
3385 * reported to only this object until no buttons are down. That
3386 * includes mouse move events, in and out events, and further button
3387 * presses. When all buttons are released, event propagation occurs as
3390 * #EVAS_CALLBACK_MOUSE_UP: event_info = pointer to Evas_Event_Mouse_Up
3392 * This event is triggered by a mouse button being released while over
3393 * an object or when passively grabbed to an object. If this is the
3394 * last mouse button to be raised on an object then the passive grab
3395 * is released and event processing will continue as normal.
3397 * #EVAS_CALLBACK_MOUSE_MOVE: event_info = pointer to Evas_Event_Mouse_Move
3399 * This event is triggered by the mouse pointer moving while over an
3400 * object or passively grabbed to an object.
3402 * #EVAS_CALLBACK_MOUSE_WHEEL: event_info = pointer to
3403 * Evas_Event_Mouse_Wheel
3405 * This event is triggered by the mouse wheel being rolled while over
3406 * an object or passively grabbed to an object.
3408 * #EVAS_CALLBACK_FREE: event_info = NULL
3410 * This event is triggered just before Evas is about to free all
3411 * memory used by an object and remove all references to it. This is
3412 * useful for programs to use if they attached data to an object and
3413 * want to free it when the object is deleted. The object is still
3414 * valid when this callback is called, but after this callback
3415 * returns, there is no guarantee on the object's validity.
3417 * #EVAS_CALLBACK_KEY_DOWN: event_info = pointer to Evas_Event_Key_Down
3419 * This callback is called when a key is pressed and the focus is on
3420 * the object, or a key has been grabbed to a particular object which
3421 * wants to intercept the key press regardless of what object has the
3424 * #EVAS_CALLBACK_KEY_UP: event_info = pointer to Evas_Event_Key_Up
3426 * This callback is called when a key is released and the focus is on
3427 * the object, or a key has been grabbed to a particular object which
3428 * wants to intercept the key release regardless of what object has
3431 * #EVAS_CALLBACK_FOCUS_IN: event_info = NULL
3433 * This event is called when an object gains the focus. When the
3434 * callback is called the object has already gained the focus.
3436 * #EVAS_CALLBACK_FOCUS_OUT: event_info = NULL
3438 * This event is triggered by an object losing the focus. When the
3439 * callback is called the object has already lost the focus.
3441 * #EVAS_CALLBACK_SHOW: event_info = NULL
3443 * This event is triggered by the object being shown by
3444 * evas_object_show().
3446 * #EVAS_CALLBACK_HIDE: event_info = NULL
3448 * This event is triggered by an object being hidden by
3449 * evas_object_hide().
3451 * #EVAS_CALLBACK_MOVE: event_info = NULL
3453 * This event is triggered by an object being
3454 * moved. evas_object_move() can trigger this, as can any
3455 * object-specific manipulations that would mean the object's origin
3458 * #EVAS_CALLBACK_RESIZE: event_info = NULL
3460 * This event is triggered by an object being resized. Resizes can be
3461 * triggered by evas_object_resize() or by any object-specific calls
3462 * that may cause the object to resize.
3466 * extern Evas_Object *object;
3467 * extern void *my_data;
3468 * void down_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3469 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3471 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_UP, up_callback, my_data);
3472 * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
3474 * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n");
3477 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, down_callback, my_data);
3478 * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
3480 * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n");
3485 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);
3488 * Delete a callback function from an object
3490 * @param obj Object to remove a callback from
3491 * @param type The type of event that was triggering the callback
3492 * @param func The function that was to be called when the event was triggered
3493 * @return The data pointer that was to be passed to the callback
3495 * This function removes the most recently added callback from the
3496 * object @p obj which was triggered by the event type @p type and was
3497 * calling the function @p func when triggered. If the removal is
3498 * successful it will also return the data pointer that was passed to
3499 * evas_object_event_callback_add() when the callback was added to the
3500 * object. If not successful NULL will be returned.
3504 * extern Evas_Object *object;
3506 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3508 * my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
3511 EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3);
3514 * Delete a callback function from an object
3516 * @param obj Object to remove a callback from
3517 * @param type The type of event that was triggering the callback
3518 * @param func The function that was to be called when the event was triggered
3519 * @param data The data pointer that was to be passed to the callback
3520 * @return The data pointer that was to be passed to the callback
3522 * This function removes the most recently added callback from the
3523 * object @p obj which was triggered by the event type @p type and was
3524 * calling the function @p func with data @p data when triggered. If
3525 * the removal is successful it will also return the data pointer that
3526 * was passed to evas_object_event_callback_add() (that will be the
3527 * same as the parameter) when the callback was added to the
3528 * object. If not successful NULL will be returned.
3532 * extern Evas_Object *object;
3534 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3536 * my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
3539 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);
3543 * Set an object's pass events state.
3544 * @param obj the Evas object
3545 * @param pass whether to pass events or not
3547 * If @p pass is true, this will cause events on @p obj to be ignored.
3548 * They will be triggered on the next lower object (that is not set to
3549 * pass events) instead.
3551 * If @p pass is false, events will be processed as normal.
3553 EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1);
3556 * Determine whether an object is set to pass events.
3558 * @return pass events state
3560 EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3563 * Set an object's repeat events state.
3564 * @param obj the object
3565 * @param repeat wheter to repeat events or not
3567 * If @p repeat is true, this will cause events on @p obj to trigger
3568 * callbacks, but also to be repeated on the next lower object in the
3571 * If @p repeat is false, events occurring on @p obj will be processed
3574 EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
3577 * Determine whether an object is set to repeat events.
3579 * @return repeat events state
3581 EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3584 * Set whether events on a smart member object should propagate to its
3587 * @param obj the smart member object
3588 * @param prop wheter to propagate events or not
3590 * This function has no effect if @p obj is not a member of a smart
3593 * If @p prop is true, events occurring on this object will propagate on
3594 * to the smart object of which @p obj is a member.
3596 * If @p prop is false, events for which callbacks are set on the member
3597 * object, @p obj, will not be passed on to the parent smart object.
3599 * The default value is true.
3601 EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1);
3604 * Determine whether an object is set to propagate events.
3606 * @return propagate events state
3608 EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3615 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspecitve, 3D...)
3617 * Evas allows different transformations to be applied to all kinds of
3618 * objects. These are applied by means of UV mapping.
3620 * With UV mapping, one maps points in the source object to a 3D space
3621 * positioning at target. This allows rotation, perspective, scale and
3622 * lots of other effects, depending on the map that is used.
3624 * Each map point may carry a multiplier color. If properly
3625 * calculated, these can do shading effects on the object, producing
3628 * As usual, Evas provides both the raw and easy to use methods. The
3629 * raw methods allow developer to create its maps somewhere else,
3630 * maybe load them from some file format. The easy to use methods,
3631 * calculate the points given some high-level parameters, such as
3632 * rotation angle, ambient light and so on.
3634 * @note applying mapping will reduce performance, so use with
3635 * care. The impact on performance depends on engine in
3636 * use. Software is quite optimized, but not as fast as OpenGL.
3638 * @ingroup Evas_Object_Group
3642 * Enable or disable the map that is set.
3644 * This enables the map that is set or disables it. On enable, the object
3645 * geometry will be saved, and the new geometry will change (position and
3646 * size) to reflect the map geometry set. If none is set yet, this may be
3647 * an undefined geometry, unless you have already set the map with
3648 * evas_object_map_set(). It is suggested you first set a map with
3649 * evas_object_map_set() with valid useful coordinates then enable and
3650 * disable the map with evas_object_map_enable_set() as needed.
3652 * @param obj object to enable the map on
3653 * @param enabled enabled state
3655 EAPI void evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled);
3658 * Get the map enabled state
3660 * This returns the currently enabled state of the map on the object indicated.
3661 * The default map enable state is off. You can enable and disable it with
3662 * evas_object_map_enable_set().
3664 * @param obj object to get the map enabled state from
3665 * @return the map enabled state
3667 EAPI Eina_Bool evas_object_map_enable_get (const Evas_Object *obj);
3670 * Set the map source object
3672 * This sets the object from which the map is taken - can be any object that
3673 * has map enabled on it.
3675 * Currently not implemented. for future use.
3677 * @param obj object to set the map source of
3678 * @param src the source object from which the map is taken
3680 EAPI void evas_object_map_source_set (Evas_Object *obj, Evas_Object *src);
3683 * Get the map source object
3685 * See evas_object_map_source_set()
3687 * @param obj object to set the map source of
3688 * @return the object set as the source
3690 EAPI Evas_Object *evas_object_map_source_get (const Evas_Object *obj);
3693 * Set current object transformation map.
3695 * This sets the map on a given object. It is copied from the @p map pointer,
3696 * so there is no need to keep the @p map object if you don't need it anymore.
3698 * A map is a set of 4 points which have canvas x, y coordinates per point,
3699 * with an optional z point value as a hint for perspective correction, if it
3700 * is available. As well each point has u and v coordinates. These are like
3701 * "texture coordinates" in OpenGL in that they define a point in the source
3702 * image that is mapped to that map vertex/point. The u corresponds to the x
3703 * coordinate of this mapped point and v, the y coordinate. Note that these
3704 * coordinates describe a bounding region to sample. If you have a 200x100
3705 * source image and want to display it at 200x100 with proper pixel
3706 * precision, then do:
3709 * Evas_Map *m = evas_map_new(4);
3710 * evas_map_point_coord_set(m, 0, 0, 0, 0);
3711 * evas_map_point_coord_set(m, 1, 200, 0, 0);
3712 * evas_map_point_coord_set(m, 2, 200, 100, 0);
3713 * evas_map_point_coord_set(m, 3, 0, 100, 0);
3714 * evas_map_point_image_uv_set(m, 0, 0, 0);
3715 * evas_map_point_image_uv_set(m, 1, 200, 0);
3716 * evas_map_point_image_uv_set(m, 2, 200, 100);
3717 * evas_map_point_image_uv_set(m, 3, 0, 100);
3718 * evas_object_map_set(obj, m);
3722 * Note that the map points a uv coordinates match the image geometry. If
3723 * the @p map parameter is NULL, the stored map will be freed and geometry
3724 * prior to enabling/setting a map will be restored.
3726 * @param obj object to change transformation map
3727 * @param map new map to use
3729 * @see evas_map_new()
3731 EAPI void evas_object_map_set (Evas_Object *obj, const Evas_Map *map);
3734 * Get current object transformation map.
3736 * This returns the current internal map set on the indicated object. It is
3737 * intended for read-only acces and is only valid as long as the object is
3738 * not deleted or the map on the object is not changed. If you wish to modify
3739 * the map and set it back do the following:
3742 * const Evas_Map *m = evas_object_map_get(obj);
3743 * Evas_Map *m2 = evas_map_dup(m);
3744 * evas_map_util_rotate(m2, 30.0, 0, 0);
3745 * evas_object_map_set(obj);
3746 * evas_map_free(m2);
3749 * @param obj object to query transformation map.
3750 * @return map reference to map in use. This is an internal data structure, so
3753 * @see evas_object_map_set()
3755 EAPI const Evas_Map *evas_object_map_get (const Evas_Object *obj);
3759 * Populate source and destination map points to match exactly object.
3761 * Usually one initialize map of an object to match it's original
3762 * position and size, then transform these with evas_map_util_*
3763 * functions, such as evas_map_util_rotate() or
3764 * evas_map_util_3d_rotate(). The original set is done by this
3765 * function, avoiding code duplication all around.
3767 * @param m map to change all 4 points (must be of size 4).
3768 * @param obj object to use unmapped geometry to populate map coordinates.
3769 * @param z Point Z Coordinate hint (pre-perspective transform). This value
3770 * will be used for all four points.
3772 * @see evas_map_util_points_populate_from_object()
3773 * @see evas_map_point_coord_set()
3774 * @see evas_map_point_image_uv_set()
3776 EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
3779 * Populate source and destination map points to match exactly object.
3781 * Usually one initialize map of an object to match it's original
3782 * position and size, then transform these with evas_map_util_*
3783 * functions, such as evas_map_util_rotate() or
3784 * evas_map_util_3d_rotate(). The original set is done by this
3785 * function, avoiding code duplication all around.
3787 * Z Point coordinate is assumed as 0 (zero).
3789 * @param m map to change all 4 points (must be of size 4).
3790 * @param obj object to use unmapped geometry to populate map coordinates.
3792 * @see evas_map_util_points_populate_from_object_full()
3793 * @see evas_map_util_points_populate_from_geometry()
3794 * @see evas_map_point_coord_set()
3795 * @see evas_map_point_image_uv_set()
3797 EAPI void evas_map_util_points_populate_from_object (Evas_Map *m, const Evas_Object *obj);
3800 * Populate source and destination map points to match given geometry.
3802 * Similar to evas_map_util_points_populate_from_object_full(), this
3803 * call takes raw values instead of querying object's unmapped
3804 * geometry. The given width will be used to calculate destination
3805 * points (evas_map_point_coord_set()) and set the image uv
3806 * (evas_map_point_image_uv_set()).
3808 * @param m map to change all 4 points (must be of size 4).
3809 * @param x Point X Coordinate
3810 * @param y Point Y Coordinate
3811 * @param w width to use to calculate second and third points.
3812 * @param h height to use to calculate third and fourth points.
3813 * @param z Point Z Coordinate hint (pre-perspective transform). This value
3814 * will be used for all four points.
3816 * @see evas_map_util_points_populate_from_object()
3817 * @see evas_map_point_coord_set()
3818 * @see evas_map_point_image_uv_set()
3820 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);
3823 * Set color of all points to given color.
3825 * This call is useful to reuse maps after they had 3d lightning or
3826 * any other colorization applied before.
3828 * @param m map to change the color of.
3829 * @param r red (0 - 255)
3830 * @param g green (0 - 255)
3831 * @param b blue (0 - 255)
3832 * @param a alpha (0 - 255)
3834 * @see evas_map_point_color_set()
3836 EAPI void evas_map_util_points_color_set (Evas_Map *m, int r, int g, int b, int a);
3839 * Change the map to apply the given rotation.
3841 * This rotates the indicated map's coordinates around the center coordinate
3842 * given by @p cx and @p cy as the rotation center. The points will have their
3843 * X and Y coordinates rotated clockwise by @p degrees degress (360.0 is a
3844 * full rotation). Negative values for degrees will rotate counter-clockwise
3845 * by that amount. All coordinates are canvas global coordinates.
3847 * @param m map to change.
3848 * @param degrees amount of degrees from 0.0 to 360.0 to rotate.
3849 * @param cx rotation's center horizontal position.
3850 * @param cy rotation's center vertical position.
3852 * @see evas_map_point_coord_set()
3853 * @see evas_map_util_zoom()
3855 EAPI void evas_map_util_rotate (Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
3858 * Change the map to apply the given zooming.
3860 * Like evas_map_util_rotate(), this zooms the points of the map from a center
3861 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
3862 * parameters specific how much to zoom in the X and Y direction respectively.
3863 * A value of 1.0 means "don't zoom". 2.0 means "dobule the size". 0.5 is
3864 * "half the size" etc. All coordinates are canvas global coordinates.
3866 * @param m map to change.
3867 * @param zoomx horizontal zoom to use.
3868 * @param zoomy vertical zoom to use.
3869 * @param cx zooming center horizontal position.
3870 * @param cy zooming center vertical position.
3872 * @see evas_map_point_coord_set()
3873 * @see evas_map_util_rotate()
3875 EAPI void evas_map_util_zoom (Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
3878 * Rotate the map around 3 axes in 3D
3880 * This will rotate not just around the "Z" axis as in evas_map_util_rotate()
3881 * (which is a convenience call for those only wanting 2D). This will rotate
3882 * around the X, Y and Z axes. The Z axis points "into" the screen with low
3883 * values at the screen and higher values further away. The X axis runs from
3884 * left to right on the screen and the Y axis from top to bottom. Like with
3885 * evas_map_util_rotate(0 you provide a center point to rotate around (in 3D).
3887 * @param m map to change.
3888 * @param dx amount of degrees from 0.0 to 360.0 to rotate arount X axis.
3889 * @param dy amount of degrees from 0.0 to 360.0 to rotate arount Y axis.
3890 * @param dz amount of degrees from 0.0 to 360.0 to rotate arount Z axis.
3891 * @param cx rotation's center horizontal position.
3892 * @param cy rotation's center vertical position.
3893 * @param cz rotation's center vertical position.
3895 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);
3898 * Perform lighting calculations on the given Map
3900 * This is used to apply lighting calculations (from a single light source)
3901 * to a given map. The R, G and B values of each vertex will be modified to
3902 * reflect the lighting based on the lixth point coordinates, the light
3903 * color and the ambient color, and at what angle the map is facing the
3904 * light source. A surface should have its points be declared in a
3905 * clockwise fashion if the face is "facing" towards you (as opposed to
3906 * away from you) as faces have a "logical" side for lighting.
3908 * @param m map to change.
3909 * @param lx X coordinate in space of light point
3910 * @param ly Y coordinate in space of light point
3911 * @param lz Z coordinate in space of light point
3912 * @param lr light red value (0 - 255)
3913 * @param lg light green value (0 - 255)
3914 * @param lb light blue value (0 - 255)
3915 * @param ar ambient color red value (0 - 255)
3916 * @param ag ambient color green value (0 - 255)
3917 * @param ab ambient color blue value (0 - 255)
3919 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);
3922 * Apply a perspective transform to the map
3924 * This applies a given perspective (3D) to the map coordinates. X, Y and Z
3925 * values are used. The px and py points specify the "infinite distance" point
3926 * in the 3D conversion (where all lines converge to like when artists draw
3927 * 3D by hand). The @p z0 value specifis the z value at which there is a 1:1
3928 * mapping between spatial coorinates and screen coordinates. Any points
3929 * on this z value will not have their X and Y values modified in the transform.
3930 * Those further away (Z value higher) will shrink into the distance, and
3931 * those less than this value will expand and become bigger. The @p foc value
3932 * determines the "focal length" of the camera. This is in reality the distance
3933 * between the camera lens plane itself (at or closer than this rendering
3934 * results are undefined) and the "z0" z value. This allows for some "depth"
3935 * control and @p foc must be greater than 0.
3937 * @param m map to change.
3938 * @param px The pespective distance X coordinate
3939 * @param py The pespective distance Y coordinate
3940 * @param z0 The "0" z plane value
3941 * @param foc The focal distance
3943 EAPI void evas_map_util_3d_perspective (Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
3946 * Get the clockwise state of a map
3948 * This determines if the output points (X and Y. Z is not used) are
3949 * clockwise or anti-clockwise. This can be used for "back-face culling". This
3950 * is where you hide objects that "face away" from you. In this case objects
3951 * that are not clockwise.
3953 * @param m map to query.
3954 * @return 1 if clockwise, 0 otherwise
3956 EAPI Eina_Bool evas_map_util_clockwise_get (Evas_Map *m);
3960 * Create map of transformation points to be later used with an Evas object.
3962 * This creates a set of points (currently only 4 is supported. no other
3963 * number for @p count will work). That is empty and ready to be modified
3964 * with evas_map calls.
3966 * @param count number of points in the map. *
3967 * @return a newly allocated map or @c NULL on errors.
3969 * @see evas_map_free()
3970 * @see evas_map_dup()
3971 * @see evas_map_point_coord_set()
3972 * @see evas_map_point_image_uv_set()
3973 * @see evas_map_util_points_populate_from_object_full()
3974 * @see evas_map_util_points_populate_from_object()
3976 * @see evas_object_map_set()
3978 EAPI Evas_Map *evas_map_new (int count);
3981 * Set the smoothing for map rendering
3983 * This sets smoothing for map rendering. If the object is a type that has
3984 * its own smoothing settings, then both the smooth settings for this object
3985 * and the map must be turned off. By default smooth maps are enabled.
3987 * @param m map to modify. Must not be NULL.
3988 * @param enabled enable or disable smooth map rendering
3990 EAPI void evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled);
3993 * get the smoothing for map rendering
3995 * This gets smoothing for map rendering.
3997 * @param m map to get the smooth from. Must not be NULL.
3999 EAPI Eina_Bool evas_map_smooth_get (const Evas_Map *m);
4002 * Set the alpha flag for map rendering
4004 * This sets alpha flag for map rendering. If the object is a type that has
4005 * its own alpha settings, then this will take precedence. Only image objects
4006 * have this currently. Fits stops alpha blending of the map area, and is
4007 * useful if you know the object and/or all sub-objects is 100% solid.
4009 * @param m map to modify. Must not be NULL.
4010 * @param enabled enable or disable alpha map rendering
4012 EAPI void evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled);
4015 * get the alpha flag for map rendering
4017 * This gets the alph flag for map rendering.
4019 * @param m map to get the alpha from. Must not be NULL.
4021 EAPI Eina_Bool evas_map_alpha_get (const Evas_Map *m);
4024 * Copy a previously allocated map.
4026 * This makes a duplicate of the @p m object and returns it.
4028 * @param m map to copy. Must not be NULL.
4029 * @return newly allocated map with the same count and contents as @p m.
4031 EAPI Evas_Map *evas_map_dup (const Evas_Map *m);
4034 * Free a previously allocated map.
4036 * This frees a givem map @p m and all memory associated with it. You must NOT
4037 * free a map returned by evas_object_map_get() as this is internal.
4039 * @param m map to free.
4041 EAPI void evas_map_free (Evas_Map *m);
4046 * Returns the number of points in a map. Should be at least 4.
4048 * @param m map to get size.
4049 * @return -1 on error, points otherwise.
4051 EAPI int evas_map_count_get (const Evas_Map *m) EINA_CONST;
4054 * Change the map point's coordinate.
4056 * This sets the fixen point's coordinate in the map. Note that points
4057 * describe the outline of a quadrangle and are ordered either clockwise
4058 * or anit-clock-wise. It is suggested to keep your quadrangles concave and
4059 * non-complex, though these polygon modes may work, they may not render
4060 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
4061 * 2 and 3, and 3 and 0 to describe the edges of the quandrangle.
4063 * The X and Y and Z coordinates are in canvas units. Z is optional and may
4064 * or may not be honored in drawing. Z is a hint and does not affect the
4065 * X and Y rendered coordinates. It may be used for calculating fills with
4066 * perspective correct rendering.
4068 * Remember all coordinates are canvas global ones like with move and reize
4071 * @param m map to change point. Must not be @c NULL.
4072 * @param idx index of point to change. Must be smaller than map size.
4073 * @param x Point X Coordinate
4074 * @param y Point Y Coordinate
4075 * @param z Point Z Coordinate hint (pre-perspective transform)
4077 * @see evas_map_util_rotate()
4078 * @see evas_map_util_zoom()
4079 * @see evas_map_util_points_populate_from_object_full()
4080 * @see evas_map_util_points_populate_from_object()
4082 EAPI void evas_map_point_coord_set (Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
4085 * Get the map point's coordinate.
4087 * This returns the coordinates of the given point in the map.
4089 * @param m map to query point.
4090 * @param idx index of point to query. Must be smaller than map size.
4091 * @param x where to return the X coordinate.
4092 * @param y where to return the Y coordinate.
4093 * @param z where to return the Z coordinate.
4095 EAPI void evas_map_point_coord_get (const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
4098 * Change the map point's U and V texture source point
4100 * This sets the U and V coordinates for the point. This determines which
4101 * coordinate in the source image is mapped to the given point, much like
4102 * OpenGL and textures. Notes that these points do select the pixel, but
4103 * are double floating point values to allow for accuracy and sub-pixel
4106 * @param m map to change the point of.
4107 * @param idx index of point to change. Must be smaller than map size.
4108 * @param u the X coordinate within the image/texture source
4109 * @param v the Y coordinate within the image/texture source
4111 * @see evas_map_point_coord_set()
4112 * @see evas_object_map_set()
4113 * @see evas_map_util_points_populate_from_object_full()
4114 * @see evas_map_util_points_populate_from_object()
4116 EAPI void evas_map_point_image_uv_set (Evas_Map *m, int idx, double u, double v);
4119 * Get the map point's U and V texture source points
4121 * This returns the texture points set by evas_map_point_image_uv_set().
4123 * @param m map to query point.
4124 * @param idx index of point to query. Must be smaller than map size.
4125 * @param u where to write the X coordinate within the image/texture source
4126 * @param v where to write the Y coordinate within the image/texture source
4128 EAPI void evas_map_point_image_uv_get (const Evas_Map *m, int idx, double *u, double *v);
4131 * Set the color of a vertex in the map
4133 * This sets the color of the vertex in the map. Colors will be linearly
4134 * interpolated between vertex points through the map. Color will multiply
4135 * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
4136 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
4137 * have no affect on modifying the texture pixels.
4139 * @param m map to change the color of.
4140 * @param idx index of point to change. Must be smaller than map size.
4141 * @param r red (0 - 255)
4142 * @param g green (0 - 255)
4143 * @param b blue (0 - 255)
4144 * @param a alpha (0 - 255)
4146 * @see evas_map_util_points_color_set()
4147 * @see evas_map_point_coord_set()
4148 * @see evas_object_map_set()
4150 EAPI void evas_map_point_color_set (Evas_Map *m, int idx, int r, int g, int b, int a);
4153 * Get the color set on a vertex in the map
4155 * This gets the color set by evas_map_point_color_set() on the given vertex
4158 * @param m map to get the color of the vertex from.
4159 * @param idx index of point get. Must be smaller than map size.
4160 * @param r pointer to red return
4161 * @param g pointer to green return
4162 * @param b pointer to blue return
4163 * @param a pointer to alpha return (0 - 255)
4165 * @see evas_map_point_coord_set()
4166 * @see evas_object_map_set()
4168 EAPI void evas_map_point_color_get (const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
4171 * @defgroup Evas_Object_Group_Size_Hints Size Hints
4173 * Objects may carry hints so another object that acts as a manager
4174 * (see @ref Evas_Smart_Object_Group) may know how to properly position
4175 * and resize the object. The Size Hints provide a common interface
4176 * that is recommended as the protocol for such information.
4178 * @ingroup Evas_Object_Group
4182 * Retrieves the size hint for the minimum size.
4184 * This is not a size enforcement in any way, it's just a hint that should
4185 * be used whenever appropriate.
4187 * Note that if any of @p w or @p h are @c NULL, the @c NULL
4188 * parameters are ignored.
4190 * @param obj The given Evas object.
4191 * @param w Pointer to an integer in which to store the minimum width.
4192 * @param h Pointer to an integer in which to store the minimum height.
4194 EAPI void evas_object_size_hint_min_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4197 * Sets the size hint for the minimum size.
4199 * This is not a size enforcement in any way, it's just a hint that should
4200 * be used whenever appropriate.
4202 * Value 0 is considered unset.
4204 * @param obj The given Evas object.
4205 * @param w Integer to use as the minimum width hint.
4206 * @param h Integer to use as the minimum height hint.
4208 EAPI void evas_object_size_hint_min_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4211 * Retrieves the size hint for the maximum size.
4213 * This is not a size enforcement in any way, it's just a hint that should
4214 * be used whenever appropriate.
4216 * Note that if any of @p w or @p h are @c NULL, the @c NULL
4217 * parameters are ignored.
4219 * @param obj The given Evas object.
4220 * @param w Pointer to an integer in which to store the maximum width.
4221 * @param h Pointer to an integer in which to store the maximum height.
4223 EAPI void evas_object_size_hint_max_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4226 * Sets the size hint for the maximum size.
4228 * This is not a size enforcement in any way, it's just a hint that should
4229 * be used whenever appropriate.
4231 * Value -1 is considered unset.
4233 * @param obj The given Evas object.
4234 * @param w Integer to use as the maximum width hint.
4235 * @param h Integer to use as the maximum height hint.
4237 EAPI void evas_object_size_hint_max_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4240 * Retrieves the size request hint.
4242 * This is not a size enforcement in any way, it's just a hint that should
4243 * be used whenever appropriate.
4245 * Note that if any of @p w or @p h are @c NULL, the @c NULL
4246 * parameters are ignored.
4248 * @param obj The given Evas object.
4249 * @param w Pointer to an integer in which to store the requested width.
4250 * @param h Pointer to an integer in which to store the requested height.
4252 EAPI void evas_object_size_hint_request_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4255 * Sets the requested size hint.
4257 * This is not a size enforcement in any way, it's just a hint that should
4258 * be used whenever appropriate.
4260 * Value 0 is considered unset.
4262 * @param obj The given Evas object.
4263 * @param w Integer to use as the preferred width hint.
4264 * @param h Integer to use as the preferred height hint.
4266 EAPI void evas_object_size_hint_request_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4269 * Retrieves the size aspect control hint.
4271 * This is not a size enforcement in any way, it's just a hint that should
4272 * be used whenever appropriate.
4274 * Note that if any of @p aspect, @p w or @p h are @c NULL, the @c NULL
4275 * parameters are ignored.
4277 * @param obj The given Evas object.
4278 * @param aspect Returns the hint on how size should be calculated.
4279 * @param w Pointer to an integer in which to store the aspect width.
4280 * @param h Pointer to an integer in which to store the aspect height.
4282 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);
4285 * Sets the size aspect control hint.
4287 * This is not a size enforcement in any way, it's just a hint that should
4288 * be used whenever appropriate.
4290 * @param obj The given Evas object.
4291 * @param aspect Hint on how to calculate size.
4292 * @param w Integer to use as aspect width hint.
4293 * @param h Integer to use as aspect height hint.
4295 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);
4298 * Retrieves the size align control hint.
4300 * This is not a size enforcement in any way, it's just a hint that should
4301 * be used whenever appropriate.
4303 * Note that if any of @p x or @p y are @c NULL, the @c NULL
4304 * parameters are ignored.
4306 * @param obj The given Evas object.
4307 * @param x Pointer to a double in which to store the align x.
4308 * @param y Pointer to a double in which to store the align y.
4310 EAPI void evas_object_size_hint_align_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
4313 * Sets the size align control hint.
4315 * This is not a size enforcement in any way, it's just a hint that should
4316 * be used whenever appropriate.
4318 * Accepted values are in the 0.0 to 1.0 range, with the special value
4319 * -1.0 used to specify "justify" or "fill" by some users. See
4320 * documentation of possible users.
4322 * @param obj The given Evas object.
4323 * @param x Double (0.0..1.0 or -1.0) to use as align x hint.
4324 * @param y Double (0.0..1.0 or -1.0) to use as align y hint.
4326 EAPI void evas_object_size_hint_align_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
4329 * Retrieves the size weight control hint.
4331 * This is not a size enforcement in any way, it's just a hint that should
4332 * be used whenever appropriate.
4334 * Note that if any of @p x or @p y are @c NULL, the @c NULL
4335 * parameters are ignored.
4337 * Accepted values are zero or positive values. Some users might use
4338 * this hint as a boolean, but some might consider it as a proportion,
4339 * see documentation of possible users.
4341 * @param obj The given Evas object.
4342 * @param x Pointer to a double in which to store the weight x.
4343 * @param y Pointer to a double in which to store the weight y.
4345 EAPI void evas_object_size_hint_weight_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
4348 * Sets the size weight control hint.
4350 * This is not a size enforcement in any way, it's just a hint that should
4351 * be used whenever appropriate.
4353 * @param obj The given Evas object.
4354 * @param x Double (0.0-1.0) to use as weight x hint.
4355 * @param y Double (0.0-1.0) to use as weight y hint.
4357 EAPI void evas_object_size_hint_weight_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
4360 * Retrieves the size padding control hint.
4362 * This is not a size enforcement in any way, it's just a hint that should
4363 * be used whenever appropriate.
4365 * Note that if any of @p l, @p r, @p t or @p b are @c NULL, the @c
4366 * NULL parameters are ignored.
4368 * @param obj The given Evas object.
4369 * @param l Pointer to an integer in which to store left padding.
4370 * @param r Pointer to an integer in which to store right padding.
4371 * @param t Pointer to an integer in which to store top padding.
4372 * @param b Pointer to an integer in which to store bottom padding.
4374 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);
4377 * Sets the size padding control hint.
4379 * This is not a size enforcement in any way, it's just a hint that should
4380 * be used whenever appropriate.
4382 * @param obj The given Evas object.
4383 * @param l Integer to specify left padding.
4384 * @param r Integer to specify right padding.
4385 * @param t Integer to specify top padding.
4386 * @param b Integer to specify bottom padding.
4388 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);
4391 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
4393 * Miscellaneous functions that also apply to any object, but are less
4394 * used or not implemented by all objects.
4396 * @ingroup Evas_Object_Group
4400 * @addtogroup Evas_Object_Group_Extras
4405 * Set an attached data pointer to an object with a given string key.
4407 * @param obj The object to attach the data pointer to
4408 * @param key The string key for the data to access it
4409 * @param data The ponter to the data to be attached
4411 * This attaches the pointer @p data to the object @p obj, given the
4412 * access string @p key. This pointer will stay "hooked" to the object
4413 * until a new pointer with the same string key is attached with
4414 * evas_object_data_set() or it is deleted with
4415 * evas_object_data_del(). On deletion of the object @p obj, the
4416 * pointers will not be accessible from the object anymore.
4418 * You can find the pointer attached under a string key using
4419 * evas_object_data_get(). It is the job of the calling application to
4420 * free any data pointed to by @p data when it is no longer required.
4422 * If @p data is @c NULL, the old value stored at @p key will be
4423 * removed but no new value will be stored. This is synonymous with
4424 * calling evas_object_data_del() with @p obj and @p key.
4426 * @note This function is very handy when you have data associated
4427 * specifically to an Evas object, being of use only when dealing with
4428 * it. Than you don't have the burden to a pointer to it elsewhere,
4429 * using this family of functions.
4435 * extern Evas_Object *obj;
4437 * my_data = malloc(500);
4438 * evas_object_data_set(obj, "name_of_data", my_data);
4439 * printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data"));
4442 EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2);
4445 * Return an attached data pointer on an Evas object by its given
4448 * @param obj The object to which the data was attached
4449 * @param key The string key the data was stored under
4450 * @return The data pointer stored, or @c NULL if none was stored
4452 * This function will return the data pointer attached to the object
4453 * @p obj, stored using the string key @p key. If the object is valid
4454 * and a data pointer was stored under the given key, that pointer
4455 * will be returned. If this is not the case, @c NULL will be
4456 * returned, signifying an invalid object or a non-existent key. It is
4457 * possible that a @c NULL pointer was stored given that key, but this
4458 * situation is non-sensical and thus can be considered an error as
4459 * well. @c NULL pointers are never stored as this is the return value
4460 * if an error occurs.
4466 * extern Evas_Object *obj;
4468 * my_data = evas_object_data_get(obj, "name_of_my_data");
4469 * if (my_data) printf("Data stored was %p\n", my_data);
4470 * else printf("No data was stored on the object\n");
4473 EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
4476 * Delete an attached data pointer from an object.
4478 * @param obj The object to delete the data pointer from
4479 * @param key The string key the data was stored under
4480 * @return The original data pointer stored at @p key on @p obj
4482 * This will remove the stored data pointer from @p obj stored under
4483 * @p key and return this same pointer, if actually there was data
4484 * there, or @c NULL, if nothing was stored under that key.
4490 * extern Evas_Object *obj;
4492 * my_data = evas_object_data_del(obj, "name_of_my_data");
4495 EAPI void *evas_object_data_del (Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
4499 * Set pointer behavior.
4502 * @param setting desired behavior.
4504 * This function has direct effect on event callbacks related to
4507 * If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse
4508 * is down at this object, events will be restricted to it as source,
4509 * mouse moves, for example, will be emitted even if outside this
4512 * If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will
4513 * be emitted just when inside this object area.
4515 * The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB.
4517 * @ingroup Evas_Object_Group_Extras
4519 EAPI void evas_object_pointer_mode_set (Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1);
4522 * Determine how pointer will behave.
4524 * @return pointer behavior.
4525 * @ingroup Evas_Object_Group_Extras
4527 EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4531 * Sets whether or not the given Evas object is to be drawn anti-aliased.
4533 * @param obj The given Evas object.
4534 * @param anti_alias 1 if the object is to be anti_aliased, 0 otherwise.
4535 * @ingroup Evas_Object_Group_Extras
4537 EAPI void evas_object_anti_alias_set (Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1);
4540 * Retrieves whether or not the given Evas object is to be drawn anti_aliased.
4541 * @param obj The given Evas object.
4542 * @return @c 1 if the object is to be anti_aliased. @c 0 otherwise.
4543 * @ingroup Evas_Object_Group_Extras
4545 EAPI Eina_Bool evas_object_anti_alias_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4549 * Sets the scaling factor for an Evas object. Does not affect all
4552 * @param obj The given Evas object.
4553 * @param scale The scaling factor. <c>1.0</c> means no scaling,
4556 * This will multiply the object's dimension by the given factor, thus
4557 * altering its geometry (width and height). Useful when you want
4558 * scalable UI elements, possibly at run time.
4560 * @see evas_object_scale_get()
4562 * @ingroup Evas_Object_Group_Extras
4564 EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
4567 * Retrieves the scaling factor for the given Evas object.
4569 * @param obj The given Evas object.
4570 * @return The scaling factor.
4572 * @ingroup Evas_Object_Group_Extras
4574 EAPI double evas_object_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4578 * Sets the render_op to be used for rendering the Evas object.
4579 * @param obj The given Evas object.
4580 * @param render_op one of the Evas_Render_Op values.
4581 * @ingroup Evas_Object_Group_Extras
4583 EAPI void evas_object_render_op_set (Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1);
4586 * Retrieves the current value of the operation used for rendering the Evas object.
4587 * @param obj The given Evas object.
4588 * @return one of the enumerated values in Evas_Render_Op.
4589 * @ingroup Evas_Object_Group_Extras
4591 EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4593 EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1);
4594 EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4596 EAPI void evas_object_static_clip_set (Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1);
4597 EAPI Eina_Bool evas_object_static_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4604 * @defgroup Evas_Object_Group_Find Finding Objects
4606 * Functions that allows finding objects by their position, name or
4609 * @ingroup Evas_Object_Group
4613 * Retrieve the object that currently has focus.
4615 * @param e The Evas canvas to query for focused object on.
4616 * @return The object that has focus or @c NULL if there is not one.
4618 * Evas can have (at most) one of its objects focused at a time.
4619 * Focused objects will be the ones having <b>key events</b> delivered
4620 * to, which the programmer can act upon by means of
4621 * evas_object_event_callback_add() usage.
4623 * @note Most users wouldn't be dealing directly with Evas' focused
4624 * objects. Instead, they would be using a higher level library for
4625 * that (like a toolkit, as Elementary) to handle focus and who's
4626 * receiving input for them.
4628 * This call returns the object that currently has focus on the canvas
4629 * @p e or @c NULL, if none.
4631 * @see evas_object_focus_set
4632 * @see evas_object_focus_get
4633 * @see evas_object_key_grab
4634 * @see evas_object_key_ungrab
4637 * @dontinclude evas-events.c
4638 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
4639 * @until evas_object_focus_set(d.bg, EINA_TRUE);
4640 * @dontinclude evas-events.c
4641 * @skip called when our rectangle gets focus
4644 * In this example the @c event_info is exactly a pointer to that
4645 * focused rectangle. See the full @ref Example_Evas_Events "example".
4647 * @ingroup Evas_Object_Group_Find
4649 EAPI Evas_Object *evas_focus_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4653 * Retrieves the object on the given evas with the given name.
4654 * @param e The given evas.
4655 * @param name The given name.
4656 * @return If successful, the Evas object with the given name. Otherwise,
4658 * @ingroup Evas_Object_Group_Find
4660 EAPI Evas_Object *evas_object_name_find (const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4664 * Retrieves the top object at the given position (x,y)
4665 * @param e The given Evas object.
4666 * @param x The horizontal coordinate
4667 * @param y The vertical coordinate
4668 * @param include_pass_events_objects Boolean Flag to include or not
4669 * pass events objects
4670 * @param include_hidden_objects Boolean Flag to include or not hidden objects
4671 * @return The Evas object that is over all others objects at the given position.
4673 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;
4676 * Retrieves the top object at mouse pointer position
4677 * @param e The given Evas object.
4678 * @return The Evas object that is over all others objects at the
4681 EAPI Evas_Object *evas_object_top_at_pointer_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4684 * Retrieves the top object in the given rectangle region
4685 * @param e The given Evas object.
4686 * @param x The horizontal coordinate.
4687 * @param y The vertical coordinate.
4688 * @param w The width size.
4689 * @param h The height size.
4690 * @param include_pass_events_objects Boolean Flag to include or not pass events objects
4691 * @param include_hidden_objects Boolean Flag to include or not hidden objects
4692 * @return The Evas object that is over all others objects at the pointer position.
4695 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;
4699 * Retrieves the objects at the given position
4700 * @param e The given Evas object.
4701 * @param x The horizontal coordinate.
4702 * @param y The vertical coordinate.
4703 * @param include_pass_events_objects Boolean Flag to include or not
4704 * pass events objects
4705 * @param include_hidden_objects Boolean Flag to include or not hidden objects
4706 * @return The list of Evas objects at the pointer position.
4709 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;
4710 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;
4714 * Get the lowest Evas object on the Evas @p e
4717 * @return the lowest object
4719 EAPI Evas_Object *evas_object_bottom_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4722 * Get the highest Evas object on the Evas @p e
4725 * @return the highest object
4727 EAPI Evas_Object *evas_object_top_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4730 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
4732 * Evas provides a way to intercept method calls. The interceptor
4733 * callback may opt to completely deny the call, or may check and
4734 * change the parameters before continuing. The continuation of an
4735 * intercepted call is done by calling the intercepted call again,
4736 * from inside the interceptor callback.
4738 * @ingroup Evas_Object_Group
4740 typedef void (*Evas_Object_Intercept_Show_Cb) (void *data, Evas_Object *obj);
4741 typedef void (*Evas_Object_Intercept_Hide_Cb) (void *data, Evas_Object *obj);
4742 typedef void (*Evas_Object_Intercept_Move_Cb) (void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
4743 typedef void (*Evas_Object_Intercept_Resize_Cb) (void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
4744 typedef void (*Evas_Object_Intercept_Raise_Cb) (void *data, Evas_Object *obj);
4745 typedef void (*Evas_Object_Intercept_Lower_Cb) (void *data, Evas_Object *obj);
4746 typedef void (*Evas_Object_Intercept_Stack_Above_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
4747 typedef void (*Evas_Object_Intercept_Stack_Below_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
4748 typedef void (*Evas_Object_Intercept_Layer_Set_Cb) (void *data, Evas_Object *obj, int l);
4749 typedef void (*Evas_Object_Intercept_Color_Set_Cb) (void *data, Evas_Object *obj, int r, int g, int b, int a);
4750 typedef void (*Evas_Object_Intercept_Clip_Set_Cb) (void *data, Evas_Object *obj, Evas_Object *clip);
4751 typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *obj);
4755 * Set the callback function that intercepts a show event of a object.
4757 * @param obj The given canvas object pointer.
4758 * @param func The given function to be the callback function.
4759 * @param data The data passed to the callback function.
4761 * This function sets a callback function to intercepts a show event
4762 * of a canvas object.
4764 * @see evas_object_intercept_show_callback_del().
4767 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);
4770 * Unset the callback function that intercepts a show event of a
4773 * @param obj The given canvas object pointer.
4774 * @param func The given callback function.
4776 * This function sets a callback function to intercepts a show event
4777 * of a canvas object.
4779 * @see evas_object_intercept_show_callback_add().
4782 EAPI void *evas_object_intercept_show_callback_del (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2);
4785 * Set the callback function that intercepts a hide event of a object.
4787 * @param obj The given canvas object pointer.
4788 * @param func The given function to be the callback function.
4789 * @param data The data passed to the callback function.
4791 * This function sets a callback function to intercepts a hide event
4792 * of a canvas object.
4794 * @see evas_object_intercept_hide_callback_del().
4797 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);
4800 * Unset the callback function that intercepts a hide event of a
4803 * @param obj The given canvas object pointer.
4804 * @param func The given callback function.
4806 * This function sets a callback function to intercepts a hide event
4807 * of a canvas object.
4809 * @see evas_object_intercept_hide_callback_add().
4812 EAPI void *evas_object_intercept_hide_callback_del (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2);
4815 * Set the callback function that intercepts a move event of a object.
4817 * @param obj The given canvas object pointer.
4818 * @param func The given function to be the callback function.
4819 * @param data The data passed to the callback function.
4821 * This function sets a callback function to intercepts a move event
4822 * of a canvas object.
4824 * @see evas_object_intercept_move_callback_del().
4827 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);
4830 * Unset the callback function that intercepts a move event of a
4833 * @param obj The given canvas object pointer.
4834 * @param func The given callback function.
4836 * This function sets a callback function to intercepts a move event
4837 * of a canvas object.
4839 * @see evas_object_intercept_move_callback_add().
4842 EAPI void *evas_object_intercept_move_callback_del (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2);
4844 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);
4845 EAPI void *evas_object_intercept_resize_callback_del (Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2);
4846 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);
4847 EAPI void *evas_object_intercept_raise_callback_del (Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2);
4848 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);
4849 EAPI void *evas_object_intercept_lower_callback_del (Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2);
4850 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);
4851 EAPI void *evas_object_intercept_stack_above_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2);
4852 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);
4853 EAPI void *evas_object_intercept_stack_below_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2);
4854 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);
4855 EAPI void *evas_object_intercept_layer_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2);
4856 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);
4857 EAPI void *evas_object_intercept_color_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2);
4858 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);
4859 EAPI void *evas_object_intercept_clip_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2);
4860 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);
4861 EAPI void *evas_object_intercept_clip_unset_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2);
4864 * @defgroup Evas_Object_Specific Specific Object Functions
4866 * Functions that work on specific objects.
4871 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
4873 * Functions that operate on evas rectangle objects.
4875 * @ingroup Evas_Object_Specific
4879 * Adds a rectangle to the given evas.
4880 * @param e The given evas.
4881 * @return The new rectangle object.
4883 EAPI Evas_Object *evas_object_rectangle_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
4886 * @defgroup Evas_Object_Image Image Object Functions
4888 * Functions used to create and manipulate image objects.
4890 * Note - Image objects may return or accept "image data" in multiple
4891 * formats. This is based on the colorspace of an object. Here is a
4892 * rundown on formats:
4894 * EVAS_COLORSPACE_ARGB8888:
4896 * This pixel format is a linear block of pixels, starting at the
4897 * top-left row by row until the bottom right of the image or pixel
4898 * region. All pixels are 32-bit unsigned int's with the high-byte
4899 * being alpha and the low byte being blue in the format ARGB. Alpha
4900 * may or may not be used by evas depending on the alpha flag of the
4901 * image, but if not used, should be set to 0xff anyway.
4903 * This colorspace uses premultiplied alpha. That means that R, G and
4904 * B cannot exceed A in value. The conversion from non-premultiplied
4907 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
4909 * So 50% transparent blue will be: 0x80000080. This will not be
4910 * "dark" - just 50% transparent. Values are 0 == black, 255 == solid
4911 * or full red, green or blue.
4913 * EVAS_COLORSPACE_YCBCR422P601_PL:
4915 * This is a pointer-list indirected set of YUV (YCbCr) pixel
4916 * data. This means that the data returned or set is not actual pixel
4917 * data, but pointers TO lines of pixel data. The list of pointers
4918 * will first be N rows of pointers to the Y plane - pointing to the
4919 * first pixel at the start of each row in the Y plane. N is the
4920 * height of the image data in pixels. Each pixel in the Y, U and V
4921 * planes is 1 byte exactly, packed. The next N / 2 pointers will
4922 * point to rows in the U plane, and the next N / 2 pointers will
4923 * point to the V plane rows. U and V planes are half the horizontal
4924 * and vertical resolution of the Y plane.
4926 * Row order is top to bottom and row pixels are stored left to right.
4928 * There is a limitation that these images MUST be a multiple of 2
4929 * pixels in size horizontally or vertically. This is due to the U and
4930 * V planes being half resolution. Also note that this assumes the
4931 * itu601 YUV colorspace specification. This is defined for standard
4932 * television and mpeg streams. HDTV may use the itu709
4935 * Values are 0 to 255, indicating full or no signal in that plane
4938 * EVAS_COLORSPACE_YCBCR422P709_PL:
4940 * Not implemented yet.
4942 * EVAS_COLORSPACE_RGB565_A5P:
4944 * In the process of being implemented in 1 engine only. This may change.
4946 * This is a pointer to image data for 16-bit half-word pixel data in
4947 * 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue), with
4948 * the high-byte containing red and the low byte containing blue, per
4949 * pixel. This data is packed row by row from the top-left to the
4952 * If the image has an alpha channel enabled there will be an extra
4953 * alpha plane after the color pixel plane. If not, then this data
4954 * will not exist and should not be accessed in any way. This plane is
4955 * a set of pixels with 1 byte per pixel defining the alpha values of
4956 * all pixels in the image from the top-left to the bottom right of
4957 * the image, row by row. Even though the values of the alpha pixels
4958 * can be 0 to 255, only values 0 through to 32 are used, 32 being
4959 * solid and 0 being transparent.
4961 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
4962 * with 0 being black and 31 or 63 being full red, green or blue
4963 * respectively. This colorspace is also pre-multiplied like
4964 * EVAS_COLORSPACE_ARGB8888 so:
4966 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
4968 * EVAS_COLORSPACE_A8:
4970 * The image is just a alpha mask (8 bit's per pixel). This is used for alpha
4973 * @ingroup Evas_Object_Specific
4975 typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o);
4979 * Creates a new image object on the given evas.
4981 * @param e The given evas.
4982 * @return The created image object.
4984 EAPI Evas_Object *evas_object_image_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
4987 * Creates a new image object that automatically scales on the given evas.
4989 * This is a helper around evas_object_image_add() and
4990 * evas_object_image_filled_set(), it will track object resizes and apply
4991 * evas_object_image_fill_set() with the new geometry.
4993 * @see evas_object_image_add()
4994 * @see evas_object_image_filled_set()
4995 * @see evas_object_image_fill_set()
4997 EAPI Evas_Object *evas_object_image_filled_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5001 * Sets the data for an image from memory to be loaded
5003 * This is the same as evas_object_image_file_set() but the file to be loaded
5004 * may exist at an address in memory (the data for the file, not the filename
5005 * itself). The @p data at the address is copied and stored for future use, so
5006 * no @p data needs to be kept after this call is made. It will be managed and
5007 * freed for you when no longer needed. The @p size is limited to 2 gigabytes
5008 * in size, and must be greater than 0. A NULL @p data pointer is also invalid.
5009 * Set the filename to NULL to reset to empty state and have the image file
5010 * data freed from memory using evas_object_image_file_set().
5012 * The @p format is optional (pass NULL if you don't need/use it). It is used
5013 * to help Evas guess better which loader to use for the data. It may simply
5014 * be the "extension" of the file as it would normally be on disk such as
5015 * "jpg" or "png" or "gif" etc.
5017 * @param obj The given image object.
5018 * @param data The image file data address
5019 * @param size The size of the image file data in bytes
5020 * @param format The format of the file (optional), or @c NULL if not needed
5021 * @param key The image key in file, or @c NULL.
5023 EAPI void evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2);
5026 * Sets the filename and key of the given image object.
5028 * If the file supports multiple data stored in it as eet, you can
5029 * specify the key to be used as the index of the image in this file.
5031 * @param obj The given image object.
5032 * @param file The image filename.
5033 * @param key The image key in file, or @c NULL.
5035 EAPI void evas_object_image_file_set (Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
5038 * Retrieves the filename and key of the given image object.
5040 * @param obj The given image object.
5041 * @param file Location to store the image filename, or @c NULL.
5042 * @param key Location to store the image key, or @c NULL.
5044 EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2);
5047 * Sets how much of each border of the given image object is not
5050 * When rendering, the image may be scaled to fit the size of the
5051 * image object. This function sets what area around the border of the
5052 * image is not to be scaled. This sort of function is useful for
5053 * widget theming, where, for example, buttons may be of varying
5054 * sizes, but the border size must remain constant.
5056 * The units used for @p l, @p r, @p t and @p b are output units.
5058 * @param obj The given image object.
5059 * @param l Distance of the left border that is not to be stretched.
5060 * @param r Distance of the right border that is not to be stretched.
5061 * @param t Distance of the top border that is not to be stretched.
5062 * @param b Distance of the bottom border that is not to be stretched.
5064 EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1);
5067 * Retrieves how much of each border of the given image object is not
5070 * See @ref evas_object_image_border_set for more details.
5072 * @param obj The given image object.
5073 * @param l Location to store the left border width in, or @c NULL.
5074 * @param r Location to store the right border width in, or @c NULL.
5075 * @param t Location to store the top border width in, or @c NULL.
5076 * @param b Location to store the bottom border width in, or @c NULL.
5078 EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
5081 * Sets if the center part of the given image object (not the border)
5084 * When rendering, the image may be scaled to fit the size of the
5085 * image object. This function sets if the center part of the scaled
5086 * image is to be drawn or left completely blank, or forced to be
5087 * solid. Very useful for frames and decorations.
5089 * @param obj The given image object.
5090 * @param fill Fill mode of the middle.
5092 EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1);
5095 * Retrieves if the center of the given image object is to be drawn or
5098 * See @ref evas_object_image_fill_set for more details.
5100 * @param obj The given image object.
5101 * @return Fill mode of the center.
5103 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;
5106 * Sets if image fill property should track object size.
5108 * If set to true, then every evas_object_resize() will automatically
5109 * trigger call to evas_object_image_fill_set() with the new size so
5110 * image will fill the whole object area.
5112 * @param obj The given image object.
5113 * @param setting whether to follow object size.
5115 * @see evas_object_image_filled_add()
5116 * @see evas_object_image_fill_set()
5118 EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
5121 * Retrieves if image fill property is tracking object size.
5123 * @param obj The given image object.
5124 * @return 1 if it is tracking, 0 if not and evas_object_fill_set()
5125 * must be called manually.
5127 EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5130 * Sets a scale factor (multiplier) for the borders of an image
5132 * @param obj The given image object.
5133 * @param scale The scale factor (default is 1.0 - i.e. no scale)
5135 EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale);
5138 * Retrieves the border scale factor
5140 * See evas_object_image_border_scale_set()
5142 * @param obj The given image object.
5143 * @return The scale factor
5145 EAPI double evas_object_image_border_scale_get (const Evas_Object *obj);
5148 * Sets the rectangle of the given image object that the image will be
5151 * Note that the image will be tiled around this one rectangle. To
5152 * have only one copy of the image drawn, @p x and @p y must be 0 and
5153 * @p w and @p h need to be the width and height of the image object
5156 * The default values for the fill parameters is @p x = 0, @p y = 0,
5157 * @p w = 32 and @p h = 32.
5159 * @param obj The given image object.
5160 * @param x The X coordinate for the top left corner of the image.
5161 * @param y The Y coordinate for the top left corner of the image.
5162 * @param w The width of the image.
5163 * @param h The height of the image.
5165 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);
5168 * Retrieves the dimensions of the rectangle of the given image object
5169 * that the image will be drawn to.
5171 * See @ref evas_object_image_fill_set for more details.
5173 * @param obj The given image object.
5174 * @param x Location to store the X coordinate for the top left corner of the image in, or @c NULL.
5175 * @param y Location to store the Y coordinate for the top left corner of the image in, or @c NULL.
5176 * @param w Location to store the width of the image in, or @c NULL.
5177 * @param h Location to store the height of the image in, or @c NULL.
5179 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);
5182 * Sets the tiling mode for the given evas image object's fill.
5183 * @param obj The given evas image object.
5184 * @param spread One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT,
5185 * EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.
5187 EAPI void evas_object_image_fill_spread_set (Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1);
5190 * Retrieves the spread (tiling mode) for the given image object's
5193 * @param obj The given evas image object.
5194 * @return The current spread mode of the image object.
5196 EAPI Evas_Fill_Spread evas_object_image_fill_spread_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5199 * Sets the size of the given image object.
5201 * This function will scale down or crop the image so that it is
5202 * treated as if it were at the given size. If the size given is
5203 * smaller than the image, it will be cropped. If the size given is
5204 * larger, then the image will be treated as if it were in the upper
5205 * left hand corner of a larger image that is otherwise transparent.
5207 * @param obj The given image object.
5208 * @param w The new width of the image.
5209 * @param h The new height of the image.
5211 EAPI void evas_object_image_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
5214 * Retrieves the size of the given image object.
5216 * See @ref evas_object_image_size_set for more details.
5218 * @param obj The given image object.
5219 * @param w Location to store the width of the image in, or @c NULL.
5220 * @param h Location to store the height of the image in, or @c NULL.
5222 EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
5225 * Retrieves the row stride of the given image object,
5227 * The row stride is the number of units between the start of a
5228 * row and the start of the next row.
5230 * @param obj The given image object.
5231 * @return The stride of the image.
5233 EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5236 * Retrieves a number representing any error that occurred during the last
5237 * load of the given image object.
5239 * @param obj The given image object.
5240 * @return A value giving the last error that occurred. It should be one of
5241 * the @c EVAS_LOAD_ERROR_* values. @c EVAS_LOAD_ERROR_NONE is
5242 * returned if there was no error.
5244 EAPI Evas_Load_Error evas_object_image_load_error_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5247 * Sets the raw image data of the given image object.
5249 * Note that the raw data must be of the same size and colorspace of
5250 * the image. If data is NULL the current image data will be freed.
5252 * @param obj The given image object.
5253 * @param data The raw data, or @c NULL.
5255 EAPI void evas_object_image_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
5258 * Converts the raw image data of the given image object to the
5259 * specified colorspace.
5261 * Note that this function does not modify the raw image data. If the
5262 * requested colorspace is the same as the image colorspace nothing is
5263 * done and NULL is returned. You should use
5264 * evas_object_image_colorspace_get() to check the current image
5267 * See @ref evas_object_image_colorspace_get.
5269 * @param obj The given image object.
5270 * @param to_cspace The colorspace to which the image raw data will be converted.
5271 * @return data A newly allocated data in the format specified by to_cspace.
5273 EAPI void *evas_object_image_data_convert (Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5276 * Get a pointer to the raw image data of the given image object.
5278 * This function returns a pointer to an image object's internal pixel
5279 * buffer, for reading only or read/write. If you request it for
5280 * writing, the image will be marked dirty so that it gets redrawn at
5283 * This is best suited when you want to modify an existing image,
5284 * without changing its dimensions.
5286 * @param obj The given image object.
5287 * @param for_writing Whether the data being retrieved will be modified.
5288 * @return The raw image data.
5290 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;
5293 * Replaces the raw image data of the given image object.
5295 * This function lets the application replace an image object's
5296 * internal pixel buffer with a user-allocated one. For best results,
5297 * you should generally first call evas_object_image_size_set() with
5298 * the width and height for the new buffer.
5300 * This call is best suited for when you will be using image data with
5301 * different dimensions than the existing image data, if any. If you
5302 * only need to modify the existing image in some fashion, then using
5303 * evas_object_image_data_get() is probably what you are after.
5305 * Note that the caller is responsible for freeing the buffer when
5306 * finished with it, as user-set image data will not be automatically
5307 * freed when the image object is deleted.
5309 * See @ref evas_object_image_data_get for more details.
5311 * @param obj The given image object.
5312 * @param data The raw data.
5314 EAPI void evas_object_image_data_copy_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
5317 * Mark a sub-region of the given image object to be redrawn.
5319 * This function schedules a particular rectangular region of an image
5320 * object to be updated (redrawn) at the next render.
5322 * @param obj The given image object.
5323 * @param x X-offset of the region to be updated.
5324 * @param y Y-offset of the region to be updated.
5325 * @param w Width of the region to be updated.
5326 * @param h Height of the region to be updated.
5328 EAPI void evas_object_image_data_update_add (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
5331 * Enable or disable alpha channel of the given image object.
5333 * This function sets a flag on an image object indicating whether or
5334 * not to use alpha channel data. A value of 1 indicates to use alpha
5335 * channel data, and 0 indicates to ignore any alpha channel
5336 * data. Note that this has nothing to do with an object's color as
5337 * manipulated by evas_object_color_set().
5339 * @param obj The given image object.
5340 * @param has_alpha Whether to use alpha channel data or not.
5342 EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1);
5345 * @brief Retrieves the alpha channel setting of the given image object.
5347 * @param obj The given image object.
5348 * @return Whether the alpha channel data is being used.
5350 * This function returns 1 if the image object's alpha channel is
5351 * being used, or 0 otherwise.
5353 * See @ref evas_object_image_alpha_set for more details.
5355 EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5358 * Sets whether to use of high-quality image scaling algorithm
5359 * of the given image object.
5361 * When enabled, a higher quality image scaling algorithm is used when
5362 * scaling images to sizes other than the source image. This gives
5363 * better results but is more computationally expensive.
5365 * @param obj The given image object.
5366 * @param smooth_scale Whether to use smooth scale or not.
5368 EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1);
5371 * Retrieves whether the given image object is using use a
5372 * high-quality image scaling algorithm.
5374 * See @ref evas_object_image_smooth_scale_set for more details.
5376 * @param obj The given image object.
5377 * @return Whether smooth scale is being used.
5379 EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5382 * Preload image in the background
5384 * This function request the preload of the data image in the
5385 * background. The worked is queued before being processed.
5387 * If image data is already loaded, it will callback
5388 * EVAS_CALLBACK_IMAGE_PRELOADED immediately and do nothing else.
5390 * If cancel is set, it will remove the image from the workqueue.
5392 * @param obj The given image object.
5393 * @param cancel 0 means add to the workqueue, 1 remove it.
5395 EAPI void evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1);
5398 * Reload a image of the canvas.
5400 * @param obj The given image object pointer.
5402 * This function reloads a image of the given canvas.
5405 EAPI void evas_object_image_reload (Evas_Object *obj) EINA_ARG_NONNULL(1);
5408 * Save the given image object to a file.
5410 * Note that you should pass the filename extension when saving. If
5411 * the file supports multiple data stored in it as eet, you can
5412 * specify the key to be used as the index of the image in this file.
5414 * You can specify some flags when saving the image. Currently
5415 * acceptable flags are quality and compress. Eg.: "quality=100
5418 * @param obj The given image object.
5419 * @param file The filename to be used to save the image.
5420 * @param key The image key in file, or @c NULL.
5421 * @param flags String containing the flags to be used.
5423 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);
5426 * Import pixels from given source to a given canvas image object.
5428 * @param obj The given canvas object.
5429 * @param pixels The pixel's source to be imported.
5431 * This function imports pixels from a given source to a given canvas image.
5434 EAPI Eina_Bool evas_object_image_pixels_import (Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2);
5437 * Set the callback function to get pixels from a canva's image.
5439 * @param obj The given canvas pointer.
5440 * @param func The callback function.
5441 * @param data The data pointer to be passed to @a func.
5443 * This functions sets a function to be the callback function that get
5444 * pixes from a image of the canvas.
5447 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);
5450 * Mark whether the given image object is dirty (needs to be redrawn).
5452 * @param obj The given image object.
5453 * @param dirty Whether the image is dirty.
5455 EAPI void evas_object_image_pixels_dirty_set (Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1);
5458 * Retrieves whether the given image object is dirty (needs to be redrawn).
5460 * @param obj The given image object.
5461 * @return Whether the image is dirty.
5463 EAPI Eina_Bool evas_object_image_pixels_dirty_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5466 * Set the dpi resolution of a loaded image of the canvas.
5468 * @param obj The given canvas pointer.
5469 * @param dpi The new dpi resolution.
5471 * This function set the dpi resolution of a given loaded canvas image.
5474 EAPI void evas_object_image_load_dpi_set (Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1);
5477 * Get the dpi resolution of a loaded image of the canvas.
5479 * @param obj The given canvas pointer.
5480 * @return The dpi resolution of the given canvas image.
5482 * This function returns the dpi resolution of given canvas image.
5485 EAPI double evas_object_image_load_dpi_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5488 * Set the size of a loaded image of the canvas.
5490 * @param obj The given canvas object.
5491 * @param w The new width of the canvas image given.
5492 * @param h The new height of the canvas image given.
5494 * This function sets a new size for the given canvas image.
5497 EAPI void evas_object_image_load_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
5500 * Get the size of a loaded image of the canvas.
5502 * @param obj The given image object.
5503 * @param w The width of the canvas image given.
5504 * @param h The height of the canvas image given.
5506 * This function get the size of the given canvas image.
5509 EAPI void evas_object_image_load_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
5512 * Set the scale down of a loaded image of the canvas.
5514 * @param obj The given image object pointer.
5515 * @param scale_down The scale to down value.
5517 * This function sets the scale down of a given canvas image.
5520 EAPI void evas_object_image_load_scale_down_set (Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1);
5523 * Get the scale down value of given image of the canvas.
5525 * @param obj The given image object pointer.
5527 * This function returns the scale down value of a given canvas image.
5530 EAPI int evas_object_image_load_scale_down_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5531 EAPI void evas_object_image_load_region_set (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
5532 EAPI void evas_object_image_load_region_get (const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
5535 * Define if the orientation information in the image file should be honored.
5537 * @param obj The given image object pointer.
5538 * @param enable @p EINA_TRUE means that it should honor the orientation information
5541 EAPI void evas_object_image_load_orientation_set (Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
5544 * Get if the orientation information in the image file should be honored.
5546 * @param obj The given image object pointer.
5549 EAPI Eina_Bool evas_object_image_load_orientation_get (const Evas_Object *obj) EINA_ARG_NONNULL(1);
5552 * Set the colorspace of a given image of the canvas.
5554 * @param obj The given image object pointer.
5555 * @param cspace The new color space.
5557 * This function sets the colorspace of given canvas image.
5560 EAPI void evas_object_image_colorspace_set (Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1);
5563 * Get the colorspace of a given image of the canvas.
5565 * @param obj The given image object pointer.
5566 * @return The colorspace of the image.
5568 * This function returns the colorspace of given canvas image.
5571 EAPI Evas_Colorspace evas_object_image_colorspace_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5574 * Set the native surface of a given image of the canvas
5576 * @param obj The given canvas pointer.
5577 * @param surf The new native surface.
5579 * This function sets a native surface of a given canvas image.
5582 EAPI void evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2);
5585 * Get the native surface of a given image of the canvas
5587 * @param obj The given canvas pointer.
5588 * @return The native surface of the given canvas image.
5590 * This function returns the native surface of a given canvas image.
5593 EAPI Evas_Native_Surface *evas_object_image_native_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5596 * Set the scale hint of a given image of the canvas.
5598 * @param obj The given canvas pointer.
5599 * @param hint The scale hint value.
5601 * This function sets the scale hint value of the given image of the canvas.
5604 EAPI void evas_object_image_scale_hint_set (Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1);
5607 * Get the scale hint of a given image of the canvas.
5609 * @param obj The given canvas pointer.
5611 * This function returns the scale hint value of the given image of the canvas.
5614 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;
5617 * Set the content hint of a given image of the canvas.
5619 * @param obj The given canvas pointer.
5620 * @param hint The content hint value.
5622 * This function sets the content hint value of the given image of the canvas.
5625 EAPI void evas_object_image_content_hint_set (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1);
5628 * Get the content hint of a given image of the canvas.
5630 * @param obj The given canvas pointer.
5632 * This function returns the content hint value of the given image of the canvas.
5635 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;
5639 * Enable an image to be used as an alpha mask.
5641 * This will set any flags, and discard any excess image data not used as an
5644 * Note there is little point in using a image as alpha mask unless it has an
5647 * @param obj Object to use as an alpha mask.
5648 * @param ismask Use image as alphamask, must be true.
5650 EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1);
5653 * Set the source object on a proxy object.
5655 * The source must be another object. The proxy will have the same base
5656 * appearance of the source object. Obviously other effects may be applied to
5657 * the proxy, such as a map to create a reflection of the original object.
5659 * Any existing source object will be removed. Setting the src to NULL clears
5662 * You cannot set a proxy on a proxy.
5664 * @param obj Proxy object.
5665 * @param src Source of the proxy.
5666 * @return EINA_TRUE on success, EINA_FALSE on error.
5668 EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1);
5671 * Get the current source object of an image.
5673 * @param obj Image object
5674 * @return Source object, or @c NULL on error.
5676 EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1);
5679 * Clear the source on a proxy image.
5681 * This is equivalent to calling evas_object_image_source_set with a NULL
5684 * @param obj Image object to clear source of.
5685 * @return EINA_TRUE on success, EINA_FALSE on error.
5687 EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1);
5690 * Check if a file extention may be supported by @ref Evas_Object_Image.
5692 * @param file The file to check
5693 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
5696 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
5698 * This functions is threadsafe.
5700 EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
5703 * Check if a file extention may be supported by @ref Evas_Object_Image.
5705 * @param file The file to check, it should be an Eina_Stringshare.
5706 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
5709 * This functions is threadsafe.
5711 EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
5714 * @defgroup Evas_Object_Text Text Object Functions
5716 * Functions that operate on single line, single style text objects.
5718 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
5720 * @ingroup Evas_Object_Specific
5722 typedef enum _Evas_Text_Style_Type
5724 /* basic styles (4 bits allocatedm use 0->10 now, 5 left) */
5725 #define EVAS_TEXT_STYLE_MASK_BASIC 0xf
5726 #define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
5727 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
5728 EVAS_TEXT_STYLE_PLAIN,
5729 EVAS_TEXT_STYLE_SHADOW,
5730 EVAS_TEXT_STYLE_OUTLINE,
5731 EVAS_TEXT_STYLE_SOFT_OUTLINE,
5732 EVAS_TEXT_STYLE_GLOW,
5733 EVAS_TEXT_STYLE_OUTLINE_SHADOW,
5734 EVAS_TEXT_STYLE_FAR_SHADOW,
5735 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW,
5736 EVAS_TEXT_STYLE_SOFT_SHADOW,
5737 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW,
5739 #define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
5740 #define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
5741 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
5742 /* OR these to modify shadow direction (3 bits needed) */
5743 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4),
5744 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4),
5745 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4),
5746 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4),
5747 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4),
5748 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4),
5749 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4),
5750 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4)
5751 } Evas_Text_Style_Type;
5754 * Creates a new text @c Evas_Object on the provided @c Evas canvas.
5756 * @param e The @c Evas canvas to create the text object upon.
5758 * @see evas_object_text_font_source_set
5759 * @see evas_object_text_font_set
5760 * @see evas_object_text_text_set
5762 * @returns NULL on error, A pointer to a new @c Evas_Object on success.
5764 EAPI Evas_Object *evas_object_text_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5766 EAPI void evas_object_text_font_source_set (Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1);
5767 EAPI const char *evas_object_text_font_source_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5768 EAPI void evas_object_text_font_set (Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1);
5771 * Query evas for font information of a text @c Evas_Object.
5773 * This function allows the font name and size of a text @c Evas_Object as
5774 * created with evas_object_text_add() to be queried. Be aware that the font
5775 * name string is still owned by Evas and should NOT have free() called on
5776 * it by the caller of the function.
5778 * @param obj The evas text object to query for font information.
5779 * @param font A pointer to the location to store the font name in (may be NULL).
5780 * @param size A pointer to the location to store the font size in (may be NULL).
5782 EAPI void evas_object_text_font_get (const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1, 2);
5785 * Sets the text to be displayed by the given evas text object.
5786 * @param obj Evas text object.
5787 * @param text Text to display.
5789 EAPI void evas_object_text_text_set (Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
5792 * @brief Sets the BiDi delimiters used in the textblock.
5794 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
5795 * is useful for example in recipients fields of e-mail clients where bidi
5796 * oddities can occur when mixing rtl and ltr.
5798 * @param obj The given text object.
5799 * @param delim A null terminated string of delimiters, e.g ",|".
5802 EAPI void evas_object_text_bidi_delimiters_set(Evas_Object *obj, const char *delim);
5805 * @brief Gets the BiDi delimiters used in the textblock.
5807 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
5808 * is useful for example in recipients fields of e-mail clients where bidi
5809 * oddities can occur when mixing rtl and ltr.
5811 * @param obj The given text object.
5812 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
5815 EAPI const char *evas_object_text_bidi_delimiters_get(const Evas_Object *obj);
5818 * Retrieves the text currently being displayed by the given evas text object.
5819 * @param obj The given evas text object.
5820 * @return The text currently being displayed. Do not free it.
5822 EAPI const char *evas_object_text_text_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5823 EAPI Evas_Coord evas_object_text_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5824 EAPI Evas_Coord evas_object_text_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5825 EAPI Evas_Coord evas_object_text_max_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5826 EAPI Evas_Coord evas_object_text_max_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5827 EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5828 EAPI Evas_Coord evas_object_text_vert_advance_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5829 EAPI Evas_Coord evas_object_text_inset_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5832 * Retrieve position and dimension information of a character within a text @c Evas_Object.
5834 * This function is used to obtain the X, Y, width and height of a the character
5835 * located at @p pos within the @c Evas_Object @p obj. @p obj must be a text object
5836 * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx,
5837 * @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to that
5840 * @param obj The text object to retrieve position information for.
5841 * @param pos The character position to request co-ordinates for.
5842 * @param cx A pointer to an @c Evas_Coord to store the X value in (can be NULL).
5843 * @param cy A pointer to an @c Evas_Coord to store the Y value in (can be NULL).
5844 * @param cw A pointer to an @c Evas_Coord to store the Width value in (can be NULL).
5845 * @param ch A pointer to an @c Evas_Coord to store the Height value in (can be NULL).
5847 * @returns EINA_FALSE on error, EINA_TRUE on success.
5849 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);
5850 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);
5853 * Returns the logical position of the last char in the text
5854 * up to the pos given. this is NOT the position of the last char
5855 * because of the possibility of RTL in the text.
5857 EAPI int evas_object_text_last_up_to_pos (const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
5858 EAPI Evas_Text_Style_Type evas_object_text_style_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5859 EAPI void evas_object_text_style_set (Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1);
5860 EAPI void evas_object_text_shadow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
5861 EAPI void evas_object_text_shadow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
5862 EAPI void evas_object_text_glow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
5863 EAPI void evas_object_text_glow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
5864 EAPI void evas_object_text_glow2_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
5865 EAPI void evas_object_text_glow2_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
5866 EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
5867 EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
5870 * Gets the text style pad of a text object.
5872 * @param obj The given text object.
5873 * @param l The left pad (or @c NULL).
5874 * @param r The right pad (or @c NULL).
5875 * @param t The top pad (or @c NULL).
5876 * @param b The bottom pad (or @c NULL).
5879 EAPI void evas_object_text_style_pad_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
5882 * Retrieves the direction of the text currently being displayed in the
5884 * @param obj The given evas text object.
5885 * @return the direction of the text
5887 EAPI Evas_BiDi_Direction evas_object_text_direction_get (const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
5890 * @defgroup Evas_Object_Textblock Textblock Object Functions
5892 * Functions used to create and manipulate textblock objects. Unlike
5893 * @ref Evas_Object_Text, these handle complex text, doing multiple
5894 * styles and multiline text based on HTML-like tags. Of these extra
5895 * features will be heavier on memory and processing cost.
5897 * @todo put here some usage examples
5899 * @ingroup Evas_Object_Specific
5903 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
5905 * This part explains about the textblock object's API and proper usage.
5906 * If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal.
5907 * The main user of the textblock object is the edje entry object in Edje, so
5908 * that's a good place to learn from, but I think this document is more than
5909 * enough, if it's not, please request for me info and I'll update it.
5911 * @subsection textblock_intro Introduction
5912 * The textblock objects is, as implied, an object that can show big chunks of
5913 * text. Textblock supports many features including: Text formatting, automatic
5914 * and manual text alignment, embedding items (for example icons) and more.
5915 * Textblock has three important parts, the text paragraphs, the format nodes
5918 * @subsection textblock_cursors Textblock Object Cursors
5919 * A textblock Cursor @ref Evas_Textblock_Cursor is data type that represents
5920 * a position in a textblock. Each cursor contains information about the
5921 * paragraph it points to, the position in that paragraph and the object itself.
5922 * Cursors register to textblock objects upon creation, this means that once
5923 * you created a cursor, it belongs to a specific obj and you can't for example
5924 * copy a cursor "into" a cursor of a different object. Registered cursors
5925 * also have the added benefit of updating automatically upon textblock changes,
5926 * this means that if you have a cursor pointing to a specific character, it'll
5927 * still point to it even after you change the whole object completely (as long
5928 * as the char was not deleted), this is not possible without updating, because
5929 * as mentioned, each cursor holds a character position. There are many
5930 * functions that handle cursors, just check out the evas_textblock_cursor*
5931 * functions. For creation and deletion of cursors check out:
5932 * @see evas_object_textblock_cursor_new()
5933 * @see evas_textblock_cursor_free()
5934 * @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).
5936 * @subsection textblock_paragraphs Textblock Object Paragraphs
5937 * The textblock object is made out of text splitted to paragraphs (delimited
5938 * by the paragraph separation character). Each paragraph has many (or none)
5939 * format nodes associated with it which are responsible for the formatting
5940 * of that paragraph.
5942 * @subsection textblock_format_nodes Textblock Object Format Nodes
5943 * As explained in @ref textblock_paragraphs each one of the format nodes
5944 * is associated with a paragraph.
5945 * There are two types of format nodes, visible and invisible:
5946 * Visible: formats that a cursor can point to, i.e formats that
5947 * occupy space, for example: newlines, tabs, items and etc. Some visible items
5948 * are made of two parts, in this case, only the opening tag is visible.
5949 * A closing tag (i.e a </tag> tag) should NEVER be visible.
5950 * Invisible: formats that don't occupy space, for example: bold and underline.
5951 * Being able to access format nodes is very important for some uses. For
5952 * example, edje uses the "<a>" format to create links in the text (and pop
5953 * popups above them when clicked). For the textblock object a is just a
5954 * formatting instruction (how to color the text), but edje utilizes the access
5955 * to the format nodes to make it do more.
5956 * For more information, take a look at all the evas_textblock_node_format_*
5958 * The translation of "<tag>" tags to actual format is done according to the
5959 * tags defined in the style, see @ref evas_textblock_style_set
5961 * @subsection textblock_special_formats Special Formats
5962 * This section is not yet written. If you want some info about styles/formats
5963 * and how to use them, expedite's textblock_basic test is a great start.
5964 * @todo Write @textblock_special_formats
5966 typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
5967 typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
5969 * @typedef Evas_Object_Textblock_Node_Format
5972 typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
5973 typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
5975 struct _Evas_Textblock_Rectangle
5977 Evas_Coord x, y, w, h;
5980 typedef enum _Evas_Textblock_Text_Type
5982 EVAS_TEXTBLOCK_TEXT_RAW,
5983 EVAS_TEXTBLOCK_TEXT_PLAIN,
5984 EVAS_TEXTBLOCK_TEXT_MARKUP
5985 } Evas_Textblock_Text_Type;
5987 typedef enum _Evas_Textblock_Cursor_Type
5989 EVAS_TEXTBLOCK_CURSOR_UNDER,
5990 EVAS_TEXTBLOCK_CURSOR_BEFORE
5991 } Evas_Textblock_Cursor_Type;
5995 * Adds a textblock to the given evas.
5996 * @param e The given evas.
5997 * @return The new textblock object.
5999 EAPI Evas_Object *evas_object_textblock_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6003 * Returns the unescaped version of escape.
6004 * @param escape the string to be escaped
6005 * @return the unescaped version of escape
6007 EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6010 * Returns the escaped version of the string.
6011 * @param string to escape
6012 * @param len_ret the len of the new escape
6013 * @return the escaped string.
6015 EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6018 * Return the unescaped version of the string between start and end.
6020 * @param escape_start the start of the string.
6021 * @param escape_end the end of the string.
6022 * @return the unescaped version of the range
6024 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;
6028 * Creates a new textblock style.
6029 * @return The new textblock style.
6031 EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
6034 * Destroys a textblock style.
6035 * @param ts The textblock style to free.
6037 EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
6040 * Sets the style ts to the style passed as text by text.
6041 * Expected a string consisting of many (or none) tag='format' pairs.
6043 * @param ts the style to set.
6044 * @param text the text to parse - NOT NULL.
6045 * @return Returns no value.
6047 EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
6050 * Return the text of the style ts.
6051 * @param ts the style to get it's text.
6052 * @return the text of the style or null on error.
6054 EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6058 * Set the objects style to ts.
6059 * @param obj the Evas object to set the style to.
6060 * @param ts the style to set.
6061 * @return Returns no value.
6063 EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
6066 * Return the style of an object.
6067 * @param obj the object to get the style from.
6068 * @return the style of the object.
6070 EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6073 * @brief Set the "replacement character" to use for the given textblock object.
6075 * @param obj The given textblock object.
6076 * @param ch The charset name.
6078 EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1);
6081 * @brief Get the "replacement character" for given textblock object. Returns
6082 * NULL if no replacement character is in use.
6084 * @param obj The given textblock object
6085 * @return replacement character or @c NULL
6087 EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6090 * @brief Sets the vertical alignment of text within the textblock object
6093 * Normally alignment is 0.0 (top of object). Values given should be
6094 * between 0.0 and 1.0 (1.0 bottom of object, 0.5 being vertically centered
6097 * @param obj The given textblock object.
6098 * @param align A value between 0.0 and 1.0
6101 EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align);
6104 * @brief Gets the vertical alignment of a textblock
6106 * @param obj The given textblock object.
6107 * @return The elignment set for the object
6110 EAPI double evas_object_textblock_valign_get(const Evas_Object *obj);
6113 * @brief Sets the BiDi delimiters used in the textblock.
6115 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
6116 * is useful for example in recipients fields of e-mail clients where bidi
6117 * oddities can occur when mixing rtl and ltr.
6119 * @param obj The given textblock object.
6120 * @param delim A null terminated string of delimiters, e.g ",|".
6123 EAPI void evas_object_textblock_bidi_delimiters_set(Evas_Object *obj, const char *delim);
6126 * @brief Gets the BiDi delimiters used in the textblock.
6128 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
6129 * is useful for example in recipients fields of e-mail clients where bidi
6130 * oddities can occur when mixing rtl and ltr.
6132 * @param obj The given textblock object.
6133 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
6136 EAPI const char *evas_object_textblock_bidi_delimiters_get(const Evas_Object *obj);
6139 * @brief Sets newline mode. When true, newline character will behave
6140 * as a paragraph separator.
6142 * @param obj The given textblock object.
6143 * @param mode EINA_TRUE for PS mode, EINA_FALSE otherwise.
6146 EAPI void evas_object_textblock_newline_mode_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1);
6149 * @brief Gets newline mode. When true, newline character behaves
6150 * as a paragraph separator.
6152 * @param obj The given textblock object.
6153 * @return EINA_TRUE if in PS mode, EINA_FALSE otherwise.
6156 EAPI Eina_Bool evas_object_textblock_newline_mode_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6160 * Sets the tetxblock's text to the markup text.
6162 * @note assumes text does not include the unicode object replacement char (0xFFFC)
6164 * @param obj the textblock object.
6165 * @param text the markup text to use.
6166 * @return Return no value.
6168 EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
6171 * Prepends markup to the cursor cur.
6173 * @note assumes text does not include the unicode object replacement char (0xFFFC)
6175 * @param cur the cursor to prepend to.
6176 * @param text the markup text to prepend.
6177 * @return Return no value.
6179 EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6182 * Return the markup of the object.
6184 * @param obj the Evas object.
6185 * @return the markup text of the object.
6187 EAPI const char *evas_object_textblock_text_markup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6191 * Return the object's main cursor.
6193 * @param obj the object.
6194 * @return the obj's main cursor.
6196 EAPI const Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6199 * Create a new cursor, associate it to the obj and init it to point
6200 * to the start of the textblock. Association to the object means the cursor
6201 * will be updated when the object will change.
6203 * @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).
6205 * @param obj the object to associate to.
6206 * @return the new cursor.
6208 EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6212 * Free the cursor and unassociate it from the object.
6213 * @note do not use it to free unassociated cursors.
6215 * @param cur the cursor to free.
6216 * @return Returns no value.
6218 EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6222 * Sets the cursor to the start of the first text node.
6224 * @param cur the cursor to update.
6225 * @return Returns no value.
6227 EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6230 * sets the cursor to the end of the last text node.
6232 * @param cur the cursor to set.
6233 * @return Returns no value.
6235 EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6238 * Advances to the start of the next text node
6240 * @param cur the cursor to update
6241 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
6243 EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6246 * Advances to the end of the previous text node
6248 * @param cur the cursor to update
6249 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
6251 EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6256 * @param obj The evas, must not be NULL.
6257 * @param anchor the anchor name to get
6258 * @return Returns the list format node corresponding to the anchor, may be null if there are none.
6260 EAPI const Eina_List *evas_textblock_node_format_list_get(const Evas_Object *obj, const char *anchor) EINA_ARG_NONNULL(1, 2);
6263 * Returns the first format node.
6265 * @param obj The evas, must not be NULL.
6266 * @return Returns the first format node, may be null if there are none.
6268 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6271 * Returns the last format node.
6273 * @param obj The evas textblock, must not be NULL.
6274 * @return Returns the first format node, may be null if there are none.
6276 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6279 * Returns the next format node (after n)
6281 * @param n the current format node - not null.
6282 * @return Returns the next format node, may be null.
6284 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
6287 * Returns the prev format node (after n)
6289 * @param n the current format node - not null.
6290 * @return Returns the prev format node, may be null.
6292 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
6295 * Remove a format node and it's match. i.e, removes a <tag> </tag> pair.
6296 * Assumes the node is the first part of <tag> i.e, this won't work if
6297 * n is a closing tag.
6299 * @param obj the Evas object of the textblock - not null.
6300 * @param n the current format node - not null.
6302 EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
6305 * Sets the cursor to point to the place where format points to.
6307 * @param cur the cursor to update.
6308 * @param n the format node to update according.
6310 EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
6313 * Return the format node at the position pointed by cur.
6315 * @param cur the position to look at.
6316 * @return the format node if found, NULL otherwise.
6317 * @see evas_textblock_cursor_format_is_visible_get()
6319 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6322 * Get the text format representation of the format node.
6324 * @param fmt the format node.
6325 * @return the textual format of the format node.
6327 EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6330 * Set the cursor to point to the position of fmt.
6332 * @param cur the cursor to update
6333 * @param fmt the format to update according to.
6335 EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
6338 * Check if the current cursor position is a visible format. This way is more
6339 * efficient than evas_textblock_cursor_format_get() to check for the existence
6340 * of a visible format.
6342 * @param cur the cursor to look at.
6343 * @return #EINA_TRUE if the cursor points to a visible format, #EINA_FALSE otherwise.
6344 * @see evas_textblock_cursor_format_get()
6346 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;
6349 * Advances to the next format node
6351 * @param cur the cursor to be updated.
6352 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6354 EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6357 * Advances to the previous format node.
6359 * @param cur the cursor to update.
6360 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6362 EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6365 * Returns true if the cursor points to a format.
6367 * @param cur the cursor to check.
6368 * @return Returns #EINA_TRUE if a cursor points to a format #EINA_FALSE otherwise.
6370 EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6373 * Advances 1 char forward.
6375 * @param cur the cursor to advance.
6376 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6378 EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6381 * Advances 1 char backward.
6383 * @param cur the cursor to advance.
6384 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6386 EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6389 * Go to the first char in the node the cursor is pointing on.
6391 * @param cur the cursor to update.
6392 * @return Returns no value.
6394 EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6397 * Go to the last char in a text node.
6399 * @param cur the cursor to update.
6400 * @return Returns no value.
6402 EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6405 * Go to the start of the current line
6407 * @param cur the cursor to update.
6408 * @return Returns no value.
6410 EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6413 * Go to the end of the current line.
6415 * @param cur the cursor to update.
6416 * @return Returns no value.
6418 EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6421 * Return the current cursor pos.
6423 * @param cur the cursor to take the position from.
6424 * @return the position or -1 on error
6426 EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6429 * Set the cursor pos.
6431 * @param cur the cursor to be set.
6432 * @param pos the pos to set.
6434 EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
6437 * Go to the start of the line passed
6439 * @param cur cursor to update.
6440 * @param line numer to set.
6441 * @return #EINA_TRUE on success, #EINA_FALSE on error.
6443 EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
6446 * Compare two cursors.
6448 * @param cur1 the first cursor.
6449 * @param cur2 the second cursor.
6450 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
6452 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;
6455 * Make cur_dest point to the same place as cur. Does not work if they don't
6456 * point to the same object.
6458 * @param cur the source cursor.
6459 * @param cur_dest destination cursor.
6460 * @return Returns no value.
6462 EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
6466 * Adds text to the current cursor position and set the cursor to *before*
6467 * the start of the text just added.
6469 * @param cur the cursor to where to add text at.
6470 * @param _text the text to add.
6471 * @return Returns the len of the text added.
6472 * @see evas_textblock_cursor_text_prepend()
6474 EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6477 * Adds text to the current cursor position and set the cursor to *after*
6478 * the start of the text just added.
6480 * @param cur the cursor to where to add text at.
6481 * @param _text the text to add.
6482 * @return Returns the len of the text added.
6483 * @see evas_textblock_cursor_text_append()
6485 EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6489 * Adds format to the current cursor position. If the format being added is a
6490 * visible format, add it *before* the cursor position, otherwise, add it after.
6491 * This behavior is because visible formats are like characters and invisible
6492 * should be stacked in a way that the last one is added last.
6494 * This function works with native formats, that means that style defined
6495 * tags like <br> won't work here. For those kind of things use markup prepend.
6497 * @param cur the cursor to where to add format at.
6498 * @param format the format to add.
6499 * @return Returns true if a visible format was added, false otherwise.
6500 * @see evas_textblock_cursor_format_prepend()
6504 * Check if the current cursor position points to the terminating null of the
6505 * last paragraph. (shouldn't be allowed to point to the terminating null of
6506 * any previous paragraph anyway.
6508 * @param cur the cursor to look at.
6509 * @return #EINA_TRUE if the cursor points to the terminating null, #EINA_FALSE otherwise.
6511 EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
6514 * Adds format to the current cursor position. If the format being added is a
6515 * visible format, add it *before* the cursor position, otherwise, add it after.
6516 * This behavior is because visible formats are like characters and invisible
6517 * should be stacked in a way that the last one is added last.
6518 * If the format is visible the cursor is advanced after it.
6520 * This function works with native formats, that means that style defined
6521 * tags like <br> won't work here. For those kind of things use markup prepend.
6523 * @param cur the cursor to where to add format at.
6524 * @param format the format to add.
6525 * @return Returns true if a visible format was added, false otherwise.
6526 * @see evas_textblock_cursor_format_prepend()
6528 EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
6531 * Delete the character at the location of the cursor. If there's a format
6532 * pointing to this position, delete it as well.
6534 * @param cur the cursor pointing to the current location.
6535 * @return Returns no value.
6537 EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6540 * Delete the range between cur1 and cur2.
6542 * @param cur1 one side of the range.
6543 * @param cur2 the second side of the range
6544 * @return Returns no value.
6546 EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
6550 * Return the text of the paragraph cur points to - returns the text in markup..
6552 * @param cur the cursor pointing to the paragraph.
6553 * @return the text on success, NULL otherwise.
6555 EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6558 * Return the length of the paragraph, cheaper the eina_unicode_strlen()
6560 * @param cur the position of the paragraph.
6561 * @return the length of the paragraph on success, -1 otehrwise.
6563 EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6566 * Return the text in the range between cur1 and cur2
6568 * FIXME: format is currently unused, you always get markup back.
6570 * @param cur1 one side of the range.
6571 * @param cur2 the other side of the range
6572 * @param format to be documented
6573 * @return the text in the range
6574 * @see elm_entry_markup_to_utf8()
6576 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;
6579 * Return the content of the cursor.
6581 * @param cur the cursor
6582 * @return the text in the range
6584 EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6588 * Returns the geometry of the cursor. Depends on the type of cursor requested.
6589 * This should be used instead of char_geometry_get because there are weird
6590 * special cases with BiDi text.
6591 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
6592 * get, except for the case of the last char of a line which depends on the
6593 * paragraph direction.
6595 * in '|' cursor mode (i.e a line between two chars) it is very varyable.
6596 * For example consider the following visual string:
6597 * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
6598 * a '|' between the c and the C.
6600 * @param cur the cursor.
6601 * @param cx the x of the cursor
6602 * @param cy the y of the cursor
6603 * @param cw the width of the cursor
6604 * @param ch the height of the cursor
6605 * @param dir the direction of the cursor, can be NULL.
6606 * @param ctype the type of the cursor.
6607 * @return line number of the char on success, -1 on error.
6609 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);
6612 * Returns the geometry of the char at cur.
6614 * @param cur the position of the char.
6615 * @param cx the x of the char.
6616 * @param cy the y of the char.
6617 * @param cw the w of the char.
6618 * @param ch the h of the char.
6619 * @return line number of the char on success, -1 on error.
6621 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);
6624 * Returns the geometry of the pen at cur.
6626 * @param cur the position of the char.
6627 * @param cpen_x the pen_x of the char.
6628 * @param cy the y of the char.
6629 * @param cadv the adv of the char.
6630 * @param ch the h of the char.
6631 * @return line number of the char on success, -1 on error.
6633 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);
6636 * Returns the geometry of the line at cur.
6638 * @param cur the position of the line.
6639 * @param cx the x of the line.
6640 * @param cy the y of the line.
6641 * @param cw the width of the line.
6642 * @param ch the height of the line.
6643 * @return line number of the line on success, -1 on error.
6645 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);
6648 * Set the position of the cursor according to the X and Y coordinates.
6650 * @param cur the cursor to set.
6651 * @param x coord to set by.
6652 * @param y coord to set by.
6653 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
6655 EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
6658 * Set the cursor position according to the y coord.
6660 * @param cur the cur to be set.
6661 * @param y the coord to set by.
6662 * @return the line number found, -1 on error.
6664 EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
6667 * Get the geometry of a range.
6669 * @param cur1 one side of the range.
6670 * @param cur2 other side of the range.
6671 * @return a list of Rectangles representing the geometry of the range.
6673 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;
6674 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);
6678 * Checks if the cursor points to the end of the line.
6680 * @param cur the cursor to check.
6681 * @return #EINA_TRUE if true, #EINA_FALSE otherwise.
6683 EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6687 * Get the geometry of a line number.
6689 * @param obj the object.
6690 * @param line the line number.
6691 * @param cx x coord of the line.
6692 * @param cy y coord of the line.
6693 * @param cw w coord of the line.
6694 * @param ch h coord of the line.
6695 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
6697 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);
6700 * Clear the textblock object.
6701 * @note Does *NOT* free the Evas object itself.
6703 * @param obj the object to clear.
6706 EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
6709 * Get the formatted width and height. This calculates the actual size after restricting
6710 * the textblock to the current size of the object.
6711 * The main difference between this and @ref evas_object_textblock_size_native_get
6712 * is that the "native" function does not wrapping into account
6713 * it just calculates the real width of the object if it was placed on an
6714 * infinite canvas, while this function gives the size after wrapping
6715 * according to the size restrictions of the object.
6717 * For example for a textblock containing the text: "You shall not pass!"
6718 * with no margins or padding and assuming a monospace font and a size of
6719 * 7x10 char widths (for simplicity) has a native size of 19x1
6720 * and a formatted size of 5x4.
6723 * @param obj the Evas object.
6724 * @param w[out] the width of the object.
6725 * @param h[out] the height of the object
6726 * @return Returns no value.
6727 * @see evas_object_textblock_size_native_get
6729 EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
6732 * Get the native width and height. This calculates the actual size without taking account
6733 * the current size of the object.
6734 * The main difference between this and @ref evas_object_textblock_size_formatted_get
6735 * is that the "native" function does not take wrapping into account
6736 * it just calculates the real width of the object if it was placed on an
6737 * infinite canvas, while the "formatted" function gives the size after
6738 * wrapping text according to the size restrictions of the object.
6740 * For example for a textblock containing the text: "You shall not pass!"
6741 * with no margins or padding and assuming a monospace font and a size of
6742 * 7x10 char widths (for simplicity) has a native size of 19x1
6743 * and a formatted size of 5x4.
6745 * @param obj the Evas object of the textblock
6746 * @param w[out] the width returned
6747 * @param h[out] the height returned
6748 * @return Returns no value.
6750 EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
6751 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);
6754 * @defgroup Evas_Line_Group Line Object Functions
6756 * Functions used to deal with evas line objects.
6758 * @ingroup Evas_Object_Specific
6762 * Adds a new evas line object to the given evas.
6763 * @param e The given evas.
6764 * @return The new evas line object.
6766 EAPI Evas_Object *evas_object_line_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6769 * Sets the coordinates of the end points of the given evas line object.
6770 * @param obj The given evas line object.
6771 * @param x1 The X coordinate of the first point.
6772 * @param y1 The Y coordinate of the first point.
6773 * @param x2 The X coordinate of the second point.
6774 * @param y2 The Y coordinate of the second point.
6776 EAPI void evas_object_line_xy_set (Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2);
6779 * Retrieves the coordinates of the end points of the given evas line object.
6780 * @param obj The given line object.
6781 * @param x1 Pointer to an integer in which to store the X coordinate of the
6783 * @param y1 Pointer to an integer in which to store the Y coordinate of the
6785 * @param x2 Pointer to an integer in which to store the X coordinate of the
6787 * @param y2 Pointer to an integer in which to store the Y coordinate of the
6790 EAPI void evas_object_line_xy_get (const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2);
6793 * @defgroup Evas_Object_Polygon Polygon Object Functions
6795 * Functions that operate on evas polygon objects.
6797 * Hint: as evas does not provide ellipse, smooth paths or circle, one
6798 * can calculate points and convert these to a polygon.
6800 * @ingroup Evas_Object_Specific
6804 * Adds a new evas polygon object to the given evas.
6805 * @param e The given evas.
6806 * @return A new evas polygon object.
6808 EAPI Evas_Object *evas_object_polygon_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6811 * Adds the given point to the given evas polygon object.
6812 * @param obj The given evas polygon object.
6813 * @param x The X coordinate of the given point.
6814 * @param y The Y coordinate of the given point.
6815 * @ingroup Evas_Polygon_Group
6817 EAPI void evas_object_polygon_point_add (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
6820 * Removes all of the points from the given evas polygon object.
6821 * @param obj The given polygon object.
6823 EAPI void evas_object_polygon_points_clear (Evas_Object *obj) EINA_ARG_NONNULL(1);
6826 * @defgroup Evas_Smart_Group Smart Functions
6828 * Functions that deal with Evas_Smart's, creating definition
6829 * (classes) of objects that will have customized behavior for methods
6830 * like evas_object_move(), evas_object_resize(),
6831 * evas_object_clip_set() and others.
6833 * These objects will accept the generic methods defined in @ref
6834 * Evas_Object_Group and the extensions defined in @ref
6835 * Evas_Smart_Object_Group. There are couple of existent smart objects
6836 * in Evas itself, see @ref Evas_Object_Box, @ref Evas_Object_Table
6837 * and @ref Evas_Smart_Object_Clipped.
6841 * @def EVAS_SMART_CLASS_VERSION
6842 * The version you have to put into the version field in the smart
6844 * @ingroup Evas_Smart_Group
6846 #define EVAS_SMART_CLASS_VERSION 4
6848 * @struct _Evas_Smart_Class
6849 * a smart object class
6850 * @ingroup Evas_Smart_Group
6852 struct _Evas_Smart_Class
6854 const char *name; /**< the string name of the class */
6856 void (*add) (Evas_Object *o);
6857 void (*del) (Evas_Object *o);
6858 void (*move) (Evas_Object *o, Evas_Coord x, Evas_Coord y);
6859 void (*resize) (Evas_Object *o, Evas_Coord w, Evas_Coord h);
6860 void (*show) (Evas_Object *o);
6861 void (*hide) (Evas_Object *o);
6862 void (*color_set) (Evas_Object *o, int r, int g, int b, int a);
6863 void (*clip_set) (Evas_Object *o, Evas_Object *clip);
6864 void (*clip_unset) (Evas_Object *o);
6865 void (*calculate) (Evas_Object *o);
6866 void (*member_add) (Evas_Object *o, Evas_Object *child);
6867 void (*member_del) (Evas_Object *o, Evas_Object *child);
6869 const Evas_Smart_Class *parent; /**< this class inherits from this parent */
6870 const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, NULL terminated */
6871 void *interfaces; /**< to be used in a future near you */
6876 * @struct _Evas_Smart_Cb_Description
6878 * Describes a callback used by a smart class
6879 * evas_object_smart_callback_call(), particularly useful to explain
6880 * to user and its code (ie: introspection) what the parameter @c
6881 * event_info will contain.
6883 * @ingroup Evas_Smart_Group
6885 struct _Evas_Smart_Cb_Description
6887 const char *name; /**< callback name, ie: "changed" */
6890 * @brief Hint type of @c event_info parameter of Evas_Smart_Cb.
6892 * The type string uses the pattern similar to
6894 * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures
6896 * but extended to optionally include variable names within
6897 * brackets preceding types. Example:
6899 * @li Structure with two integers:
6902 * @li Structure called 'x' with two integers named 'a' and 'b':
6903 * @c "[x]([a]i[b]i)"
6905 * @li Array of integers:
6908 * @li Array called 'x' of struct with two integers:
6911 * @note This type string is used as a hint and is @b not validated
6912 * or enforced anyhow. Implementors should make the best use
6913 * of it to help bindings, documentation and other users of
6914 * introspection features.
6920 * @def EVAS_SMART_CLASS_INIT_NULL
6921 * Initializer to zero a whole Evas_Smart_Class structure.
6923 * @see EVAS_SMART_CLASS_INIT_VERSION
6924 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
6925 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
6926 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6927 * @ingroup Evas_Smart_Group
6929 #define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
6932 * @def EVAS_SMART_CLASS_INIT_VERSION
6933 * Initializer to zero a whole Evas_Smart_Class structure and set version.
6935 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
6936 * latest EVAS_SMART_CLASS_VERSION.
6938 * @see EVAS_SMART_CLASS_INIT_NULL
6939 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
6940 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
6941 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6942 * @ingroup Evas_Smart_Group
6944 #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}
6947 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
6948 * Initializer to zero a whole Evas_Smart_Class structure and set name
6951 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
6952 * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
6954 * It will keep a reference to name field as a "const char *", that is,
6955 * name must be available while the structure is used (hint: static or global!)
6956 * and will not be modified.
6958 * @see EVAS_SMART_CLASS_INIT_NULL
6959 * @see EVAS_SMART_CLASS_INIT_VERSION
6960 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
6961 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6962 * @ingroup Evas_Smart_Group
6964 #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}
6967 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
6968 * Initializer to zero a whole Evas_Smart_Class structure and set name,
6969 * version and parent class.
6971 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
6972 * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
6975 * It will keep a reference to name field as a "const char *", that is,
6976 * name must be available while the structure is used (hint: static or global!)
6977 * and will not be modified. Similarly, parent reference will be kept.
6979 * @see EVAS_SMART_CLASS_INIT_NULL
6980 * @see EVAS_SMART_CLASS_INIT_VERSION
6981 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
6982 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6983 * @ingroup Evas_Smart_Group
6985 #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}
6988 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6989 * Initializer to zero a whole Evas_Smart_Class structure and set name,
6990 * version, parent class and callbacks definition.
6992 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
6993 * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
6994 * class and callbacks at this level.
6996 * It will keep a reference to name field as a "const char *", that is,
6997 * name must be available while the structure is used (hint: static or global!)
6998 * and will not be modified. Similarly, parent and callbacks reference
7001 * @see EVAS_SMART_CLASS_INIT_NULL
7002 * @see EVAS_SMART_CLASS_INIT_VERSION
7003 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
7004 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
7005 * @ingroup Evas_Smart_Group
7007 #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}
7010 * @def EVAS_SMART_SUBCLASS_NEW
7012 * Convenience macro to subclass a Smart Class.
7014 * This macro saves some typing when writing a Smart Class derived from
7015 * another one. In order to work, the user needs to provide some functions
7016 * adhering to the following guidelines.
7017 * - @<prefix@>_smart_set_user(): the internal _smart_set function will call
7018 * this one provided by the user after inheriting everything from the
7019 * parent, which should take care of setting the right member functions
7021 * - @<prefix@>_parent_sc: pointer to the smart class of the parent. When calling
7022 * parent functions from overloaded ones, use this global variable.
7023 * - @<prefix@>_smart_class_new(): this function returns the Evas_Smart needed
7024 * to create smart objects with this class, should be called by the public
7026 * - If this new class should be subclassable as well, a public _smart_set()
7027 * function is desirable to fill the class used as parent by the children.
7028 * It's up to the user to provide this interface, which will most likely
7029 * call @<prefix@>_smart_set() to get the job done.
7031 * @param smart_name The name used for the Smart Class. e.g: "Evas_Object_Box".
7032 * @param prefix Prefix used for all variables and functions defined.
7033 * @param api_type Type of the structure used as API for the Smart Class. Either Evas_Smart_Class or something derived from it.
7034 * @param parent_type Type of the parent class API.
7035 * @param parent_func Function that gets the parent class. e.g: evas_object_box_smart_class_get().
7036 * @param cb_desc Array of callback descriptions for this Smart Class.
7038 * @ingroup Evas_Smart_Group
7040 #define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
7041 static const parent_type * prefix##_parent_sc = NULL; \
7042 static void prefix##_smart_set_user(api_type *api); \
7043 static void prefix##_smart_set(api_type *api) \
7045 Evas_Smart_Class *sc; \
7046 if (!(sc = (Evas_Smart_Class *)api)) \
7048 if (!prefix##_parent_sc) \
7049 prefix##_parent_sc = parent_func(); \
7050 evas_smart_class_inherit(sc, (const Evas_Smart_Class *)prefix##_parent_sc); \
7051 prefix##_smart_set_user(api); \
7053 static Evas_Smart * prefix##_smart_class_new(void) \
7055 static Evas_Smart *smart = NULL; \
7056 static api_type api; \
7059 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
7060 memset(&api, 0, sizeof(api_type)); \
7061 sc->version = EVAS_SMART_CLASS_VERSION; \
7062 sc->name = smart_name; \
7063 sc->callbacks = cb_desc; \
7064 prefix##_smart_set(&api); \
7065 smart = evas_smart_class_new(sc); \
7071 * @def EVAS_SMART_DATA_ALLOC
7072 * Convenience macro to allocate smart data only if needed.
7074 * When writing a subclassable smart object, the .add function will need
7075 * to check if the smart private data was already allocated by some child
7076 * object or not. This macro makes it easier to do it.
7078 * @param o Evas object passed to the .add function
7079 * @param priv_type The type of the data to allocate
7080 * @ingroup Evas_Smart_Group
7082 #define EVAS_SMART_DATA_ALLOC(o, priv_type) \
7084 priv = evas_object_smart_data_get(o); \
7086 priv = (priv_type *)calloc(1, sizeof(priv_type)); \
7087 if (!priv) return; \
7088 evas_object_smart_data_set(o, priv); \
7093 * Free an Evas_Smart
7095 * If this smart was created using evas_smart_class_new(), the associated
7096 * Evas_Smart_Class will not be freed.
7098 * @param s the Evas_Smart to free
7101 EAPI void evas_smart_free (Evas_Smart *s) EINA_ARG_NONNULL(1);
7104 * Creates an Evas_Smart from an Evas_Smart_Class.
7106 * @param sc the smart class definition
7107 * @return an Evas_Smart
7109 EAPI Evas_Smart *evas_smart_class_new (const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7112 * Get the Evas_Smart_Class of an Evas_Smart
7114 * @param s the Evas_Smart
7115 * @return the Evas_Smart_Class
7117 EAPI const Evas_Smart_Class *evas_smart_class_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7121 * @brief Get the data pointer set on an Evas_Smart.
7123 * @param s Evas_Smart
7125 * This data pointer is set either as the final parameter to
7126 * evas_smart_new or as the data field in the Evas_Smart_Class passed
7127 * in to evas_smart_class_new
7129 EAPI void *evas_smart_data_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7132 * Get the callbacks known by this Evas_Smart.
7134 * This is likely different from Evas_Smart_Class::callbacks as it
7135 * will contain the callbacks of all class hierarchy sorted, while the
7136 * direct smart class member refers only to that specific class and
7137 * should not include parent's.
7139 * If no callbacks are known, this function returns @c NULL.
7141 * The array elements and thus their contents will be reference to
7142 * original values given to evas_smart_new() as
7143 * Evas_Smart_Class::callbacks.
7145 * The array is sorted by name. The last array element is the @c NULL
7146 * pointer and is not counted in @a count. Loop iterations can check
7147 * any of these cases.
7149 * @param s the Evas_Smart.
7150 * @param count returns the number of elements in returned array.
7151 * @return the array with callback descriptions known by this class,
7152 * its size is returned in @a count parameter. It should not
7153 * be modified anyhow. If no callbacks are known, @c NULL is
7154 * returned. The array is sorted by name and elements refer to
7155 * the original value given to evas_smart_new().
7157 * @note objects may provide per-instance callbacks, use
7158 * evas_object_smart_callbacks_descriptions_get() to get those
7160 * @see evas_object_smart_callbacks_descriptions_get()
7162 EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
7166 * Find callback description for callback called @a name.
7168 * @param s the Evas_Smart.
7169 * @param name name of desired callback, must @b not be @c NULL. The
7170 * search have a special case for @a name being the same
7171 * pointer as registered with Evas_Smart_Cb_Description, one
7172 * can use it to avoid excessive use of strcmp().
7173 * @return reference to description if found, @c NULL if not found.
7175 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;
7179 * Sets one class to inherit from the other.
7181 * Copy all function pointers, set @c parent to @a parent_sc and copy
7182 * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
7183 * using @a parent_sc_size as reference.
7185 * This is recommended instead of a single memcpy() since it will take
7186 * care to not modify @a sc name, version, callbacks and possible
7189 * @param sc child class.
7190 * @param parent_sc parent class, will provide attributes.
7191 * @param parent_sc_size size of parent_sc structure, child should be at least
7192 * this size. Everything after @c Evas_Smart_Class size is copied
7193 * using regular memcpy().
7195 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);
7198 * Get the number of users of the smart instance
7200 * @param s The Evas_Smart to get the usage count of
7201 * @return The number of uses of the smart instance
7203 * This function tells you how many more uses of the smart instance are in
7204 * existence. This should be used before freeing/clearing any of the
7205 * Evas_Smart_Class that was used to create the smart instance. The smart
7206 * instance will refer to data in the Evas_Smart_Class used to create it and
7207 * thus you cannot remove the original data until all users of it are gone.
7208 * When the usage count goes to 0, you can evas_smart_free() the smart
7209 * instance @p s and remove from memory any of the Evas_Smart_Class that
7210 * was used to create the smart instance, if you desire. Removing it from
7211 * memory without doing this will cause problems (crashes, undefined
7212 * behavior etc. etc.), so either never remove the original
7213 * Evas_Smart_Class data from memory (have it be a constant structure and
7214 * data), or use this API call and be very careful.
7216 EAPI int evas_smart_usage_get(const Evas_Smart *s);
7219 * @def evas_smart_class_inherit
7220 * Easy to use version of evas_smart_class_inherit_full().
7222 * This version will use sizeof(parent_sc), copying everything.
7224 * @param sc child class, will have methods copied from @a parent_sc
7225 * @param parent_sc parent class, will provide contents to be copied.
7226 * @return 1 on success, 0 on failure.
7227 * @ingroup Evas_Smart_Group
7229 #define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, parent_sc, sizeof(*parent_sc))
7232 * @defgroup Evas_Smart_Object_Group Smart Object Functions
7234 * Functions dealing with evas smart objects (instances).
7236 * Smart objects are groupings of primitive Evas objects that behave as a
7237 * cohesive group. For instance, a file manager icon may be a smart object
7238 * composed of an image object, a text label and two rectangles that appear
7239 * behind the image and text when the icon is selected. As a smart object,
7240 * the normal evas api could be used on the icon object.
7242 * @see @ref Evas_Smart_Group for class definitions.
7246 * Instantiates a new smart object described by @p s.
7248 * @param e the evas on which to add the object
7249 * @param s the Evas_Smart describing the smart object
7250 * @return a new Evas_Object
7251 * @ingroup Evas_Smart_Object_Group
7253 EAPI Evas_Object *evas_object_smart_add (Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC;
7256 * Set an Evas object as a member of a smart object.
7258 * @param obj The member object
7259 * @param smart_obj The smart object
7261 * Members will automatically be stacked and layered with the smart object.
7262 * The various stacking function will operate on members relative to the
7263 * other members instead of the entire canvas.
7265 * Non-member objects can not interleave a smart object's members.
7267 * @ingroup Evas_Smart_Object_Group
7269 EAPI void evas_object_smart_member_add (Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2);
7272 * Removes a member object from a smart object.
7274 * @param obj the member object
7275 * @ingroup Evas_Smart_Object_Group
7277 * This removes a member object from a smart object. The object will still
7278 * be on the canvas, but no longer associated with whichever smart object
7279 * it was associated with.
7282 EAPI void evas_object_smart_member_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
7285 * Gets the smart parent of an Evas_Object
7286 * @param obj the Evas_Object you want to get the parent
7287 * @return Returns the smart parent of @a obj, or @c NULL if @a obj is not a smart member of another Evas_Object
7288 * @ingroup Evas_Smart_Object_Group
7290 EAPI Evas_Object *evas_object_smart_parent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7293 * Checks the Smart type of the object and its parents
7294 * @param obj the Evas_Object to check the type of
7295 * @param type the type to check for
7296 * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise
7297 * @ingroup Evas_Smart_Object_Group
7299 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;
7302 * Checks the Smart type of the object and its parents using pointer comparison
7303 * @param obj the Evas_Object to check the type of
7304 * @param type the type to check for. Must be the name pointer in the smart class used to create the object
7305 * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise
7306 * @ingroup Evas_Smart_Object_Group
7308 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;
7311 * Gets the list of the member objects of an Evas_Object
7312 * @param obj the Evas_Object you want to get the list of member objects
7313 * @return Returns the list of the member objects of @a obj.
7314 * The returned list should be freed with eina_list_free() when you no longer need it
7316 EAPI Eina_List *evas_object_smart_members_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7319 * Get the Evas_Smart from which @p obj was created.
7321 * @param obj a smart object
7322 * @return the Evas_Smart
7323 * @ingroup Evas_Smart_Object_Group
7325 EAPI Evas_Smart *evas_object_smart_smart_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7328 * Retrieve user data stored on a smart object.
7330 * @param obj The smart object
7331 * @return A pointer to data stored using evas_object_smart_data_set(), or
7332 * NULL if none has been set.
7333 * @ingroup Evas_Smart_Object_Group
7335 EAPI void *evas_object_smart_data_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7338 * Store a pointer to user data for a smart object.
7340 * @param obj The smart object
7341 * @param data A pointer to user data
7342 * @ingroup Evas_Smart_Object_Group
7344 EAPI void evas_object_smart_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
7347 * Add a callback for the smart event specified by @p event.
7349 * @param obj a smart object
7350 * @param event the event name
7351 * @param func the callback function
7352 * @param data user data to be passed to the callback function
7353 * @ingroup Evas_Smart_Object_Group
7355 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);
7358 * Remove a smart callback
7360 * Removes a callback that was added by evas_object_smart_callback_add()
7362 * @param obj a smart object
7363 * @param event the event name
7364 * @param func the callback function
7365 * @return the data pointer
7366 * @ingroup Evas_Smart_Object_Group
7368 EAPI void *evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3);
7371 * Call any smart callbacks on @p obj for @p event.
7373 * @param obj the smart object
7374 * @param event the event name
7375 * @param event_info an event specific struct of info to pass to the callback
7377 * This should be called internally in the smart object when some specific
7378 * event has occurred. The documentation for the smart object should include
7379 * a list of possible events and what type of @p event_info to expect.
7381 * @ingroup Evas_Smart_Object_Group
7383 EAPI void evas_object_smart_callback_call (Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2);
7387 * Set smart object instance callbacks descriptions.
7389 * These descriptions are hints to be used by introspection and are
7390 * not enforced in any way.
7392 * It will not be checked if instance callbacks descriptions have the
7393 * same name as another in class. Both are kept in different arrays
7394 * and users of evas_object_smart_callbacks_descriptions_get() should
7395 * handle this case as they wish.
7397 * @param obj The smart object
7398 * @param descriptions NULL terminated (name != NULL) array with
7399 * descriptions. Array elements will not be modified, but
7400 * reference to them and their contents will be made, so this
7401 * array should be kept alive during object lifetime.
7402 * @return 1 on success, 0 on failure.
7403 * @ingroup Evas_Smart_Object_Group
7405 * @note while instance callbacks descriptions are possible, they are
7406 * not recommended. Use class callbacks descriptions instead as they
7407 * make user's life simpler and will use less memory as descriptions
7408 * and arrays will be shared among all instances.
7410 EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1);
7413 * Get the callbacks descriptions known by this smart object.
7415 * This call retrieves processed callbacks descriptions for both
7416 * instance and class. These arrays are sorted by description's name
7417 * and are @c NULL terminated, so both @a class_count and
7418 * @a instance_count can be ignored, the terminator @c NULL is not
7419 * counted in these values.
7421 * @param obj the smart object.
7422 * @param class_descriptions where to store class callbacks
7423 * descriptions array, if any is known. If no descriptions are
7424 * known, @c NULL is returned. This parameter may be @c NULL if
7425 * it is not of interest.
7426 * @param class_count returns how many class callbacks descriptions
7428 * @param instance_descriptions where to store instance callbacks
7429 * descriptions array, if any is known. If no descriptions are
7430 * known, @c NULL is returned. This parameter may be @c NULL if
7431 * it is not of interest.
7432 * @param instance_count returns how many instance callbacks
7433 * descriptions are known.
7435 * @note if just class descriptions are of interest, try
7436 * evas_smart_callbacks_descriptions_get() instead.
7438 * @see evas_smart_callbacks_descriptions_get()
7439 * @ingroup Evas_Smart_Object_Group
7441 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);
7444 * Find callback description for callback called @a name.
7446 * @param obj the smart object.
7447 * @param name name of desired callback, must @b not be @c NULL. The
7448 * search have a special case for @a name being the same
7449 * pointer as registered with Evas_Smart_Cb_Description, one
7450 * can use it to avoid excessive use of strcmp().
7451 * @param class_description pointer to return class description or @c
7452 * NULL if not found. If parameter is @c NULL, no search will
7453 * be done on class descriptions.
7454 * @param instance_description pointer to return instance description
7455 * or @c NULL if not found. If parameter is @c NULL, no search
7456 * will be done on instance descriptions.
7457 * @return reference to description if found, @c NULL if not found.
7459 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);
7463 * Mark smart object as changed, dirty.
7465 * This will inform the scene that it changed and needs to be redraw, also
7466 * setting need_recalculate on the given object.
7468 * @see evas_object_smart_need_recalculate_set().
7470 * @ingroup Evas_Smart_Object_Group
7472 EAPI void evas_object_smart_changed (Evas_Object *obj) EINA_ARG_NONNULL(1);
7475 * Set the need_recalculate flag of given smart object.
7477 * If this flag is set then calculate() callback (method) of the given
7478 * smart object will be called, if one is provided, during render phase
7479 * usually evas_render(). After this step, this flag will be automatically
7482 * If no calculate() is provided, this flag will be left unchanged.
7484 * @note just setting this flag will not make scene dirty and evas_render()
7485 * will have no effect. To do that, use evas_object_smart_changed(),
7486 * that will automatically call this function with 1 as parameter.
7488 * @param obj the smart object
7489 * @param value if one want to set or unset the need_recalculate flag.
7491 * @ingroup Evas_Smart_Object_Group
7493 EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
7496 * Get the current value of need_recalculate flag.
7498 * @note this flag will be unset during the render phase, after calculate()
7499 * is called if one is provided. If no calculate() is provided, then
7500 * the flag will be left unchanged after render phase.
7502 * @param obj the smart object
7503 * @return if flag is set or not.
7505 * @ingroup Evas_Smart_Object_Group
7507 EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7510 * Call user provided calculate() and unset need_calculate.
7512 * @param obj the smart object
7514 * @ingroup Evas_Smart_Object_Group
7516 EAPI void evas_object_smart_calculate (Evas_Object *obj) EINA_ARG_NONNULL(1);
7520 * Call user provided calculate() and unset need_calculate on all objects.
7522 * @param e The canvas to calculate all objects in
7524 * @ingroup Evas_Smart_Object_Group
7526 EAPI void evas_smart_objects_calculate (Evas *e);
7529 * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
7531 * Clipped smart object is a base to construct other smart objects
7532 * that based on the concept of having an internal clipper that is
7533 * applied to all its other children. This clipper will control the
7534 * visibility, clipping and color of sibling objects (remember that
7535 * the clipping is recursive, and clipper color modulates the color of
7536 * its clippees). By default, this base will also move children
7537 * relatively to the parent, and delete them when parent is
7538 * deleted. In other words, it is the base for simple object grouping.
7540 * @see evas_object_smart_clipped_smart_set()
7542 * @ingroup Evas_Smart_Object_Group
7546 * Every subclass should provide this at the beginning of their own
7547 * data set with evas_object_smart_data_set().
7549 typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
7550 struct _Evas_Object_Smart_Clipped_Data
7552 Evas_Object *clipper;
7558 * Get the clipper object for the given clipped smart object.
7560 * @param obj the clipped smart object to retrieve the associated clipper.
7561 * @return the clipper object.
7563 * @see evas_object_smart_clipped_smart_add()
7565 EAPI Evas_Object *evas_object_smart_clipped_clipper_get (Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7568 * Set smart class callbacks so it implements the "Clipped Smart Object".
7570 * This call will assign all the required methods of Evas_Smart_Class,
7571 * if one wants to "subclass" it, call this function and later
7572 * override values, if one wants to call the original method, save it
7573 * somewhere, example:
7576 * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
7578 * static void my_class_smart_add(Evas_Object *o)
7581 * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
7585 * Evas_Smart_Class *my_class_new(void)
7587 * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
7588 * if (!parent_sc.name)
7590 * evas_object_smart_clipped_smart_set(&sc);
7592 * sc.add = my_class_smart_add;
7598 * Default behavior is:
7599 * - add: creates a hidden clipper with "infinite" size;
7600 * - del: delete all children objects;
7601 * - move: move all objects relative relatively;
7602 * - resize: not defined;
7603 * - show: if there are children objects, show clipper;
7604 * - hide: hides clipper;
7605 * - color_set: set the color of clipper;
7606 * - clip_set: set clipper of clipper;
7607 * - clip_unset: unset the clipper of clipper;
7609 EAPI void evas_object_smart_clipped_smart_set (Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
7612 * Get a pointer to the Clipped Smart Class to use for proper inheritance
7614 EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get (void) EINA_CONST;
7618 * Moves all children objects relative to given offset.
7620 * @param obj the smart Evas object to use.
7621 * @param dx horizontal offset.
7622 * @param dy vertical offset.
7624 EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1);
7627 * @defgroup Evas_Object_Box Box (Sequence) Smart Object.
7629 * Convenience smart object that packs children as a sequence using
7630 * a layout function specified by user. There are a couple of helper
7631 * layout functions, all of them using children size hints to define
7632 * their size and alignment inside their cell space.
7634 * @see @ref Evas_Object_Group_Size_Hints
7636 * @ingroup Evas_Smart_Object_Group
7639 * @typedef Evas_Object_Box_Api
7640 * Smart Class extension providing extra box requirements.
7641 * @ingroup Evas_Object_Box
7643 typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
7645 * @typedef Evas_Object_Box_Data
7646 * Smart instance data providing box requirements.
7647 * @ingroup Evas_Object_Box
7649 typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
7651 * @typedef Evas_Object_Box_Option
7652 * The base structure for a box option.
7653 * @ingroup Evas_Object_Box
7655 typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
7656 typedef void (*Evas_Object_Box_Layout) (Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
7659 * @def EVAS_OBJECT_BOX_API_VERSION
7660 * @ingroup Evas_Object_Box
7662 #define EVAS_OBJECT_BOX_API_VERSION 1
7664 * @struct _Evas_Object_Box_Api
7666 * This structure should be used by any class that wants to inherit
7667 * from box to provide custom behavior not allowed only by providing a
7668 * layout function with evas_object_box_layout_set().
7670 * @extends Evas_Smart_Class
7671 * @ingroup Evas_Object_Box
7673 struct _Evas_Object_Box_Api
7675 Evas_Smart_Class base;
7677 Evas_Object_Box_Option *(*append) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
7678 Evas_Object_Box_Option *(*prepend) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
7679 Evas_Object_Box_Option *(*insert_before) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, const Evas_Object *reference);
7680 Evas_Object_Box_Option *(*insert_after) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, const Evas_Object *reference);
7681 Evas_Object_Box_Option *(*insert_at) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, unsigned int pos);
7682 Evas_Object *(*remove) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
7683 Evas_Object *(*remove_at) (Evas_Object *o, Evas_Object_Box_Data *priv, unsigned int pos);
7684 Eina_Bool (*property_set) (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args);
7685 Eina_Bool (*property_get) (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args);
7686 const char *(*property_name_get)(Evas_Object *o, int property);
7687 int (*property_id_get) (Evas_Object *o, const char *name);
7688 Evas_Object_Box_Option *(*option_new) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
7689 void (*option_free) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt);
7693 * @def EVAS_OBJECT_BOX_API_INIT
7694 * Initializer for whole Evas_Object_Box_Api structure.
7696 * @param smart_class_init initializer to use for the "base" field
7697 * (Evas_Smart_Class).
7699 * @see EVAS_SMART_CLASS_INIT_NULL
7700 * @see EVAS_SMART_CLASS_INIT_VERSION
7701 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
7702 * @see EVAS_OBJECT_BOX_API_INIT_NULL
7703 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
7704 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
7705 * @ingroup Evas_Object_Box
7707 #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}
7710 * @def EVAS_OBJECT_BOX_API_INIT_NULL
7711 * Initializer to zero a whole Evas_Object_Box_Api structure.
7713 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
7714 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
7715 * @see EVAS_OBJECT_BOX_API_INIT
7716 * @ingroup Evas_Object_Box
7718 #define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
7721 * @def EVAS_OBJECT_BOX_API_INIT_VERSION
7722 * Initializer to zero a whole Evas_Object_Box_Api structure and set version.
7724 * Similar to EVAS_OBJECT_BOX_API_INIT_NULL, but will set version field of
7725 * Evas_Smart_Class (base field) to latest EVAS_SMART_CLASS_VERSION
7727 * @see EVAS_OBJECT_BOX_API_INIT_NULL
7728 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
7729 * @see EVAS_OBJECT_BOX_API_INIT
7730 * @ingroup Evas_Object_Box
7732 #define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
7735 * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
7736 * Initializer to zero a whole Evas_Object_Box_Api structure and set
7739 * Similar to EVAS_OBJECT_BOX_API_INIT_NULL, but will set version field of
7740 * Evas_Smart_Class (base field) to latest EVAS_SMART_CLASS_VERSION and name
7741 * to the specific value.
7743 * It will keep a reference to name field as a "const char *", that is,
7744 * name must be available while the structure is used (hint: static or global!)
7745 * and will not be modified.
7747 * @see EVAS_OBJECT_BOX_API_INIT_NULL
7748 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
7749 * @see EVAS_OBJECT_BOX_API_INIT
7750 * @ingroup Evas_Object_Box
7752 #define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
7755 * @struct _Evas_Object_Box_Data
7757 * This structure augments clipped smart object's instance data,
7758 * providing extra members required by generic box implementation. If
7759 * a subclass inherits from #Evas_Object_Box_Api then it may augment
7760 * #Evas_Object_Box_Data to fit its own needs.
7762 * @extends Evas_Object_Smart_Clipped_Data
7763 * @ingroup Evas_Object_Box
7765 struct _Evas_Object_Box_Data
7767 Evas_Object_Smart_Clipped_Data base;
7768 const Evas_Object_Box_Api *api;
7775 Eina_List *children;
7777 Evas_Object_Box_Layout cb;
7779 void (*free_data)(void *data);
7781 Eina_Bool layouting : 1;
7782 Eina_Bool children_changed : 1;
7785 struct _Evas_Object_Box_Option
7788 Eina_Bool max_reached:1;
7789 Eina_Bool min_reached:1;
7790 Evas_Coord alloc_size;
7795 * Set the default box @a api struct (Evas_Object_Box_Api)
7796 * with the default values. May be used to extend that API.
7798 EAPI void evas_object_box_smart_set (Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
7801 * Get Box Smart Class for inheritance purposes
7803 EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get (void) EINA_CONST;
7806 * Set a 'calculate' callback (@a cb) to the @a o box's smart class,
7807 * which here defines its genre (horizontal, vertical, homogeneous,
7810 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);
7816 * Its layout function must be set via evas_object_box_layout_set()
7817 * (defaults to evas_object_box_layout_horizontal()). The other
7818 * properties of the box must be set/retrieved via
7819 * evas_object_box_{h,v}_{align,padding}_{get,set)().
7821 EAPI Evas_Object *evas_object_box_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7824 * Create a box that is child of a given element @a parent.
7826 * @see evas_object_box_add()
7828 EAPI Evas_Object *evas_object_box_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7832 * Layout function which sets the box @a o to a (basic) horizontal
7833 * box. @a priv must be the smart data of the box.
7835 * The object's overall behavior is controlled by its properties,
7836 * which are set by the evas_object_box_{h,v}_{align,padding}_set()
7837 * family of functions. The properties of the elements in the box --
7838 * set by evas_object_size_hint_{align,padding,weight}_set() functions
7839 * -- also control the way this function works.
7841 * \par box's properties:
7842 * @c align_h controls the horizontal alignment of the child objects
7843 * relative to the containing box. When set to 0, children are aligned
7844 * to the left. A value of 1 lets them aligned to the right border.
7845 * Values in between align them proportionally. Note that if the size
7846 * required by the children, which is given by their widths and the @c
7847 * padding_h property of the box, is bigger than the container width,
7848 * the children will be displayed out of its bounds. A negative value
7849 * of @c align_h makes the box to *justify* its children. The padding
7850 * between them, in this case, is corrected so that the leftmost one
7851 * touches the left border and the rightmost one touches the right
7852 * border (even if they must overlap). The @c align_v and @c
7853 * padding_v properties of the box don't contribute to its behaviour
7854 * when this layout is chosen.
7856 * \par Child element's properties:
7857 * @c align_x does not influence the box's behavior. @c padding_l and
7858 * @c padding_r sum up to the container's horizontal padding between
7859 * elements. The child's @c padding_t, @c padding_b and @c align_y
7860 * properties apply for padding/positioning relative to the overall
7861 * height of the box. Finally, there is the @c weight_x property,
7862 * which, if set to a non-zero value, tells the container that the
7863 * child width is not pre-defined. If the container can't accommodate
7864 * all its children, it sets the widths of the children *with weights*
7865 * to sizes as small as they can all fit into it. If the size
7866 * required by the children is less than the available, the box
7867 * increases its children's (which have weights) widths as to fit the
7868 * remaining space. The @c weight_x property, besides telling the
7869 * element is resizable, gives a *weight* for the resizing process.
7870 * The parent box will try to distribute (or take off) widths
7871 * accordingly to the *normalized* list of weigths: most weighted
7872 * children remain/get larger in this process than the least ones.
7873 * @c weight_y does not influence the layout.
7875 * If one desires that, besides having weights, child elements must be
7876 * resized bounded to a minimum or maximum size, their size hint
7877 * properties must be set (by the
7878 * evas_object_size_hint_{min,max}_set() functions.
7880 EAPI void evas_object_box_layout_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
7883 * Layout function which sets the box @a o to a (basic) vertical box.
7884 * @a priv must be the smart data of the box.
7886 * This function behaves analogously to
7887 * evas_object_box_layout_horizontal(). The description of its
7888 * behaviour can be derived from that function's documentation.
7890 EAPI void evas_object_box_layout_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
7893 * Layout function which sets the box @a o to a *homogeneous* vertical
7894 * box. @a priv must be the smart data of the box.
7896 * This function behaves analogously to
7897 * evas_object_box_layout_homogeneous_horizontal(). The description
7898 * of its behaviour can be derived from that function's documentation.
7900 EAPI void evas_object_box_layout_homogeneous_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
7903 * Layout function which sets the box @a o to a *homogeneous*
7904 * horizontal box. @a priv must be the smart data of the box.
7906 * In a homogeneous horizontal box, its width is divided equally
7907 * between the contained objects. The box's overall behavior is
7908 * controlled by its properties, which are set by the
7909 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
7910 * The properties of the elements in the box -- set by
7911 * evas_object_size_hint_{align,padding,weight}_set() functions --
7912 * also control the way this function works.
7914 * \par box's properties:
7915 * @c align_h has no influence on the box for this layout. @c
7916 * padding_h tells the box to draw empty spaces of that size, in
7917 * pixels, between the (still equal) child objects's cells. The @c
7918 * align_v and @c padding_v properties of the box don't contribute to
7919 * its behaviour when this layout is chosen.
7921 * \par Child element's properties:
7922 * @c padding_l and @c padding_r sum up to the required width of the
7923 * child element. The @c align_x property tells the relative position
7924 * of this overall child width in its allocated cell (0 to extreme
7925 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
7926 * box try to resize this child element to the exact width of its cell
7927 * (respecting the min and max hints on the child's width *and*
7928 * accounting its horizontal padding properties). The child's @c
7929 * padding_t, @c padding_b and @c align_y properties apply for
7930 * padding/positioning relative to the overall height of the box. A
7931 * value of -1.0 to @c align_y makes the box try to resize this child
7932 * element to the exact height of its parent (respecting the max hint
7933 * on the child's height).
7935 EAPI void evas_object_box_layout_homogeneous_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
7938 * Layout function which sets the box @a o to a *max size-homogeneous*
7939 * horizontal box. @a priv must be the smart data of the box.
7941 * In a max size-homogeneous horizontal box, the equal sized cells
7942 * reserved for the child objects have the width of the space required
7943 * by the largest child (in width). The box's overall behavior is
7944 * controlled by its properties, which are set by the
7945 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
7946 * The properties of the elements in the box -- set by
7947 * evas_object_size_hint_{align,padding,weight}_set() functions --
7948 * also control the way this function works.
7950 * \par box's properties:
7951 * @c padding_h tells the box to draw empty spaces of that size, in
7952 * pixels, between the child objects's cells. @c align_h controls the
7953 * horizontal alignment of the child objects relative to the
7954 * containing box. When set to 0, children are aligned to the left. A
7955 * value of 1 lets them aligned to the right border. Values in
7956 * between align them proportionally. A negative value of @c align_h
7957 * makes the box to *justify* its children cells. The padding between
7958 * them, in this case, is corrected so that the leftmost one touches
7959 * the left border and the rightmost one touches the right border
7960 * (even if they must overlap). The @c align_v and @c padding_v
7961 * properties of the box don't contribute to its behaviour when this
7964 * \par Child element's properties:
7965 * @c padding_l and @c padding_r sum up to the required width of the
7966 * child element. The @c align_x property tells the relative position
7967 * of this overall child width in its allocated cell (0 to extreme
7968 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
7969 * box try to resize this child element to the exact width of its cell
7970 * (respecting the min and max hints on the child's width *and*
7971 * accounting its horizontal padding properties). The child's @c
7972 * padding_t, @c padding_b and @c align_y properties apply for
7973 * padding/positioning relative to the overall height of the box. A
7974 * value of -1.0 to @c align_y makes the box try to resize this child
7975 * element to the exact height of its parent (respecting the max hint
7976 * on the child's height).
7978 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);
7981 * Layout function which sets the box @a o to a *max size-homogeneous*
7982 * vertical box. @a priv must be the smart data of the box.
7984 * This function behaves analogously to
7985 * evas_object_box_layout_homogeneous_max_size_horizontal(). The
7986 * description of its behaviour can be derived from that function's
7989 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);
7992 * Layout function which sets the box @a o to a *flow* horizontal box.
7993 * @a priv must be the smart data of the box.
7995 * In a flow horizontal box, the box's child elements are placed in
7996 * rows (think of text as an analogy). A row has as much elements as
7997 * can fit into the box's width. The box's overall behavior is
7998 * controlled by its properties, which are set by the
7999 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
8000 * The properties of the elements in the box -- set by
8001 * evas_object_size_hint_{align,padding,weight}_set() functions --
8002 * also control the way this function works.
8004 * \par box's properties:
8005 * @c padding_h tells the box to draw empty spaces of that size, in
8006 * pixels, between the child objects's cells. @c align_h dictates the
8007 * horizontal alignment of the rows (0 to left align them, 1 to right
8008 * align). A value of -1.0 to @c align_h lets the rows *justified*
8009 * horizontally. @c align_v controls the vertical alignment of the
8010 * entire set of rows (0 to top, 1 to bottom). A value of -1.0 to @c
8011 * align_v makes the box to *justify* the rows vertically. The padding
8012 * between them, in this case, is corrected so that the first row
8013 * touches the top border and the last one touches the bottom border
8014 * (even if they must overlap). @c padding_v has no influence on the
8017 * \par Child element's properties:
8018 * @c padding_l and @c padding_r sum up to the required width of the
8019 * child element. The @c align_x property has no influence on the
8020 * layout. The child's @c padding_t and @c padding_b sum up to the
8021 * required height of the child element and is the only means (besides
8022 * row justifying) of setting space between rows. Note, however, that
8023 * @c align_y dictates positioning relative to the *largest height*
8024 * required by a child object in the actual row.
8026 EAPI void evas_object_box_layout_flow_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8029 * Layout function which sets the box @a o to a *flow* vertical box.
8030 * @a priv must be the smart data of the box.
8032 * This function behaves analogously to
8033 * evas_object_box_layout_flow_horizontal(). The description of its
8034 * behaviour can be derived from that function's documentation.
8036 EAPI void evas_object_box_layout_flow_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8039 * Layout function which sets the box @a o to set all children to the
8040 * size of the object. @a priv must be the smart data of the box.
8042 * In a stack box, all children will be given the same size and they
8043 * will be stacked on above the other, so the first object will be the
8046 * \par box's properties:
8047 * No box option is used.
8049 * \par Child element's properties:
8050 * @c padding_l and @c padding_r sum up to the required width of the
8051 * child element. The @c align_x property tells the relative position
8052 * of this overall child width in its allocated cell (0 to extreme
8053 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
8054 * box try to resize this child element to the exact width of its cell
8055 * (respecting the min and max hints on the child's width *and*
8056 * accounting its horizontal padding properties). Same applies to
8059 EAPI void evas_object_box_layout_stack (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8063 * Set the alignment of the whole bounding box of contents.
8065 EAPI void evas_object_box_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
8068 * Get alignment of the whole bounding box of contents.
8070 EAPI void evas_object_box_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
8073 * Set the space (padding) between cells.
8075 EAPI void evas_object_box_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
8078 * Get the (space) padding between cells.
8080 EAPI void evas_object_box_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
8084 * Append a new object @a child to the box @a o. On error, @c NULL is
8087 EAPI Evas_Object_Box_Option *evas_object_box_append (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8090 * Prepend a new object @a child to the box @a o. On error, @c NULL is
8093 EAPI Evas_Object_Box_Option *evas_object_box_prepend (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8096 * Prepend a new object @a child to the box @c o relative to element @a
8097 * reference. If @a reference is not contained in the box or any other
8098 * error occurs, @c NULL is returned.
8100 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);
8103 * Append a new object @a child to the box @c o relative to element @a
8104 * reference. If @a reference is not contained in the box or any other
8105 * error occurs, @c NULL is returend.
8107 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);
8110 * Insert a new object @a child to the box @a o at position @a pos. On
8111 * error, @c NULL is returned.
8113 EAPI Evas_Object_Box_Option *evas_object_box_insert_at (Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2);
8116 * Remove an object @a child from the box @a o. On error, @c 0 is
8119 EAPI Eina_Bool evas_object_box_remove (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8122 * Remove an object from the box @a o which occupies position @a
8123 * pos. On error, @c 0 is returned.
8125 EAPI Eina_Bool evas_object_box_remove_at (Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1);
8128 * Remove all child objects.
8129 * @return 0 on errors
8131 EAPI Eina_Bool evas_object_box_remove_all (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8134 * Get an iterator to walk the list of children for the box.
8136 * @note Do not remove or delete objects while walking the list.
8138 EAPI Eina_Iterator *evas_object_box_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8141 * Get an accessor to get random access to the list of children for the box.
8143 * @note Do not remove or delete objects while walking the list.
8145 EAPI Eina_Accessor *evas_object_box_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8148 * Get the list of children for the box.
8150 * @note This is a duplicate of the list kept by the box internally.
8151 * It's up to the user to destroy it when it no longer needs it.
8152 * It's possible to remove objects from the box when walking this
8153 * list, but these removals won't be reflected on it.
8155 EAPI Eina_List *evas_object_box_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8159 * Get the name of the property of the child elements of the box @a o
8160 * whose id is @a property. On error, @c NULL is returned.
8162 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;
8165 * Get the id of the property of the child elements of the box @a o
8166 * whose name is @a name. On error, @c -1 is returned.
8168 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;
8171 * Set the property (with id @a property) of the child element of the
8172 * box @a o whose property struct is @a opt. The property's values
8173 * must be the last arguments and their type *must* match that of the
8174 * property itself. On error, @c 0 is returned.
8176 EAPI Eina_Bool evas_object_box_option_property_set (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
8179 * Set the property (with id @a property) of the child element of the
8180 * box @a o whose property struct is @a opt. The property's values
8181 * must be the args which the va_list @a args is initialized with and
8182 * their type *must* match that of the property itself. On error, @c 0
8185 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);
8188 * Get the property (with id @a property) of the child element of the
8189 * box @a o whose property struct is @a opt. The last arguments must
8190 * be addresses of variables with the same type of that property. On
8191 * error, @c 0 is returned.
8193 EAPI Eina_Bool evas_object_box_option_property_get (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
8196 * Get the property (with id @a property) of the child element of the
8197 * box @a o whose property struct is @a opt. The args which the
8198 * va_list @a args is initialized with must be addresses of variables
8199 * with the same type of that property. On error, @c 0 is returned.
8201 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);
8204 * @defgroup Evas_Object_Table Table Smart Object.
8206 * Convenience smart object that packs children using a tabular
8207 * layout using children size hints to define their size and
8208 * alignment inside their cell space.
8210 * @see @ref Evas_Object_Group_Size_Hints
8212 * @ingroup Evas_Smart_Object_Group
8216 * Create a new table.
8218 * It's set to non-homogeneous by default, add children with
8219 * evas_object_table_pack().
8221 EAPI Evas_Object *evas_object_table_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8224 * Create a table that is child of a given element @a parent.
8226 * @see evas_object_table_add()
8228 EAPI Evas_Object *evas_object_table_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8231 * Set how this table should layout children.
8233 * @todo consider aspect hint and respect it.
8235 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE
8236 * If table does not use homogeneous mode then columns and rows will
8237 * be calculated based on hints of individual cells. This operation
8238 * mode is more flexible, but more complex and heavy to calculate as
8239 * well. @b Weight properties are handled as a boolean
8240 * expand. Negative alignment will be considered as 0.5.
8242 * @todo @c EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE should balance weight.
8244 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE
8245 * When homogeneous is relative to table the own table size is divided
8246 * equally among children, filling the whole table area. That is, if
8247 * table has @c WIDTH and @c COLUMNS, each cell will get <tt>WIDTH /
8248 * COLUMNS</tt> pixels. If children have minimum size that is larger
8249 * than this amount (including padding), then it will overflow and be
8250 * aligned respecting the alignment hint, possible overlapping sibling
8251 * cells. @b Weight hint is used as a boolean, if greater than zero it
8252 * will make the child expand in that axis, taking as much space as
8253 * possible (bounded to maximum size hint). Negative alignment will be
8254 * considered as 0.5.
8256 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM
8257 * When homogeneous is relative to item it means the greatest minimum
8258 * cell size will be used. That is, if no element is set to expand,
8259 * the table will have its contents to a minimum size, the bounding
8260 * box of all these children will be aligned relatively to the table
8261 * object using evas_object_table_align_get(). If the table area is
8262 * too small to hold this minimum bounding box, then the objects will
8263 * keep their size and the bounding box will overflow the box area,
8264 * still respecting the alignment. @b Weight hint is used as a
8265 * boolean, if greater than zero it will make that cell expand in that
8266 * axis, toggling the <b>expand mode</b>, which makes the table behave
8267 * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the
8268 * bounding box will overflow and items will not overlap siblings. If
8269 * no minimum size is provided at all then the table will fallback to
8270 * expand mode as well.
8272 EAPI void evas_object_table_homogeneous_set (Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1);
8275 * Get the current layout homogeneous mode.
8277 * @see evas_object_table_homogeneous_set()
8279 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;
8282 * Set padding between cells.
8284 EAPI void evas_object_table_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
8287 * Get padding between cells.
8289 EAPI void evas_object_table_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
8292 * Set the alignment of the whole bounding box of contents.
8294 EAPI void evas_object_table_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
8297 * Get alignment of the whole bounding box of contents.
8299 EAPI void evas_object_table_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
8302 * Sets the mirrored mode of the table. In mirrored mode the table items go
8303 * from right to left instead of left to right. That is, 1,1 is top right, not
8306 * @param obj The table object.
8307 * @param mirrored the mirrored mode to set
8310 EAPI void evas_object_table_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
8313 * Gets the mirrored mode of the table. In mirrored mode the table items go
8314 * from right to left instead of left to right. That is, 1,1 is top right, not
8317 * @param obj The table object.
8318 * @return EINA_TRUE if it's a mirrored table, EINA_FALSE otherwise.
8323 * Get a child from the table using its coordinates
8325 * @note This does not take into account col/row spanning
8327 EAPI Eina_Bool evas_object_table_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
8331 * Add a new child to a table object.
8333 * @param o The given table object.
8334 * @param child The child object to add.
8335 * @param col relative-horizontal position to place child.
8336 * @param row relative-vertical position to place child.
8337 * @param colspan how many relative-horizontal position to use for this child.
8338 * @param rowspan how many relative-vertical position to use for this child.
8340 * @return 1 on success, 0 on failure.
8342 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);
8345 * Remove child from table.
8347 * @note removing a child will immediately call a walk over children in order
8348 * to recalculate numbers of columns and rows. If you plan to remove
8349 * all children, use evas_object_table_clear() instead.
8351 * @return 1 on success, 0 on failure.
8353 EAPI Eina_Bool evas_object_table_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8356 * Faster way to remove all child objects from a table object.
8358 * @param o The given table object.
8359 * @param clear if true, it will delete just removed children.
8361 EAPI void evas_object_table_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8365 * Get the number of columns and rows this table takes.
8367 * @note columns and rows are virtual entities, one can specify a table
8368 * with a single object that takes 4 columns and 5 rows. The only
8369 * difference for a single cell table is that paddings will be
8370 * accounted proportionally.
8372 EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1);
8375 * Get an iterator to walk the list of children for the table.
8377 * @note Do not remove or delete objects while walking the list.
8379 EAPI Eina_Iterator *evas_object_table_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8382 * Get an accessor to get random access to the list of children for the table.
8384 * @note Do not remove or delete objects while walking the list.
8386 EAPI Eina_Accessor *evas_object_table_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8389 * Get the list of children for the table.
8391 * @note This is a duplicate of the list kept by the table internally.
8392 * It's up to the user to destroy it when it no longer needs it.
8393 * It's possible to remove objects from the table when walking this
8394 * list, but these removals won't be reflected on it.
8396 EAPI Eina_List *evas_object_table_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8397 EAPI Evas_Object *evas_object_table_child_get (const Evas_Object *o, unsigned short col, unsigned short row) EINA_ARG_NONNULL(1);
8400 * @defgroup Evas_Object_Grid Grid Smart Object.
8402 * Convenience smart object that packs children using a regular grid
8403 * layout using Their virtual grid location and size to determine
8404 * position inside the grid object
8406 * @ingroup Evas_Smart_Object_Group
8411 * Create a new grid.
8413 * It's set to a virtual size of 1x1 by default and add children with
8414 * evas_object_grid_pack().
8417 EAPI Evas_Object *evas_object_grid_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8420 * Create a grid that is child of a given element @a parent.
8422 * @see evas_object_grid_add()
8425 EAPI Evas_Object *evas_object_grid_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8428 * Set the virtual resolution for the grid
8430 * @param o The grid object to modify
8431 * @param w The virtual horizontal size (resolution) in integer units
8432 * @param h The virtual vertical size (resolution) in integer units
8435 EAPI void evas_object_grid_size_set (Evas_Object *o, int w, int h) EINA_ARG_NONNULL(1);
8438 * Get the current virtual resolution
8440 * @param o The grid object to query
8441 * @param w A pointer to an integer to store the virtual width
8442 * @param h A pointer to an integer to store the virtual height
8443 * @see evas_object_grid_size_set()
8446 EAPI void evas_object_grid_size_get (const Evas_Object *o, int *w, int *h) EINA_ARG_NONNULL(1) EINA_PURE;
8449 * Sets the mirrored mode of the grid. In mirrored mode the grid items go
8450 * from right to left instead of left to right. That is, 0,0 is top right, not
8453 * @param obj The grid object.
8454 * @param mirrored the mirrored mode to set
8457 EAPI void evas_object_grid_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
8460 * Gets the mirrored mode of the grid.
8462 * @param obj The grid object.
8463 * @return EINA_TRUE if it's a mirrored grid, EINA_FALSE otherwise.
8464 * @see evas_object_grid_mirrored_set()
8467 EAPI Eina_Bool evas_object_grid_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
8470 * Add a new child to a grid object.
8472 * @param o The given grid object.
8473 * @param child The child object to add.
8474 * @param x The virtual x coordinate of the child
8475 * @param y The virtual y coordinate of the child
8476 * @param w The virtual width of the child
8477 * @param h The virtual height of the child
8478 * @return 1 on success, 0 on failure.
8481 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);
8484 * Remove child from grid.
8486 * @note removing a child will immediately call a walk over children in order
8487 * to recalculate numbers of columns and rows. If you plan to remove
8488 * all children, use evas_object_grid_clear() instead.
8490 * @return 1 on success, 0 on failure.
8493 EAPI Eina_Bool evas_object_grid_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8496 * Faster way to remove all child objects from a grid object.
8498 * @param o The given grid object.
8499 * @param clear if true, it will delete just removed children.
8502 EAPI void evas_object_grid_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8505 * Get the pack options for a grid child
8507 * Get the pack x, y, width and height in virtual coordinates set by
8508 * evas_object_grid_pack()
8509 * @param o The grid object
8510 * @param child The grid child to query for coordinates
8511 * @param x The pointer to where the x coordinate will be returned
8512 * @param y The pointer to where the y coordinate will be returned
8513 * @param w The pointer to where the width will be returned
8514 * @param h The pointer to where the height will be returned
8515 * @return 1 on success, 0 on failure.
8518 EAPI Eina_Bool evas_object_grid_pack_get (Evas_Object *o, Evas_Object *child, int *x, int *y, int *w, int *h);
8521 * Get an iterator to walk the list of children for the grid.
8523 * @note Do not remove or delete objects while walking the list.
8526 EAPI Eina_Iterator *evas_object_grid_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8529 * Get an accessor to get random access to the list of children for the grid.
8531 * @note Do not remove or delete objects while walking the list.
8534 EAPI Eina_Accessor *evas_object_grid_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8537 * Get the list of children for the grid.
8539 * @note This is a duplicate of the list kept by the grid internally.
8540 * It's up to the user to destroy it when it no longer needs it.
8541 * It's possible to remove objects from the grid when walking this
8542 * list, but these removals won't be reflected on it.
8545 EAPI Eina_List *evas_object_grid_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8548 * @defgroup Evas_Cserve Shared Image Cache Server
8550 * Provides client-server infrastructure to share bitmaps across
8551 * multiple processes, saving data and processing power.
8553 typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
8554 typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
8555 typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
8556 typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
8559 * Statistics about server that shares cached bitmaps.
8560 * @ingroup Evas_Cserve
8562 struct _Evas_Cserve_Stats
8564 int saved_memory; /**< current saved memory, in bytes */
8565 int wasted_memory; /**< current wasted memory, in bytes */
8566 int saved_memory_peak; /**< peak of saved memory, in bytes */
8567 int wasted_memory_peak; /**< peak of wasted memory, in bytes */
8568 double saved_time_image_header_load; /**< time, in seconds, saved in header loads by sharing cached loads instead */
8569 double saved_time_image_data_load; /**< time, in seconds, saved in data loads by sharing cached loads instead */
8573 * Cache of images shared by server.
8574 * @ingroup Evas_Cserve
8576 struct _Evas_Cserve_Image_Cache
8586 * An image shared by the server.
8587 * @ingroup Evas_Cserve
8589 struct _Evas_Cserve_Image
8591 const char *file, *key;
8593 time_t file_mod_time;
8594 time_t file_checked_time;
8598 int memory_footprint;
8599 double head_load_time;
8600 double data_load_time;
8601 Eina_Bool alpha : 1;
8602 Eina_Bool data_loaded : 1;
8603 Eina_Bool active : 1;
8605 Eina_Bool useless : 1;
8609 * Configuration that controls the server that shares cached bitmaps.
8610 * @ingroup Evas_Cserve
8612 struct _Evas_Cserve_Config
8614 int cache_max_usage;
8615 int cache_item_timeout;
8616 int cache_item_timeout_check;
8621 * Retrieves if the system wants to share bitmaps using the server.
8622 * @return @c EINA_TRUE if wants, @c EINA_FALSE otherwise.
8623 * @ingroup Evas_Cserve
8625 EAPI Eina_Bool evas_cserve_want_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE;
8628 * Retrieves if the system is connected to the server used to shae bitmaps.
8629 * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise.
8630 * @ingroup Evas_Cserve
8632 EAPI Eina_Bool evas_cserve_connected_get (void) EINA_WARN_UNUSED_RESULT;
8635 * Retrieves if the system wants to share bitmaps using the server.
8636 * @param stats pointer to structure to fill with statistics about
8638 * @return @c EINA_TRUE if @p stats were filled with data,
8639 * @c EINA_FALSE otherwise and @p stats is untouched.
8640 * @ingroup Evas_Cserve
8642 EAPI Eina_Bool evas_cserve_stats_get (Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
8643 EAPI void evas_cserve_image_cache_contents_clean (Evas_Cserve_Image_Cache *cache) EINA_PURE;
8646 * Retrieves the current configuration of the server.
8647 * @param config where to store current server configuration.
8648 * @return @c EINA_TRUE if @p config were filled with data,
8649 * @c EINA_FALSE otherwise and @p config is untouched.
8650 * @ingroup Evas_Cserve
8652 EAPI Eina_Bool evas_cserve_config_get (Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE;
8655 * Changes the configuration of the server.
8656 * @param config where to store current server configuration.
8657 * @return @c EINA_TRUE if @p config were successfully applied,
8658 * @c EINA_FALSE otherwise.
8659 * @ingroup Evas_Cserve
8661 EAPI Eina_Bool evas_cserve_config_set (const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE;
8664 * Force system to disconnect from cache server.
8665 * @ingroup Evas_Cserve
8667 EAPI void evas_cserve_disconnect (void);
8670 * @defgroup Evas_Utils General Utilities
8672 * Some functions that are handy but are not specific of canvas or
8677 * Converts the given Evas image load error code into a string
8678 * describing it in english.
8680 * @param error the error code, a value in ::Evas_Load_Error.
8681 * @return Always returns a valid string. If the given @p error is not
8682 * supported, <code>"Unknown error"</code> is returned.
8684 * Mostly evas_object_image_file_set() would be the function setting
8685 * that error value afterwards, but also evas_object_image_load(),
8686 * evas_object_image_save(), evas_object_image_data_get(),
8687 * evas_object_image_data_convert(), evas_object_image_pixels_import()
8688 * and evas_object_image_is_inside(). This function is meant to be
8689 * used in conjunction with evas_object_image_load_error_get(), as in:
8692 * @dontinclude evas-load-error-str.c
8694 * @until ecore_main_loop_begin(
8696 * Here, being @c valid_path the path to a valid image and @c
8697 * bogus_path a path to a file which does not exist, the two outputs
8698 * of evas_load_error_str() would be (if no other errors occur):
8699 * <code>"No error on load"</code> and <code>"File (or file path) does
8700 * not exist"</code>, respectively. See the full @ref
8701 * Example_Evas_Load_Error_Str "example".
8703 * @ingroup Evas_Utils
8705 EAPI const char *evas_load_error_str (Evas_Load_Error error);
8707 /* Evas utility routines for color space conversions */
8708 /* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
8709 /* rgb color space has r,g,b in the range 0 to 255 */
8712 * Convert a given color from HSV to RGB format.
8714 * @param h The Hue component of the color.
8715 * @param s The Saturation component of the color.
8716 * @param v The Value component of the color.
8717 * @param r The Red component of the color.
8718 * @param g The Green component of the color.
8719 * @param b The Blue component of the color.
8721 * This function converts a given color in HSV color format to RGB
8724 * @ingroup Evas_Utils
8726 EAPI void evas_color_hsv_to_rgb (float h, float s, float v, int *r, int *g, int *b);
8729 * Convert a given color from RGB to HSV format.
8731 * @param r The Red component of the color.
8732 * @param g The Green component of the color.
8733 * @param b The Blue component of the color.
8734 * @param h The Hue component of the color.
8735 * @param s The Saturation component of the color.
8736 * @param v The Value component of the color.
8738 * This function converts a given color in RGB color format to HSV
8741 * @ingroup Evas_Utils
8743 EAPI void evas_color_rgb_to_hsv (int r, int g, int b, float *h, float *s, float *v);
8745 /* argb color space has a,r,g,b in the range 0 to 255 */
8748 * Pre-multiplies a rgb triplet by an alpha factor.
8750 * @param a The alpha factor.
8751 * @param r The Red component of the color.
8752 * @param g The Green component of the color.
8753 * @param b The Blue component of the color.
8755 * This function pre-multiplies a given rbg triplet by an alpha
8756 * factor. Alpha factor is used to define transparency.
8758 * @ingroup Evas_Utils
8760 EAPI void evas_color_argb_premul (int a, int *r, int *g, int *b);
8763 * Undo pre-multiplication of a rgb triplet by an alpha factor.
8765 * @param a The alpha factor.
8766 * @param r The Red component of the color.
8767 * @param g The Green component of the color.
8768 * @param b The Blue component of the color.
8770 * This function undoes pre-multiplication a given rbg triplet by an
8771 * alpha factor. Alpha factor is used to define transparency.
8773 * @see evas_color_argb_premul().
8775 * @ingroup Evas_Utils
8777 EAPI void evas_color_argb_unpremul (int a, int *r, int *g, int *b);
8781 * Pre-multiplies data by an alpha factor.
8783 * @param data The data value.
8784 * @param len The length value.
8786 * This function pre-multiplies a given data by an alpha
8787 * factor. Alpha factor is used to define transparency.
8789 * @ingroup Evas_Utils
8791 EAPI void evas_data_argb_premul (unsigned int *data, unsigned int len);
8794 * Undo pre-multiplication data by an alpha factor.
8796 * @param data The data value.
8797 * @param len The length value.
8799 * This function undoes pre-multiplication of a given data by an alpha
8800 * factor. Alpha factor is used to define transparency.
8802 * @ingroup Evas_Utils
8804 EAPI void evas_data_argb_unpremul (unsigned int *data, unsigned int len);
8806 /* string and font handling */
8809 * Gets the next character in the string
8811 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
8812 * this function will place in @p decoded the decoded code point at @p pos
8813 * and return the byte index for the next character in the string.
8815 * The only boundary check done is that @p pos must be >= 0. Other than that,
8816 * no checks are performed, so passing an index value that's not within the
8817 * length of the string will result in undefined behavior.
8819 * @param str The UTF-8 string
8820 * @param pos The byte index where to start
8821 * @param decoded Address where to store the decoded code point. Optional.
8823 * @return The byte index of the next character
8825 * @ingroup Evas_Utils
8827 EAPI int evas_string_char_next_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
8830 * Gets the previous character in the string
8832 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
8833 * this function will place in @p decoded the decoded code point at @p pos
8834 * and return the byte index for the previous character in the string.
8836 * The only boundary check done is that @p pos must be >= 1. Other than that,
8837 * no checks are performed, so passing an index value that's not within the
8838 * length of the string will result in undefined behavior.
8840 * @param str The UTF-8 string
8841 * @param pos The byte index where to start
8842 * @param decoded Address where to store the decoded code point. Optional.
8844 * @return The byte index of the previous character
8846 * @ingroup Evas_Utils
8848 EAPI int evas_string_char_prev_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
8851 * Get the length in characters of the string.
8852 * @param str The string to get the length of.
8853 * @return The length in characters (not bytes)
8854 * @ingroup Evas_Utils
8856 EAPI int evas_string_char_len_get (const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8859 * @defgroup Evas_Keys Key Input Functions
8861 * Functions which feed key events to the canvas.
8863 * As explained in @ref intro_not_evas, Evas is @b not aware of input
8864 * systems at all. Then, the user, if using it crudely (evas_new()),
8865 * will have to feed it with input events, so that it can react
8866 * somehow. If, however, the user creates a canvas by means of the
8867 * Ecore_Evas wrapper, it will automatically bind the chosen display
8868 * engine's input events to the canvas, for you.
8870 * This group presents the functions dealing with the feeding of key
8871 * events to the canvas. On most of them, one has to reference a given
8872 * key by a name (<code>keyname</code> argument). Those are
8873 * <b>platform dependent</b> symbolic names for the keys. Sometimes
8874 * you'll get the right <code>keyname</code> by simply using an ASCII
8875 * value of the key name, but it won't be like that always.
8877 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
8878 * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
8879 * to your display engine's documentation when using evas through an
8880 * Ecore helper wrapper when you need the <code>keyname</code>s.
8883 * @dontinclude evas-events.c
8884 * @skip mods = evas_key_modifier_get(evas);
8887 * All the other @c evas_key functions behave on the same manner. See
8888 * the full @ref Example_Evas_Events "example".
8890 * @ingroup Evas_Canvas
8894 * @addtogroup Evas_Keys
8899 * Returns a handle to the list of modifier keys registered in the
8900 * canvas @p e. This is required to check for which modifiers are set
8901 * at a given time with the evas_key_modifier_is_set() function.
8903 * @param e The pointer to the Evas canvas
8905 * @see evas_key_modifier_add
8906 * @see evas_key_modifier_del
8907 * @see evas_key_modifier_on
8908 * @see evas_key_modifier_off
8909 * @see evas_key_modifier_is_set
8911 * @return An ::Evas_Modifier handle to query Evas' keys subsystem
8912 * with evas_key_modifier_is_set(), or @c NULL on error.
8914 EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8917 * Returns a handle to the list of lock keys registered in the canvas
8918 * @p e. This is required to check for which locks are set at a given
8919 * time with the evas_key_lock_is_set() function.
8921 * @param e The pointer to the Evas canvas
8923 * @see evas_key_lock_add
8924 * @see evas_key_lock_del
8925 * @see evas_key_lock_on
8926 * @see evas_key_lock_off
8927 * @see evas_key_lock_is_set
8929 * @return An ::Evas_Lock handle to query Evas' keys subsystem with
8930 * evas_key_lock_is_set(), or @c NULL on error.
8932 EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8936 * Checks the state of a given modifier key, at the time of the
8937 * call. If the modifier is set, such as shift being pressed, this
8938 * function returns @c Eina_True.
8940 * @param m The current modifiers set, as returned by
8941 * evas_key_modifier_get().
8942 * @param keyname The name of the modifier key to check status for.
8944 * @return @c Eina_True if the modifier key named @p keyname is on, @c
8945 * Eina_False otherwise.
8947 * @see evas_key_modifier_add
8948 * @see evas_key_modifier_del
8949 * @see evas_key_modifier_get
8950 * @see evas_key_modifier_on
8951 * @see evas_key_modifier_off
8953 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;
8957 * Checks the state of a given lock key, at the time of the call. If
8958 * the lock is set, such as caps lock, this function returns @c
8961 * @param l The current locks set, as returned by evas_key_lock_get().
8962 * @param keyname The name of the lock key to check status for.
8964 * @return @c Eina_True if the @p keyname lock key is set, @c
8965 * Eina_False otherwise.
8967 * @see evas_key_lock_get
8968 * @see evas_key_lock_add
8969 * @see evas_key_lock_del
8970 * @see evas_key_lock_on
8971 * @see evas_key_lock_off
8973 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;
8977 * Adds the @p keyname key to the current list of modifier keys.
8979 * @param e The pointer to the Evas canvas
8980 * @param keyname The name of the modifier key to add to the list of
8983 * Modifiers are keys like shift, alt and ctrl, i.e., keys which are
8984 * meant to be pressed together with others, altering the behavior of
8985 * the secondly pressed keys somehow. Evas is so that these keys can
8988 * This call allows custom modifiers to be added to the Evas system at
8989 * run time. It is then possible to set and unset modifier keys
8990 * programmatically for other parts of the program to check and act
8991 * on. Programmers using Evas would check for modifier keys on key
8992 * event callbacks using evas_key_modifier_is_set().
8994 * @see evas_key_modifier_del
8995 * @see evas_key_modifier_get
8996 * @see evas_key_modifier_on
8997 * @see evas_key_modifier_off
8998 * @see evas_key_modifier_is_set
9000 * @note If the programmer instantiates the canvas by means of the
9001 * ecore_evas_new() family of helper functions, Ecore will take
9002 * care of registering on it all standard modifiers: "Shift",
9003 * "Control", "Alt", "Meta", "Hyper", "Super".
9005 EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9008 * Removes the @p keyname key from the current list of modifier keys
9011 * @param e The pointer to the Evas canvas
9012 * @param keyname The name of the key to remove from the modifiers list.
9014 * @see evas_key_modifier_add
9015 * @see evas_key_modifier_get
9016 * @see evas_key_modifier_on
9017 * @see evas_key_modifier_off
9018 * @see evas_key_modifier_is_set
9020 EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9023 * Adds the @p keyname key to the current list of lock keys.
9025 * @param e The pointer to the Evas canvas
9026 * @param keyname The name of the key to add to the locks list.
9028 * Locks are keys like caps lock, num lock or scroll lock, i.e., keys
9029 * which are meant to be pressed once -- toggling a binary state which
9030 * is bound to it -- and thus altering the behavior of all
9031 * subsequently pressed keys somehow, depending on its state. Evas is
9032 * so that these keys can be defined by the user.
9034 * This allows custom locks to be added to the evas system at run
9035 * time. It is then possible to set and unset lock keys
9036 * programmatically for other parts of the program to check and act
9037 * on. Programmers using Evas would check for lock keys on key event
9038 * callbacks using evas_key_lock_is_set().
9040 * @see evas_key_lock_get
9041 * @see evas_key_lock_del
9042 * @see evas_key_lock_on
9043 * @see evas_key_lock_off
9044 * @see evas_key_lock_is_set
9046 * @note If the programmer instantiates the canvas by means of the
9047 * ecore_evas_new() family of helper functions, Ecore will take
9048 * care of registering on it all standard lock keys: "Caps_Lock",
9049 * "Num_Lock", "Scroll_Lock".
9051 EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9054 * Removes the @p keyname key from the current list of lock keys on
9057 * @param e The pointer to the Evas canvas
9058 * @param keyname The name of the key to remove from the locks list.
9060 * @see evas_key_lock_get
9061 * @see evas_key_lock_add
9062 * @see evas_key_lock_on
9063 * @see evas_key_lock_off
9065 EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9069 * Enables or turns on programmatically the modifier key with name @p
9072 * @param e The pointer to the Evas canvas
9073 * @param keyname The name of the modifier to enable.
9075 * The effect will be as if the key was pressed for the whole time
9076 * between this call and a matching evas_key_modifier_off().
9078 * @see evas_key_modifier_add
9079 * @see evas_key_modifier_get
9080 * @see evas_key_modifier_off
9081 * @see evas_key_modifier_is_set
9083 EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9086 * Disables or turns off programmatically the modifier key with name
9089 * @param e The pointer to the Evas canvas
9090 * @param keyname The name of the modifier to disable.
9092 * @see evas_key_modifier_add
9093 * @see evas_key_modifier_get
9094 * @see evas_key_modifier_on
9095 * @see evas_key_modifier_is_set
9097 EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9100 * Enables or turns on programmatically the lock key with name @p
9103 * @param e The pointer to the Evas canvas
9104 * @param keyname The name of the lock to enable.
9106 * The effect will be as if the key was put on its active state after
9109 * @see evas_key_lock_get
9110 * @see evas_key_lock_add
9111 * @see evas_key_lock_del
9112 * @see evas_key_lock_off
9114 EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9117 * Disables or turns off programmatically the lock key with name @p
9120 * @param e The pointer to the Evas canvas
9121 * @param keyname The name of the lock to disable.
9123 * The effect will be as if the key was put on its inactive state
9126 * @see evas_key_lock_get
9127 * @see evas_key_lock_add
9128 * @see evas_key_lock_del
9129 * @see evas_key_lock_on
9131 EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9135 * Creates a bit mask from the @p keyname @b modifier key. Values
9136 * returned from different calls to it may be ORed together,
9139 * @param e The canvas whom to query the bit mask from.
9140 * @param keyname The name of the modifier key to create the mask for.
9142 * @returns the bit mask or 0 if the @p keyname key wasn't registered as a
9143 * modifier for canvas @p e.
9145 * This function is meant to be using in conjunction with
9146 * evas_object_key_grab()/evas_object_key_ungrab(). Go check their
9147 * documentation for more information.
9149 * @see evas_key_modifier_add
9150 * @see evas_key_modifier_get
9151 * @see evas_key_modifier_on
9152 * @see evas_key_modifier_off
9153 * @see evas_key_modifier_is_set
9154 * @see evas_object_key_grab
9155 * @see evas_object_key_ungrab
9157 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;
9161 * Requests @p keyname key events be directed to @p obj.
9163 * Key grabs allow an object to receive key events for specific key
9164 * strokes even if another object has focus. If the grab is
9165 * non-exclusive then all objects that have grabs on the key will get
9166 * the event, however if the grab is exclusive, no other object can
9167 * get a grab on the key and only that object will get the event.
9169 * @p keyname is a platform dependent symbolic name for the key
9170 * pressed. It is sometimes possible to convert the string to an
9171 * ASCII value of the key, but not always for example the enter key
9172 * may be returned as the string 'Enter'.
9174 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
9175 * (Ecore_X) when using Evas with Ecore and Ecore_Evas.
9177 * For a list of keynames for the Linux frame buffer, please refer to
9178 * the Ecore_FB documentation.
9180 * @p modifiers and @p not_modifiers are bit masks of all the
9181 * modifiers that are required and not required respectively for the
9182 * new grab. Modifiers can be things such as shift and ctrl as well
9183 * as user defigned types via evas_key_modifier_add.
9185 * @see evas_object_key_ungrab
9186 * @see evas_object_focus_set
9187 * @see evas_object_focus_get
9188 * @see evas_focus_get
9189 * @see evas_key_modifier_add
9191 * @param obj the object to direct @p keyname events to.
9192 * @param keyname the key to request events for.
9193 * @param modifiers a mask of modifiers that should be present to
9194 * trigger the event.
9195 * @param not_modifiers a mask of modifiers that should not be present
9196 * to trigger the event.
9197 * @param exclusive request that the @p obj is the only object
9198 * receiving the @p keyname events.
9199 * @return Boolean indicating whether the grab succeeded
9201 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);
9204 * Request that the grab on @p obj be removed.
9206 * Removes the grab on @p obj if @p keyname, @p modifiers, and @p not_modifiers
9209 * @see evas_object_key_grab
9210 * @see evas_object_focus_set
9211 * @see evas_object_focus_get
9212 * @see evas_focus_get
9214 * @param obj the object that has an existing grab.
9215 * @param keyname the key the grab is for.
9216 * @param modifiers a mask of modifiers that should be present to
9217 * trigger the event.
9218 * @param not_modifiers a mask of modifiers that should not be present
9219 * to trigger the event.
9221 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);