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>
35 @section toc Table of Contents
42 @li @ref intro_example
45 @section intro What is Evas?
47 Evas is a clean display canvas API for several target display systems that
48 can draw anti-aliased text, smooth super and sub-sampled scaled images,
49 alpha-blend objects much and more.
51 It abstracts any need to know much about what the characteristics of your
52 display system are or what graphics calls are used to draw them and how. It
53 deals on an object level where all you do is create and manipulate objects
54 in a canvas, set their properties, and the rest is done for you.
56 Evas optimises the rendering pipeline to minimise effort in redrawing changes
57 made to the canvas and so takes this work out of the programmers hand,
58 saving a lot of time and energy.
60 It's small and lean, designed to work on embedded systems all the way to
61 large and powerful multi-cpu workstations. It can be compiled to only have
62 the features you need for your target platform if you so wish, thus keeping
63 it small and lean. It has several display back-ends, letting it display on
64 several display systems, making it portable for cross-device and
65 cross-platform development.
67 @subsection intro_not_evas What Evas is not?
69 Evas is not a widget set or widget toolkit, however it is their
70 base. See Elementary (http://docs.enlightenment.org/auto/elementary/)
71 for a toolkit based on Evas, Edje, Ecore and other Enlightenment
74 It is not dependent or aware of main loops, input or output
75 systems. Input should be polled from various sources and feed them to
76 Evas. Similarly, it will not create windows or report windows updates
77 to your system, rather just drawing the pixels and reporting to the
78 user the areas that were changed. Of course these operations are quite
79 common and thus they are ready to use in Ecore, particularly in
80 Ecore_Evas (http://docs.enlightenment.org/auto/ecore/).
83 @section work How does Evas work?
85 Evas is a canvas display library. This is markedly different from most
86 display and windowing systems as a Canvas is structural and is also a state
87 engine, whereas most display and windowing systems are immediate mode display
88 targets. Evas handles the logic between a structural display via its' state
89 engine, and controls the target windowing system in order to produce
90 rendered results of the current canvases state on the display.
92 Immediate mode display systems retain very little, or no state. A program
93 will execute a series of commands, as in the pseudo code:
96 draw line from position (0, 0) to position (100, 200);
98 draw rectangle from position (10, 30) to position (50, 500);
100 bitmap_handle = create_bitmap();
101 scale bitmap_handle to size 100 x 100;
102 draw image bitmap_handle at position (10, 30);
105 The series of commands is executed by the windowing system and the results
106 are displayed on the screen (normally). Once the commands are executed the
107 display system has little or no idea of how to reproduce this image again,
108 and so has to be instructed by the application how to redraw sections of the
109 screen whenever needed. Each successive command will be executed as
110 instructed by the application and either emulated by software or sent to the
111 graphics hardware on the device to be performed.
113 The advantage of such a system is that it is simple, and gives a program
114 tight control over how something looks and is drawn. Given the increasing
115 complexity of displays and demands by users to have better looking
116 interfaces, more and more work is needing to be done at this level by the
117 internals of widget sets, custom display widgets and other programs. This
118 means more and more logic and display rendering code needs to be written
119 time and time again, each time the application needs to figure out how to
120 minimise redraws so that display is fast and interactive, and keep track of
121 redraw logic. The power comes at a high-price, lots of extra code and work.
122 Programmers not very familiar with graphics programming will often make
123 mistakes at this level and produce code that is sub optimal. Those familiar
124 with this kind of programming will simply get bored by writing the same code
127 For example, if in the above scene, the windowing system requires the
128 application to redraw the area from 0, 0 to 50, 50 (also referred as
129 "expose event"), then the programmer must calculate manually the
130 updates and repaint it again:
133 Redraw from position (0, 0) to position (50, 50):
135 // what was in area (0, 0, 50, 50)?
137 // 1. intersection part of line (0, 0) to (100, 200)?
138 draw line from position (0, 0) to position (25, 50);
140 // 2. intersection part of rectangle (10, 30) to (50, 500)?
141 draw rectangle from position (10, 30) to position (50, 50)
143 // 3. intersection part of image at (10, 30), size 100 x 100?
144 bitmap_subimage = subregion from position (0, 0) to position (40, 20)
145 draw image bitmap_subimage at position (10, 30);
148 The clever reader might have noticed that, if all elements in the
149 above scene are opaque, then the system is doing useless paints: part
150 of the line is behind the rectangle, and part of the rectangle is
151 behind the image. These useless paints tends to be very costly, as
152 pixels tend to be 4 bytes in size, thus an overlapping region of 100 x
153 100 pixels is around 40000 useless writes! The developer could write
154 code to calculate the overlapping areas and avoid painting then, but
155 then it should be mixed with the "expose event" handling mentioned
156 above and quickly one realizes the initially simpler method became
159 Evas is a structural system in which the programmer creates and manages
160 display objects and their properties, and as a result of this higher level
161 state management, the canvas is able to redraw the set of objects when
162 needed to represent the current state of the canvas.
164 For example, the pseudo code:
167 line_handle = create_line();
168 set line_handle from position (0, 0) to position (100, 200);
171 rectangle_handle = create_rectangle();
172 move rectangle_handle to position (10, 30);
173 resize rectangle_handle to size 40 x 470;
174 show rectangle_handle;
176 bitmap_handle = create_bitmap();
177 scale bitmap_handle to size 100 x 100;
178 move bitmap_handle to position (10, 30);
184 This may look longer, but when the display needs to be refreshed or updated,
185 the programmer only moves, resizes, shows, hides etc. the objects that they
186 need to change. The programmer simply thinks at the object logic level, and
187 the canvas software does the rest of the work for them, figuring out what
188 actually changed in the canvas since it was last drawn, how to most
189 efficiently redraw he canvas and its contents to reflect the current state,
190 and then it can go off and do the actual drawing of the canvas.
192 This lets the programmer think in a more natural way when dealing with a
193 display, and saves time and effort of working out how to load and display
194 images, render given the current display system etc. Since Evas also is
195 portable across different display systems, this also gives the programmer
196 the ability to have their code ported and display on different display
197 systems with very little work.
199 Evas can be seen as a display system that stands somewhere between a widget
200 set and an immediate mode display system. It retains basic display logic,
201 but does very little high-level logic such as scrollbars, sliders, push
205 @section compiling How to compile using Evas ?
207 Evas is a library your application links to. The procedure for this is very
208 simple. You simply have to compile your application with the appropriate
209 compiler flags that the @p pkg-config script outputs. For example:
211 Compiling C or C++ files into object files:
214 gcc -c -o main.o main.c `pkg-config --cflags evas`
217 Linking object files into a binary executable:
220 gcc -o my_application main.o `pkg-config --libs evas`
223 You simply have to make sure that pkg-config is in your shell's PATH (see
224 the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig
225 or its path is in the PKG_CONFIG_PATH environment variable. It's that simple
226 to link and use Evas once you have written your code to use it.
228 Since the program is linked to Evas, it is now able to use any advertised
229 API calls to display graphics in a canvas managed by Evas, as well as use
230 the API calls provided to manage data as well.
232 You should make sure you add any extra compile and link flags to your
233 compile commands that your application may need as well. The above example
234 is only guaranteed to make Evas add it's own requirements.
237 @section install How is it installed?
249 @section next_steps Next Steps
251 After you understood what Evas is and installed it in your system you
252 should proceed understanding the programming interface for all
253 objects, then see the specific for the most used elements. We'd
254 recommend you to take a while to learn Ecore
255 (http://docs.enlightenment.org/auto/ecore/) and Edje
256 (http://docs.enlightenment.org/auto/edje/) as they will likely save
257 you tons of work compared to using just Evas directly.
261 @li @ref Evas_Object_Group
262 @li @ref Evas_Object_Rectangle
263 @li @ref Evas_Object_Image
264 @li @ref Evas_Object_Text
265 @li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group to define
266 an object that provides custom functions to handle clipping,
267 hiding, moving, resizing, setting the color and more. These could
268 be as simple as a group of objects that move together (see @ref
269 Evas_Smart_Object_Clipped). These smart objects can implement what
270 ends to be a widget, providing some intelligence (thus the name),
271 like a button or check box.
273 @section intro_example Introductory Example
275 @include evas-buffer-simple.c
290 # ifdef EFL_EVAS_BUILD
292 # define EAPI __declspec(dllexport)
295 # endif /* ! DLL_EXPORT */
297 # define EAPI __declspec(dllimport)
298 # endif /* ! EFL_EVAS_BUILD */
302 # define EAPI __attribute__ ((visibility("default")))
309 #endif /* ! _WIN32 */
315 #define EVAS_VERSION_MAJOR 1
316 #define EVAS_VERSION_MINOR 0
318 typedef struct _Evas_Version
326 EAPI extern Evas_Version *evas_version;
330 * @brief These routines are used for Evas library interaction.
332 * @todo check boolean return values and convert to Eina_Bool
333 * @todo change all api to use EINA_SAFETY_*
334 * @todo finish api documentation
337 /* BiDi exposed stuff */
339 typedef enum _Evas_BiDi_Direction
341 EVAS_BIDI_DIRECTION_NATURAL,
342 EVAS_BIDI_DIRECTION_LTR,
343 EVAS_BIDI_DIRECTION_RTL
344 } Evas_BiDi_Direction;
347 * Identifier of callbacks to be used with object or canvas.
349 * @see evas_object_event_callback_add()
350 * @see evas_event_callback_add()
352 typedef enum _Evas_Callback_Type
355 * The following events are only for use with objects
356 * evas_object_event_callback_add():
358 EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */
359 EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
360 EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
361 EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
362 EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
363 EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
364 EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
365 EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
366 EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
367 EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
368 EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
369 EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
370 EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
371 EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
372 EVAS_CALLBACK_SHOW, /**< Show Event */
373 EVAS_CALLBACK_HIDE, /**< Hide Event */
374 EVAS_CALLBACK_MOVE, /**< Move Event */
375 EVAS_CALLBACK_RESIZE, /**< Resize Event */
376 EVAS_CALLBACK_RESTACK, /**< Restack Event */
377 EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
378 EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
379 EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
380 EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image as been preloaded */
383 * The following events are only for use with canvas
384 * evas_event_callback_add():
386 EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
387 EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
388 EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */
389 EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
390 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
391 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
394 * More object event types - see evas_object_event_callback_add():
396 EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanims in evas that throws out original image data) */
398 /* the following id no event number, but a sentinel: */
399 EVAS_CALLBACK_LAST /**< keep as last element/sentinel -- not really an event */
400 } Evas_Callback_Type; /**< The type of event to trigger the callback */
403 * Flags for Mouse Button events
405 typedef enum _Evas_Button_Flags
407 EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
408 EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< This mouse button press was the 2nd press of a double click */
409 EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< This mouse button press was the 3rd press of a triple click */
410 } Evas_Button_Flags; /**< Flags for Mouse Button events */
415 typedef enum _Evas_Event_Flags
417 EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
418 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 */
419 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 */
420 } Evas_Event_Flags; /**< Flags for Events */
423 * Flags for Font Hinting
424 * @ingroup Evas_Font_Group
426 typedef enum _Evas_Font_Hinting_Flags
428 EVAS_FONT_HINTING_NONE, /**< No font hinting */
429 EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
430 EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
431 } Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */
434 * Colorspaces for pixel data supported by Evas
435 * @ingroup Evas_Object_Image
437 typedef enum _Evas_Colorspace
439 EVAS_COLORSPACE_ARGB8888, /**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */
440 /* these are not currently supported - but planned for the future */
441 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 */
442 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 */
443 EVAS_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */
444 EVAS_COLORSPACE_GRY8 /**< 8bit grayscale */
445 } Evas_Colorspace; /**< Colorspaces for pixel data supported by Evas */
448 * How to pack items into cells in a table.
449 * @ingroup Evas_Object_Table
451 typedef enum _Evas_Object_Table_Homogeneous_Mode
453 EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0,
454 EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1,
455 EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2
456 } Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode. */
458 typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< A generic rectangle handle */
459 typedef struct _Evas_Point Evas_Point; /**< integer point */
461 typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */
462 typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */
464 typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */
465 typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */
468 * @typedef Evas_Smart_Class
469 * A smart object base class
470 * @ingroup Evas_Smart_Group
472 typedef struct _Evas_Smart_Class Evas_Smart_Class;
475 * @typedef Evas_Smart_Cb_Description
476 * A smart object callback description, used to provide introspection
477 * @ingroup Evas_Smart_Group
479 typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
483 * An opaque handle to map points
484 * @see evas_map_new()
485 * @see evas_map_free()
486 * @see evas_map_dup()
487 * @ingroup Evas_Object_Group_Map
489 typedef struct _Evas_Map Evas_Map;
493 * An opaque handle to an Evas canvas.
496 * @ingroup Evas_Canvas
498 typedef struct _Evas Evas;
501 * @typedef Evas_Object
502 * An Evas Object handle.
503 * @ingroup Evas_Object_Group
505 typedef struct _Evas_Object Evas_Object;
507 typedef void Evas_Performance; /**< An Evas Performance handle */
508 typedef struct _Evas_Modifier Evas_Modifier; /**< An opaque type containing information on which modifier keys are registered in an Evas canvas */
509 typedef struct _Evas_Lock Evas_Lock; /**< An opaque type containing information on which lock keys are registered in an Evas canvas */
510 typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
511 typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< A generic datatype for engine specific native surface information */
512 typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */
514 typedef int Evas_Coord;
515 typedef int Evas_Font_Size;
516 typedef int Evas_Angle;
518 struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */
520 Evas_Coord x; /**< top-left x co-ordinate of rectangle */
521 Evas_Coord y; /**< top-left y co-ordinate of rectangle */
522 Evas_Coord w; /**< width of rectangle */
523 Evas_Coord h; /**< height of rectangle */
531 struct _Evas_Coord_Point
536 struct _Evas_Coord_Precision_Point
542 struct _Evas_Position
545 Evas_Coord_Point canvas;
548 struct _Evas_Precision_Position
551 Evas_Coord_Precision_Point canvas;
554 typedef enum _Evas_Aspect_Control
556 EVAS_ASPECT_CONTROL_NONE = 0,
557 EVAS_ASPECT_CONTROL_NEITHER = 1,
558 EVAS_ASPECT_CONTROL_HORIZONTAL = 2,
559 EVAS_ASPECT_CONTROL_VERTICAL = 3,
560 EVAS_ASPECT_CONTROL_BOTH = 4
561 } Evas_Aspect_Control;
563 typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< A source description of pixels for importing pixels */
564 typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< A generic Evas Engine information structure */
565 typedef struct _Evas_Device Evas_Device; /**< A source device handle - where the event came from */
566 typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
567 typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
568 typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
569 typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
570 typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
571 typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
572 typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
573 typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
574 typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
575 typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
576 typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
577 typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< Event structure for #EVAS_CALLBACK_HOLD event callbacks */
579 typedef enum _Evas_Load_Error
581 EVAS_LOAD_ERROR_NONE = 0, /**< No error on load */
582 EVAS_LOAD_ERROR_GENERIC = 1, /**< A non-specific error occurred */
583 EVAS_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< File (or file path) does not exist */
584 EVAS_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission deinied to an existing file (or path) */
585 EVAS_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Allocation of resources failure prevented load */
586 EVAS_LOAD_ERROR_CORRUPT_FILE = 5, /**< File corrupt (but was detected as a known format) */
587 EVAS_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */
588 } Evas_Load_Error; /**< Evas image load error codes one can get - see evas_load_error_str() too. */
591 typedef enum _Evas_Alloc_Error
593 EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */
594 EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */
595 EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded, but extra memory had to be found by freeing up speculative resources */
596 } Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */
598 typedef enum _Evas_Fill_Spread
600 EVAS_TEXTURE_REFLECT = 0, /**< image fill tiling mode - tiling reflects */
601 EVAS_TEXTURE_REPEAT = 1, /**< tiling repeats */
602 EVAS_TEXTURE_RESTRICT = 2, /**< tiling clamps - range offset ignored */
603 EVAS_TEXTURE_RESTRICT_REFLECT = 3, /**< tiling clamps and any range offset reflects */
604 EVAS_TEXTURE_RESTRICT_REPEAT = 4, /**< tiling clamps and any range offset repeats */
605 EVAS_TEXTURE_PAD = 5 /**< tiling extends with end values */
606 } Evas_Fill_Spread; /**< Fill types used for evas_object_image_fill_spread_set() */
608 typedef enum _Evas_Pixel_Import_Pixel_Format
610 EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
611 EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
612 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 */
613 } Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
615 struct _Evas_Pixel_Import_Source
617 Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
618 int w, h; /**< width and height of source in pixels */
619 void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
622 /* magic version number to know what the native surf struct looks like */
623 #define EVAS_NATIVE_SURFACE_VERSION 2
625 typedef enum _Evas_Native_Surface_Type
627 EVAS_NATIVE_SURFACE_NONE,
628 EVAS_NATIVE_SURFACE_X11,
629 EVAS_NATIVE_SURFACE_OPENGL
630 } Evas_Native_Surface_Type;
632 struct _Evas_Native_Surface
635 Evas_Native_Surface_Type type;
638 void *visual; /**< visual of the pixmap to use (Visual) */
639 unsigned long pixmap; /**< pixmap id to use (Pixmap) */
642 unsigned int texture_id; /**< opengl texture id to use from glGenTextures() */
643 unsigned int framebuffer_id; /**< 0 if not a FBO, FBO id otherwise from glGenFramebuffers() */
644 unsigned int internal_format; /**< same as 'internalFormat' for glTexImage2D() */
645 unsigned int format; /**< same as 'format' for glTexImage2D() */
646 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) */
651 #define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
652 #define EVAS_LAYER_MAX 32767 /**< top-most layer number */
654 #define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
655 #define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
656 #define EVAS_TEXT_INVALID -1 /**< Not used for anything */
657 #define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
659 #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() */
660 #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() */
661 #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) */
662 #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) */
663 #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 */
664 #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 */
667 * How the object should be rendered to output.
668 * @ingroup Evas_Object_Group_Extras
670 typedef enum _Evas_Render_Op
672 EVAS_RENDER_BLEND = 0, /**< default op: d = d*(1-sa) + s */
673 EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
674 EVAS_RENDER_COPY = 2, /**< d = s */
675 EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
676 EVAS_RENDER_ADD = 4, /**< d = d + s */
677 EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
678 EVAS_RENDER_SUB = 6, /**< d = d - s */
679 EVAS_RENDER_SUB_REL = 7, /**< d = d - s*da */
680 EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
681 EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
682 EVAS_RENDER_MASK = 10, /**< d = d*sa */
683 EVAS_RENDER_MUL = 11 /**< d = d*s */
684 } Evas_Render_Op; /**< How the object should be rendered to output. */
686 typedef enum _Evas_Border_Fill_Mode
688 EVAS_BORDER_FILL_NONE = 0,
689 EVAS_BORDER_FILL_DEFAULT = 1,
690 EVAS_BORDER_FILL_SOLID = 2
691 } Evas_Border_Fill_Mode;
693 typedef enum _Evas_Image_Scale_Hint
695 EVAS_IMAGE_SCALE_HINT_NONE = 0,
696 EVAS_IMAGE_SCALE_HINT_DYNAMIC = 1,
697 EVAS_IMAGE_SCALE_HINT_STATIC = 2
698 } Evas_Image_Scale_Hint;
700 typedef enum _Evas_Engine_Render_Mode
702 EVAS_RENDER_MODE_BLOCKING = 0,
703 EVAS_RENDER_MODE_NONBLOCKING = 1,
704 } Evas_Engine_Render_Mode;
706 typedef enum _Evas_Image_Content_Hint
708 EVAS_IMAGE_CONTENT_HINT_NONE = 0,
709 EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1,
710 EVAS_IMAGE_CONTENT_HINT_STATIC = 2
711 } Evas_Image_Content_Hint;
713 struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
715 int magic; /**< Magic number */
718 struct _Evas_Event_Mouse_Down /** Mouse button press event */
720 int button; /**< Mouse button number that went down (1 - 32) */
723 Evas_Coord_Point canvas;
726 Evas_Modifier *modifiers;
729 Evas_Button_Flags flags;
730 unsigned int timestamp;
731 Evas_Event_Flags event_flags;
735 struct _Evas_Event_Mouse_Up /** Mouse button release event */
737 int button; /**< Mouse button number that was raised (1 - 32) */
740 Evas_Coord_Point canvas;
743 Evas_Modifier *modifiers;
746 Evas_Button_Flags flags;
747 unsigned int timestamp;
748 Evas_Event_Flags event_flags;
752 struct _Evas_Event_Mouse_In /** Mouse enter event */
754 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
757 Evas_Coord_Point canvas;
760 Evas_Modifier *modifiers;
762 unsigned int timestamp;
763 Evas_Event_Flags event_flags;
767 struct _Evas_Event_Mouse_Out /** Mouse leave event */
769 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
773 Evas_Coord_Point canvas;
776 Evas_Modifier *modifiers;
778 unsigned int timestamp;
779 Evas_Event_Flags event_flags;
783 struct _Evas_Event_Mouse_Move /** Mouse button down event */
785 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
787 Evas_Position cur, prev;
790 Evas_Modifier *modifiers;
792 unsigned int timestamp;
793 Evas_Event_Flags event_flags;
797 struct _Evas_Event_Mouse_Wheel /** Wheel event */
799 int direction; /* 0 = default up/down wheel FIXME: more wheel types */
800 int z; /* ...,-2,-1 = down, 1,2,... = up */
803 Evas_Coord_Point canvas;
806 Evas_Modifier *modifiers;
808 unsigned int timestamp;
809 Evas_Event_Flags event_flags;
813 struct _Evas_Event_Multi_Down /** Multi button press event */
815 int device; /**< Multi device number that went down (1 or more for extra touches) */
816 double radius, radius_x, radius_y;
817 double pressure, angle;
820 Evas_Coord_Precision_Point canvas;
823 Evas_Modifier *modifiers;
826 Evas_Button_Flags flags;
827 unsigned int timestamp;
828 Evas_Event_Flags event_flags;
832 struct _Evas_Event_Multi_Up /** Multi button release event */
834 int device; /**< Multi device number that went up (1 or more for extra touches) */
835 double radius, radius_x, radius_y;
836 double pressure, angle;
839 Evas_Coord_Precision_Point canvas;
842 Evas_Modifier *modifiers;
845 Evas_Button_Flags flags;
846 unsigned int timestamp;
847 Evas_Event_Flags event_flags;
851 struct _Evas_Event_Multi_Move /** Multi button down event */
853 int device; /**< Multi device number that moved (1 or more for extra touches) */
854 double radius, radius_x, radius_y;
855 double pressure, angle;
857 Evas_Precision_Position cur;
860 Evas_Modifier *modifiers;
862 unsigned int timestamp;
863 Evas_Event_Flags event_flags;
867 struct _Evas_Event_Key_Down /** Key press event */
869 char *keyname; /**< The string name of the key pressed */
871 Evas_Modifier *modifiers;
874 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
875 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
876 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 */
877 unsigned int timestamp;
878 Evas_Event_Flags event_flags;
882 struct _Evas_Event_Key_Up /** Key release event */
884 char *keyname; /**< The string name of the key released */
886 Evas_Modifier *modifiers;
889 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
890 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
891 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 */
892 unsigned int timestamp;
893 Evas_Event_Flags event_flags;
897 struct _Evas_Event_Hold /** Hold change event */
899 int hold; /**< The hold flag */
902 unsigned int timestamp;
903 Evas_Event_Flags event_flags;
908 * How mouse pointer should be handled by Evas.
910 * If #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse is down an
911 * object, then moves outside of it, the pointer still behaves as
912 * being bound to the object, albeit out of its drawing region. On
913 * mouse up, the event will be feed to the object, that may check if
914 * the final position is over or not and do something about it.
916 * @ingroup Evas_Object_Group_Extras
918 typedef enum _Evas_Object_Pointer_Mode
920 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
921 EVAS_OBJECT_POINTER_MODE_NOGRAB
922 } Evas_Object_Pointer_Mode; /**< How mouse pointer should be handled by Evas. */
924 typedef void (*Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info);
925 typedef void (*Evas_Event_Cb) (void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
926 typedef Eina_Bool (*Evas_Object_Event_Post_Cb) (void *data, Evas *e);
927 typedef void (*Evas_Object_Event_Cb) (void *data, Evas *e, Evas_Object *obj, void *event_info);
928 typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
931 * @defgroup Evas_Group Top Level Functions
933 * Functions that affect Evas as a whole.
939 * @return The init counter value.
941 * This function initializes Evas and increments a counter of the
942 * number of calls to it. It returs the new counter's value.
944 * @see evas_shutdown().
946 * Most EFL users wouldn't be using this function directly, because
947 * they wouldn't access Evas directly by themselves. Instead, they
948 * would be using higher level helpers, like @c ecore_evas_init().
949 * See http://docs.enlightenment.org/auto/ecore/.
951 * You should be using this if your use is something like the
952 * following. The buffer engine is just one of the many ones Evas
955 * @dontinclude evas-buffer-simple.c
958 * And being the canvas creation something like:
959 * @skip static Evas *create_canvas
960 * @until evas_output_viewport_set(canvas,
962 * Note that this is code creating an Evas canvas with no usage of
963 * Ecore helpers at all -- no linkage with Ecore on this scenario,
964 * thus. Again, this wouldn't be on Evas common usage for most
965 * developers. See the full @ref Example_Evas_Buffer_Simple "example".
967 * @ingroup Evas_Group
969 EAPI int evas_init (void);
974 * @return Evas' init counter value.
976 * This function finalizes Evas, decrementing the counter of the
977 * number of calls to the function evas_init(). This new value for the
978 * counter is returned.
982 * If you were the sole user of Evas, by means of evas_init(), you can
983 * check if it's being properly shut down by expecting a return value
986 * Example code follows.
987 * @dontinclude evas-buffer-simple.c
988 * @skip // NOTE: use ecore_evas_buffer_new
989 * @until evas_shutdown
990 * Where that function would contain:
991 * @skip evas_free(canvas)
992 * @until evas_free(canvas)
994 * Most users would be using ecore_evas_shutdown() instead, like told
995 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
998 * @ingroup Evas_Group
1000 EAPI int evas_shutdown (void);
1004 * Return if any allocation errors have occurred during the prior function
1005 * @return The allocation error flag
1007 * This function will return if any memory allocation errors occurred during,
1008 * and what kind they were. The return value will be one of
1009 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
1010 * with each meaning something different.
1012 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
1013 * worked as expected.
1015 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
1016 * its job and will have exited as cleanly as possible. The programmer
1017 * should consider this as a sign of very low memory and should try and safely
1018 * recover from the prior functions failure (or try free up memory elsewhere
1019 * and try again after more memory is freed).
1021 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
1022 * recovered from by evas finding memory of its own it has allocated and
1023 * freeing what it sees as not really usefully allocated memory. What is freed
1024 * may vary. Evas may reduce the resolution of images, free cached images or
1025 * fonts, trhow out pre-rendered data, reduce the complexity of change lists
1026 * etc. Evas and the program will function as per normal after this, but this
1027 * is a sign of low memory, and it is suggested that the program try and
1028 * identify memory it doesn't need, and free it.
1032 * extern Evas_Object *object;
1033 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
1035 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
1036 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
1038 * fprintf(stderr, "ERROR: Completely unable to attach callabck. Must\n");
1039 * fprintf(stderr, " destroy object now as it cannot be used.\n");
1040 * evas_object_del(object);
1042 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1043 * my_memory_cleanup();
1045 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
1047 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1048 * my_memory_cleanup();
1052 * @ingroup Evas_Group
1054 EAPI Evas_Alloc_Error evas_alloc_error (void);
1058 * @brief Get evas' internal asynchronous events read file descriptor.
1060 * @return The canvas' asynchronous events read file descriptor.
1062 * Evas' asynchronous events are meant to be dealt with internally,
1063 * i. e., when building stuff to be glued together into the EFL
1064 * infrastructure -- a module, for example. The context which demands
1065 * its use is when calculations need to be done out of the main
1066 * thread, asynchronously, and some action must be performed after
1069 * An example of actual use of this API is for image asynchronous
1070 * preload inside evas. If the canvas was instantiated through
1071 * ecore-evas usage, ecore itself will take care of calling those
1072 * events' processing.
1074 * This function returns the read file descriptor where to get the
1075 * asynchronous events of the canvas. Naturally, other mainloops,
1076 * apart from ecore, may make use of it.
1078 * @ingroup Evas_Group
1080 EAPI int evas_async_events_fd_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE;
1083 * @brief Trigger the processing of all events waiting on the file
1084 * descriptor returned by evas_async_events_fd_get().
1086 * @return The number of events processed.
1088 * All asynchronous events queued up by evas_async_events_put() are
1089 * processed here. More precisely, the callback functions, informed
1090 * together with other event parameters, when queued, get called (with
1091 * those parameters), in that order.
1093 * @ingroup Evas_Group
1095 EAPI int evas_async_events_process (void);
1098 * Insert asynchronous events on the canvas.
1100 * @param target The target to be affected by the events.
1101 * @param type The type of callback function.
1102 * @param event_info Information about the event.
1103 * @param func The callback function pointer.
1105 * This is the way, for a routine running outside evas' main thread,
1106 * to report an asynchronous event. A callback function is informed,
1107 * whose call is to happen after evas_async_events_process() is
1110 * @ingroup Evas_Group
1112 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);
1115 * @defgroup Evas_Canvas Canvas Functions
1117 * Low level Evas canvas functions. Sub groups will present more high
1118 * level ones, though.
1120 * Most of these functions deal with low level Evas actions, like:
1121 * @li create/destroy raw canvases, not bound to any displaying engine
1122 * @li tell a canvas i got focused (in a windowing context, for example)
1123 * @li tell a canvas a region should not be calculated anymore in rendering
1124 * @li tell a canvas to render its contents, immediately
1126 * Most users will be using Evas by means of the @c Ecore_Evas
1127 * wrapper, which deals with all the above mentioned issues
1128 * automatically for them. Thus, you'll be looking at this section
1129 * only if you're building low level stuff.
1131 * The groups within present you functions that deal with the canvas
1132 * directly, too, and not yet with its @b objects. They are the
1133 * functions you need to use at a minimum to get a working canvas.
1137 * Creates a new empty evas.
1139 * Note that before you can use the evas, you will to at a minimum:
1140 * @li Set its render method with @ref evas_output_method_set .
1141 * @li Set its viewport size with @ref evas_output_viewport_set .
1142 * @li Set its size of the canvas with @ref evas_output_size_set .
1143 * @li Ensure that the render engine is given the correct settings
1144 * with @ref evas_engine_info_set .
1146 * This function should only fail if the memory allocation fails
1148 * @note this function is very low level. Instead of using it
1149 * directly, consider using the high level functions in
1150 * Ecore_Evas such as @c ecore_evas_new(). See
1151 * http://docs.enlightenment.org/auto/ecore/.
1153 * @attention it is recommended that one calls evas_init() before
1154 * creating new canvas.
1156 * @return A new uninitialised Evas canvas on success. Otherwise, @c
1158 * @ingroup Evas_Canvas
1160 EAPI Evas *evas_new (void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
1163 * Frees the given evas and any objects created on it.
1165 * Any objects with 'free' callbacks will have those callbacks called
1168 * @param e The given evas.
1170 * @ingroup Evas_Canvas
1172 EAPI void evas_free (Evas *e) EINA_ARG_NONNULL(1);
1176 * Inform to the evas that it got the focus.
1178 * @param e The evas to change information.
1179 * @ingroup Evas_Canvas
1181 EAPI void evas_focus_in (Evas *e);
1184 * Inform to the evas that it lost the focus.
1186 * @param e The evas to change information.
1187 * @ingroup Evas_Canvas
1189 EAPI void evas_focus_out (Evas *e);
1192 * Get the focus state known by the given evas
1194 * @param e The evas to query information.
1195 * @ingroup Evas_Canvas
1197 EAPI Eina_Bool evas_focus_state_get (const Evas *e) EINA_PURE;
1200 * Push the nochange flag up 1
1202 * This tells evas, that while the nochange flag is greater than 0, do not
1203 * mark objects as "changed" when making changes.
1205 * @param e The evas to change information.
1206 * @ingroup Evas_Canvas
1208 EAPI void evas_nochange_push (Evas *e);
1211 * Pop the nochange flag down 1
1213 * This tells evas, that while the nochange flag is greater than 0, do not
1214 * mark objects as "changed" when making changes.
1216 * @param e The evas to change information.
1217 * @ingroup Evas_Canvas
1219 EAPI void evas_nochange_pop (Evas *e);
1223 * Attaches a specific pointer to the evas for fetching later
1225 * @param e The canvas to attach the pointer to
1226 * @param data The pointer to attach
1227 * @ingroup Evas_Canvas
1229 EAPI void evas_data_attach_set (Evas *e, void *data) EINA_ARG_NONNULL(1);
1232 * Returns the pointer attached by evas_data_attach_set()
1234 * @param e The canvas to attach the pointer to
1235 * @return The pointer attached
1236 * @ingroup Evas_Canvas
1238 EAPI void *evas_data_attach_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1242 * Add a damage rectangle.
1244 * @param e The given canvas pointer.
1245 * @param x The rectangle's left position.
1246 * @param y The rectangle's top position.
1247 * @param w The rectangle's width.
1248 * @param h The rectangle's height.
1250 * This is the function by which one tells evas that a part of the
1251 * canvas has to be repainted.
1253 * @ingroup Evas_Canvas
1255 EAPI void evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1258 * Add an "obscured region" to an Evas canvas.
1260 * @param e The given canvas pointer.
1261 * @param x The rectangle's top left corner's horizontal coordinate.
1262 * @param y The rectangle's top left corner's vertical coordinate
1263 * @param w The rectangle's width.
1264 * @param h The rectangle's height.
1266 * This is the function by which one tells an Evas canvas that a part
1267 * of it <b>must not</b> be repainted. The region must be
1268 * rectangular and its coordinates inside the canvas viewport are
1269 * passed in the call. After this call, the region specified won't
1270 * participate in any form in Evas' calculations and actions during
1271 * its rendering updates, having its displaying content frozen as it
1272 * was just after this function took place.
1274 * We call it "obscured region" because the most common use case for
1275 * this rendering (partial) freeze is something else (most problaby
1276 * other canvas) being on top of the specified rectangular region,
1277 * thus shading it completely from the user's final scene in a
1278 * display. To avoid unecessary processing, one should indicate to the
1279 * obscured canvas not to bother about the non-important area.
1281 * The majority of users won't have to worry about this funcion, as
1282 * they'll be using just one canvas in their applications, with
1283 * nothing inset or on top of it in any form.
1285 * To make this region one that @b has to be repainted again, call the
1286 * function evas_obscured_clear().
1288 * @note This is a <b>very low level function</b>, which most of
1289 * Evas' users wouldn't care about.
1291 * @note This function does @b not flag the canvas as having its state
1292 * changed. If you want to re-render it afterwards expecting new
1293 * contents, you have to add "damage" regions yourself (see
1294 * evas_damage_rectangle_add()).
1296 * @see evas_obscured_clear()
1297 * @see evas_render_updates()
1299 * Example code follows.
1300 * @dontinclude evas-events.c
1301 * @skip add an obscured
1302 * @until evas_obscured_clear(evas);
1304 * In that example, pressing the "Ctrl" and "o" keys will impose or
1305 * remove an obscured region in the middle of the canvas. You'll get
1306 * the same contents at the time the key was pressed, if toggling it
1307 * on, until you toggle it off again (make sure the animation is
1308 * running on to get the idea better). See the full @ref
1309 * Example_Evas_Events "example".
1311 * @ingroup Evas_Canvas
1313 EAPI void evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
1316 * Remove all "obscured regions" from an Evas canvas.
1318 * @param e The given canvas pointer.
1320 * This function removes all the rectangles from the obscured regions
1321 * list of the canvas @p e. It takes obscured areas added with
1322 * evas_obscured_rectangle_add() and make them again a regions that @b
1323 * have to be repainted on rendering updates.
1325 * @note This is a <b>very low level function</b>, which most of
1326 * Evas' users wouldn't care about.
1328 * @note This function does @b not flag the canvas as having its state
1329 * changed. If you want to re-render it afterwards expecting new
1330 * contents, you have to add "damage" regions yourself (see
1331 * evas_damage_rectangle_add()).
1333 * @see evas_obscured_rectangle_add() for an example
1334 * @see evas_render_updates()
1336 * @ingroup Evas_Canvas
1338 EAPI void evas_obscured_clear (Evas *e) EINA_ARG_NONNULL(1);
1341 * Force immediate renderization of the given Evas canvas.
1343 * @param e The given canvas pointer.
1344 * @return A newly allocated list of updated rectangles of the canvas
1345 * (@c Eina_Rectangle structs). Free this list with
1346 * evas_render_updates_free().
1348 * This function forces an immediate renderization update of the given
1351 * @note This is a <b>very low level function</b>, which most of
1352 * Evas' users wouldn't care about. One would use it, for example, to
1353 * grab an Evas' canvas update regions and paint them back, using the
1354 * canvas' pixmap, on a displaying system working below Evas.
1356 * @note Evas is a stateful canvas. If no operations changing its
1357 * state took place since the last rendering action, you won't see no
1358 * changes and this call will be a no-op.
1360 * Example code follows.
1361 * @dontinclude evas-events.c
1362 * @skip add an obscured
1363 * @until d.obscured = !d.obscured;
1365 * See the full @ref Example_Evas_Events "example".
1367 * @ingroup Evas_Canvas
1369 EAPI Eina_List *evas_render_updates (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1372 * Free the rectangles returned by evas_render_updates().
1374 * @param updates The list of updated rectangles of the canvas.
1376 * This function removes the region from the render updates list. It
1377 * makes the region doesn't be render updated anymore.
1379 * @see evas_render_updates() for an example
1381 * @ingroup Evas_Canvas
1383 EAPI void evas_render_updates_free (Eina_List *updates);
1386 * Force renderization of the given canvas.
1388 * @param e The given canvas pointer.
1390 * @ingroup Evas_Canvas
1392 EAPI void evas_render (Evas *e) EINA_ARG_NONNULL(1);
1395 * Update the canvas internal objects but not triggering immediate
1398 * @param e The given canvas pointer.
1400 * This function updates the canvas internal objects not triggering
1401 * renderization. To force renderization function evas_render() should
1406 * @ingroup Evas_Canvas
1408 EAPI void evas_norender (Evas *e) EINA_ARG_NONNULL(1);
1411 * Make the canvas discard internally cached data used for rendering.
1413 * @param e The given canvas pointer.
1415 * This function flushes the arrays of delete, active and render objects.
1416 * Other things it may also discard are: shared memory segments,
1417 * temporary scratch buffers, cached data to avoid re-compute of that data etc.
1419 * @ingroup Evas_Canvas
1421 EAPI void evas_render_idle_flush (Evas *e) EINA_ARG_NONNULL(1);
1424 * Make the canvas discard as much data as possible used by the engine at
1427 * @param e The given canvas pointer.
1429 * This function will unload images, delete textures and much more, where
1430 * possible. You may also want to call evas_render_idle_flush() immediately
1431 * prior to this to perhaps discard a little more, though evas_render_dump()
1432 * should implicitly delete most of what evas_render_idle_flush() might
1435 * @ingroup Evas_Canvas
1437 EAPI void evas_render_dump (Evas *e) EINA_ARG_NONNULL(1);
1440 * @defgroup Evas_Output_Method Render Engine Functions
1442 * Functions that are used to set the render engine for a given
1443 * function, and then get that engine working.
1445 * The following code snippet shows how they can be used to
1446 * initialise an evas that uses the X11 software engine:
1449 * Evas_Engine_Info_Software_X11 *einfo;
1450 * extern Display *display;
1451 * extern Window win;
1455 * evas = evas_new();
1456 * evas_output_method_set(evas, evas_render_method_lookup("software_x11"));
1457 * evas_output_size_set(evas, 640, 480);
1458 * evas_output_viewport_set(evas, 0, 0, 640, 480);
1459 * einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas);
1460 * einfo->info.display = display;
1461 * einfo->info.visual = DefaultVisual(display, DefaultScreen(display));
1462 * einfo->info.colormap = DefaultColormap(display, DefaultScreen(display));
1463 * einfo->info.drawable = win;
1464 * einfo->info.depth = DefaultDepth(display, DefaultScreen(display));
1465 * evas_engine_info_set(evas, (Evas_Engine_Info *)einfo);
1468 * @ingroup Evas_Canvas
1472 * Look up a numeric ID from a string name of a rendering engine.
1474 * @param name The string name of an engine
1475 * @return A numeric (opaque) ID for the rendering engine
1476 * @ingroup Evas_Output_Method
1478 * This function looks up a numeric return value for the named engine
1479 * in the string @p name. This is a normal C string, NUL byte
1480 * terminated. The name is case sensitive. If the rendering engine is
1481 * available, a numeric ID for that engine is returned that is not
1482 * 0. If the engine is not available, 0 is returned, indicating an
1485 * The programmer should NEVER rely on the numeric ID of an engine
1486 * unless it is returned by this function. Programs should NOT be
1487 * written accessing render method ID's directly, without first
1488 * obtaining it from this function.
1490 * @attention it is mandatory that one calls evas_init() before
1491 * looking up the render method.
1500 * evas = evas_new();
1503 * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
1506 * engine_id = evas_render_method_lookup("software_x11");
1509 * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
1512 * evas_output_method_set(evas, engine_id);
1515 EAPI int evas_render_method_lookup (const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1518 * List all the rendering engines compiled into the copy of the Evas library
1520 * @return A linked list whose data members are C strings of engine names
1521 * @ingroup Evas_Output_Method
1523 * Calling this will return a handle (pointer) to an Evas linked
1524 * list. Each node in the linked list will have the data pointer be a
1525 * (char *) pointer to the string name of the rendering engine
1526 * available. The strings should never be modified, neither should the
1527 * list be modified. This list should be cleaned up as soon as the
1528 * program no longer needs it using evas_render_method_list_free(). If
1529 * no engines are available from Evas, NULL will be returned.
1533 * Eina_List *engine_list, *l;
1534 * char *engine_name;
1536 * engine_list = evas_render_method_list();
1539 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1542 * printf("Available Evas Engines:\n");
1543 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1544 * printf("%s\n", engine_name);
1545 * evas_render_method_list_free(engine_list);
1548 EAPI Eina_List *evas_render_method_list (void) EINA_WARN_UNUSED_RESULT;
1551 * This function should be called to free a list of engine names
1553 * @param list The Eina_List base pointer for the engine list to be freed
1554 * @ingroup Evas_Output_Method
1556 * When this function is called it will free the engine list passed in
1557 * as @p list. The list should only be a list of engines generated by
1558 * calling evas_render_method_list(). If @p list is NULL, nothing will
1563 * Eina_List *engine_list, *l;
1564 * char *engine_name;
1566 * engine_list = evas_render_method_list();
1569 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1572 * printf("Available Evas Engines:\n");
1573 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1574 * printf("%s\n", engine_name);
1575 * evas_render_method_list_free(engine_list);
1578 EAPI void evas_render_method_list_free (Eina_List *list);
1582 * Sets the output engine for the given evas.
1584 * Once the output engine for an evas is set, any attempt to change it
1585 * will be ignored. The value for @p render_method can be found using
1586 * @ref evas_render_method_lookup .
1588 * @param e The given evas.
1589 * @param render_method The numeric engine value to use.
1591 * @attention it is mandatory that one calls evas_init() before
1592 * setting the output method.
1594 * @ingroup Evas_Output_Method
1596 EAPI void evas_output_method_set (Evas *e, int render_method) EINA_ARG_NONNULL(1);
1599 * Retrieves the number of the output engine used for the given evas.
1600 * @param e The given evas.
1601 * @return The ID number of the output engine being used. @c 0 is
1602 * returned if there is an error.
1603 * @ingroup Evas_Output_Method
1605 EAPI int evas_output_method_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1609 * Retrieves the current render engine info struct from the given evas.
1611 * The returned structure is publicly modifiable. The contents are
1612 * valid until either @ref evas_engine_info_set or @ref evas_render
1615 * This structure does not need to be freed by the caller.
1617 * @param e The given evas.
1618 * @return A pointer to the Engine Info structure. @c NULL is returned if
1619 * an engine has not yet been assigned.
1620 * @ingroup Evas_Output_Method
1622 EAPI Evas_Engine_Info *evas_engine_info_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
1625 * Applies the engine settings for the given evas from the given @c
1626 * Evas_Engine_Info structure.
1628 * To get the Evas_Engine_Info structure to use, call @ref
1629 * evas_engine_info_get . Do not try to obtain a pointer to an
1630 * @c Evas_Engine_Info structure in any other way.
1632 * You will need to call this function at least once before you can
1633 * create objects on an evas or render that evas. Some engines allow
1634 * their settings to be changed more than once.
1636 * Once called, the @p info pointer should be considered invalid.
1638 * @param e The pointer to the Evas Canvas
1639 * @param info The pointer to the Engine Info to use
1640 * @return 1 if no error occurred, 0 otherwise
1641 * @ingroup Evas_Output_Method
1643 EAPI Eina_Bool evas_engine_info_set (Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1);
1646 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1648 * Functions that set and retrieve the output and viewport size of an
1651 * @ingroup Evas_Canvas
1655 * Sets the output size of the render engine of the given evas.
1657 * The evas will render to a rectangle of the given size once this
1658 * function is called. The output size is independent of the viewport
1659 * size. The viewport will be stretched to fill the given rectangle.
1661 * The units used for @p w and @p h depend on the engine used by the
1664 * @param e The given evas.
1665 * @param w The width in output units, usually pixels.
1666 * @param h The height in output units, usually pixels.
1667 * @ingroup Evas_Output_Size
1669 EAPI void evas_output_size_set (Evas *e, int w, int h) EINA_ARG_NONNULL(1);
1672 * Retrieve the output size of the render engine of the given evas.
1674 * The output size is given in whatever the output units are for the
1677 * If either @p w or @p h is @c NULL, then it is ignored. If @p e is
1678 * invalid, the returned results are undefined.
1680 * @param e The given evas.
1681 * @param w The pointer to an integer to store the width in.
1682 * @param h The pointer to an integer to store the height in.
1683 * @ingroup Evas_Output_Size
1685 EAPI void evas_output_size_get (const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1);
1688 * Sets the output viewport of the given evas in evas units.
1690 * The output viewport is the area of the evas that will be visible to
1691 * the viewer. The viewport will be stretched to fit the output
1692 * target of the evas when rendering is performed.
1694 * @note The coordinate values do not have to map 1-to-1 with the output
1695 * target. However, it is generally advised that it is done for ease
1698 * @param e The given evas.
1699 * @param x The top-left corner x value of the viewport.
1700 * @param y The top-left corner y value of the viewport.
1701 * @param w The width of the viewport. Must be greater than 0.
1702 * @param h The height of the viewport. Must be greater than 0.
1703 * @ingroup Evas_Output_Size
1705 EAPI void evas_output_viewport_set (Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
1708 * Get the render engine's output viewport co-ordinates in canvas units.
1709 * @param e The pointer to the Evas Canvas
1710 * @param x The pointer to a x variable to be filled in
1711 * @param y The pointer to a y variable to be filled in
1712 * @param w The pointer to a width variable to be filled in
1713 * @param h The pointer to a height variable to be filled in
1714 * @ingroup Evas_Output_Size
1716 * Calling this function writes the current canvas output viewport
1717 * size and location values into the variables pointed to by @p x, @p
1718 * y, @p w and @p h. On success the variables have the output
1719 * location and size values written to them in canvas units. Any of @p
1720 * x, @p y, @p w or @p h that are NULL will not be written to. If @p e
1721 * is invalid, the results are undefined.
1725 * extern Evas *evas;
1726 * Evas_Coord x, y, width, height;
1728 * evas_output_viewport_get(evas, &x, &y, &w, &h);
1731 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);
1734 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1736 * Functions that are used to map coordinates from the canvas to the
1737 * screen or the screen to the canvas.
1739 * @ingroup Evas_Canvas
1743 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1745 * @param e The pointer to the Evas Canvas
1746 * @param x The screen/output x co-ordinate
1747 * @return The screen co-ordinate translated to canvas unit co-ordinates
1748 * @ingroup Evas_Coord_Mapping_Group
1750 * This function takes in a horizontal co-ordinate as the @p x
1751 * parameter and converts it into canvas units, accounting for output
1752 * size, viewport size and location, returning it as the function
1753 * return value. If @p e is invalid, the results are undefined.
1757 * extern Evas *evas;
1758 * extern int screen_x;
1759 * Evas_Coord canvas_x;
1761 * canvas_x = evas_coord_screen_x_to_world(evas, screen_x);
1764 EAPI Evas_Coord evas_coord_screen_x_to_world (const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1767 * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
1769 * @param e The pointer to the Evas Canvas
1770 * @param y The screen/output y co-ordinate
1771 * @return The screen co-ordinate translated to canvas unit co-ordinates
1772 * @ingroup Evas_Coord_Mapping_Group
1774 * This function takes in a vertical co-ordinate as the @p y parameter
1775 * and converts it into canvas units, accounting for output size,
1776 * viewport size and location, returning it as the function return
1777 * value. If @p e is invalid, the results are undefined.
1781 * extern Evas *evas;
1782 * extern int screen_y;
1783 * Evas_Coord canvas_y;
1785 * canvas_y = evas_coord_screen_y_to_world(evas, screen_y);
1788 EAPI Evas_Coord evas_coord_screen_y_to_world (const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1791 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1793 * @param e The pointer to the Evas Canvas
1794 * @param x The canvas x co-ordinate
1795 * @return The output/screen co-ordinate translated to output co-ordinates
1796 * @ingroup Evas_Coord_Mapping_Group
1798 * This function takes in a horizontal co-ordinate as the @p x
1799 * parameter and converts it into output units, accounting for output
1800 * size, viewport size and location, returning it as the function
1801 * return value. If @p e is invalid, the results are undefined.
1805 * extern Evas *evas;
1807 * extern Evas_Coord canvas_x;
1809 * screen_x = evas_coord_world_x_to_screen(evas, canvas_x);
1812 EAPI int evas_coord_world_x_to_screen (const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1815 * Convert/scale a canvas co-ordinate into output screen co-ordinates
1817 * @param e The pointer to the Evas Canvas
1818 * @param y The canvas y co-ordinate
1819 * @return The output/screen co-ordinate translated to output co-ordinates
1820 * @ingroup Evas_Coord_Mapping_Group
1822 * This function takes in a vertical co-ordinate as the @p x parameter
1823 * and converts it into output units, accounting for output size,
1824 * viewport size and location, returning it as the function return
1825 * value. If @p e is invalid, the results are undefined.
1829 * extern Evas *evas;
1831 * extern Evas_Coord canvas_y;
1833 * screen_y = evas_coord_world_y_to_screen(evas, canvas_y);
1836 EAPI int evas_coord_world_y_to_screen (const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1839 * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
1841 * Functions that deal with the status of the pointer (mouse cursor).
1843 * @ingroup Evas_Canvas
1847 * This function returns the current known pointer co-ordinates
1849 * @param e The pointer to the Evas Canvas
1850 * @param x The pointer to an integer to be filled in
1851 * @param y The pointer to an integer to be filled in
1852 * @ingroup Evas_Pointer_Group
1854 * This function returns the current known screen/output co-ordinates
1855 * of the mouse pointer and sets the contents of the integers pointed
1856 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
1857 * valid canvas the results of this function are undefined.
1861 * extern Evas *evas;
1862 * int mouse_x, mouse_y;
1864 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
1865 * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y);
1868 EAPI void evas_pointer_output_xy_get (const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1);
1871 * This function returns the current known pointer co-ordinates
1873 * @param e The pointer to the Evas Canvas
1874 * @param x The pointer to a Evas_Coord to be filled in
1875 * @param y The pointer to a Evas_Coord to be filled in
1876 * @ingroup Evas_Pointer_Group
1878 * This function returns the current known canvas unit co-ordinates of
1879 * the mouse pointer and sets the contents of the Evas_Coords pointed
1880 * to by @p x and @p y to contain these co-ordinates. If @p e is not a
1881 * valid canvas the results of this function are undefined.
1885 * extern Evas *evas;
1886 * Evas_Coord mouse_x, mouse_y;
1888 * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
1889 * printf("Mouse is at canvas position %f, %f\n", mouse_x, mouse_y);
1892 EAPI void evas_pointer_canvas_xy_get (const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
1895 * Returns a bitmask with the mouse buttons currently pressed, set to 1
1897 * @param e The pointer to the Evas Canvas
1898 * @return A bitmask of the currently depressed buttons on the cavas
1899 * @ingroup Evas_Pointer_Group
1901 * Calling this function will return a 32-bit integer with the
1902 * appropriate bits set to 1 that correspond to a mouse button being
1903 * depressed. This limits Evas to a mouse devices with a maximum of 32
1904 * buttons, but that is generally in excess of any host system's
1905 * pointing device abilities.
1907 * A canvas by default begins with no mouse buttons being pressed and
1908 * only calls to evas_event_feed_mouse_down(),
1909 * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and
1910 * evas_event_feed_mouse_up_data() will alter that.
1912 * The least significant bit corresponds to the first mouse button
1913 * (button 1) and the most significant bit corresponds to the last
1914 * mouse button (button 32).
1916 * If @p e is not a valid canvas, the return value is undefined.
1920 * extern Evas *evas;
1921 * int button_mask, i;
1923 * button_mask = evas_pointer_button_down_mask_get(evas);
1924 * printf("Buttons currently pressed:\n");
1925 * for (i = 0; i < 32; i++)
1927 * if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1);
1931 EAPI int evas_pointer_button_down_mask_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1934 * Returns whether the mouse pointer is logically inside the canvas
1936 * @param e The pointer to the Evas Canvas
1937 * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise
1938 * @ingroup Evas_Pointer_Group
1940 * When this function is called it will return a value of either 0 or
1941 * 1, depending on if evas_event_feed_mouse_in(),
1942 * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(),
1943 * evas_event_feed_mouse_out_data() have been called to feed in a
1944 * mouse enter event into the canvas.
1946 * A return value of 1 indicates the mouse is logically inside the
1947 * canvas, and 0 implies it is logically outside the canvas.
1949 * A canvas begins with the mouse being assumed outside (0).
1951 * If @p e is not a valid canvas, the return value is undefined.
1955 * extern Evas *evas;
1957 * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n");
1958 * else printf("Mouse is out!\n");
1961 EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1962 EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1);
1965 * @defgroup Evas_Canvas_Events Canvas Events
1967 * Functions relating to canvas events, be they input (mice,
1968 * keyboards, etc) or output ones (internal states changing, etc).
1970 * @ingroup Evas_Canvas
1974 * @addtogroup Evas_Canvas_Events
1979 * Add (register) a callback function to a given canvas event.
1981 * @param e Canvas to attach a callback to
1982 * @param type The type of event that will trigger the callback
1983 * @param func The (callback) function to be called when the event is
1985 * @param data The data pointer to be passed to @p func
1987 * This function adds a function callback to the canvas @p e when the
1988 * event of type @p type occurs on it. The function pointer is @p
1991 * In the event of a memory allocation error during the addition of
1992 * the callback to the canvas, evas_alloc_error() should be used to
1993 * determine the nature of the error, if any, and the program should
1994 * sensibly try and recover.
1996 * A callback function must have the ::Evas_Event_Cb prototype
1997 * definition. The first parameter (@p data) in this definition will
1998 * have the same value passed to evas_event_callback_add() as the @p
1999 * data parameter, at runtime. The second parameter @p e is the canvas
2000 * pointer on which the event occurred. The third parameter @p
2001 * event_info is a pointer to a data structure that may or may not be
2002 * passed to the callback, depending on the event type that triggered
2003 * the callback. This is so because some events don't carry extra
2004 * context with them, but others do.
2006 * The event type @p type to trigger the function may be one of
2007 * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST,
2008 * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT,
2009 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and
2010 * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of
2011 * event that will trigger the callback to be called. Only the last
2012 * two of the event types listed here provide useful event information
2013 * data -- a pointer to the recently focused Evas object. For the
2014 * others the @p event_info pointer is going to be @c NULL.
2017 * @dontinclude evas-events.c
2018 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE
2019 * @until two canvas event callbacks
2021 * Looking to the callbacks registered above,
2022 * @dontinclude evas-events.c
2023 * @skip called when our rectangle gets focus
2024 * @until let's have our events back
2026 * we see that the canvas flushes its rendering pipeline
2027 * (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb
2028 * routine takes place: it has to redraw that image at a different
2029 * size. Also, the callback on an object being focused comes just
2030 * after we focus it explicitly, on code.
2032 * See the full @ref Example_Evas_Events "example".
2034 * @note Be careful not to add the same callback multiple times, if
2035 * that's not what you want, because Evas won't check if a callback
2036 * existed before exactly as the one being registered (and thus, call
2037 * it more than once on the event, in this case). This would make
2038 * sense if you passed different functions and/or callback data, only.
2040 EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
2043 * Delete a callback function from the canvas.
2045 * @param e Canvas to remove a callback from
2046 * @param type The type of event that was triggering the callback
2047 * @param func The function that was to be called when the event was triggered
2048 * @return The data pointer that was to be passed to the callback
2050 * This function removes the most recently added callback from the
2051 * canvas @p e which was triggered by the event type @p type and was
2052 * calling the function @p func when triggered. If the removal is
2053 * successful it will also return the data pointer that was passed to
2054 * evas_event_callback_add() when the callback was added to the
2055 * canvas. If not successful NULL will be returned.
2061 * void focus_in_callback(void *data, Evas *e, void *event_info);
2063 * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
2066 EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
2069 * Delete (unregister) a callback function registered to a given
2072 * @param e Canvas to remove an event callback from
2073 * @param type The type of event that was triggering the callback
2074 * @param func The function that was to be called when the event was
2076 * @param data The data pointer that was to be passed to the callback
2077 * @return The data pointer that was to be passed to the callback
2079 * This function removes <b>the first</b> added callback from the
2080 * canvas @p e matching the event type @p type, the registered
2081 * function pointer @p func and the callback data pointer @p data. If
2082 * the removal is successful it will also return the data pointer that
2083 * was passed to evas_event_callback_add() (that will be the same as
2084 * the parameter) when the callback(s) was(were) added to the
2085 * canvas. If not successful @c NULL will be returned. A common use
2086 * would be to remove an exact match of a callback.
2089 * @dontinclude evas-events.c
2090 * @skip evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
2091 * @until _object_focus_in_cb, NULL);
2093 * See the full @ref Example_Evas_Events "example".
2095 * @note For deletion of canvas events callbacks filtering by just
2096 * type and function pointer, user evas_event_callback_del().
2098 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);
2101 * Push a callback on the post-event callback stack
2103 * @param e Canvas to push the callback on
2104 * @param func The function that to be called when the stack is unwound
2105 * @param data The data pointer to be passed to the callback
2107 * Evas has a stack of callbacks that get called after all the callbacks for
2108 * an event have triggered (all the objects it triggers on and al the callbacks
2109 * in each object triggered). When all these have been called, the stack is
2110 * unwond from most recently to least recently pushed item and removed from the
2111 * stack calling the callback set for it.
2113 * This is intended for doing reverse logic-like processing, example - when a
2114 * child object that happens to get the event later is meant to be able to
2115 * "steal" functions from a parent and thus on unwind of this stack hav its
2116 * function called first, thus being able to set flags, or return 0 from the
2117 * post-callback that stops all other post-callbacks in the current stack from
2118 * being called (thus basically allowing a child to take control, if the event
2119 * callback prepares information ready for taking action, but the post callback
2120 * actually does the action).
2123 EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2126 * Remove a callback from the post-event callback stack
2128 * @param e Canvas to push the callback on
2129 * @param func The function that to be called when the stack is unwound
2131 * This removes a callback from the stack added with
2132 * evas_post_event_callback_push(). The first instance of the function in
2133 * the callback stack is removed from being executed when the stack is
2134 * unwound. Further instances may still be run on unwind.
2136 EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func);
2139 * Remove a callback from the post-event callback stack
2141 * @param e Canvas to push the callback on
2142 * @param func The function that to be called when the stack is unwound
2143 * @param data The data pointer to be passed to the callback
2145 * This removes a callback from the stack added with
2146 * evas_post_event_callback_push(). The first instance of the function and data
2147 * in the callback stack is removed from being executed when the stack is
2148 * unwound. Further instances may still be run on unwind.
2150 EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
2153 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
2155 * Functions that deal with the freezing of input event processing of
2158 * There might be scenarios during a graphical user interface
2159 * program's use when the developer whishes the users wouldn't be able
2160 * to deliver input events to this application. It may, for example,
2161 * be the time for it to populate a view or to change some
2162 * layout. Assuming proper behavior with user interaction during this
2163 * exact time would be hard, as things are in a changing state. The
2164 * programmer can then tell the canvas to ignore input events,
2165 * bringing it back to normal behavior when he/she wants.
2167 * @ingroup Evas_Canvas_Events
2171 * @addtogroup Evas_Event_Freezing_Group
2176 * Freeze all input events processing.
2178 * @param e The canvas to freeze input events processing on.
2180 * This function will indicate to Evas that the canvas @p e is to have
2181 * all input event processing frozen until a matching
2182 * evas_event_thaw() function is called on the same canvas. All events
2183 * of this kind during the freeze will get @b discarded. Every freeze
2184 * call must be matched by a thaw call in order to completely thaw out
2185 * a canvas (i.e. these calls may be nested). The most common use is
2186 * when you don't want the user to interect with your user interface
2187 * when you're populating a view or changing the layout.
2190 * @dontinclude evas-events.c
2191 * @skip freeze input for 3 seconds
2193 * @dontinclude evas-events.c
2194 * @skip let's have our events back
2197 * See the full @ref Example_Evas_Events "example".
2199 * If you run that example, you'll see the canvas ignoring all input
2200 * events for 3 seconds, when the "f" key is pressed. In a more
2201 * realistic code we would be freezing while a toolkit or Edje was
2202 * doing some UI changes, thawing it back afterwards.
2204 EAPI void evas_event_freeze (Evas *e) EINA_ARG_NONNULL(1);
2207 * Thaw a canvas out after freezing (for input events).
2209 * @param e The canvas to thaw out.
2211 * This will thaw out a canvas after a matching evas_event_freeze()
2212 * call. If this call completely thaws out a canvas, i.e., there's no
2213 * other unbalanced call to evas_event_freeze(), events will start to
2214 * be processed again, but any "missed" events will @b not be
2217 * See evas_event_freeze() for an example.
2219 EAPI void evas_event_thaw (Evas *e) EINA_ARG_NONNULL(1);
2222 * Return the freeze count on input events of a given canvas.
2224 * @param e The canvas to fetch the freeze count from.
2226 * This returns the number of times the canvas has been told to freeze
2227 * input events. It is possible to call evas_event_freeze() multiple
2228 * times, and these must be matched by evas_event_thaw() calls. This
2229 * call allows the program to discover just how many times things have
2230 * been frozen in case it may want to break out of a deep freeze state
2231 * where the count is high.
2235 * extern Evas *evas;
2237 * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
2241 EAPI int evas_event_freeze_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2244 * After thaw of a canvas, re-evaluate the state of objects and call callbacks
2246 * @param e The canvas to evaluate after a thaw
2248 * This is normally called after evas_event_thaw() to re-evaluate mouse
2249 * containment and other states and thus also call callbacks for mouse in and
2250 * out on new objects if the state change demands it.
2252 EAPI void evas_event_thaw_eval (Evas *e) EINA_ARG_NONNULL(1);
2259 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
2261 * Functions to tell Evas that input events happened and should be
2264 * As explained in @ref intro_not_evas, Evas does not know how to poll
2265 * for input events, so the developer should do it and then feed such
2266 * events to the canvas to be processed. This is only required if
2267 * operating Evas directly. Modules such as Ecore_Evas do that for
2270 * @ingroup Evas_Canvas_Events
2274 * @addtogroup Evas_Event_Feeding_Group
2279 * Mouse down event feed.
2281 * @param e The given canvas pointer.
2282 * @param b The button number.
2283 * @param flags The evas button flags.
2284 * @param timestamp The timestamp of the mouse down event.
2285 * @param data The data for canvas.
2287 * This function will set some evas properties that is necessary when
2288 * the mouse button is pressed. It prepares information to be treated
2289 * by the callback function.
2292 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);
2295 * Mouse up event feed.
2297 * @param e The given canvas pointer.
2298 * @param b The button number.
2299 * @param flags evas button flags.
2300 * @param timestamp The timestamp of the mouse up event.
2301 * @param data The data for canvas.
2303 * This function will set some evas properties that is necessary when
2304 * the mouse button is released. It prepares information to be treated
2305 * by the callback function.
2308 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);
2311 * Mouse move event feed.
2313 * @param e The given canvas pointer.
2314 * @param x The horizontal position of the mouse pointer.
2315 * @param y The vertical position of the mouse pointer.
2316 * @param timestamp The timestamp of the mouse up event.
2317 * @param data The data for canvas.
2319 * This function will set some evas properties that is necessary when
2320 * the mouse is moved from its last position. It prepares information
2321 * to be treated by the callback function.
2324 EAPI void evas_event_feed_mouse_move (Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2327 * Mouse in event feed.
2329 * @param e The given canvas pointer.
2330 * @param timestamp The timestamp of the mouse up event.
2331 * @param data The data for canvas.
2333 * This function will set some evas properties that is necessary when
2334 * the mouse in event happens. It prepares information to be treated
2335 * by the callback function.
2338 EAPI void evas_event_feed_mouse_in (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2341 * Mouse out event feed.
2343 * @param e The given canvas pointer.
2344 * @param timestamp Timestamp of the mouse up event.
2345 * @param data The data for canvas.
2347 * This function will set some evas properties that is necessary when
2348 * the mouse out event happens. It prepares information to be treated
2349 * by the callback function.
2352 EAPI void evas_event_feed_mouse_out (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2353 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);
2354 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);
2355 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);
2358 * Mouse cancel event feed.
2360 * @param e The given canvas pointer.
2361 * @param timestamp The timestamp of the mouse up event.
2362 * @param data The data for canvas.
2364 * This function will call evas_event_feed_mouse_up() when a
2365 * mouse cancel event happens.
2368 EAPI void evas_event_feed_mouse_cancel (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2371 * Mouse wheel event feed.
2373 * @param e The given canvas pointer.
2374 * @param direction The wheel mouse direction.
2375 * @param z How much mouse wheel was scrolled up or down.
2376 * @param timestamp The timestamp of the mouse up event.
2377 * @param data The data for canvas.
2379 * This function will set some evas properties that is necessary when
2380 * the mouse wheel is scrolled up or down. It prepares information to
2381 * be treated by the callback function.
2384 EAPI void evas_event_feed_mouse_wheel (Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2387 * Key down event feed
2389 * @param e The canvas to thaw out
2390 * @param keyname Name of the key
2391 * @param key The key pressed.
2392 * @param string A String
2393 * @param compose The compose string
2394 * @param timestamp Timestamp of the mouse up event
2395 * @param data Data for canvas.
2397 * This function will set some evas properties that is necessary when
2398 * a key is pressed. It prepares information to be treated by the
2399 * callback function.
2402 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);
2407 * @param e The canvas to thaw out
2408 * @param keyname Name of the key
2409 * @param key The key released.
2410 * @param string string
2411 * @param compose compose
2412 * @param timestamp Timestamp of the mouse up event
2413 * @param data Data for canvas.
2415 * This function will set some evas properties that is necessary when
2416 * a key is released. It prepares information to be treated by the
2417 * callback function.
2420 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);
2425 * @param e The given canvas pointer.
2426 * @param hold The hold.
2427 * @param timestamp The timestamp of the mouse up event.
2428 * @param data The data for canvas.
2430 * This function makes the object to stop sending events.
2433 EAPI void evas_event_feed_hold (Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
2444 * @defgroup Evas_Image_Group Image Functions
2446 * Functions that deals with images at canvas level.
2448 * @ingroup Evas_Canvas
2452 * Flush the image cache of the canvas.
2454 * @param e The given evas pointer.
2456 * This function flushes image cache of canvas.
2459 EAPI void evas_image_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2462 * Reload the image cache
2464 * @param e The given evas pointer.
2466 * This function reloads the image cache of canvas.
2469 EAPI void evas_image_cache_reload (Evas *e) EINA_ARG_NONNULL(1);
2472 * Set the image cache.
2474 * @param e The given evas pointer.
2475 * @param size The cache size.
2477 * This function sets the image cache of canvas.
2480 EAPI void evas_image_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2483 * Set the image cache
2485 * @param e The given evas pointer.
2487 * This function returns the image cache of canvas.
2490 EAPI int evas_image_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2493 * @defgroup Evas_Font_Group Font Functions
2495 * Functions that deals with fonts.
2497 * @ingroup Evas_Canvas
2501 * Changes the font hinting for the given evas.
2503 * @param e The given evas.
2504 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2505 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2506 * @ingroup Evas_Font_Group
2508 EAPI void evas_font_hinting_set (Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1);
2511 * Retrieves the font hinting used by the given evas.
2513 * @param e The given evas to query.
2514 * @return The hinting in use, one of #EVAS_FONT_HINTING_NONE,
2515 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2516 * @ingroup Evas_Font_Group
2518 EAPI Evas_Font_Hinting_Flags evas_font_hinting_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2521 * Checks if the font hinting is supported by the given evas.
2523 * @param e The given evas to query.
2524 * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE,
2525 * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
2526 * @return @c EINA_TRUE if it is supported, @c EINA_FALSE otherwise.
2527 * @ingroup Evas_Font_Group
2529 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;
2533 * Force the given evas and associated engine to flush its font cache.
2535 * @param e The given evas to flush font cache.
2536 * @ingroup Evas_Font_Group
2538 EAPI void evas_font_cache_flush (Evas *e) EINA_ARG_NONNULL(1);
2541 * Changes the size of font cache of the given evas.
2543 * @param e The given evas to flush font cache.
2544 * @param size The size, in bytes.
2546 * @ingroup Evas_Font_Group
2548 EAPI void evas_font_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1);
2551 * Changes the size of font cache of the given evas.
2553 * @param e The given evas to flush font cache.
2554 * @return The size, in bytes.
2556 * @ingroup Evas_Font_Group
2558 EAPI int evas_font_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2562 * List of available font descriptions known or found by this evas.
2564 * The list depends on Evas compile time configuration, such as
2565 * fontconfig support, and the paths provided at runtime as explained
2566 * in @ref Evas_Font_Path_Group.
2568 * @param e The evas instance to query.
2569 * @return a newly allocated list of strings. Do not change the
2570 * strings. Be sure to call evas_font_available_list_free()
2571 * after you're done.
2573 * @ingroup Evas_Font_Group
2575 EAPI Eina_List *evas_font_available_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2578 * Free list of font descriptions returned by evas_font_dir_available_list().
2580 * @param e The evas instance that returned such list.
2581 * @param available the list returned by evas_font_dir_available_list().
2583 * @ingroup Evas_Font_Group
2585 EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1);
2588 * @defgroup Evas_Font_Path_Group Font Path Functions
2590 * Functions that edit the paths being used to load fonts.
2592 * @ingroup Evas_Font_Group
2596 * Removes all font paths loaded into memory for the given evas.
2597 * @param e The given evas.
2598 * @ingroup Evas_Font_Path_Group
2600 EAPI void evas_font_path_clear (Evas *e) EINA_ARG_NONNULL(1);
2603 * Appends a font path to the list of font paths used by the given evas.
2604 * @param e The given evas.
2605 * @param path The new font path.
2606 * @ingroup Evas_Font_Path_Group
2608 EAPI void evas_font_path_append (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2611 * Prepends a font path to the list of font paths used by the given evas.
2612 * @param e The given evas.
2613 * @param path The new font path.
2614 * @ingroup Evas_Font_Path_Group
2616 EAPI void evas_font_path_prepend (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
2619 * Retrieves the list of font paths used by the given evas.
2620 * @param e The given evas.
2621 * @return The list of font paths used.
2622 * @ingroup Evas_Font_Path_Group
2624 EAPI const Eina_List *evas_font_path_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2627 * @defgroup Evas_Object_Group Generic Object Functions
2629 * Functions that manipulate generic Evas objects.
2631 * All Evas displaying units are Evas objects. One handles them all by
2632 * means of the handle ::Evas_Object. Besides Evas treats their
2633 * objects equally, they have @b types, which define their specific
2634 * behavior (and individual API).
2636 * Evas comes with a set of built-in object types:
2644 * These functions apply to @b any Evas object, whichever type thay
2647 * @note The built-in types which are most used are rectangles, text
2648 * and images. In fact, with these ones one can create 2D interfaces
2649 * of arbitrary complexity and EFL makes it easy.
2653 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
2655 * Methods that are broadly used, like those that change the color,
2656 * clippers and geometry of an Evas object.
2658 * @ingroup Evas_Object_Group
2662 * @addtogroup Evas_Object_Group_Basic
2667 * Clip one object to another.
2669 * @param obj The object to be clipped
2670 * @param clip The object to clip @p obj by
2672 * This function will clip the object @p obj to the area occupied by
2673 * the object @p clip. This means the object @p obj will only be
2674 * visible within the area occupied by the clipping object (@p clip).
2676 * The color of the object being clipped will be multiplied by the
2677 * color of the clipping one, so the resulting color for the former
2678 * will be <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color
2679 * element (red, green, blue and alpha).
2681 * Clipping is recursive, so clipping objects may be clipped by
2682 * others, and their color will in term be multiplied. You may @b not
2683 * set up circular clipping lists (i.e. object 1 clips object 2, which
2684 * clips object 1): the behavior of Evas is undefined in this case.
2686 * Objects which do not clip others are visible in the canvas as
2687 * normal; <b>those that clip one or more objects become invisible
2688 * themselves</b>, only affecting what they clip. If an object ceases
2689 * to have other objects being clipped by it, it will become visible
2692 * The visibility of an object affects the objects that are clipped by
2693 * it, so if the object clipping others is not shown (as in
2694 * evas_object_show()), the objects clipped by it will not be shown
2697 * If @p obj was being clipped by another object when this function is
2698 * called, it gets implicitly removed from the old clipper's domain
2699 * and is made now to be clipped by its new clipper.
2701 * @note At the moment the <b>only objects that can validly be used to
2702 * clip other objects are rectangle objects</b>. All other object
2703 * types are invalid and the result of using them is undefined. The
2704 * clip object @p clip must be a valid object, but can also be @c
2705 * NULL, in which case the effect of this function is the same as
2706 * calling evas_object_clip_unset() on the @p obj object.
2709 * @dontinclude evas-object-manipulation.c
2710 * @skip solid white clipper (note that it's the default color for a
2711 * @until evas_object_show(d.clipper);
2713 * See the full @ref Example_Evas_Object_Manipulation "example".
2715 EAPI void evas_object_clip_set (Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2);
2718 * Get the object clipping @p obj (if any).
2720 * @param obj The object to get the clipper from
2722 * This function returns the object clipping @p obj. If @p obj is
2723 * not being clipped at all, @c NULL is returned. The object @p obj
2724 * must be a valid ::Evas_Object.
2726 * See also evas_object_clip_set(), evas_object_clip_unset() and
2727 * evas_object_clipees_get().
2730 * @dontinclude evas-object-manipulation.c
2731 * @skip if (evas_object_clip_get(d.img) == d.clipper)
2734 * See the full @ref Example_Evas_Object_Manipulation "example".
2736 EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2739 * Disable/cease clipping on a clipped @p obj object.
2741 * @param obj The object to cease clipping on
2743 * This function disables clipping for the object @p obj, if it was
2744 * already clipped, i.e., its visibility and color get detached from
2745 * the previous clipper. If it wasn't, this has no effect. The object
2746 * @p obj must be a valid ::Evas_Object.
2748 * See also evas_object_clip_set() (for an example),
2749 * evas_object_clipees_get() and evas_object_clip_get().
2752 EAPI void evas_object_clip_unset (Evas_Object *obj);
2755 * Return a list of objects currently clipped by @p obj.
2757 * @param obj The object to get a list of clippees from
2758 * @return a list of objects being clipped by @p obj
2760 * This returns the internal list handle that contains all objects
2761 * clipped by the object @p obj. If none are clipped by it, the call
2762 * returns @c NULL. This list is only valid until the clip list is
2763 * changed and should be fetched again with another call to
2764 * evas_object_clipees_get() if any objects being clipped by this
2765 * object are unclipped, clipped by a new object, deleted or get the
2766 * clipper deleted. These operations will invalidate the list
2767 * returned, so it should not be used anymore after that point. Any
2768 * use of the list after this may have undefined results, possibly
2769 * leading to crashes. The object @p obj must be a valid
2772 * See also evas_object_clip_set(), evas_object_clip_unset() and
2773 * evas_object_clip_get().
2777 * extern Evas_Object *obj;
2778 * Evas_Object *clipper;
2780 * clipper = evas_object_clip_get(obj);
2783 * Eina_List *clippees, *l;
2784 * Evas_Object *obj_tmp;
2786 * clippees = evas_object_clipees_get(clipper);
2787 * printf("Clipper clips %i objects\n", eina_list_count(clippees));
2788 * EINA_LIST_FOREACH(clippees, l, obj_tmp)
2789 * evas_object_show(obj_tmp);
2793 EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2797 * Sets focus to the given object.
2799 * @param obj The object to be focused or unfocused.
2800 * @param focus set or remove focus to the object.
2802 * Changing focus only affects where key events go. There can be only
2803 * one object focused at any time. <p> If the parameter (@p focus) is
2804 * set, the passed object will be set as the currently focused object.
2805 * It will receive all keyboard events that are not exclusive key
2806 * grabs on other objects.
2808 * @see evas_object_focus_get
2809 * @see evas_focus_get
2810 * @see evas_object_key_grab
2811 * @see evas_object_key_ungrab
2813 EAPI void evas_object_focus_set (Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
2816 * Test if the object has focus.
2818 * @param obj The object to be tested.
2820 * If the passed object is the currently focused object 1 is returned,
2823 * @see evas_object_focus_set
2824 * @see evas_focus_get
2825 * @see evas_object_key_grab
2826 * @see evas_object_key_ungrab
2828 * @return 1 if the object has the focus, 0 otherwise.
2830 EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2834 * Sets the layer of the evas that the given object will be part of.
2836 * It is not possible to change the layer of a smart object's child.
2838 * @param obj The given Evas object.
2839 * @param l The number of the layer to place the object on.
2840 * Between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
2842 EAPI void evas_object_layer_set (Evas_Object *obj, short l) EINA_ARG_NONNULL(1);
2845 * Retrieves the layer of the evas that the given object is part of.
2847 * Be careful, it doesn't make sense to change the layer of smart object's
2848 * child. So the returned value could be wrong in some case. Don't rely on
2851 * @param obj The given Evas object.
2852 * @return Number of the layer.
2854 EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2858 * Sets the name of the given Evas object to the given name.
2860 * @param obj The given object.
2861 * @param name The given name.
2863 * There might be ocasions where one would like to name his/her
2867 * @dontinclude evas-events.c
2868 * @skip d.bg = evas_object_rectangle_add(d.canvas);
2869 * @until evas_object_name_set(d.bg, "our dear rectangle");
2871 * See the full @ref Example_Evas_Events "example".
2873 EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
2876 * Retrieves the name of the given Evas object.
2878 * @param obj The given object.
2879 * @return The name of the object or @c NULL, if no name has been given
2883 * @dontinclude evas-events.c
2884 * @skip fprintf(stdout, "An object got focused: %s\n",
2885 * @until evas_focus_get
2887 * See the full @ref Example_Evas_Events "example".
2889 EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
2893 * Increments object reference count to defer its deletion.
2895 * @param obj The given Evas object to reference
2897 * This increments the reference count of an object, which if greater
2898 * than 0 will defer deletion by evas_object_del() until all
2899 * references are released back (counter back to 0). References cannot
2900 * go below 0 and unreferencing past that will result in the reference
2901 * count being limited to 0. References are limited to <c>2^32 - 1</c>
2902 * for an object. Referencing it more than this will result in it
2903 * being limited to this value.
2905 * @see evas_object_unref()
2906 * @see evas_object_del()
2908 * @note This is a <b>very simple<b> reference counting mechanism! For
2909 * instance, Evas is not ready to check for pending references on a
2910 * canvas deletion, or things like that. This is useful on scenarios
2911 * where, inside a code block, callbacks exist which would possibly
2912 * delete an object we are operating on afterwards. Then, one would
2913 * evas_object_ref() it on the beginning of the block and
2914 * evas_object_unref() it on the end. I would then be deleted at this
2915 * point, if it should be.
2919 * evas_object_ref(obj);
2922 * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
2923 * // more action here...
2924 * evas_object_unref(obj);
2927 * @ingroup Evas_Object_Group_Basic
2930 EAPI void evas_object_ref (Evas_Object *obj);
2933 * Decrements object reference count.
2935 * @param obj The given Evas object to unreference
2937 * This decrements the reference count of an object. If the object has
2938 * had evas_object_del() called on it while references were more than
2939 * 0, it will be deleted at the time this function is called and puts
2940 * the counter back to 0. See evas_object_ref() for more information.
2942 * @see evas_object_ref() (for an example)
2943 * @see evas_object_del()
2945 * @ingroup Evas_Object_Group_Basic
2948 EAPI void evas_object_unref (Evas_Object *obj);
2952 * Marks the given Evas object for deletion (when Evas will free its
2955 * @param obj The given Evas object.
2957 * This call will mark @p obj for deletion, which will take place
2958 * whenever it has no more references to it (see evas_object_ref() and
2959 * evas_object_unref()).
2961 * At actual deletion time, which may or may not be just after this
2962 * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks will
2963 * be called. If the object currently had the focus, its
2964 * ::EVAS_CALLBACK_FOCUS_OUT callback will also be called.
2966 * @see evas_object_ref()
2967 * @see evas_object_unref()
2969 * @ingroup Evas_Object_Group_Basic
2971 EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
2974 * Move the given Evas object to the given location inside its
2977 * @param obj The given Evas object.
2978 * @param x X position to move the object to, in canvas units.
2979 * @param y Y position to move the object to, in canvas units.
2981 * Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback
2984 * @note Naturally, newly created objects are placed at the canvas'
2985 * origin: <code>0, 0</code>.
2988 * @dontinclude evas-object-manipulation.c
2989 * @skip evas_object_image_border_set(d.clipper_border, 3, 3, 3, 3);
2990 * @until evas_object_show
2992 * See the full @ref Example_Evas_Object_Manipulation "example".
2994 * @ingroup Evas_Object_Group_Basic
2996 EAPI void evas_object_move (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
2999 * Changes the size of the given Evas object.
3001 * @param obj The given Evas object.
3002 * @param w The new width of the Evas object.
3003 * @param h The new height of the Evas object.
3005 * Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback
3008 * @note Newly created objects have zeroed dimensions. Then, you most
3009 * probably want to use evas_object_resize() on them after they are
3012 * @note Be aware that resizing an object changes its drawing area,
3013 * but that does imply the object is rescaled! For instance, images
3014 * are filled inside their drawing area using the specifications of
3015 * evas_object_image_fill_set(). Thus to scale the image to match
3016 * exactly your drawing area, you need to change the
3017 * evas_object_image_fill_set() as well.
3019 * @note This is more evident in images, but text, textblock, lines
3020 * and polygons will behave similarly. Check their specific APIs to
3021 * know how to achieve your desired behavior. Consider the following
3025 * // rescale image to fill exactly its area without tiling:
3026 * evas_object_resize(img, w, h);
3027 * evas_object_image_fill_set(img, 0, 0, w, h);
3030 * @ingroup Evas_Object_Group_Basic
3032 EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
3035 * Retrieves the position and (rectangular) size of the given Evas
3038 * @param obj The given Evas object.
3039 * @param x Pointer to an integer in which to store the X coordinate
3041 * @param y Pointer to an integer in which to store the Y coordinate
3043 * @param w Pointer to an integer in which to store the width of the
3045 * @param h Pointer to an integer in which to store the height of the
3048 * The position, naturally, will be relative to the top left corner of
3049 * the canvas' viewport.
3051 * @note Use @c NULL pointers on the geometry components you're not
3052 * interested in: they'll be ignored by the function.
3055 * @dontinclude evas-events.c
3056 * @skip int w, h, cw, ch;
3059 * See the full @ref Example_Evas_Events "example".
3061 * @ingroup Evas_Object_Group_Basic
3063 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);
3067 * Makes the given Evas object visible.
3069 * @param obj The given Evas object.
3071 * Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW
3072 * callback will be called.
3074 * @see evas_object_hide() for more on object visibility.
3075 * @see evas_object_visible_get()
3077 * @ingroup Evas_Object_Group_Basic
3079 EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1);
3082 * Makes the given Evas object invisible.
3084 * @param obj The given Evas object.
3086 * Hidden objects, besides not being shown at all in your canvas,
3087 * won't be checked for changes on the canvas rendering
3088 * process. Furthermore, they will not catch input events. Thus, they
3089 * are much ligher (in processing needs) than an object that is
3090 * invisible due to indirect causes, such as being clipped or out of
3091 * the canvas' viewport.
3093 * Besides becoming hidden, @p obj object's ::EVAS_CALLBACK_SHOW
3094 * callback will be called.
3096 * @note All objects are created in the hidden state! If you want them
3097 * shown, use evas_object_show() after their creation.
3099 * @see evas_object_show()
3100 * @see evas_object_visible_get()
3103 * @dontinclude evas-object-manipulation.c
3104 * @skip if (evas_object_visible_get(d.clipper))
3107 * See the full @ref Example_Evas_Object_Manipulation "example".
3109 * @ingroup Evas_Object_Group_Basic
3111 EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1);
3114 * Retrieves whether or not the given Evas object is visible.
3116 * @param obj The given Evas object.
3117 * @return @c EINA_TRUE if the object is visible, @c EINA_FALSE
3120 * This retrieves an object's visibily as the one enforced by
3121 * evas_object_show() and evas_object_hide().
3123 * @note The value returned isn't, by any means, influenced by
3124 * clippers covering @obj, it being out of its canvas' viewport or
3125 * stacked below other object.
3127 * @see evas_object_show()
3128 * @see evas_object_hide() (for an example)
3130 * @ingroup Evas_Object_Group_Basic
3132 EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3136 * Sets the general/main color of the given Evas object to the given
3139 * @param obj The given Evas object.
3140 * @param r The red component of the given color.
3141 * @param g The green component of the given color.
3142 * @param b The blue component of the given color.
3143 * @param a The alpha component of the given color.
3145 * @see evas_object_color_get() (for an example)
3147 * @ingroup Evas_Object_Group_Basic
3149 EAPI void evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
3152 * Retrieves the general/main color of the given Evas object.
3154 * @param obj The given Evas object to retrieve color from.
3155 * @param r Pointer to an integer in which to store the red component
3157 * @param g Pointer to an integer in which to store the green
3158 * component of the color.
3159 * @param b Pointer to an integer in which to store the blue component
3161 * @param a Pointer to an integer in which to store the alpha
3162 * component of the color.
3164 * Retrieves the “main” color's RGB component (and alpha channel)
3165 * values, <b>which range from 0 to 255</b>. For the alpha channel,
3166 * which defines the object's transparency level, the former value
3167 * means totally trasparent, while the latter means opaque.
3169 * Usually you’ll use this attribute for text and rectangle objects,
3170 * where the “main” color is their unique one. If set for objects
3171 * which themselves have colors, like the images one, those colors get
3172 * modulated by this one.
3174 * @note All newly created Evas rectangles get the default color
3175 * values of <code>255 255 255 255</code> (opaque white).
3177 * @note Use @c NULL pointers on the components you're not interested
3178 * in: they'll be ignored by the function.
3181 * @dontinclude evas-object-manipulation.c
3182 * @skip int alpha, r, g, b;
3185 * See the full @ref Example_Evas_Object_Manipulation "example".
3187 * @ingroup Evas_Object_Group_Basic
3189 EAPI void evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
3193 * Retrieves the Evas canvas that the given object lives on.
3195 * @param obj The given Evas object.
3196 * @return A pointer to the canvas where the object is on.
3198 * This function is most useful at code contexts where you need to
3199 * operate on the canvas but have only the object pointer.
3201 * @ingroup Evas_Object_Group_Basic
3203 EAPI Evas *evas_object_evas_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3206 * Retrieves the type of the given Evas object.
3208 * @param obj The given object.
3209 * @return The type of the object.
3211 * For Evas' builtin types, the return strings will be one of:
3212 * - <c>"rectangle"</c>,
3214 * - <c>"polygon"</c>,
3216 * - <c>"textblock"</c> and
3219 * For Evas smart objects (see @ref Evas_Smart_Group), the name of the
3220 * smart class itself is returned on this call. For the built-in
3221 * clipped smart object, it is <c>"EvasObjectSmartClipped"</c>.
3224 * @dontinclude evas-object-manipulation.c
3225 * @skip d.img = evas_object_image_filled_add(d.canvas);
3226 * @until border on the
3228 * See the full @ref Example_Evas_Object_Manipulation "example".
3230 EAPI const char *evas_object_type_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3233 * Raise @p obj to the top of its layer.
3235 * @param obj the object to raise
3237 EAPI void evas_object_raise (Evas_Object *obj) EINA_ARG_NONNULL(1);
3240 * Lower @p obj to the bottom of its layer.
3242 * @param obj the object to lower
3244 EAPI void evas_object_lower (Evas_Object *obj) EINA_ARG_NONNULL(1);
3247 * Stack @p obj immediately above @p above
3249 * If @p obj is a member of a smart object, then @p above must also be
3250 * a member of the same smart object.
3252 * Similarly, if @p obj is not a member of smart object, @p above may
3255 * @param obj the object to stack
3256 * @param above the object above which to stack
3258 EAPI void evas_object_stack_above (Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2);
3261 * Stack @p obj immediately below @p below
3263 * If @p obj is a member of a smart object, then @p below must also be
3264 * a member of the same smart object.
3266 * Similarly, if @p obj is not a member of smart object, @p below may
3269 * @param obj the object to stack
3270 * @param below the object below which to stack
3272 EAPI void evas_object_stack_below (Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2);
3275 * Get the Evas object above @p obj
3277 * @param obj an Evas_Object
3278 * @return the Evas_Object directly above
3280 EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3283 * Get the Evas object below @p obj
3285 * @param obj an Evas_Object
3286 * @return the Evas_Object directly below
3288 EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3295 * @defgroup Evas_Object_Group_Events Object Events
3297 * Objects generates events when they are moved, resized, when their
3298 * visibility change, when they are deleted and so on. These methods
3299 * will allow one to handle such events.
3301 * The events can be those from keyboard and mouse, if the object
3302 * accepts these events.
3304 * @ingroup Evas_Object_Group
3308 * @addtogroup Evas_Object_Group_Events
3313 * Add a callback function to an object
3315 * @param obj Object to attach a callback to
3316 * @param type The type of event that will trigger the callback
3317 * @param func The function to be called when the event is triggered
3318 * @param data The data pointer to be passed to @p func
3320 * This function adds a function callback to an object when the event
3321 * of type @p type occurs on object @p obj. The function is @p func.
3323 * In the event of a memory allocation error during addition of the
3324 * callback to the object, evas_alloc_error() should be used to
3325 * determine the nature of the error, if any, and the program should
3326 * sensibly try and recover.
3328 * The function will be passed the pointer @p data when it is
3329 * called. A callback function must look like this:
3332 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
3335 * The first parameter @p data in this function will be the same value
3336 * passed to evas_object_event_callback_add() as the @p data
3337 * parameter. The second parameter is a convenience for the programmer
3338 * to know what evas canvas the event occurred on. The third parameter
3339 * @p obj is the Object handle on which the event occurred. The foruth
3340 * parameter @p event_info is a pointer to a data structure that may
3341 * or may not be passed to the callback, depending on the event type
3342 * that triggered the callback.
3344 * The event type @p type to trigger the function may be one of
3345 * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT,
3346 * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP,
3347 * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL,
3348 * #EVAS_CALLBACK_FREE, #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP,
3349 * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT,
3350 * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE,
3351 * #EVAS_CALLBACK_RESIZE or #EVAS_CALLBACK_RESTACK.
3352 * This determines the kind of event that will trigger the callback to
3353 * be called. The @p event_info pointer passed to the callback will
3354 * be one of the following, depending on the event triggering it:
3356 * #EVAS_CALLBACK_MOUSE_IN: event_info = pointer to Evas_Event_Mouse_In
3358 * This event is triggered when the mouse pointer enters the region of
3359 * the object @p obj. This may occur by the mouse pointer being moved
3360 * by evas_event_feed_mouse_move() or
3361 * evas_event_feed_mouse_move_data() calls, or by the object being
3362 * shown, raised, moved, resized, or other objects being moved out of
3363 * the way, hidden, lowered or moved out of the way.
3365 * #EVAS_CALLBACK_MOUSE_OUT: event_info = pointer to Evas_Event_Mouse_Out
3367 * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is, but
3368 * occurs when the mouse pointer exits an object. Note that no out
3369 * events will be reported if the mouse pointer is implicitly grabbed
3370 * to an object (the mouse buttons are down at all and any were
3371 * pressed on that object). An out event will be reported as soon as
3372 * the mouse is no longer grabbed (no mouse buttons are
3373 * depressed). Out events will be reported once all buttons are
3374 * released, if the mouse has left the object.
3376 * #EVAS_CALLBACK_MOUSE_DOWN: event_info = pointer to
3377 * Evas_Event_Mouse_Down
3379 * This event is triggered by a mouse button being depressed while
3380 * over an object. If pointermode is EVAS_OBJECT_POINTER_MODE_AUTOGRAB
3381 * (default) this causes this object to passively grab the mouse until
3382 * all mouse buttons have been released. That means if this mouse
3383 * button is the first to be pressed, all future mouse events will be
3384 * reported to only this object until no buttons are down. That
3385 * includes mouse move events, in and out events, and further button
3386 * presses. When all buttons are released, event propagation occurs as
3389 * #EVAS_CALLBACK_MOUSE_UP: event_info = pointer to Evas_Event_Mouse_Up
3391 * This event is triggered by a mouse button being released while over
3392 * an object or when passively grabbed to an object. If this is the
3393 * last mouse button to be raised on an object then the passive grab
3394 * is released and event processing will continue as normal.
3396 * #EVAS_CALLBACK_MOUSE_MOVE: event_info = pointer to Evas_Event_Mouse_Move
3398 * This event is triggered by the mouse pointer moving while over an
3399 * object or passively grabbed to an object.
3401 * #EVAS_CALLBACK_MOUSE_WHEEL: event_info = pointer to
3402 * Evas_Event_Mouse_Wheel
3404 * This event is triggered by the mouse wheel being rolled while over
3405 * an object or passively grabbed to an object.
3407 * #EVAS_CALLBACK_FREE: event_info = NULL
3409 * This event is triggered just before Evas is about to free all
3410 * memory used by an object and remove all references to it. This is
3411 * useful for programs to use if they attached data to an object and
3412 * want to free it when the object is deleted. The object is still
3413 * valid when this callback is called, but after this callback
3414 * returns, there is no guarantee on the object's validity.
3416 * #EVAS_CALLBACK_KEY_DOWN: event_info = pointer to Evas_Event_Key_Down
3418 * This callback is called when a key is pressed and the focus is on
3419 * the object, or a key has been grabbed to a particular object which
3420 * wants to intercept the key press regardless of what object has the
3423 * #EVAS_CALLBACK_KEY_UP: event_info = pointer to Evas_Event_Key_Up
3425 * This callback is called when a key is released and the focus is on
3426 * the object, or a key has been grabbed to a particular object which
3427 * wants to intercept the key release regardless of what object has
3430 * #EVAS_CALLBACK_FOCUS_IN: event_info = NULL
3432 * This event is called when an object gains the focus. When the
3433 * callback is called the object has already gained the focus.
3435 * #EVAS_CALLBACK_FOCUS_OUT: event_info = NULL
3437 * This event is triggered by an object losing the focus. When the
3438 * callback is called the object has already lost the focus.
3440 * #EVAS_CALLBACK_SHOW: event_info = NULL
3442 * This event is triggered by the object being shown by
3443 * evas_object_show().
3445 * #EVAS_CALLBACK_HIDE: event_info = NULL
3447 * This event is triggered by an object being hidden by
3448 * evas_object_hide().
3450 * #EVAS_CALLBACK_MOVE: event_info = NULL
3452 * This event is triggered by an object being
3453 * moved. evas_object_move() can trigger this, as can any
3454 * object-specific manipulations that would mean the object's origin
3457 * #EVAS_CALLBACK_RESIZE: event_info = NULL
3459 * This event is triggered by an object being resized. Resizes can be
3460 * triggered by evas_object_resize() or by any object-specific calls
3461 * that may cause the object to resize.
3465 * extern Evas_Object *object;
3466 * extern void *my_data;
3467 * void down_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3468 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3470 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_UP, up_callback, my_data);
3471 * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
3473 * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n");
3476 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, down_callback, my_data);
3477 * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
3479 * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n");
3484 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);
3487 * Delete a callback function from an object
3489 * @param obj Object to remove a callback from
3490 * @param type The type of event that was triggering the callback
3491 * @param func The function that was to be called when the event was triggered
3492 * @return The data pointer that was to be passed to the callback
3494 * This function removes the most recently added callback from the
3495 * object @p obj which was triggered by the event type @p type and was
3496 * calling the function @p func when triggered. If the removal is
3497 * successful it will also return the data pointer that was passed to
3498 * evas_object_event_callback_add() when the callback was added to the
3499 * object. If not successful NULL will be returned.
3503 * extern Evas_Object *object;
3505 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3507 * my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
3510 EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3);
3513 * Delete a callback function from an object
3515 * @param obj Object to remove a callback from
3516 * @param type The type of event that was triggering the callback
3517 * @param func The function that was to be called when the event was triggered
3518 * @param data The data pointer that was to be passed to the callback
3519 * @return The data pointer that was to be passed to the callback
3521 * This function removes the most recently added callback from the
3522 * object @p obj which was triggered by the event type @p type and was
3523 * calling the function @p func with data @p data when triggered. If
3524 * the removal is successful it will also return the data pointer that
3525 * was passed to evas_object_event_callback_add() (that will be the
3526 * same as the parameter) when the callback was added to the
3527 * object. If not successful NULL will be returned.
3531 * extern Evas_Object *object;
3533 * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
3535 * my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
3538 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);
3542 * Set an object's pass events state.
3543 * @param obj the Evas object
3544 * @param pass whether to pass events or not
3546 * If @p pass is true, this will cause events on @p obj to be ignored.
3547 * They will be triggered on the next lower object (that is not set to
3548 * pass events) instead.
3550 * If @p pass is false, events will be processed as normal.
3552 EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1);
3555 * Determine whether an object is set to pass events.
3557 * @return pass events state
3559 EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3562 * Set an object's repeat events state.
3563 * @param obj the object
3564 * @param repeat wheter to repeat events or not
3566 * If @p repeat is true, this will cause events on @p obj to trigger
3567 * callbacks, but also to be repeated on the next lower object in the
3570 * If @p repeat is false, events occurring on @p obj will be processed
3573 EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
3576 * Determine whether an object is set to repeat events.
3578 * @return repeat events state
3580 EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3583 * Set whether events on a smart member object should propagate to its
3586 * @param obj the smart member object
3587 * @param prop wheter to propagate events or not
3589 * This function has no effect if @p obj is not a member of a smart
3592 * If @p prop is true, events occurring on this object will propagate on
3593 * to the smart object of which @p obj is a member.
3595 * If @p prop is false, events for which callbacks are set on the member
3596 * object, @p obj, will not be passed on to the parent smart object.
3598 * The default value is true.
3600 EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1);
3603 * Determine whether an object is set to propagate events.
3605 * @return propagate events state
3607 EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
3614 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspecitve, 3D...)
3616 * Evas allows different transformations to be applied to all kinds of
3617 * objects. These are applied by means of UV mapping.
3619 * With UV mapping, one maps points in the source object to a 3D space
3620 * positioning at target. This allows rotation, perspective, scale and
3621 * lots of other effects, depending on the map that is used.
3623 * Each map point may carry a multiplier color. If properly
3624 * calculated, these can do shading effects on the object, producing
3627 * As usual, Evas provides both the raw and easy to use methods. The
3628 * raw methods allow developer to create its maps somewhere else,
3629 * maybe load them from some file format. The easy to use methods,
3630 * calculate the points given some high-level parameters, such as
3631 * rotation angle, ambient light and so on.
3633 * @note applying mapping will reduce performance, so use with
3634 * care. The impact on performance depends on engine in
3635 * use. Software is quite optimized, but not as fast as OpenGL.
3637 * @ingroup Evas_Object_Group
3641 * Enable or disable the map that is set.
3643 * This enables the map that is set or disables it. On enable, the object
3644 * geometry will be saved, and the new geometry will change (position and
3645 * size) to reflect the map geometry set. If none is set yet, this may be
3646 * an undefined geometry, unless you have already set the map with
3647 * evas_object_map_set(). It is suggested you first set a map with
3648 * evas_object_map_set() with valid useful coordinates then enable and
3649 * disable the map with evas_object_map_enable_set() as needed.
3651 * @param obj object to enable the map on
3652 * @param enabled enabled state
3654 EAPI void evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled);
3657 * Get the map enabled state
3659 * This returns the currently enabled state of the map on the object indicated.
3660 * The default map enable state is off. You can enable and disable it with
3661 * evas_object_map_enable_set().
3663 * @param obj object to get the map enabled state from
3664 * @return the map enabled state
3666 EAPI Eina_Bool evas_object_map_enable_get (const Evas_Object *obj);
3669 * Set the map source object
3671 * This sets the object from which the map is taken - can be any object that
3672 * has map enabled on it.
3674 * Currently not implemented. for future use.
3676 * @param obj object to set the map source of
3677 * @param src the source object from which the map is taken
3679 EAPI void evas_object_map_source_set (Evas_Object *obj, Evas_Object *src);
3682 * Get the map source object
3684 * See evas_object_map_source_set()
3686 * @param obj object to set the map source of
3687 * @return the object set as the source
3689 EAPI Evas_Object *evas_object_map_source_get (const Evas_Object *obj);
3692 * Set current object transformation map.
3694 * This sets the map on a given object. It is copied from the @p map pointer,
3695 * so there is no need to keep the @p map object if you don't need it anymore.
3697 * A map is a set of 4 points which have canvas x, y coordinates per point,
3698 * with an optional z point value as a hint for perspective correction, if it
3699 * is available. As well each point has u and v coordinates. These are like
3700 * "texture coordinates" in OpenGL in that they define a point in the source
3701 * image that is mapped to that map vertex/point. The u corresponds to the x
3702 * coordinate of this mapped point and v, the y coordinate. Note that these
3703 * coordinates describe a bounding region to sample. If you have a 200x100
3704 * source image and want to display it at 200x100 with proper pixel
3705 * precision, then do:
3708 * Evas_Map *m = evas_map_new(4);
3709 * evas_map_point_coord_set(m, 0, 0, 0, 0);
3710 * evas_map_point_coord_set(m, 1, 200, 0, 0);
3711 * evas_map_point_coord_set(m, 2, 200, 100, 0);
3712 * evas_map_point_coord_set(m, 3, 0, 100, 0);
3713 * evas_map_point_image_uv_set(m, 0, 0, 0);
3714 * evas_map_point_image_uv_set(m, 1, 200, 0);
3715 * evas_map_point_image_uv_set(m, 2, 200, 100);
3716 * evas_map_point_image_uv_set(m, 3, 0, 100);
3717 * evas_object_map_set(obj, m);
3721 * Note that the map points a uv coordinates match the image geometry. If
3722 * the @p map parameter is NULL, the stored map will be freed and geometry
3723 * prior to enabling/setting a map will be restored.
3725 * @param obj object to change transformation map
3726 * @param map new map to use
3728 * @see evas_map_new()
3730 EAPI void evas_object_map_set (Evas_Object *obj, const Evas_Map *map);
3733 * Get current object transformation map.
3735 * This returns the current internal map set on the indicated object. It is
3736 * intended for read-only acces and is only valid as long as the object is
3737 * not deleted or the map on the object is not changed. If you wish to modify
3738 * the map and set it back do the following:
3741 * const Evas_Map *m = evas_object_map_get(obj);
3742 * Evas_Map *m2 = evas_map_dup(m);
3743 * evas_map_util_rotate(m2, 30.0, 0, 0);
3744 * evas_object_map_set(obj);
3745 * evas_map_free(m2);
3748 * @param obj object to query transformation map.
3749 * @return map reference to map in use. This is an internal data structure, so
3752 * @see evas_object_map_set()
3754 EAPI const Evas_Map *evas_object_map_get (const Evas_Object *obj);
3758 * Populate source and destination map points to match exactly object.
3760 * Usually one initialize map of an object to match it's original
3761 * position and size, then transform these with evas_map_util_*
3762 * functions, such as evas_map_util_rotate() or
3763 * evas_map_util_3d_rotate(). The original set is done by this
3764 * function, avoiding code duplication all around.
3766 * @param m map to change all 4 points (must be of size 4).
3767 * @param obj object to use unmapped geometry to populate map coordinates.
3768 * @param z Point Z Coordinate hint (pre-perspective transform). This value
3769 * will be used for all four points.
3771 * @see evas_map_util_points_populate_from_object()
3772 * @see evas_map_point_coord_set()
3773 * @see evas_map_point_image_uv_set()
3775 EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
3778 * Populate source and destination map points to match exactly object.
3780 * Usually one initialize map of an object to match it's original
3781 * position and size, then transform these with evas_map_util_*
3782 * functions, such as evas_map_util_rotate() or
3783 * evas_map_util_3d_rotate(). The original set is done by this
3784 * function, avoiding code duplication all around.
3786 * Z Point coordinate is assumed as 0 (zero).
3788 * @param m map to change all 4 points (must be of size 4).
3789 * @param obj object to use unmapped geometry to populate map coordinates.
3791 * @see evas_map_util_points_populate_from_object_full()
3792 * @see evas_map_util_points_populate_from_geometry()
3793 * @see evas_map_point_coord_set()
3794 * @see evas_map_point_image_uv_set()
3796 EAPI void evas_map_util_points_populate_from_object (Evas_Map *m, const Evas_Object *obj);
3799 * Populate source and destination map points to match given geometry.
3801 * Similar to evas_map_util_points_populate_from_object_full(), this
3802 * call takes raw values instead of querying object's unmapped
3803 * geometry. The given width will be used to calculate destination
3804 * points (evas_map_point_coord_set()) and set the image uv
3805 * (evas_map_point_image_uv_set()).
3807 * @param m map to change all 4 points (must be of size 4).
3808 * @param x Point X Coordinate
3809 * @param y Point Y Coordinate
3810 * @param w width to use to calculate second and third points.
3811 * @param h height to use to calculate third and fourth points.
3812 * @param z Point Z Coordinate hint (pre-perspective transform). This value
3813 * will be used for all four points.
3815 * @see evas_map_util_points_populate_from_object()
3816 * @see evas_map_point_coord_set()
3817 * @see evas_map_point_image_uv_set()
3819 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);
3822 * Set color of all points to given color.
3824 * This call is useful to reuse maps after they had 3d lightning or
3825 * any other colorization applied before.
3827 * @param m map to change the color of.
3828 * @param r red (0 - 255)
3829 * @param g green (0 - 255)
3830 * @param b blue (0 - 255)
3831 * @param a alpha (0 - 255)
3833 * @see evas_map_point_color_set()
3835 EAPI void evas_map_util_points_color_set (Evas_Map *m, int r, int g, int b, int a);
3838 * Change the map to apply the given rotation.
3840 * This rotates the indicated map's coordinates around the center coordinate
3841 * given by @p cx and @p cy as the rotation center. The points will have their
3842 * X and Y coordinates rotated clockwise by @p degrees degress (360.0 is a
3843 * full rotation). Negative values for degrees will rotate counter-clockwise
3844 * by that amount. All coordinates are canvas global coordinates.
3846 * @param m map to change.
3847 * @param degrees amount of degrees from 0.0 to 360.0 to rotate.
3848 * @param cx rotation's center horizontal position.
3849 * @param cy rotation's center vertical position.
3851 * @see evas_map_point_coord_set()
3852 * @see evas_map_util_zoom()
3854 EAPI void evas_map_util_rotate (Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
3857 * Change the map to apply the given zooming.
3859 * Like evas_map_util_rotate(), this zooms the points of the map from a center
3860 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
3861 * parameters specific how much to zoom in the X and Y direction respectively.
3862 * A value of 1.0 means "don't zoom". 2.0 means "dobule the size". 0.5 is
3863 * "half the size" etc. All coordinates are canvas global coordinates.
3865 * @param m map to change.
3866 * @param zoomx horizontal zoom to use.
3867 * @param zoomy vertical zoom to use.
3868 * @param cx zooming center horizontal position.
3869 * @param cy zooming center vertical position.
3871 * @see evas_map_point_coord_set()
3872 * @see evas_map_util_rotate()
3874 EAPI void evas_map_util_zoom (Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
3877 * Rotate the map around 3 axes in 3D
3879 * This will rotate not just around the "Z" axis as in evas_map_util_rotate()
3880 * (which is a convenience call for those only wanting 2D). This will rotate
3881 * around the X, Y and Z axes. The Z axis points "into" the screen with low
3882 * values at the screen and higher values further away. The X axis runs from
3883 * left to right on the screen and the Y axis from top to bottom. Like with
3884 * evas_map_util_rotate(0 you provide a center point to rotate around (in 3D).
3886 * @param m map to change.
3887 * @param dx amount of degrees from 0.0 to 360.0 to rotate arount X axis.
3888 * @param dy amount of degrees from 0.0 to 360.0 to rotate arount Y axis.
3889 * @param dz amount of degrees from 0.0 to 360.0 to rotate arount Z axis.
3890 * @param cx rotation's center horizontal position.
3891 * @param cy rotation's center vertical position.
3892 * @param cz rotation's center vertical position.
3894 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);
3897 * Perform lighting calculations on the given Map
3899 * This is used to apply lighting calculations (from a single light source)
3900 * to a given map. The R, G and B values of each vertex will be modified to
3901 * reflect the lighting based on the lixth point coordinates, the light
3902 * color and the ambient color, and at what angle the map is facing the
3903 * light source. A surface should have its points be declared in a
3904 * clockwise fashion if the face is "facing" towards you (as opposed to
3905 * away from you) as faces have a "logical" side for lighting.
3907 * @param m map to change.
3908 * @param lx X coordinate in space of light point
3909 * @param ly Y coordinate in space of light point
3910 * @param lz Z coordinate in space of light point
3911 * @param lr light red value (0 - 255)
3912 * @param lg light green value (0 - 255)
3913 * @param lb light blue value (0 - 255)
3914 * @param ar ambient color red value (0 - 255)
3915 * @param ag ambient color green value (0 - 255)
3916 * @param ab ambient color blue value (0 - 255)
3918 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);
3921 * Apply a perspective transform to the map
3923 * This applies a given perspective (3D) to the map coordinates. X, Y and Z
3924 * values are used. The px and py points specify the "infinite distance" point
3925 * in the 3D conversion (where all lines converge to like when artists draw
3926 * 3D by hand). The @p z0 value specifis the z value at which there is a 1:1
3927 * mapping between spatial coorinates and screen coordinates. Any points
3928 * on this z value will not have their X and Y values modified in the transform.
3929 * Those further away (Z value higher) will shrink into the distance, and
3930 * those less than this value will expand and become bigger. The @p foc value
3931 * determines the "focal length" of the camera. This is in reality the distance
3932 * between the camera lens plane itself (at or closer than this rendering
3933 * results are undefined) and the "z0" z value. This allows for some "depth"
3934 * control and @p foc must be greater than 0.
3936 * @param m map to change.
3937 * @param px The pespective distance X coordinate
3938 * @param py The pespective distance Y coordinate
3939 * @param z0 The "0" z plane value
3940 * @param foc The focal distance
3942 EAPI void evas_map_util_3d_perspective (Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
3945 * Get the clockwise state of a map
3947 * This determines if the output points (X and Y. Z is not used) are
3948 * clockwise or anti-clockwise. This can be used for "back-face culling". This
3949 * is where you hide objects that "face away" from you. In this case objects
3950 * that are not clockwise.
3952 * @param m map to query.
3953 * @return 1 if clockwise, 0 otherwise
3955 EAPI Eina_Bool evas_map_util_clockwise_get (Evas_Map *m);
3959 * Create map of transformation points to be later used with an Evas object.
3961 * This creates a set of points (currently only 4 is supported. no other
3962 * number for @p count will work). That is empty and ready to be modified
3963 * with evas_map calls.
3965 * @param count number of points in the map. *
3966 * @return a newly allocated map or @c NULL on errors.
3968 * @see evas_map_free()
3969 * @see evas_map_dup()
3970 * @see evas_map_point_coord_set()
3971 * @see evas_map_point_image_uv_set()
3972 * @see evas_map_util_points_populate_from_object_full()
3973 * @see evas_map_util_points_populate_from_object()
3975 * @see evas_object_map_set()
3977 EAPI Evas_Map *evas_map_new (int count);
3980 * Set the smoothing for map rendering
3982 * This sets smoothing for map rendering. If the object is a type that has
3983 * its own smoothing settings, then both the smooth settings for this object
3984 * and the map must be turned off. By default smooth maps are enabled.
3986 * @param m map to modify. Must not be NULL.
3987 * @param enabled enable or disable smooth map rendering
3989 EAPI void evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled);
3992 * get the smoothing for map rendering
3994 * This gets smoothing for map rendering.
3996 * @param m map to get the smooth from. Must not be NULL.
3998 EAPI Eina_Bool evas_map_smooth_get (const Evas_Map *m);
4001 * Set the alpha flag for map rendering
4003 * This sets alpha flag for map rendering. If the object is a type that has
4004 * its own alpha settings, then this will take precedence. Only image objects
4005 * have this currently. Fits stops alpha blending of the map area, and is
4006 * useful if you know the object and/or all sub-objects is 100% solid.
4008 * @param m map to modify. Must not be NULL.
4009 * @param enabled enable or disable alpha map rendering
4011 EAPI void evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled);
4014 * get the alpha flag for map rendering
4016 * This gets the alph flag for map rendering.
4018 * @param m map to get the alpha from. Must not be NULL.
4020 EAPI Eina_Bool evas_map_alpha_get (const Evas_Map *m);
4023 * Copy a previously allocated map.
4025 * This makes a duplicate of the @p m object and returns it.
4027 * @param m map to copy. Must not be NULL.
4028 * @return newly allocated map with the same count and contents as @p m.
4030 EAPI Evas_Map *evas_map_dup (const Evas_Map *m);
4033 * Free a previously allocated map.
4035 * This frees a givem map @p m and all memory associated with it. You must NOT
4036 * free a map returned by evas_object_map_get() as this is internal.
4038 * @param m map to free.
4040 EAPI void evas_map_free (Evas_Map *m);
4045 * Returns the number of points in a map. Should be at least 4.
4047 * @param m map to get size.
4048 * @return -1 on error, points otherwise.
4050 EAPI int evas_map_count_get (const Evas_Map *m) EINA_CONST;
4053 * Change the map point's coordinate.
4055 * This sets the fixen point's coordinate in the map. Note that points
4056 * describe the outline of a quadrangle and are ordered either clockwise
4057 * or anit-clock-wise. It is suggested to keep your quadrangles concave and
4058 * non-complex, though these polygon modes may work, they may not render
4059 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
4060 * 2 and 3, and 3 and 0 to describe the edges of the quandrangle.
4062 * The X and Y and Z coordinates are in canvas units. Z is optional and may
4063 * or may not be honored in drawing. Z is a hint and does not affect the
4064 * X and Y rendered coordinates. It may be used for calculating fills with
4065 * perspective correct rendering.
4067 * Remember all coordinates are canvas global ones like with move and reize
4070 * @param m map to change point. Must not be @c NULL.
4071 * @param idx index of point to change. Must be smaller than map size.
4072 * @param x Point X Coordinate
4073 * @param y Point Y Coordinate
4074 * @param z Point Z Coordinate hint (pre-perspective transform)
4076 * @see evas_map_util_rotate()
4077 * @see evas_map_util_zoom()
4078 * @see evas_map_util_points_populate_from_object_full()
4079 * @see evas_map_util_points_populate_from_object()
4081 EAPI void evas_map_point_coord_set (Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
4084 * Get the map point's coordinate.
4086 * This returns the coordinates of the given point in the map.
4088 * @param m map to query point.
4089 * @param idx index of point to query. Must be smaller than map size.
4090 * @param x where to return the X coordinate.
4091 * @param y where to return the Y coordinate.
4092 * @param z where to return the Z coordinate.
4094 EAPI void evas_map_point_coord_get (const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
4097 * Change the map point's U and V texture source point
4099 * This sets the U and V coordinates for the point. This determines which
4100 * coordinate in the source image is mapped to the given point, much like
4101 * OpenGL and textures. Notes that these points do select the pixel, but
4102 * are double floating point values to allow for accuracy and sub-pixel
4105 * @param m map to change the point of.
4106 * @param idx index of point to change. Must be smaller than map size.
4107 * @param u the X coordinate within the image/texture source
4108 * @param v the Y coordinate within the image/texture source
4110 * @see evas_map_point_coord_set()
4111 * @see evas_object_map_set()
4112 * @see evas_map_util_points_populate_from_object_full()
4113 * @see evas_map_util_points_populate_from_object()
4115 EAPI void evas_map_point_image_uv_set (Evas_Map *m, int idx, double u, double v);
4118 * Get the map point's U and V texture source points
4120 * This returns the texture points set by evas_map_point_image_uv_set().
4122 * @param m map to query point.
4123 * @param idx index of point to query. Must be smaller than map size.
4124 * @param u where to write the X coordinate within the image/texture source
4125 * @param v where to write the Y coordinate within the image/texture source
4127 EAPI void evas_map_point_image_uv_get (const Evas_Map *m, int idx, double *u, double *v);
4130 * Set the color of a vertex in the map
4132 * This sets the color of the vertex in the map. Colors will be linearly
4133 * interpolated between vertex points through the map. Color will multiply
4134 * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
4135 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
4136 * have no affect on modifying the texture pixels.
4138 * @param m map to change the color of.
4139 * @param idx index of point to change. Must be smaller than map size.
4140 * @param r red (0 - 255)
4141 * @param g green (0 - 255)
4142 * @param b blue (0 - 255)
4143 * @param a alpha (0 - 255)
4145 * @see evas_map_util_points_color_set()
4146 * @see evas_map_point_coord_set()
4147 * @see evas_object_map_set()
4149 EAPI void evas_map_point_color_set (Evas_Map *m, int idx, int r, int g, int b, int a);
4152 * Get the color set on a vertex in the map
4154 * This gets the color set by evas_map_point_color_set() on the given vertex
4157 * @param m map to get the color of the vertex from.
4158 * @param idx index of point get. Must be smaller than map size.
4159 * @param r pointer to red return
4160 * @param g pointer to green return
4161 * @param b pointer to blue return
4162 * @param a pointer to alpha return (0 - 255)
4164 * @see evas_map_point_coord_set()
4165 * @see evas_object_map_set()
4167 EAPI void evas_map_point_color_get (const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
4170 * @defgroup Evas_Object_Group_Size_Hints Size Hints
4172 * Objects may carry hints so another object that acts as a manager
4173 * (see @ref Evas_Smart_Object_Group) may know how to properly position
4174 * and resize the object. The Size Hints provide a common interface
4175 * that is recommended as the protocol for such information.
4177 * @ingroup Evas_Object_Group
4181 * Retrieves the size hint for the minimum size.
4183 * This is not a size enforcement in any way, it's just a hint that should
4184 * be used whenever appropriate.
4186 * Note that if any of @p w or @p h are @c NULL, the @c NULL
4187 * parameters are ignored.
4189 * @param obj The given Evas object.
4190 * @param w Pointer to an integer in which to store the minimum width.
4191 * @param h Pointer to an integer in which to store the minimum height.
4193 EAPI void evas_object_size_hint_min_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4196 * Sets the size hint for the minimum size.
4198 * This is not a size enforcement in any way, it's just a hint that should
4199 * be used whenever appropriate.
4201 * Value 0 is considered unset.
4203 * @param obj The given Evas object.
4204 * @param w Integer to use as the minimum width hint.
4205 * @param h Integer to use as the minimum height hint.
4207 EAPI void evas_object_size_hint_min_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4210 * Retrieves the size hint for the maximum size.
4212 * This is not a size enforcement in any way, it's just a hint that should
4213 * be used whenever appropriate.
4215 * Note that if any of @p w or @p h are @c NULL, the @c NULL
4216 * parameters are ignored.
4218 * @param obj The given Evas object.
4219 * @param w Pointer to an integer in which to store the maximum width.
4220 * @param h Pointer to an integer in which to store the maximum height.
4222 EAPI void evas_object_size_hint_max_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4225 * Sets the size hint for the maximum size.
4227 * This is not a size enforcement in any way, it's just a hint that should
4228 * be used whenever appropriate.
4230 * Value -1 is considered unset.
4232 * @param obj The given Evas object.
4233 * @param w Integer to use as the maximum width hint.
4234 * @param h Integer to use as the maximum height hint.
4236 EAPI void evas_object_size_hint_max_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4239 * Retrieves the size request hint.
4241 * This is not a size enforcement in any way, it's just a hint that should
4242 * be used whenever appropriate.
4244 * Note that if any of @p w or @p h are @c NULL, the @c NULL
4245 * parameters are ignored.
4247 * @param obj The given Evas object.
4248 * @param w Pointer to an integer in which to store the requested width.
4249 * @param h Pointer to an integer in which to store the requested height.
4251 EAPI void evas_object_size_hint_request_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
4254 * Sets the requested size hint.
4256 * This is not a size enforcement in any way, it's just a hint that should
4257 * be used whenever appropriate.
4259 * Value 0 is considered unset.
4261 * @param obj The given Evas object.
4262 * @param w Integer to use as the preferred width hint.
4263 * @param h Integer to use as the preferred height hint.
4265 EAPI void evas_object_size_hint_request_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
4268 * Retrieves the size aspect control hint.
4270 * This is not a size enforcement in any way, it's just a hint that should
4271 * be used whenever appropriate.
4273 * Note that if any of @p aspect, @p w or @p h are @c NULL, the @c NULL
4274 * parameters are ignored.
4276 * @param obj The given Evas object.
4277 * @param aspect Returns the hint on how size should be calculated.
4278 * @param w Pointer to an integer in which to store the aspect width.
4279 * @param h Pointer to an integer in which to store the aspect height.
4281 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);
4284 * Sets the size aspect control hint.
4286 * This is not a size enforcement in any way, it's just a hint that should
4287 * be used whenever appropriate.
4289 * @param obj The given Evas object.
4290 * @param aspect Hint on how to calculate size.
4291 * @param w Integer to use as aspect width hint.
4292 * @param h Integer to use as aspect height hint.
4294 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);
4297 * Retrieves the size align control hint.
4299 * This is not a size enforcement in any way, it's just a hint that should
4300 * be used whenever appropriate.
4302 * Note that if any of @p x or @p y are @c NULL, the @c NULL
4303 * parameters are ignored.
4305 * @param obj The given Evas object.
4306 * @param x Pointer to a double in which to store the align x.
4307 * @param y Pointer to a double in which to store the align y.
4309 EAPI void evas_object_size_hint_align_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
4312 * Sets the size align control hint.
4314 * This is not a size enforcement in any way, it's just a hint that should
4315 * be used whenever appropriate.
4317 * Accepted values are in the 0.0 to 1.0 range, with the special value
4318 * -1.0 used to specify "justify" or "fill" by some users. See
4319 * documentation of possible users.
4321 * @param obj The given Evas object.
4322 * @param x Double (0.0..1.0 or -1.0) to use as align x hint.
4323 * @param y Double (0.0..1.0 or -1.0) to use as align y hint.
4325 EAPI void evas_object_size_hint_align_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
4328 * Retrieves the size weight control hint.
4330 * This is not a size enforcement in any way, it's just a hint that should
4331 * be used whenever appropriate.
4333 * Note that if any of @p x or @p y are @c NULL, the @c NULL
4334 * parameters are ignored.
4336 * Accepted values are zero or positive values. Some users might use
4337 * this hint as a boolean, but some might consider it as a proportion,
4338 * see documentation of possible users.
4340 * @param obj The given Evas object.
4341 * @param x Pointer to a double in which to store the weight x.
4342 * @param y Pointer to a double in which to store the weight y.
4344 EAPI void evas_object_size_hint_weight_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
4347 * Sets the size weight control hint.
4349 * This is not a size enforcement in any way, it's just a hint that should
4350 * be used whenever appropriate.
4352 * @param obj The given Evas object.
4353 * @param x Double (0.0-1.0) to use as weight x hint.
4354 * @param y Double (0.0-1.0) to use as weight y hint.
4356 EAPI void evas_object_size_hint_weight_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
4359 * Retrieves the size padding control hint.
4361 * This is not a size enforcement in any way, it's just a hint that should
4362 * be used whenever appropriate.
4364 * Note that if any of @p l, @p r, @p t or @p b are @c NULL, the @c
4365 * NULL parameters are ignored.
4367 * @param obj The given Evas object.
4368 * @param l Pointer to an integer in which to store left padding.
4369 * @param r Pointer to an integer in which to store right padding.
4370 * @param t Pointer to an integer in which to store top padding.
4371 * @param b Pointer to an integer in which to store bottom padding.
4373 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);
4376 * Sets the size padding control hint.
4378 * This is not a size enforcement in any way, it's just a hint that should
4379 * be used whenever appropriate.
4381 * @param obj The given Evas object.
4382 * @param l Integer to specify left padding.
4383 * @param r Integer to specify right padding.
4384 * @param t Integer to specify top padding.
4385 * @param b Integer to specify bottom padding.
4387 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);
4390 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
4392 * Miscellaneous functions that also apply to any object, but are less
4393 * used or not implemented by all objects.
4395 * @ingroup Evas_Object_Group
4399 * @addtogroup Evas_Object_Group_Extras
4404 * Set an attached data pointer to an object with a given string key.
4406 * @param obj The object to attach the data pointer to
4407 * @param key The string key for the data to access it
4408 * @param data The ponter to the data to be attached
4410 * This attaches the pointer @p data to the object @p obj, given the
4411 * access string @p key. This pointer will stay "hooked" to the object
4412 * until a new pointer with the same string key is attached with
4413 * evas_object_data_set() or it is deleted with
4414 * evas_object_data_del(). On deletion of the object @p obj, the
4415 * pointers will not be accessible from the object anymore.
4417 * You can find the pointer attached under a string key using
4418 * evas_object_data_get(). It is the job of the calling application to
4419 * free any data pointed to by @p data when it is no longer required.
4421 * If @p data is @c NULL, the old value stored at @p key will be
4422 * removed but no new value will be stored. This is synonymous with
4423 * calling evas_object_data_del() with @p obj and @p key.
4425 * @note This function is very handy when you have data associated
4426 * specifically to an Evas object, being of use only when dealing with
4427 * it. Than you don't have the burden to a pointer to it elsewhere,
4428 * using this family of functions.
4434 * extern Evas_Object *obj;
4436 * my_data = malloc(500);
4437 * evas_object_data_set(obj, "name_of_data", my_data);
4438 * printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data"));
4441 EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2);
4444 * Return an attached data pointer on an Evas object by its given
4447 * @param obj The object to which the data was attached
4448 * @param key The string key the data was stored under
4449 * @return The data pointer stored, or @c NULL if none was stored
4451 * This function will return the data pointer attached to the object
4452 * @p obj, stored using the string key @p key. If the object is valid
4453 * and a data pointer was stored under the given key, that pointer
4454 * will be returned. If this is not the case, @c NULL will be
4455 * returned, signifying an invalid object or a non-existent key. It is
4456 * possible that a @c NULL pointer was stored given that key, but this
4457 * situation is non-sensical and thus can be considered an error as
4458 * well. @c NULL pointers are never stored as this is the return value
4459 * if an error occurs.
4465 * extern Evas_Object *obj;
4467 * my_data = evas_object_data_get(obj, "name_of_my_data");
4468 * if (my_data) printf("Data stored was %p\n", my_data);
4469 * else printf("No data was stored on the object\n");
4472 EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
4475 * Delete an attached data pointer from an object.
4477 * @param obj The object to delete the data pointer from
4478 * @param key The string key the data was stored under
4479 * @return The original data pointer stored at @p key on @p obj
4481 * This will remove the stored data pointer from @p obj stored under
4482 * @p key and return this same pointer, if actually there was data
4483 * there, or @c NULL, if nothing was stored under that key.
4489 * extern Evas_Object *obj;
4491 * my_data = evas_object_data_del(obj, "name_of_my_data");
4494 EAPI void *evas_object_data_del (Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
4498 * Set pointer behavior.
4501 * @param setting desired behavior.
4503 * This function has direct effect on event callbacks related to
4506 * If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse
4507 * is down at this object, events will be restricted to it as source,
4508 * mouse moves, for example, will be emitted even if outside this
4511 * If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will
4512 * be emitted just when inside this object area.
4514 * The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB.
4516 * @ingroup Evas_Object_Group_Extras
4518 EAPI void evas_object_pointer_mode_set (Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1);
4521 * Determine how pointer will behave.
4523 * @return pointer behavior.
4524 * @ingroup Evas_Object_Group_Extras
4526 EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4530 * Sets whether or not the given Evas object is to be drawn anti-aliased.
4532 * @param obj The given Evas object.
4533 * @param anti_alias 1 if the object is to be anti_aliased, 0 otherwise.
4534 * @ingroup Evas_Object_Group_Extras
4536 EAPI void evas_object_anti_alias_set (Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1);
4539 * Retrieves whether or not the given Evas object is to be drawn anti_aliased.
4540 * @param obj The given Evas object.
4541 * @return @c 1 if the object is to be anti_aliased. @c 0 otherwise.
4542 * @ingroup Evas_Object_Group_Extras
4544 EAPI Eina_Bool evas_object_anti_alias_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4548 * Sets the scaling factor for an Evas object. Does not affect all
4551 * @param obj The given Evas object.
4552 * @param scale The scaling factor. <c>1.0</c> means no scaling,
4555 * This will multiply the object's dimension by the given factor, thus
4556 * altering its geometry (width and height). Useful when you want
4557 * scalable UI elements, possibly at run time.
4559 * @see evas_object_scale_get()
4561 * @ingroup Evas_Object_Group_Extras
4563 EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
4566 * Retrieves the scaling factor for the given Evas object.
4568 * @param obj The given Evas object.
4569 * @return The scaling factor.
4571 * @ingroup Evas_Object_Group_Extras
4573 EAPI double evas_object_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4577 * Sets the render_op to be used for rendering the Evas object.
4578 * @param obj The given Evas object.
4579 * @param render_op one of the Evas_Render_Op values.
4580 * @ingroup Evas_Object_Group_Extras
4582 EAPI void evas_object_render_op_set (Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1);
4585 * Retrieves the current value of the operation used for rendering the Evas object.
4586 * @param obj The given Evas object.
4587 * @return one of the enumerated values in Evas_Render_Op.
4588 * @ingroup Evas_Object_Group_Extras
4590 EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4592 EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1);
4593 EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4595 EAPI void evas_object_static_clip_set (Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1);
4596 EAPI Eina_Bool evas_object_static_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4603 * @defgroup Evas_Object_Group_Find Finding Objects
4605 * Functions that allows finding objects by their position, name or
4608 * @ingroup Evas_Object_Group
4612 * Retrieve the object that currently has focus.
4614 * @param e The Evas canvas to query for focused object on.
4615 * @return The object that has focus or @c NULL if there is not one.
4617 * Evas can have (at most) one of its objects focused at a time.
4618 * Focused objects will be the ones having <b>key events</b> delivered
4619 * to, which the programmer can act upon by means of
4620 * evas_object_event_callback_add() usage.
4622 * @note Most users wouldn't be dealing directly with Evas' focused
4623 * objects. Instead, they would be using a higher level library for
4624 * that (like a toolkit, as Elementary) to handle focus and who's
4625 * receiving input for them.
4627 * This call returns the object that currently has focus on the canvas
4628 * @p e or @c NULL, if none.
4630 * @see evas_object_focus_set
4631 * @see evas_object_focus_get
4632 * @see evas_object_key_grab
4633 * @see evas_object_key_ungrab
4636 * @dontinclude evas-events.c
4637 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
4638 * @until evas_object_focus_set(d.bg, EINA_TRUE);
4639 * @dontinclude evas-events.c
4640 * @skip called when our rectangle gets focus
4643 * In this example the @c event_info is exactly a pointer to that
4644 * focused rectangle. See the full @ref Example_Evas_Events "example".
4646 * @ingroup Evas_Object_Group_Find
4648 EAPI Evas_Object *evas_focus_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4652 * Retrieves the object on the given evas with the given name.
4653 * @param e The given evas.
4654 * @param name The given name.
4655 * @return If successful, the Evas object with the given name. Otherwise,
4657 * @ingroup Evas_Object_Group_Find
4659 EAPI Evas_Object *evas_object_name_find (const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4663 * Retrieves the top object at the given position (x,y)
4664 * @param e The given Evas object.
4665 * @param x The horizontal coordinate
4666 * @param y The vertical coordinate
4667 * @param include_pass_events_objects Boolean Flag to include or not
4668 * pass events objects
4669 * @param include_hidden_objects Boolean Flag to include or not hidden objects
4670 * @return The Evas object that is over all others objects at the given position.
4672 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;
4675 * Retrieves the top object at mouse pointer position
4676 * @param e The given Evas object.
4677 * @return The Evas object that is over all others objects at the
4680 EAPI Evas_Object *evas_object_top_at_pointer_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4683 * Retrieves the top object in the given rectangle region
4684 * @param e The given Evas object.
4685 * @param x The horizontal coordinate.
4686 * @param y The vertical coordinate.
4687 * @param w The width size.
4688 * @param h The height size.
4689 * @param include_pass_events_objects Boolean Flag to include or not pass events objects
4690 * @param include_hidden_objects Boolean Flag to include or not hidden objects
4691 * @return The Evas object that is over all others objects at the pointer position.
4694 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;
4698 * Retrieves the objects at the given position
4699 * @param e The given Evas object.
4700 * @param x The horizontal coordinate.
4701 * @param y The vertical coordinate.
4702 * @param include_pass_events_objects Boolean Flag to include or not
4703 * pass events objects
4704 * @param include_hidden_objects Boolean Flag to include or not hidden objects
4705 * @return The list of Evas objects at the pointer position.
4708 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;
4709 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;
4713 * Get the lowest Evas object on the Evas @p e
4716 * @return the lowest object
4718 EAPI Evas_Object *evas_object_bottom_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4721 * Get the highest Evas object on the Evas @p e
4724 * @return the highest object
4726 EAPI Evas_Object *evas_object_top_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
4729 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
4731 * Evas provides a way to intercept method calls. The interceptor
4732 * callback may opt to completely deny the call, or may check and
4733 * change the parameters before continuing. The continuation of an
4734 * intercepted call is done by calling the intercepted call again,
4735 * from inside the interceptor callback.
4737 * @ingroup Evas_Object_Group
4739 typedef void (*Evas_Object_Intercept_Show_Cb) (void *data, Evas_Object *obj);
4740 typedef void (*Evas_Object_Intercept_Hide_Cb) (void *data, Evas_Object *obj);
4741 typedef void (*Evas_Object_Intercept_Move_Cb) (void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
4742 typedef void (*Evas_Object_Intercept_Resize_Cb) (void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
4743 typedef void (*Evas_Object_Intercept_Raise_Cb) (void *data, Evas_Object *obj);
4744 typedef void (*Evas_Object_Intercept_Lower_Cb) (void *data, Evas_Object *obj);
4745 typedef void (*Evas_Object_Intercept_Stack_Above_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
4746 typedef void (*Evas_Object_Intercept_Stack_Below_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
4747 typedef void (*Evas_Object_Intercept_Layer_Set_Cb) (void *data, Evas_Object *obj, int l);
4748 typedef void (*Evas_Object_Intercept_Color_Set_Cb) (void *data, Evas_Object *obj, int r, int g, int b, int a);
4749 typedef void (*Evas_Object_Intercept_Clip_Set_Cb) (void *data, Evas_Object *obj, Evas_Object *clip);
4750 typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *obj);
4754 * Set the callback function that intercepts a show event of a object.
4756 * @param obj The given canvas object pointer.
4757 * @param func The given function to be the callback function.
4758 * @param data The data passed to the callback function.
4760 * This function sets a callback function to intercepts a show event
4761 * of a canvas object.
4763 * @see evas_object_intercept_show_callback_del().
4766 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);
4769 * Unset the callback function that intercepts a show event of a
4772 * @param obj The given canvas object pointer.
4773 * @param func The given callback function.
4775 * This function sets a callback function to intercepts a show event
4776 * of a canvas object.
4778 * @see evas_object_intercept_show_callback_add().
4781 EAPI void *evas_object_intercept_show_callback_del (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2);
4784 * Set the callback function that intercepts a hide event of a object.
4786 * @param obj The given canvas object pointer.
4787 * @param func The given function to be the callback function.
4788 * @param data The data passed to the callback function.
4790 * This function sets a callback function to intercepts a hide event
4791 * of a canvas object.
4793 * @see evas_object_intercept_hide_callback_del().
4796 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);
4799 * Unset the callback function that intercepts a hide event of a
4802 * @param obj The given canvas object pointer.
4803 * @param func The given callback function.
4805 * This function sets a callback function to intercepts a hide event
4806 * of a canvas object.
4808 * @see evas_object_intercept_hide_callback_add().
4811 EAPI void *evas_object_intercept_hide_callback_del (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2);
4814 * Set the callback function that intercepts a move event of a object.
4816 * @param obj The given canvas object pointer.
4817 * @param func The given function to be the callback function.
4818 * @param data The data passed to the callback function.
4820 * This function sets a callback function to intercepts a move event
4821 * of a canvas object.
4823 * @see evas_object_intercept_move_callback_del().
4826 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);
4829 * Unset the callback function that intercepts a move event of a
4832 * @param obj The given canvas object pointer.
4833 * @param func The given callback function.
4835 * This function sets a callback function to intercepts a move event
4836 * of a canvas object.
4838 * @see evas_object_intercept_move_callback_add().
4841 EAPI void *evas_object_intercept_move_callback_del (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2);
4843 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);
4844 EAPI void *evas_object_intercept_resize_callback_del (Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2);
4845 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);
4846 EAPI void *evas_object_intercept_raise_callback_del (Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2);
4847 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);
4848 EAPI void *evas_object_intercept_lower_callback_del (Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2);
4849 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);
4850 EAPI void *evas_object_intercept_stack_above_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2);
4851 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);
4852 EAPI void *evas_object_intercept_stack_below_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2);
4853 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);
4854 EAPI void *evas_object_intercept_layer_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2);
4855 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);
4856 EAPI void *evas_object_intercept_color_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2);
4857 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);
4858 EAPI void *evas_object_intercept_clip_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2);
4859 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);
4860 EAPI void *evas_object_intercept_clip_unset_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2);
4863 * @defgroup Evas_Object_Specific Specific Object Functions
4865 * Functions that work on specific objects.
4870 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
4872 * Functions that operate on evas rectangle objects.
4874 * @ingroup Evas_Object_Specific
4878 * Adds a rectangle to the given evas.
4879 * @param e The given evas.
4880 * @return The new rectangle object.
4882 EAPI Evas_Object *evas_object_rectangle_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
4885 * @defgroup Evas_Object_Image Image Object Functions
4887 * Functions used to create and manipulate image objects.
4889 * Note - Image objects may return or accept "image data" in multiple
4890 * formats. This is based on the colorspace of an object. Here is a
4891 * rundown on formats:
4893 * EVAS_COLORSPACE_ARGB8888:
4895 * This pixel format is a linear block of pixels, starting at the
4896 * top-left row by row until the bottom right of the image or pixel
4897 * region. All pixels are 32-bit unsigned int's with the high-byte
4898 * being alpha and the low byte being blue in the format ARGB. Alpha
4899 * may or may not be used by evas depending on the alpha flag of the
4900 * image, but if not used, should be set to 0xff anyway.
4902 * This colorspace uses premultiplied alpha. That means that R, G and
4903 * B cannot exceed A in value. The conversion from non-premultiplied
4906 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
4908 * So 50% transparent blue will be: 0x80000080. This will not be
4909 * "dark" - just 50% transparent. Values are 0 == black, 255 == solid
4910 * or full red, green or blue.
4912 * EVAS_COLORSPACE_YCBCR422P601_PL:
4914 * This is a pointer-list indirected set of YUV (YCbCr) pixel
4915 * data. This means that the data returned or set is not actual pixel
4916 * data, but pointers TO lines of pixel data. The list of pointers
4917 * will first be N rows of pointers to the Y plane - pointing to the
4918 * first pixel at the start of each row in the Y plane. N is the
4919 * height of the image data in pixels. Each pixel in the Y, U and V
4920 * planes is 1 byte exactly, packed. The next N / 2 pointers will
4921 * point to rows in the U plane, and the next N / 2 pointers will
4922 * point to the V plane rows. U and V planes are half the horizontal
4923 * and vertical resolution of the Y plane.
4925 * Row order is top to bottom and row pixels are stored left to right.
4927 * There is a limitation that these images MUST be a multiple of 2
4928 * pixels in size horizontally or vertically. This is due to the U and
4929 * V planes being half resolution. Also note that this assumes the
4930 * itu601 YUV colorspace specification. This is defined for standard
4931 * television and mpeg streams. HDTV may use the itu709
4934 * Values are 0 to 255, indicating full or no signal in that plane
4937 * EVAS_COLORSPACE_YCBCR422P709_PL:
4939 * Not implemented yet.
4941 * EVAS_COLORSPACE_RGB565_A5P:
4943 * In the process of being implemented in 1 engine only. This may change.
4945 * This is a pointer to image data for 16-bit half-word pixel data in
4946 * 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue), with
4947 * the high-byte containing red and the low byte containing blue, per
4948 * pixel. This data is packed row by row from the top-left to the
4951 * If the image has an alpha channel enabled there will be an extra
4952 * alpha plane after the color pixel plane. If not, then this data
4953 * will not exist and should not be accessed in any way. This plane is
4954 * a set of pixels with 1 byte per pixel defining the alpha values of
4955 * all pixels in the image from the top-left to the bottom right of
4956 * the image, row by row. Even though the values of the alpha pixels
4957 * can be 0 to 255, only values 0 through to 32 are used, 32 being
4958 * solid and 0 being transparent.
4960 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
4961 * with 0 being black and 31 or 63 being full red, green or blue
4962 * respectively. This colorspace is also pre-multiplied like
4963 * EVAS_COLORSPACE_ARGB8888 so:
4965 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
4967 * EVAS_COLORSPACE_A8:
4969 * The image is just a alpha mask (8 bit's per pixel). This is used for alpha
4972 * @ingroup Evas_Object_Specific
4974 typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o);
4978 * Creates a new image object on the given evas.
4980 * @param e The given evas.
4981 * @return The created image object.
4983 EAPI Evas_Object *evas_object_image_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
4986 * Creates a new image object that automatically scales on the given evas.
4988 * This is a helper around evas_object_image_add() and
4989 * evas_object_image_filled_set(), it will track object resizes and apply
4990 * evas_object_image_fill_set() with the new geometry.
4992 * @see evas_object_image_add()
4993 * @see evas_object_image_filled_set()
4994 * @see evas_object_image_fill_set()
4996 EAPI Evas_Object *evas_object_image_filled_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5000 * Sets the data for an image from memory to be loaded
5002 * This is the same as evas_object_image_file_set() but the file to be loaded
5003 * may exist at an address in memory (the data for the file, not the filename
5004 * itself). The @p data at the address is copied and stored for future use, so
5005 * no @p data needs to be kept after this call is made. It will be managed and
5006 * freed for you when no longer needed. The @p size is limited to 2 gigabytes
5007 * in size, and must be greater than 0. A NULL @p data pointer is also invalid.
5008 * Set the filename to NULL to reset to empty state and have the image file
5009 * data freed from memory using evas_object_image_file_set().
5011 * The @p format is optional (pass NULL if you don't need/use it). It is used
5012 * to help Evas guess better which loader to use for the data. It may simply
5013 * be the "extension" of the file as it would normally be on disk such as
5014 * "jpg" or "png" or "gif" etc.
5016 * @param obj The given image object.
5017 * @param data The image file data address
5018 * @param size The size of the image file data in bytes
5019 * @param format The format of the file (optional), or @c NULL if not needed
5020 * @param key The image key in file, or @c NULL.
5022 EAPI void evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2);
5025 * Sets the filename and key of the given image object.
5027 * If the file supports multiple data stored in it as eet, you can
5028 * specify the key to be used as the index of the image in this file.
5030 * @param obj The given image object.
5031 * @param file The image filename.
5032 * @param key The image key in file, or @c NULL.
5034 EAPI void evas_object_image_file_set (Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
5037 * Retrieves the filename and key of the given image object.
5039 * @param obj The given image object.
5040 * @param file Location to store the image filename, or @c NULL.
5041 * @param key Location to store the image key, or @c NULL.
5043 EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2);
5046 * Sets how much of each border of the given image object is not
5049 * When rendering, the image may be scaled to fit the size of the
5050 * image object. This function sets what area around the border of the
5051 * image is not to be scaled. This sort of function is useful for
5052 * widget theming, where, for example, buttons may be of varying
5053 * sizes, but the border size must remain constant.
5055 * The units used for @p l, @p r, @p t and @p b are output units.
5057 * @param obj The given image object.
5058 * @param l Distance of the left border that is not to be stretched.
5059 * @param r Distance of the right border that is not to be stretched.
5060 * @param t Distance of the top border that is not to be stretched.
5061 * @param b Distance of the bottom border that is not to be stretched.
5063 EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1);
5066 * Retrieves how much of each border of the given image object is not
5069 * See @ref evas_object_image_border_set for more details.
5071 * @param obj The given image object.
5072 * @param l Location to store the left border width in, or @c NULL.
5073 * @param r Location to store the right border width in, or @c NULL.
5074 * @param t Location to store the top border width in, or @c NULL.
5075 * @param b Location to store the bottom border width in, or @c NULL.
5077 EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
5080 * Sets if the center part of the given image object (not the border)
5083 * When rendering, the image may be scaled to fit the size of the
5084 * image object. This function sets if the center part of the scaled
5085 * image is to be drawn or left completely blank, or forced to be
5086 * solid. Very useful for frames and decorations.
5088 * @param obj The given image object.
5089 * @param fill Fill mode of the middle.
5091 EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1);
5094 * Retrieves if the center of the given image object is to be drawn or
5097 * See @ref evas_object_image_fill_set for more details.
5099 * @param obj The given image object.
5100 * @return Fill mode of the center.
5102 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;
5105 * Sets if image fill property should track object size.
5107 * If set to true, then every evas_object_resize() will automatically
5108 * trigger call to evas_object_image_fill_set() with the new size so
5109 * image will fill the whole object area.
5111 * @param obj The given image object.
5112 * @param setting whether to follow object size.
5114 * @see evas_object_image_filled_add()
5115 * @see evas_object_image_fill_set()
5117 EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
5120 * Retrieves if image fill property is tracking object size.
5122 * @param obj The given image object.
5123 * @return 1 if it is tracking, 0 if not and evas_object_fill_set()
5124 * must be called manually.
5126 EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5129 * Sets a scale factor (multiplier) for the borders of an image
5131 * @param obj The given image object.
5132 * @param scale The scale factor (default is 1.0 - i.e. no scale)
5134 EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale);
5137 * Retrieves the border scale factor
5139 * See evas_object_image_border_scale_set()
5141 * @param obj The given image object.
5142 * @return The scale factor
5144 EAPI double evas_object_image_border_scale_get (const Evas_Object *obj);
5147 * Sets the rectangle of the given image object that the image will be
5150 * Note that the image will be tiled around this one rectangle. To
5151 * have only one copy of the image drawn, @p x and @p y must be 0 and
5152 * @p w and @p h need to be the width and height of the image object
5155 * The default values for the fill parameters is @p x = 0, @p y = 0,
5156 * @p w = 32 and @p h = 32.
5158 * @param obj The given image object.
5159 * @param x The X coordinate for the top left corner of the image.
5160 * @param y The Y coordinate for the top left corner of the image.
5161 * @param w The width of the image.
5162 * @param h The height of the image.
5164 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);
5167 * Retrieves the dimensions of the rectangle of the given image object
5168 * that the image will be drawn to.
5170 * See @ref evas_object_image_fill_set for more details.
5172 * @param obj The given image object.
5173 * @param x Location to store the X coordinate for the top left corner of the image in, or @c NULL.
5174 * @param y Location to store the Y coordinate for the top left corner of the image in, or @c NULL.
5175 * @param w Location to store the width of the image in, or @c NULL.
5176 * @param h Location to store the height of the image in, or @c NULL.
5178 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);
5181 * Sets the tiling mode for the given evas image object's fill.
5182 * @param obj The given evas image object.
5183 * @param spread One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT,
5184 * EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.
5186 EAPI void evas_object_image_fill_spread_set (Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1);
5189 * Retrieves the spread (tiling mode) for the given image object's
5192 * @param obj The given evas image object.
5193 * @return The current spread mode of the image object.
5195 EAPI Evas_Fill_Spread evas_object_image_fill_spread_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5198 * Sets the size of the given image object.
5200 * This function will scale down or crop the image so that it is
5201 * treated as if it were at the given size. If the size given is
5202 * smaller than the image, it will be cropped. If the size given is
5203 * larger, then the image will be treated as if it were in the upper
5204 * left hand corner of a larger image that is otherwise transparent.
5206 * @param obj The given image object.
5207 * @param w The new width of the image.
5208 * @param h The new height of the image.
5210 EAPI void evas_object_image_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
5213 * Retrieves the size of the given image object.
5215 * See @ref evas_object_image_size_set for more details.
5217 * @param obj The given image object.
5218 * @param w Location to store the width of the image in, or @c NULL.
5219 * @param h Location to store the height of the image in, or @c NULL.
5221 EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
5224 * Retrieves the row stride of the given image object,
5226 * The row stride is the number of units between the start of a
5227 * row and the start of the next row.
5229 * @param obj The given image object.
5230 * @return The stride of the image.
5232 EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5235 * Retrieves a number representing any error that occurred during the last
5236 * load of the given image object.
5238 * @param obj The given image object.
5239 * @return A value giving the last error that occurred. It should be one of
5240 * the @c EVAS_LOAD_ERROR_* values. @c EVAS_LOAD_ERROR_NONE is
5241 * returned if there was no error.
5243 EAPI Evas_Load_Error evas_object_image_load_error_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5246 * Sets the raw image data of the given image object.
5248 * Note that the raw data must be of the same size and colorspace of
5249 * the image. If data is NULL the current image data will be freed.
5251 * @param obj The given image object.
5252 * @param data The raw data, or @c NULL.
5254 EAPI void evas_object_image_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
5257 * Converts the raw image data of the given image object to the
5258 * specified colorspace.
5260 * Note that this function does not modify the raw image data. If the
5261 * requested colorspace is the same as the image colorspace nothing is
5262 * done and NULL is returned. You should use
5263 * evas_object_image_colorspace_get() to check the current image
5266 * See @ref evas_object_image_colorspace_get.
5268 * @param obj The given image object.
5269 * @param to_cspace The colorspace to which the image raw data will be converted.
5270 * @return data A newly allocated data in the format specified by to_cspace.
5272 EAPI void *evas_object_image_data_convert (Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5275 * Get a pointer to the raw image data of the given image object.
5277 * This function returns a pointer to an image object's internal pixel
5278 * buffer, for reading only or read/write. If you request it for
5279 * writing, the image will be marked dirty so that it gets redrawn at
5282 * This is best suited when you want to modify an existing image,
5283 * without changing its dimensions.
5285 * @param obj The given image object.
5286 * @param for_writing Whether the data being retrieved will be modified.
5287 * @return The raw image data.
5289 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;
5292 * Replaces the raw image data of the given image object.
5294 * This function lets the application replace an image object's
5295 * internal pixel buffer with a user-allocated one. For best results,
5296 * you should generally first call evas_object_image_size_set() with
5297 * the width and height for the new buffer.
5299 * This call is best suited for when you will be using image data with
5300 * different dimensions than the existing image data, if any. If you
5301 * only need to modify the existing image in some fashion, then using
5302 * evas_object_image_data_get() is probably what you are after.
5304 * Note that the caller is responsible for freeing the buffer when
5305 * finished with it, as user-set image data will not be automatically
5306 * freed when the image object is deleted.
5308 * See @ref evas_object_image_data_get for more details.
5310 * @param obj The given image object.
5311 * @param data The raw data.
5313 EAPI void evas_object_image_data_copy_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
5316 * Mark a sub-region of the given image object to be redrawn.
5318 * This function schedules a particular rectangular region of an image
5319 * object to be updated (redrawn) at the next render.
5321 * @param obj The given image object.
5322 * @param x X-offset of the region to be updated.
5323 * @param y Y-offset of the region to be updated.
5324 * @param w Width of the region to be updated.
5325 * @param h Height of the region to be updated.
5327 EAPI void evas_object_image_data_update_add (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
5330 * Enable or disable alpha channel of the given image object.
5332 * This function sets a flag on an image object indicating whether or
5333 * not to use alpha channel data. A value of 1 indicates to use alpha
5334 * channel data, and 0 indicates to ignore any alpha channel
5335 * data. Note that this has nothing to do with an object's color as
5336 * manipulated by evas_object_color_set().
5338 * @param obj The given image object.
5339 * @param has_alpha Whether to use alpha channel data or not.
5341 EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1);
5344 * @brief Retrieves the alpha channel setting of the given image object.
5346 * @param obj The given image object.
5347 * @return Whether the alpha channel data is being used.
5349 * This function returns 1 if the image object's alpha channel is
5350 * being used, or 0 otherwise.
5352 * See @ref evas_object_image_alpha_set for more details.
5354 EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5357 * Sets whether to use of high-quality image scaling algorithm
5358 * of the given image object.
5360 * When enabled, a higher quality image scaling algorithm is used when
5361 * scaling images to sizes other than the source image. This gives
5362 * better results but is more computationally expensive.
5364 * @param obj The given image object.
5365 * @param smooth_scale Whether to use smooth scale or not.
5367 EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1);
5370 * Retrieves whether the given image object is using use a
5371 * high-quality image scaling algorithm.
5373 * See @ref evas_object_image_smooth_scale_set for more details.
5375 * @param obj The given image object.
5376 * @return Whether smooth scale is being used.
5378 EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5381 * Preload image in the background
5383 * This function request the preload of the data image in the
5384 * background. The worked is queued before being processed.
5386 * If image data is already loaded, it will callback
5387 * EVAS_CALLBACK_IMAGE_PRELOADED immediately and do nothing else.
5389 * If cancel is set, it will remove the image from the workqueue.
5391 * @param obj The given image object.
5392 * @param cancel 0 means add to the workqueue, 1 remove it.
5394 EAPI void evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1);
5397 * Reload a image of the canvas.
5399 * @param obj The given image object pointer.
5401 * This function reloads a image of the given canvas.
5404 EAPI void evas_object_image_reload (Evas_Object *obj) EINA_ARG_NONNULL(1);
5407 * Save the given image object to a file.
5409 * Note that you should pass the filename extension when saving. If
5410 * the file supports multiple data stored in it as eet, you can
5411 * specify the key to be used as the index of the image in this file.
5413 * You can specify some flags when saving the image. Currently
5414 * acceptable flags are quality and compress. Eg.: "quality=100
5417 * @param obj The given image object.
5418 * @param file The filename to be used to save the image.
5419 * @param key The image key in file, or @c NULL.
5420 * @param flags String containing the flags to be used.
5422 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);
5425 * Import pixels from given source to a given canvas image object.
5427 * @param obj The given canvas object.
5428 * @param pixels The pixel's source to be imported.
5430 * This function imports pixels from a given source to a given canvas image.
5433 EAPI Eina_Bool evas_object_image_pixels_import (Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2);
5436 * Set the callback function to get pixels from a canva's image.
5438 * @param obj The given canvas pointer.
5439 * @param func The callback function.
5440 * @param data The data pointer to be passed to @a func.
5442 * This functions sets a function to be the callback function that get
5443 * pixes from a image of the canvas.
5446 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);
5449 * Mark whether the given image object is dirty (needs to be redrawn).
5451 * @param obj The given image object.
5452 * @param dirty Whether the image is dirty.
5454 EAPI void evas_object_image_pixels_dirty_set (Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1);
5457 * Retrieves whether the given image object is dirty (needs to be redrawn).
5459 * @param obj The given image object.
5460 * @return Whether the image is dirty.
5462 EAPI Eina_Bool evas_object_image_pixels_dirty_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5465 * Set the dpi resolution of a loaded image of the canvas.
5467 * @param obj The given canvas pointer.
5468 * @param dpi The new dpi resolution.
5470 * This function set the dpi resolution of a given loaded canvas image.
5473 EAPI void evas_object_image_load_dpi_set (Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1);
5476 * Get the dpi resolution of a loaded image of the canvas.
5478 * @param obj The given canvas pointer.
5479 * @return The dpi resolution of the given canvas image.
5481 * This function returns the dpi resolution of given canvas image.
5484 EAPI double evas_object_image_load_dpi_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5487 * Set the size of a loaded image of the canvas.
5489 * @param obj The given canvas object.
5490 * @param w The new width of the canvas image given.
5491 * @param h The new height of the canvas image given.
5493 * This function sets a new size for the given canvas image.
5496 EAPI void evas_object_image_load_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
5499 * Get the size of a loaded image of the canvas.
5501 * @param obj The given image object.
5502 * @param w The width of the canvas image given.
5503 * @param h The height of the canvas image given.
5505 * This function get the size of the given canvas image.
5508 EAPI void evas_object_image_load_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
5511 * Set the scale down of a loaded image of the canvas.
5513 * @param obj The given image object pointer.
5514 * @param scale_down The scale to down value.
5516 * This function sets the scale down of a given canvas image.
5519 EAPI void evas_object_image_load_scale_down_set (Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1);
5522 * Get the scale down value of given image of the canvas.
5524 * @param obj The given image object pointer.
5526 * This function returns the scale down value of a given canvas image.
5529 EAPI int evas_object_image_load_scale_down_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5530 EAPI void evas_object_image_load_region_set (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
5531 EAPI void evas_object_image_load_region_get (const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
5534 * Define if the orientation information in the image file should be honored.
5536 * @param obj The given image object pointer.
5537 * @param enable @p EINA_TRUE means that it should honor the orientation information
5540 EAPI void evas_object_image_load_orientation_set (Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
5543 * Get if the orientation information in the image file should be honored.
5545 * @param obj The given image object pointer.
5548 EAPI Eina_Bool evas_object_image_load_orientation_get (const Evas_Object *obj) EINA_ARG_NONNULL(1);
5551 * Set the colorspace of a given image of the canvas.
5553 * @param obj The given image object pointer.
5554 * @param cspace The new color space.
5556 * This function sets the colorspace of given canvas image.
5559 EAPI void evas_object_image_colorspace_set (Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1);
5562 * Get the colorspace of a given image of the canvas.
5564 * @param obj The given image object pointer.
5565 * @return The colorspace of the image.
5567 * This function returns the colorspace of given canvas image.
5570 EAPI Evas_Colorspace evas_object_image_colorspace_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5573 * Set the native surface of a given image of the canvas
5575 * @param obj The given canvas pointer.
5576 * @param surf The new native surface.
5578 * This function sets a native surface of a given canvas image.
5581 EAPI void evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2);
5584 * Get the native surface of a given image of the canvas
5586 * @param obj The given canvas pointer.
5587 * @return The native surface of the given canvas image.
5589 * This function returns the native surface of a given canvas image.
5592 EAPI Evas_Native_Surface *evas_object_image_native_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5595 * Set the scale hint of a given image of the canvas.
5597 * @param obj The given canvas pointer.
5598 * @param hint The scale hint value.
5600 * This function sets the scale hint value of the given image of the canvas.
5603 EAPI void evas_object_image_scale_hint_set (Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1);
5606 * Get the scale hint of a given image of the canvas.
5608 * @param obj The given canvas pointer.
5610 * This function returns the scale hint value of the given image of the canvas.
5613 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;
5616 * Set the content hint of a given image of the canvas.
5618 * @param obj The given canvas pointer.
5619 * @param hint The content hint value.
5621 * This function sets the content hint value of the given image of the canvas.
5624 EAPI void evas_object_image_content_hint_set (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1);
5627 * Get the content hint of a given image of the canvas.
5629 * @param obj The given canvas pointer.
5631 * This function returns the content hint value of the given image of the canvas.
5634 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;
5638 * Enable an image to be used as an alpha mask.
5640 * This will set any flags, and discard any excess image data not used as an
5643 * Note there is little point in using a image as alpha mask unless it has an
5646 * @param obj Object to use as an alpha mask.
5647 * @param ismask Use image as alphamask, must be true.
5649 EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1);
5652 * Set the source object on a proxy object.
5654 * The source must be another object. The proxy will have the same base
5655 * appearance of the source object. Obviously other effects may be applied to
5656 * the proxy, such as a map to create a reflection of the original object.
5658 * Any existing source object will be removed. Setting the src to NULL clears
5661 * You cannot set a proxy on a proxy.
5663 * @param obj Proxy object.
5664 * @param src Source of the proxy.
5665 * @return EINA_TRUE on success, EINA_FALSE on error.
5667 EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1);
5670 * Get the current source object of an image.
5672 * @param obj Image object
5673 * @return Source object, or @c NULL on error.
5675 EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1);
5678 * Clear the source on a proxy image.
5680 * This is equivalent to calling evas_object_image_source_set with a NULL
5683 * @param obj Image object to clear source of.
5684 * @return EINA_TRUE on success, EINA_FALSE on error.
5686 EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1);
5689 * Check if a file extention may be supported by @ref Evas_Object_Image.
5691 * @param file The file to check
5692 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
5695 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
5697 * This functions is threadsafe.
5699 EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
5702 * Check if a file extention may be supported by @ref Evas_Object_Image.
5704 * @param file The file to check, it should be an Eina_Stringshare.
5705 * @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
5708 * This functions is threadsafe.
5710 EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
5713 * @defgroup Evas_Object_Text Text Object Functions
5715 * Functions that operate on single line, single style text objects.
5717 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
5719 * @ingroup Evas_Object_Specific
5721 typedef enum _Evas_Text_Style_Type
5723 /* basic styles (4 bits allocatedm use 0->10 now, 5 left) */
5724 #define EVAS_TEXT_STYLE_MASK_BASIC 0xf
5725 #define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
5726 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
5727 EVAS_TEXT_STYLE_PLAIN,
5728 EVAS_TEXT_STYLE_SHADOW,
5729 EVAS_TEXT_STYLE_OUTLINE,
5730 EVAS_TEXT_STYLE_SOFT_OUTLINE,
5731 EVAS_TEXT_STYLE_GLOW,
5732 EVAS_TEXT_STYLE_OUTLINE_SHADOW,
5733 EVAS_TEXT_STYLE_FAR_SHADOW,
5734 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW,
5735 EVAS_TEXT_STYLE_SOFT_SHADOW,
5736 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW,
5738 #define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
5739 #define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
5740 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
5741 /* OR these to modify shadow direction (3 bits needed) */
5742 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4),
5743 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4),
5744 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4),
5745 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4),
5746 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4),
5747 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4),
5748 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4),
5749 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4)
5750 } Evas_Text_Style_Type;
5753 * Creates a new text @c Evas_Object on the provided @c Evas canvas.
5755 * @param e The @c Evas canvas to create the text object upon.
5757 * @see evas_object_text_font_source_set
5758 * @see evas_object_text_font_set
5759 * @see evas_object_text_text_set
5761 * @returns NULL on error, A pointer to a new @c Evas_Object on success.
5763 EAPI Evas_Object *evas_object_text_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5765 EAPI void evas_object_text_font_source_set (Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1);
5766 EAPI const char *evas_object_text_font_source_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5767 EAPI void evas_object_text_font_set (Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1);
5770 * Query evas for font information of a text @c Evas_Object.
5772 * This function allows the font name and size of a text @c Evas_Object as
5773 * created with evas_object_text_add() to be queried. Be aware that the font
5774 * name string is still owned by Evas and should NOT have free() called on
5775 * it by the caller of the function.
5777 * @param obj The evas text object to query for font information.
5778 * @param font A pointer to the location to store the font name in (may be NULL).
5779 * @param size A pointer to the location to store the font size in (may be NULL).
5781 EAPI void evas_object_text_font_get (const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1, 2);
5784 * Sets the text to be displayed by the given evas text object.
5785 * @param obj Evas text object.
5786 * @param text Text to display.
5788 EAPI void evas_object_text_text_set (Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
5791 * @brief Sets the BiDi delimiters used in the textblock.
5793 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
5794 * is useful for example in recipients fields of e-mail clients where bidi
5795 * oddities can occur when mixing rtl and ltr.
5797 * @param obj The given text object.
5798 * @param delim A null terminated string of delimiters, e.g ",|".
5801 EAPI void evas_object_text_bidi_delimiters_set(Evas_Object *obj, const char *delim);
5804 * @brief Gets the BiDi delimiters used in the textblock.
5806 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
5807 * is useful for example in recipients fields of e-mail clients where bidi
5808 * oddities can occur when mixing rtl and ltr.
5810 * @param obj The given text object.
5811 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
5814 EAPI const char *evas_object_text_bidi_delimiters_get(const Evas_Object *obj);
5817 * Retrieves the text currently being displayed by the given evas text object.
5818 * @param obj The given evas text object.
5819 * @return The text currently being displayed. Do not free it.
5821 EAPI const char *evas_object_text_text_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5822 EAPI Evas_Coord evas_object_text_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5823 EAPI Evas_Coord evas_object_text_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5824 EAPI Evas_Coord evas_object_text_max_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5825 EAPI Evas_Coord evas_object_text_max_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5826 EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5827 EAPI Evas_Coord evas_object_text_vert_advance_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5828 EAPI Evas_Coord evas_object_text_inset_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5831 * Retrieve position and dimension information of a character within a text @c Evas_Object.
5833 * This function is used to obtain the X, Y, width and height of a the character
5834 * located at @p pos within the @c Evas_Object @p obj. @p obj must be a text object
5835 * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx,
5836 * @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to that
5839 * @param obj The text object to retrieve position information for.
5840 * @param pos The character position to request co-ordinates for.
5841 * @param cx A pointer to an @c Evas_Coord to store the X value in (can be NULL).
5842 * @param cy A pointer to an @c Evas_Coord to store the Y value in (can be NULL).
5843 * @param cw A pointer to an @c Evas_Coord to store the Width value in (can be NULL).
5844 * @param ch A pointer to an @c Evas_Coord to store the Height value in (can be NULL).
5846 * @returns EINA_FALSE on error, EINA_TRUE on success.
5848 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);
5849 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);
5852 * Returns the logical position of the last char in the text
5853 * up to the pos given. this is NOT the position of the last char
5854 * because of the possibility of RTL in the text.
5856 EAPI int evas_object_text_last_up_to_pos (const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
5857 EAPI Evas_Text_Style_Type evas_object_text_style_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
5858 EAPI void evas_object_text_style_set (Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1);
5859 EAPI void evas_object_text_shadow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
5860 EAPI void evas_object_text_shadow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
5861 EAPI void evas_object_text_glow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
5862 EAPI void evas_object_text_glow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
5863 EAPI void evas_object_text_glow2_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
5864 EAPI void evas_object_text_glow2_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
5865 EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
5866 EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
5869 * Gets the text style pad of a text object.
5871 * @param obj The given text object.
5872 * @param l The left pad (or @c NULL).
5873 * @param r The right pad (or @c NULL).
5874 * @param t The top pad (or @c NULL).
5875 * @param b The bottom pad (or @c NULL).
5878 EAPI void evas_object_text_style_pad_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
5881 * Retrieves the direction of the text currently being displayed in the
5883 * @param obj The given evas text object.
5884 * @return the direction of the text
5886 EAPI Evas_BiDi_Direction evas_object_text_direction_get (const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
5889 * @defgroup Evas_Object_Textblock Textblock Object Functions
5891 * Functions used to create and manipulate textblock objects. Unlike
5892 * @ref Evas_Object_Text, these handle complex text, doing multiple
5893 * styles and multiline text based on HTML-like tags. Of these extra
5894 * features will be heavier on memory and processing cost.
5896 * @todo put here some usage examples
5898 * @ingroup Evas_Object_Specific
5902 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
5904 * This part explains about the textblock object's API and proper usage.
5905 * If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal.
5906 * The main user of the textblock object is the edje entry object in Edje, so
5907 * that's a good place to learn from, but I think this document is more than
5908 * enough, if it's not, please request for me info and I'll update it.
5910 * @subsection textblock_intro Introduction
5911 * The textblock objects is, as implied, an object that can show big chunks of
5912 * text. Textblock supports many features including: Text formatting, automatic
5913 * and manual text alignment, embedding items (for example icons) and more.
5914 * Textblock has three important parts, the text paragraphs, the format nodes
5917 * @subsection textblock_cursors Textblock Object Cursors
5918 * A textblock Cursor @ref Evas_Textblock_Cursor is data type that represents
5919 * a position in a textblock. Each cursor contains information about the
5920 * paragraph it points to, the position in that paragraph and the object itself.
5921 * Cursors register to textblock objects upon creation, this means that once
5922 * you created a cursor, it belongs to a specific obj and you can't for example
5923 * copy a cursor "into" a cursor of a different object. Registered cursors
5924 * also have the added benefit of updating automatically upon textblock changes,
5925 * this means that if you have a cursor pointing to a specific character, it'll
5926 * still point to it even after you change the whole object completely (as long
5927 * as the char was not deleted), this is not possible without updating, because
5928 * as mentioned, each cursor holds a character position. There are many
5929 * functions that handle cursors, just check out the evas_textblock_cursor*
5930 * functions. For creation and deletion of cursors check out:
5931 * @see evas_object_textblock_cursor_new()
5932 * @see evas_textblock_cursor_free()
5933 * @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).
5935 * @subsection textblock_paragraphs Textblock Object Paragraphs
5936 * The textblock object is made out of text splitted to paragraphs (delimited
5937 * by the paragraph separation character). Each paragraph has many (or none)
5938 * format nodes associated with it which are responsible for the formatting
5939 * of that paragraph.
5941 * @subsection textblock_format_nodes Textblock Object Format Nodes
5942 * As explained in @ref textblock_paragraphs each one of the format nodes
5943 * is associated with a paragraph.
5944 * There are two types of format nodes, visible and invisible:
5945 * Visible: formats that a cursor can point to, i.e formats that
5946 * occupy space, for example: newlines, tabs, items and etc. Some visible items
5947 * are made of two parts, in this case, only the opening tag is visible.
5948 * A closing tag (i.e a </tag> tag) should NEVER be visible.
5949 * Invisible: formats that don't occupy space, for example: bold and underline.
5950 * Being able to access format nodes is very important for some uses. For
5951 * example, edje uses the "<a>" format to create links in the text (and pop
5952 * popups above them when clicked). For the textblock object a is just a
5953 * formatting instruction (how to color the text), but edje utilizes the access
5954 * to the format nodes to make it do more.
5955 * For more information, take a look at all the evas_textblock_node_format_*
5957 * The translation of "<tag>" tags to actual format is done according to the
5958 * tags defined in the style, see @ref evas_textblock_style_set
5960 * @subsection textblock_special_formats Special Formats
5961 * This section is not yet written. If you want some info about styles/formats
5962 * and how to use them, expedite's textblock_basic test is a great start.
5963 * @todo Write @textblock_special_formats
5965 typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
5966 typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
5968 * @typedef Evas_Object_Textblock_Node_Format
5971 typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
5972 typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
5974 struct _Evas_Textblock_Rectangle
5976 Evas_Coord x, y, w, h;
5979 typedef enum _Evas_Textblock_Text_Type
5981 EVAS_TEXTBLOCK_TEXT_RAW,
5982 EVAS_TEXTBLOCK_TEXT_PLAIN,
5983 EVAS_TEXTBLOCK_TEXT_MARKUP
5984 } Evas_Textblock_Text_Type;
5986 typedef enum _Evas_Textblock_Cursor_Type
5988 EVAS_TEXTBLOCK_CURSOR_UNDER,
5989 EVAS_TEXTBLOCK_CURSOR_BEFORE
5990 } Evas_Textblock_Cursor_Type;
5994 * Adds a textblock to the given evas.
5995 * @param e The given evas.
5996 * @return The new textblock object.
5998 EAPI Evas_Object *evas_object_textblock_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6002 * Returns the unescaped version of escape.
6003 * @param escape the string to be escaped
6004 * @return the unescaped version of escape
6006 EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6009 * Returns the escaped version of the string.
6010 * @param string to escape
6011 * @param len_ret the len of the new escape
6012 * @return the escaped string.
6014 EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6017 * Return the unescaped version of the string between start and end.
6019 * @param escape_start the start of the string.
6020 * @param escape_end the end of the string.
6021 * @return the unescaped version of the range
6023 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;
6027 * Creates a new textblock style.
6028 * @return The new textblock style.
6030 EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
6033 * Destroys a textblock style.
6034 * @param ts The textblock style to free.
6036 EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
6039 * Sets the style ts to the style passed as text by text.
6040 * Expected a string consisting of many (or none) tag='format' pairs.
6042 * @param ts the style to set.
6043 * @param text the text to parse - NOT NULL.
6044 * @return Returns no value.
6046 EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
6049 * Return the text of the style ts.
6050 * @param ts the style to get it's text.
6051 * @return the text of the style or null on error.
6053 EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6057 * Set the objects style to ts.
6058 * @param obj the Evas object to set the style to.
6059 * @param ts the style to set.
6060 * @return Returns no value.
6062 EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
6065 * Return the style of an object.
6066 * @param obj the object to get the style from.
6067 * @return the style of the object.
6069 EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6072 * @brief Set the "replacement character" to use for the given textblock object.
6074 * @param obj The given textblock object.
6075 * @param ch The charset name.
6077 EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1);
6080 * @brief Get the "replacement character" for given textblock object. Returns
6081 * NULL if no replacement character is in use.
6083 * @param obj The given textblock object
6084 * @return replacement character or @c NULL
6086 EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6089 * @brief Sets the vertical alignment of text within the textblock object
6092 * Normally alignment is 0.0 (top of object). Values given should be
6093 * between 0.0 and 1.0 (1.0 bottom of object, 0.5 being vertically centered
6096 * @param obj The given textblock object.
6097 * @param align A value between 0.0 and 1.0
6100 EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align);
6103 * @brief Gets the vertical alignment of a textblock
6105 * @param obj The given textblock object.
6106 * @return The elignment set for the object
6109 EAPI double evas_object_textblock_valign_get(const Evas_Object *obj);
6112 * @brief Sets the BiDi delimiters used in the textblock.
6114 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
6115 * is useful for example in recipients fields of e-mail clients where bidi
6116 * oddities can occur when mixing rtl and ltr.
6118 * @param obj The given textblock object.
6119 * @param delim A null terminated string of delimiters, e.g ",|".
6122 EAPI void evas_object_textblock_bidi_delimiters_set(Evas_Object *obj, const char *delim);
6125 * @brief Gets the BiDi delimiters used in the textblock.
6127 * BiDi delimiters are use for in-paragraph separation of bidi segments. This
6128 * is useful for example in recipients fields of e-mail clients where bidi
6129 * oddities can occur when mixing rtl and ltr.
6131 * @param obj The given textblock object.
6132 * @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
6135 EAPI const char *evas_object_textblock_bidi_delimiters_get(const Evas_Object *obj);
6138 * @brief Sets newline mode. When true, newline character will behave
6139 * as a paragraph separator.
6141 * @param obj The given textblock object.
6142 * @param mode EINA_TRUE for PS mode, EINA_FALSE otherwise.
6145 EAPI void evas_object_textblock_newline_mode_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1);
6148 * @brief Gets newline mode. When true, newline character behaves
6149 * as a paragraph separator.
6151 * @param obj The given textblock object.
6152 * @return EINA_TRUE if in PS mode, EINA_FALSE otherwise.
6155 EAPI Eina_Bool evas_object_textblock_newline_mode_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6159 * Sets the tetxblock's text to the markup text.
6161 * @note assumes text does not include the unicode object replacement char (0xFFFC)
6163 * @param obj the textblock object.
6164 * @param text the markup text to use.
6165 * @return Return no value.
6167 EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
6170 * Prepends markup to the cursor cur.
6172 * @note assumes text does not include the unicode object replacement char (0xFFFC)
6174 * @param cur the cursor to prepend to.
6175 * @param text the markup text to prepend.
6176 * @return Return no value.
6178 EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6181 * Return the markup of the object.
6183 * @param obj the Evas object.
6184 * @return the markup text of the object.
6186 EAPI const char *evas_object_textblock_text_markup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6190 * Return the object's main cursor.
6192 * @param obj the object.
6193 * @return the obj's main cursor.
6195 EAPI const Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6198 * Create a new cursor, associate it to the obj and init it to point
6199 * to the start of the textblock. Association to the object means the cursor
6200 * will be updated when the object will change.
6202 * @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).
6204 * @param obj the object to associate to.
6205 * @return the new cursor.
6207 EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6211 * Free the cursor and unassociate it from the object.
6212 * @note do not use it to free unassociated cursors.
6214 * @param cur the cursor to free.
6215 * @return Returns no value.
6217 EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6221 * Sets the cursor to the start of the first text node.
6223 * @param cur the cursor to update.
6224 * @return Returns no value.
6226 EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6229 * sets the cursor to the end of the last text node.
6231 * @param cur the cursor to set.
6232 * @return Returns no value.
6234 EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6237 * Advances to the start of the next text node
6239 * @param cur the cursor to update
6240 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
6242 EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6245 * Advances to the end of the previous text node
6247 * @param cur the cursor to update
6248 * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise.
6250 EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6255 * @param obj The evas, must not be NULL.
6256 * @param anchor the anchor name to get
6257 * @return Returns the list format node corresponding to the anchor, may be null if there are none.
6259 EAPI const Eina_List *evas_textblock_node_format_list_get(const Evas_Object *obj, const char *anchor) EINA_ARG_NONNULL(1, 2);
6262 * Returns the first format node.
6264 * @param obj The evas, must not be NULL.
6265 * @return Returns the first format node, may be null if there are none.
6267 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6270 * Returns the last format node.
6272 * @param obj The evas textblock, must not be NULL.
6273 * @return Returns the first format node, may be null if there are none.
6275 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
6278 * Returns the next format node (after n)
6280 * @param n the current format node - not null.
6281 * @return Returns the next format node, may be null.
6283 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
6286 * Returns the prev format node (after n)
6288 * @param n the current format node - not null.
6289 * @return Returns the prev format node, may be null.
6291 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
6294 * Remove a format node and it's match. i.e, removes a <tag> </tag> pair.
6295 * Assumes the node is the first part of <tag> i.e, this won't work if
6296 * n is a closing tag.
6298 * @param obj the Evas object of the textblock - not null.
6299 * @param n the current format node - not null.
6301 EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
6304 * Sets the cursor to point to the place where format points to.
6306 * @param cur the cursor to update.
6307 * @param n the format node to update according.
6309 EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
6312 * Return the format node at the position pointed by cur.
6314 * @param cur the position to look at.
6315 * @return the format node if found, NULL otherwise.
6316 * @see evas_textblock_cursor_format_is_visible_get()
6318 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6321 * Get the text format representation of the format node.
6323 * @param fmt the format node.
6324 * @return the textual format of the format node.
6326 EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6329 * Set the cursor to point to the position of fmt.
6331 * @param cur the cursor to update
6332 * @param fmt the format to update according to.
6334 EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
6337 * Check if the current cursor position is a visible format. This way is more
6338 * efficient than evas_textblock_cursor_format_get() to check for the existence
6339 * of a visible format.
6341 * @param cur the cursor to look at.
6342 * @return #EINA_TRUE if the cursor points to a visible format, #EINA_FALSE otherwise.
6343 * @see evas_textblock_cursor_format_get()
6345 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;
6348 * Advances to the next format node
6350 * @param cur the cursor to be updated.
6351 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6353 EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6356 * Advances to the previous format node.
6358 * @param cur the cursor to update.
6359 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6361 EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6364 * Returns true if the cursor points to a format.
6366 * @param cur the cursor to check.
6367 * @return Returns #EINA_TRUE if a cursor points to a format #EINA_FALSE otherwise.
6369 EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6372 * Advances 1 char forward.
6374 * @param cur the cursor to advance.
6375 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6377 EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6380 * Advances 1 char backward.
6382 * @param cur the cursor to advance.
6383 * @return #EINA_TRUE on success #EINA_FALSE otherwise.
6385 EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6388 * Go to the first char in the node the cursor is pointing on.
6390 * @param cur the cursor to update.
6391 * @return Returns no value.
6393 EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6396 * Go to the last char in a text node.
6398 * @param cur the cursor to update.
6399 * @return Returns no value.
6401 EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6404 * Go to the start of the current line
6406 * @param cur the cursor to update.
6407 * @return Returns no value.
6409 EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6412 * Go to the end of the current line.
6414 * @param cur the cursor to update.
6415 * @return Returns no value.
6417 EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6420 * Return the current cursor pos.
6422 * @param cur the cursor to take the position from.
6423 * @return the position or -1 on error
6425 EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6428 * Set the cursor pos.
6430 * @param cur the cursor to be set.
6431 * @param pos the pos to set.
6433 EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
6436 * Go to the start of the line passed
6438 * @param cur cursor to update.
6439 * @param line numer to set.
6440 * @return #EINA_TRUE on success, #EINA_FALSE on error.
6442 EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
6445 * Compare two cursors.
6447 * @param cur1 the first cursor.
6448 * @param cur2 the second cursor.
6449 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
6451 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;
6454 * Make cur_dest point to the same place as cur. Does not work if they don't
6455 * point to the same object.
6457 * @param cur the source cursor.
6458 * @param cur_dest destination cursor.
6459 * @return Returns no value.
6461 EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
6465 * Adds text to the current cursor position and set the cursor to *before*
6466 * the start of the text just added.
6468 * @param cur the cursor to where to add text at.
6469 * @param _text the text to add.
6470 * @return Returns the len of the text added.
6471 * @see evas_textblock_cursor_text_prepend()
6473 EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6476 * Adds text to the current cursor position and set the cursor to *after*
6477 * the start of the text just added.
6479 * @param cur the cursor to where to add text at.
6480 * @param _text the text to add.
6481 * @return Returns the len of the text added.
6482 * @see evas_textblock_cursor_text_append()
6484 EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
6488 * Adds format to the current cursor position. If the format being added is a
6489 * visible format, add it *before* the cursor position, otherwise, add it after.
6490 * This behavior is because visible formats are like characters and invisible
6491 * should be stacked in a way that the last one is added last.
6493 * This function works with native formats, that means that style defined
6494 * tags like <br> won't work here. For those kind of things use markup prepend.
6496 * @param cur the cursor to where to add format at.
6497 * @param format the format to add.
6498 * @return Returns true if a visible format was added, false otherwise.
6499 * @see evas_textblock_cursor_format_prepend()
6503 * Check if the current cursor position points to the terminating null of the
6504 * last paragraph. (shouldn't be allowed to point to the terminating null of
6505 * any previous paragraph anyway.
6507 * @param cur the cursor to look at.
6508 * @return #EINA_TRUE if the cursor points to the terminating null, #EINA_FALSE otherwise.
6510 EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
6513 * Adds format to the current cursor position. If the format being added is a
6514 * visible format, add it *before* the cursor position, otherwise, add it after.
6515 * This behavior is because visible formats are like characters and invisible
6516 * should be stacked in a way that the last one is added last.
6517 * If the format is visible the cursor is advanced after it.
6519 * This function works with native formats, that means that style defined
6520 * tags like <br> won't work here. For those kind of things use markup prepend.
6522 * @param cur the cursor to where to add format at.
6523 * @param format the format to add.
6524 * @return Returns true if a visible format was added, false otherwise.
6525 * @see evas_textblock_cursor_format_prepend()
6527 EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
6530 * Delete the character at the location of the cursor. If there's a format
6531 * pointing to this position, delete it as well.
6533 * @param cur the cursor pointing to the current location.
6534 * @return Returns no value.
6536 EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
6539 * Delete the range between cur1 and cur2.
6541 * @param cur1 one side of the range.
6542 * @param cur2 the second side of the range
6543 * @return Returns no value.
6545 EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
6549 * Return the text of the paragraph cur points to - returns the text in markup..
6551 * @param cur the cursor pointing to the paragraph.
6552 * @return the text on success, NULL otherwise.
6554 EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6557 * Return the length of the paragraph, cheaper the eina_unicode_strlen()
6559 * @param cur the position of the paragraph.
6560 * @return the length of the paragraph on success, -1 otehrwise.
6562 EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6565 * Return the text in the range between cur1 and cur2
6567 * FIXME: format is currently unused, you always get markup back.
6569 * @param cur1 one side of the range.
6570 * @param cur2 the other side of the range
6571 * @param format to be documented
6572 * @return the text in the range
6573 * @see elm_entry_markup_to_utf8()
6575 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;
6578 * Return the content of the cursor.
6580 * @param cur the cursor
6581 * @return the text in the range
6583 EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6587 * Returns the geometry of the cursor. Depends on the type of cursor requested.
6588 * This should be used instead of char_geometry_get because there are weird
6589 * special cases with BiDi text.
6590 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
6591 * get, except for the case of the last char of a line which depends on the
6592 * paragraph direction.
6594 * in '|' cursor mode (i.e a line between two chars) it is very varyable.
6595 * For example consider the following visual string:
6596 * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
6597 * a '|' between the c and the C.
6599 * @param cur the cursor.
6600 * @param cx the x of the cursor
6601 * @param cy the y of the cursor
6602 * @param cw the width of the cursor
6603 * @param ch the height of the cursor
6604 * @param dir the direction of the cursor, can be NULL.
6605 * @param ctype the type of the cursor.
6606 * @return line number of the char on success, -1 on error.
6608 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);
6611 * Returns the geometry of the char at cur.
6613 * @param cur the position of the char.
6614 * @param cx the x of the char.
6615 * @param cy the y of the char.
6616 * @param cw the w of the char.
6617 * @param ch the h of the char.
6618 * @return line number of the char on success, -1 on error.
6620 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);
6623 * Returns the geometry of the pen at cur.
6625 * @param cur the position of the char.
6626 * @param cpen_x the pen_x of the char.
6627 * @param cy the y of the char.
6628 * @param cadv the adv of the char.
6629 * @param ch the h of the char.
6630 * @return line number of the char on success, -1 on error.
6632 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);
6635 * Returns the geometry of the line at cur.
6637 * @param cur the position of the line.
6638 * @param cx the x of the line.
6639 * @param cy the y of the line.
6640 * @param cw the width of the line.
6641 * @param ch the height of the line.
6642 * @return line number of the line on success, -1 on error.
6644 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);
6647 * Set the position of the cursor according to the X and Y coordinates.
6649 * @param cur the cursor to set.
6650 * @param x coord to set by.
6651 * @param y coord to set by.
6652 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
6654 EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
6657 * Set the cursor position according to the y coord.
6659 * @param cur the cur to be set.
6660 * @param y the coord to set by.
6661 * @return the line number found, -1 on error.
6663 EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
6666 * Get the geometry of a range.
6668 * @param cur1 one side of the range.
6669 * @param cur2 other side of the range.
6670 * @return a list of Rectangles representing the geometry of the range.
6672 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;
6673 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);
6677 * Checks if the cursor points to the end of the line.
6679 * @param cur the cursor to check.
6680 * @return #EINA_TRUE if true, #EINA_FALSE otherwise.
6682 EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
6686 * Get the geometry of a line number.
6688 * @param obj the object.
6689 * @param line the line number.
6690 * @param cx x coord of the line.
6691 * @param cy y coord of the line.
6692 * @param cw w coord of the line.
6693 * @param ch h coord of the line.
6694 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
6696 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);
6699 * Clear the textblock object.
6700 * @note Does *NOT* free the Evas object itself.
6702 * @param obj the object to clear.
6705 EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
6708 * Get the formatted width and height. This calculates the actual size after restricting
6709 * the textblock to the current size of the object.
6710 * The main difference between this and @ref evas_object_textblock_size_native_get
6711 * is that the "native" function does not wrapping into account
6712 * it just calculates the real width of the object if it was placed on an
6713 * infinite canvas, while this function gives the size after wrapping
6714 * according to the size restrictions of the object.
6716 * For example for a textblock containing the text: "You shall not pass!"
6717 * with no margins or padding and assuming a monospace font and a size of
6718 * 7x10 char widths (for simplicity) has a native size of 19x1
6719 * and a formatted size of 5x4.
6722 * @param obj the Evas object.
6723 * @param w[out] the width of the object.
6724 * @param h[out] the height of the object
6725 * @return Returns no value.
6726 * @see evas_object_textblock_size_native_get
6728 EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
6731 * Get the native width and height. This calculates the actual size without taking account
6732 * the current size of the object.
6733 * The main difference between this and @ref evas_object_textblock_size_formatted_get
6734 * is that the "native" function does not take wrapping into account
6735 * it just calculates the real width of the object if it was placed on an
6736 * infinite canvas, while the "formatted" function gives the size after
6737 * wrapping text according to the size restrictions of the object.
6739 * For example for a textblock containing the text: "You shall not pass!"
6740 * with no margins or padding and assuming a monospace font and a size of
6741 * 7x10 char widths (for simplicity) has a native size of 19x1
6742 * and a formatted size of 5x4.
6744 * @param obj the Evas object of the textblock
6745 * @param w[out] the width returned
6746 * @param h[out] the height returned
6747 * @return Returns no value.
6749 EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
6750 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);
6753 * @defgroup Evas_Line_Group Line Object Functions
6755 * Functions used to deal with evas line objects.
6757 * @ingroup Evas_Object_Specific
6761 * Adds a new evas line object to the given evas.
6762 * @param e The given evas.
6763 * @return The new evas line object.
6765 EAPI Evas_Object *evas_object_line_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6768 * Sets the coordinates of the end points of the given evas line object.
6769 * @param obj The given evas line object.
6770 * @param x1 The X coordinate of the first point.
6771 * @param y1 The Y coordinate of the first point.
6772 * @param x2 The X coordinate of the second point.
6773 * @param y2 The Y coordinate of the second point.
6775 EAPI void evas_object_line_xy_set (Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2);
6778 * Retrieves the coordinates of the end points of the given evas line object.
6779 * @param obj The given line object.
6780 * @param x1 Pointer to an integer in which to store the X coordinate of the
6782 * @param y1 Pointer to an integer in which to store the Y coordinate of the
6784 * @param x2 Pointer to an integer in which to store the X coordinate of the
6786 * @param y2 Pointer to an integer in which to store the Y coordinate of the
6789 EAPI void evas_object_line_xy_get (const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2);
6792 * @defgroup Evas_Object_Polygon Polygon Object Functions
6794 * Functions that operate on evas polygon objects.
6796 * Hint: as evas does not provide ellipse, smooth paths or circle, one
6797 * can calculate points and convert these to a polygon.
6799 * @ingroup Evas_Object_Specific
6803 * Adds a new evas polygon object to the given evas.
6804 * @param e The given evas.
6805 * @return A new evas polygon object.
6807 EAPI Evas_Object *evas_object_polygon_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
6810 * Adds the given point to the given evas polygon object.
6811 * @param obj The given evas polygon object.
6812 * @param x The X coordinate of the given point.
6813 * @param y The Y coordinate of the given point.
6814 * @ingroup Evas_Polygon_Group
6816 EAPI void evas_object_polygon_point_add (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
6819 * Removes all of the points from the given evas polygon object.
6820 * @param obj The given polygon object.
6822 EAPI void evas_object_polygon_points_clear (Evas_Object *obj) EINA_ARG_NONNULL(1);
6825 * @defgroup Evas_Smart_Group Smart Functions
6827 * Functions that deal with Evas_Smart's, creating definition
6828 * (classes) of objects that will have customized behavior for methods
6829 * like evas_object_move(), evas_object_resize(),
6830 * evas_object_clip_set() and others.
6832 * These objects will accept the generic methods defined in @ref
6833 * Evas_Object_Group and the extensions defined in @ref
6834 * Evas_Smart_Object_Group. There are couple of existent smart objects
6835 * in Evas itself, see @ref Evas_Object_Box, @ref Evas_Object_Table
6836 * and @ref Evas_Smart_Object_Clipped.
6840 * @def EVAS_SMART_CLASS_VERSION
6841 * The version you have to put into the version field in the smart
6843 * @ingroup Evas_Smart_Group
6845 #define EVAS_SMART_CLASS_VERSION 4
6847 * @struct _Evas_Smart_Class
6848 * a smart object class
6849 * @ingroup Evas_Smart_Group
6851 struct _Evas_Smart_Class
6853 const char *name; /**< the string name of the class */
6855 void (*add) (Evas_Object *o);
6856 void (*del) (Evas_Object *o);
6857 void (*move) (Evas_Object *o, Evas_Coord x, Evas_Coord y);
6858 void (*resize) (Evas_Object *o, Evas_Coord w, Evas_Coord h);
6859 void (*show) (Evas_Object *o);
6860 void (*hide) (Evas_Object *o);
6861 void (*color_set) (Evas_Object *o, int r, int g, int b, int a);
6862 void (*clip_set) (Evas_Object *o, Evas_Object *clip);
6863 void (*clip_unset) (Evas_Object *o);
6864 void (*calculate) (Evas_Object *o);
6865 void (*member_add) (Evas_Object *o, Evas_Object *child);
6866 void (*member_del) (Evas_Object *o, Evas_Object *child);
6868 const Evas_Smart_Class *parent; /**< this class inherits from this parent */
6869 const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, NULL terminated */
6870 void *interfaces; /**< to be used in a future near you */
6875 * @struct _Evas_Smart_Cb_Description
6877 * Describes a callback used by a smart class
6878 * evas_object_smart_callback_call(), particularly useful to explain
6879 * to user and its code (ie: introspection) what the parameter @c
6880 * event_info will contain.
6882 * @ingroup Evas_Smart_Group
6884 struct _Evas_Smart_Cb_Description
6886 const char *name; /**< callback name, ie: "changed" */
6889 * @brief Hint type of @c event_info parameter of Evas_Smart_Cb.
6891 * The type string uses the pattern similar to
6893 * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures
6895 * but extended to optionally include variable names within
6896 * brackets preceding types. Example:
6898 * @li Structure with two integers:
6901 * @li Structure called 'x' with two integers named 'a' and 'b':
6902 * @c "[x]([a]i[b]i)"
6904 * @li Array of integers:
6907 * @li Array called 'x' of struct with two integers:
6910 * @note This type string is used as a hint and is @b not validated
6911 * or enforced anyhow. Implementors should make the best use
6912 * of it to help bindings, documentation and other users of
6913 * introspection features.
6919 * @def EVAS_SMART_CLASS_INIT_NULL
6920 * Initializer to zero a whole Evas_Smart_Class structure.
6922 * @see EVAS_SMART_CLASS_INIT_VERSION
6923 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
6924 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
6925 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6926 * @ingroup Evas_Smart_Group
6928 #define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
6931 * @def EVAS_SMART_CLASS_INIT_VERSION
6932 * Initializer to zero a whole Evas_Smart_Class structure and set version.
6934 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
6935 * latest EVAS_SMART_CLASS_VERSION.
6937 * @see EVAS_SMART_CLASS_INIT_NULL
6938 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
6939 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
6940 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6941 * @ingroup Evas_Smart_Group
6943 #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}
6946 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
6947 * Initializer to zero a whole Evas_Smart_Class structure and set name
6950 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
6951 * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
6953 * It will keep a reference to name field as a "const char *", that is,
6954 * name must be available while the structure is used (hint: static or global!)
6955 * and will not be modified.
6957 * @see EVAS_SMART_CLASS_INIT_NULL
6958 * @see EVAS_SMART_CLASS_INIT_VERSION
6959 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
6960 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6961 * @ingroup Evas_Smart_Group
6963 #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}
6966 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
6967 * Initializer to zero a whole Evas_Smart_Class structure and set name,
6968 * version and parent class.
6970 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
6971 * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
6974 * It will keep a reference to name field as a "const char *", that is,
6975 * name must be available while the structure is used (hint: static or global!)
6976 * and will not be modified. Similarly, parent reference will be kept.
6978 * @see EVAS_SMART_CLASS_INIT_NULL
6979 * @see EVAS_SMART_CLASS_INIT_VERSION
6980 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
6981 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6982 * @ingroup Evas_Smart_Group
6984 #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}
6987 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
6988 * Initializer to zero a whole Evas_Smart_Class structure and set name,
6989 * version, parent class and callbacks definition.
6991 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
6992 * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
6993 * class and callbacks at this level.
6995 * It will keep a reference to name field as a "const char *", that is,
6996 * name must be available while the structure is used (hint: static or global!)
6997 * and will not be modified. Similarly, parent and callbacks reference
7000 * @see EVAS_SMART_CLASS_INIT_NULL
7001 * @see EVAS_SMART_CLASS_INIT_VERSION
7002 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
7003 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
7004 * @ingroup Evas_Smart_Group
7006 #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}
7009 * @def EVAS_SMART_SUBCLASS_NEW
7011 * Convenience macro to subclass a Smart Class.
7013 * This macro saves some typing when writing a Smart Class derived from
7014 * another one. In order to work, the user needs to provide some functions
7015 * adhering to the following guidelines.
7016 * - @<prefix@>_smart_set_user(): the internal _smart_set function will call
7017 * this one provided by the user after inheriting everything from the
7018 * parent, which should take care of setting the right member functions
7020 * - @<prefix@>_parent_sc: pointer to the smart class of the parent. When calling
7021 * parent functions from overloaded ones, use this global variable.
7022 * - @<prefix@>_smart_class_new(): this function returns the Evas_Smart needed
7023 * to create smart objects with this class, should be called by the public
7025 * - If this new class should be subclassable as well, a public _smart_set()
7026 * function is desirable to fill the class used as parent by the children.
7027 * It's up to the user to provide this interface, which will most likely
7028 * call @<prefix@>_smart_set() to get the job done.
7030 * @param smart_name The name used for the Smart Class. e.g: "Evas_Object_Box".
7031 * @param prefix Prefix used for all variables and functions defined.
7032 * @param api_type Type of the structure used as API for the Smart Class. Either Evas_Smart_Class or something derived from it.
7033 * @param parent_type Type of the parent class API.
7034 * @param parent_func Function that gets the parent class. e.g: evas_object_box_smart_class_get().
7035 * @param cb_desc Array of callback descriptions for this Smart Class.
7037 * @ingroup Evas_Smart_Group
7039 #define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
7040 static const parent_type * prefix##_parent_sc = NULL; \
7041 static void prefix##_smart_set_user(api_type *api); \
7042 static void prefix##_smart_set(api_type *api) \
7044 Evas_Smart_Class *sc; \
7045 if (!(sc = (Evas_Smart_Class *)api)) \
7047 if (!prefix##_parent_sc) \
7048 prefix##_parent_sc = parent_func(); \
7049 evas_smart_class_inherit(sc, (const Evas_Smart_Class *)prefix##_parent_sc); \
7050 prefix##_smart_set_user(api); \
7052 static Evas_Smart * prefix##_smart_class_new(void) \
7054 static Evas_Smart *smart = NULL; \
7055 static api_type api; \
7058 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
7059 memset(&api, 0, sizeof(api_type)); \
7060 sc->version = EVAS_SMART_CLASS_VERSION; \
7061 sc->name = smart_name; \
7062 sc->callbacks = cb_desc; \
7063 prefix##_smart_set(&api); \
7064 smart = evas_smart_class_new(sc); \
7070 * @def EVAS_SMART_DATA_ALLOC
7071 * Convenience macro to allocate smart data only if needed.
7073 * When writing a subclassable smart object, the .add function will need
7074 * to check if the smart private data was already allocated by some child
7075 * object or not. This macro makes it easier to do it.
7077 * @param o Evas object passed to the .add function
7078 * @param priv_type The type of the data to allocate
7079 * @ingroup Evas_Smart_Group
7081 #define EVAS_SMART_DATA_ALLOC(o, priv_type) \
7083 priv = evas_object_smart_data_get(o); \
7085 priv = (priv_type *)calloc(1, sizeof(priv_type)); \
7086 if (!priv) return; \
7087 evas_object_smart_data_set(o, priv); \
7092 * Free an Evas_Smart
7094 * If this smart was created using evas_smart_class_new(), the associated
7095 * Evas_Smart_Class will not be freed.
7097 * @param s the Evas_Smart to free
7100 EAPI void evas_smart_free (Evas_Smart *s) EINA_ARG_NONNULL(1);
7103 * Creates an Evas_Smart from an Evas_Smart_Class.
7105 * @param sc the smart class definition
7106 * @return an Evas_Smart
7108 EAPI Evas_Smart *evas_smart_class_new (const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7111 * Get the Evas_Smart_Class of an Evas_Smart
7113 * @param s the Evas_Smart
7114 * @return the Evas_Smart_Class
7116 EAPI const Evas_Smart_Class *evas_smart_class_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7120 * @brief Get the data pointer set on an Evas_Smart.
7122 * @param s Evas_Smart
7124 * This data pointer is set either as the final parameter to
7125 * evas_smart_new or as the data field in the Evas_Smart_Class passed
7126 * in to evas_smart_class_new
7128 EAPI void *evas_smart_data_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7131 * Get the callbacks known by this Evas_Smart.
7133 * This is likely different from Evas_Smart_Class::callbacks as it
7134 * will contain the callbacks of all class hierarchy sorted, while the
7135 * direct smart class member refers only to that specific class and
7136 * should not include parent's.
7138 * If no callbacks are known, this function returns @c NULL.
7140 * The array elements and thus their contents will be reference to
7141 * original values given to evas_smart_new() as
7142 * Evas_Smart_Class::callbacks.
7144 * The array is sorted by name. The last array element is the @c NULL
7145 * pointer and is not counted in @a count. Loop iterations can check
7146 * any of these cases.
7148 * @param s the Evas_Smart.
7149 * @param count returns the number of elements in returned array.
7150 * @return the array with callback descriptions known by this class,
7151 * its size is returned in @a count parameter. It should not
7152 * be modified anyhow. If no callbacks are known, @c NULL is
7153 * returned. The array is sorted by name and elements refer to
7154 * the original value given to evas_smart_new().
7156 * @note objects may provide per-instance callbacks, use
7157 * evas_object_smart_callbacks_descriptions_get() to get those
7159 * @see evas_object_smart_callbacks_descriptions_get()
7161 EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
7165 * Find callback description for callback called @a name.
7167 * @param s the Evas_Smart.
7168 * @param name name of desired callback, must @b not be @c NULL. The
7169 * search have a special case for @a name being the same
7170 * pointer as registered with Evas_Smart_Cb_Description, one
7171 * can use it to avoid excessive use of strcmp().
7172 * @return reference to description if found, @c NULL if not found.
7174 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;
7178 * Sets one class to inherit from the other.
7180 * Copy all function pointers, set @c parent to @a parent_sc and copy
7181 * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
7182 * using @a parent_sc_size as reference.
7184 * This is recommended instead of a single memcpy() since it will take
7185 * care to not modify @a sc name, version, callbacks and possible
7188 * @param sc child class.
7189 * @param parent_sc parent class, will provide attributes.
7190 * @param parent_sc_size size of parent_sc structure, child should be at least
7191 * this size. Everything after @c Evas_Smart_Class size is copied
7192 * using regular memcpy().
7194 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);
7197 * Get the number of users of the smart instance
7199 * @param s The Evas_Smart to get the usage count of
7200 * @return The number of uses of the smart instance
7202 * This function tells you how many more uses of the smart instance are in
7203 * existence. This should be used before freeing/clearing any of the
7204 * Evas_Smart_Class that was used to create the smart instance. The smart
7205 * instance will refer to data in the Evas_Smart_Class used to create it and
7206 * thus you cannot remove the original data until all users of it are gone.
7207 * When the usage count goes to 0, you can evas_smart_free() the smart
7208 * instance @p s and remove from memory any of the Evas_Smart_Class that
7209 * was used to create the smart instance, if you desire. Removing it from
7210 * memory without doing this will cause problems (crashes, undefined
7211 * behavior etc. etc.), so either never remove the original
7212 * Evas_Smart_Class data from memory (have it be a constant structure and
7213 * data), or use this API call and be very careful.
7215 EAPI int evas_smart_usage_get(const Evas_Smart *s);
7218 * @def evas_smart_class_inherit
7219 * Easy to use version of evas_smart_class_inherit_full().
7221 * This version will use sizeof(parent_sc), copying everything.
7223 * @param sc child class, will have methods copied from @a parent_sc
7224 * @param parent_sc parent class, will provide contents to be copied.
7225 * @return 1 on success, 0 on failure.
7226 * @ingroup Evas_Smart_Group
7228 #define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, parent_sc, sizeof(*parent_sc))
7231 * @defgroup Evas_Smart_Object_Group Smart Object Functions
7233 * Functions dealing with evas smart objects (instances).
7235 * Smart objects are groupings of primitive Evas objects that behave as a
7236 * cohesive group. For instance, a file manager icon may be a smart object
7237 * composed of an image object, a text label and two rectangles that appear
7238 * behind the image and text when the icon is selected. As a smart object,
7239 * the normal evas api could be used on the icon object.
7241 * @see @ref Evas_Smart_Group for class definitions.
7245 * Instantiates a new smart object described by @p s.
7247 * @param e the evas on which to add the object
7248 * @param s the Evas_Smart describing the smart object
7249 * @return a new Evas_Object
7250 * @ingroup Evas_Smart_Object_Group
7252 EAPI Evas_Object *evas_object_smart_add (Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC;
7255 * Set an Evas object as a member of a smart object.
7257 * @param obj The member object
7258 * @param smart_obj The smart object
7260 * Members will automatically be stacked and layered with the smart object.
7261 * The various stacking function will operate on members relative to the
7262 * other members instead of the entire canvas.
7264 * Non-member objects can not interleave a smart object's members.
7266 * @ingroup Evas_Smart_Object_Group
7268 EAPI void evas_object_smart_member_add (Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2);
7271 * Removes a member object from a smart object.
7273 * @param obj the member object
7274 * @ingroup Evas_Smart_Object_Group
7276 * This removes a member object from a smart object. The object will still
7277 * be on the canvas, but no longer associated with whichever smart object
7278 * it was associated with.
7281 EAPI void evas_object_smart_member_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
7284 * Gets the smart parent of an Evas_Object
7285 * @param obj the Evas_Object you want to get the parent
7286 * @return Returns the smart parent of @a obj, or @c NULL if @a obj is not a smart member of another Evas_Object
7287 * @ingroup Evas_Smart_Object_Group
7289 EAPI Evas_Object *evas_object_smart_parent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7292 * Checks the Smart type of the object and its parents
7293 * @param obj the Evas_Object to check the type of
7294 * @param type the type to check for
7295 * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise
7296 * @ingroup Evas_Smart_Object_Group
7298 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;
7301 * Checks the Smart type of the object and its parents using pointer comparison
7302 * @param obj the Evas_Object to check the type of
7303 * @param type the type to check for. Must be the name pointer in the smart class used to create the object
7304 * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise
7305 * @ingroup Evas_Smart_Object_Group
7307 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;
7310 * Gets the list of the member objects of an Evas_Object
7311 * @param obj the Evas_Object you want to get the list of member objects
7312 * @return Returns the list of the member objects of @a obj.
7313 * The returned list should be freed with eina_list_free() when you no longer need it
7315 EAPI Eina_List *evas_object_smart_members_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7318 * Get the Evas_Smart from which @p obj was created.
7320 * @param obj a smart object
7321 * @return the Evas_Smart
7322 * @ingroup Evas_Smart_Object_Group
7324 EAPI Evas_Smart *evas_object_smart_smart_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7327 * Retrieve user data stored on a smart object.
7329 * @param obj The smart object
7330 * @return A pointer to data stored using evas_object_smart_data_set(), or
7331 * NULL if none has been set.
7332 * @ingroup Evas_Smart_Object_Group
7334 EAPI void *evas_object_smart_data_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7337 * Store a pointer to user data for a smart object.
7339 * @param obj The smart object
7340 * @param data A pointer to user data
7341 * @ingroup Evas_Smart_Object_Group
7343 EAPI void evas_object_smart_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
7346 * Add a callback for the smart event specified by @p event.
7348 * @param obj a smart object
7349 * @param event the event name
7350 * @param func the callback function
7351 * @param data user data to be passed to the callback function
7352 * @ingroup Evas_Smart_Object_Group
7354 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);
7357 * Remove a smart callback
7359 * Removes a callback that was added by evas_object_smart_callback_add()
7361 * @param obj a smart object
7362 * @param event the event name
7363 * @param func the callback function
7364 * @return the data pointer
7365 * @ingroup Evas_Smart_Object_Group
7367 EAPI void *evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3);
7370 * Call any smart callbacks on @p obj for @p event.
7372 * @param obj the smart object
7373 * @param event the event name
7374 * @param event_info an event specific struct of info to pass to the callback
7376 * This should be called internally in the smart object when some specific
7377 * event has occurred. The documentation for the smart object should include
7378 * a list of possible events and what type of @p event_info to expect.
7380 * @ingroup Evas_Smart_Object_Group
7382 EAPI void evas_object_smart_callback_call (Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2);
7386 * Set smart object instance callbacks descriptions.
7388 * These descriptions are hints to be used by introspection and are
7389 * not enforced in any way.
7391 * It will not be checked if instance callbacks descriptions have the
7392 * same name as another in class. Both are kept in different arrays
7393 * and users of evas_object_smart_callbacks_descriptions_get() should
7394 * handle this case as they wish.
7396 * @param obj The smart object
7397 * @param descriptions NULL terminated (name != NULL) array with
7398 * descriptions. Array elements will not be modified, but
7399 * reference to them and their contents will be made, so this
7400 * array should be kept alive during object lifetime.
7401 * @return 1 on success, 0 on failure.
7402 * @ingroup Evas_Smart_Object_Group
7404 * @note while instance callbacks descriptions are possible, they are
7405 * not recommended. Use class callbacks descriptions instead as they
7406 * make user's life simpler and will use less memory as descriptions
7407 * and arrays will be shared among all instances.
7409 EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1);
7412 * Get the callbacks descriptions known by this smart object.
7414 * This call retrieves processed callbacks descriptions for both
7415 * instance and class. These arrays are sorted by description's name
7416 * and are @c NULL terminated, so both @a class_count and
7417 * @a instance_count can be ignored, the terminator @c NULL is not
7418 * counted in these values.
7420 * @param obj the smart object.
7421 * @param class_descriptions where to store class callbacks
7422 * descriptions array, if any is known. If no descriptions are
7423 * known, @c NULL is returned. This parameter may be @c NULL if
7424 * it is not of interest.
7425 * @param class_count returns how many class callbacks descriptions
7427 * @param instance_descriptions where to store instance callbacks
7428 * descriptions array, if any is known. If no descriptions are
7429 * known, @c NULL is returned. This parameter may be @c NULL if
7430 * it is not of interest.
7431 * @param instance_count returns how many instance callbacks
7432 * descriptions are known.
7434 * @note if just class descriptions are of interest, try
7435 * evas_smart_callbacks_descriptions_get() instead.
7437 * @see evas_smart_callbacks_descriptions_get()
7438 * @ingroup Evas_Smart_Object_Group
7440 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);
7443 * Find callback description for callback called @a name.
7445 * @param obj the smart object.
7446 * @param name name of desired callback, must @b not be @c NULL. The
7447 * search have a special case for @a name being the same
7448 * pointer as registered with Evas_Smart_Cb_Description, one
7449 * can use it to avoid excessive use of strcmp().
7450 * @param class_description pointer to return class description or @c
7451 * NULL if not found. If parameter is @c NULL, no search will
7452 * be done on class descriptions.
7453 * @param instance_description pointer to return instance description
7454 * or @c NULL if not found. If parameter is @c NULL, no search
7455 * will be done on instance descriptions.
7456 * @return reference to description if found, @c NULL if not found.
7458 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);
7462 * Mark smart object as changed, dirty.
7464 * This will inform the scene that it changed and needs to be redraw, also
7465 * setting need_recalculate on the given object.
7467 * @see evas_object_smart_need_recalculate_set().
7469 * @ingroup Evas_Smart_Object_Group
7471 EAPI void evas_object_smart_changed (Evas_Object *obj) EINA_ARG_NONNULL(1);
7474 * Set the need_recalculate flag of given smart object.
7476 * If this flag is set then calculate() callback (method) of the given
7477 * smart object will be called, if one is provided, during render phase
7478 * usually evas_render(). After this step, this flag will be automatically
7481 * If no calculate() is provided, this flag will be left unchanged.
7483 * @note just setting this flag will not make scene dirty and evas_render()
7484 * will have no effect. To do that, use evas_object_smart_changed(),
7485 * that will automatically call this function with 1 as parameter.
7487 * @param obj the smart object
7488 * @param value if one want to set or unset the need_recalculate flag.
7490 * @ingroup Evas_Smart_Object_Group
7492 EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
7495 * Get the current value of need_recalculate flag.
7497 * @note this flag will be unset during the render phase, after calculate()
7498 * is called if one is provided. If no calculate() is provided, then
7499 * the flag will be left unchanged after render phase.
7501 * @param obj the smart object
7502 * @return if flag is set or not.
7504 * @ingroup Evas_Smart_Object_Group
7506 EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7509 * Call user provided calculate() and unset need_calculate.
7511 * @param obj the smart object
7513 * @ingroup Evas_Smart_Object_Group
7515 EAPI void evas_object_smart_calculate (Evas_Object *obj) EINA_ARG_NONNULL(1);
7519 * Call user provided calculate() and unset need_calculate on all objects.
7521 * @param e The canvas to calculate all objects in
7523 * @ingroup Evas_Smart_Object_Group
7525 EAPI void evas_smart_objects_calculate (Evas *e);
7528 * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
7530 * Clipped smart object is a base to construct other smart objects
7531 * that based on the concept of having an internal clipper that is
7532 * applied to all its other children. This clipper will control the
7533 * visibility, clipping and color of sibling objects (remember that
7534 * the clipping is recursive, and clipper color modulates the color of
7535 * its clippees). By default, this base will also move children
7536 * relatively to the parent, and delete them when parent is
7537 * deleted. In other words, it is the base for simple object grouping.
7539 * @see evas_object_smart_clipped_smart_set()
7541 * @ingroup Evas_Smart_Object_Group
7545 * Every subclass should provide this at the beginning of their own
7546 * data set with evas_object_smart_data_set().
7548 typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
7549 struct _Evas_Object_Smart_Clipped_Data
7551 Evas_Object *clipper;
7557 * Get the clipper object for the given clipped smart object.
7559 * @param obj the clipped smart object to retrieve the associated clipper.
7560 * @return the clipper object.
7562 * @see evas_object_smart_clipped_smart_add()
7564 EAPI Evas_Object *evas_object_smart_clipped_clipper_get (Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
7567 * Set smart class callbacks so it implements the "Clipped Smart Object".
7569 * This call will assign all the required methods of Evas_Smart_Class,
7570 * if one wants to "subclass" it, call this function and later
7571 * override values, if one wants to call the original method, save it
7572 * somewhere, example:
7575 * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
7577 * static void my_class_smart_add(Evas_Object *o)
7580 * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
7584 * Evas_Smart_Class *my_class_new(void)
7586 * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
7587 * if (!parent_sc.name)
7589 * evas_object_smart_clipped_smart_set(&sc);
7591 * sc.add = my_class_smart_add;
7597 * Default behavior is:
7598 * - add: creates a hidden clipper with "infinite" size;
7599 * - del: delete all children objects;
7600 * - move: move all objects relative relatively;
7601 * - resize: not defined;
7602 * - show: if there are children objects, show clipper;
7603 * - hide: hides clipper;
7604 * - color_set: set the color of clipper;
7605 * - clip_set: set clipper of clipper;
7606 * - clip_unset: unset the clipper of clipper;
7608 EAPI void evas_object_smart_clipped_smart_set (Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
7611 * Get a pointer to the Clipped Smart Class to use for proper inheritance
7613 EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get (void) EINA_CONST;
7617 * Moves all children objects relative to given offset.
7619 * @param obj the smart Evas object to use.
7620 * @param dx horizontal offset.
7621 * @param dy vertical offset.
7623 EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1);
7626 * @defgroup Evas_Object_Box Box (Sequence) Smart Object.
7628 * Convenience smart object that packs children as a sequence using
7629 * a layout function specified by user. There are a couple of helper
7630 * layout functions, all of them using children size hints to define
7631 * their size and alignment inside their cell space.
7633 * @see @ref Evas_Object_Group_Size_Hints
7635 * @ingroup Evas_Smart_Object_Group
7638 * @typedef Evas_Object_Box_Api
7639 * Smart Class extension providing extra box requirements.
7640 * @ingroup Evas_Object_Box
7642 typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
7644 * @typedef Evas_Object_Box_Data
7645 * Smart instance data providing box requirements.
7646 * @ingroup Evas_Object_Box
7648 typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
7650 * @typedef Evas_Object_Box_Option
7651 * The base structure for a box option.
7652 * @ingroup Evas_Object_Box
7654 typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
7655 typedef void (*Evas_Object_Box_Layout) (Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
7658 * @def EVAS_OBJECT_BOX_API_VERSION
7659 * @ingroup Evas_Object_Box
7661 #define EVAS_OBJECT_BOX_API_VERSION 1
7663 * @struct _Evas_Object_Box_Api
7665 * This structure should be used by any class that wants to inherit
7666 * from box to provide custom behavior not allowed only by providing a
7667 * layout function with evas_object_box_layout_set().
7669 * @extends Evas_Smart_Class
7670 * @ingroup Evas_Object_Box
7672 struct _Evas_Object_Box_Api
7674 Evas_Smart_Class base;
7676 Evas_Object_Box_Option *(*append) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
7677 Evas_Object_Box_Option *(*prepend) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
7678 Evas_Object_Box_Option *(*insert_before) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, const Evas_Object *reference);
7679 Evas_Object_Box_Option *(*insert_after) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, const Evas_Object *reference);
7680 Evas_Object_Box_Option *(*insert_at) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child, unsigned int pos);
7681 Evas_Object *(*remove) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
7682 Evas_Object *(*remove_at) (Evas_Object *o, Evas_Object_Box_Data *priv, unsigned int pos);
7683 Eina_Bool (*property_set) (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args);
7684 Eina_Bool (*property_get) (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args);
7685 const char *(*property_name_get)(Evas_Object *o, int property);
7686 int (*property_id_get) (Evas_Object *o, const char *name);
7687 Evas_Object_Box_Option *(*option_new) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object *child);
7688 void (*option_free) (Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt);
7692 * @def EVAS_OBJECT_BOX_API_INIT
7693 * Initializer for whole Evas_Object_Box_Api structure.
7695 * @param smart_class_init initializer to use for the "base" field
7696 * (Evas_Smart_Class).
7698 * @see EVAS_SMART_CLASS_INIT_NULL
7699 * @see EVAS_SMART_CLASS_INIT_VERSION
7700 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
7701 * @see EVAS_OBJECT_BOX_API_INIT_NULL
7702 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
7703 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
7704 * @ingroup Evas_Object_Box
7706 #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}
7709 * @def EVAS_OBJECT_BOX_API_INIT_NULL
7710 * Initializer to zero a whole Evas_Object_Box_Api structure.
7712 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
7713 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
7714 * @see EVAS_OBJECT_BOX_API_INIT
7715 * @ingroup Evas_Object_Box
7717 #define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
7720 * @def EVAS_OBJECT_BOX_API_INIT_VERSION
7721 * Initializer to zero a whole Evas_Object_Box_Api structure and set version.
7723 * Similar to EVAS_OBJECT_BOX_API_INIT_NULL, but will set version field of
7724 * Evas_Smart_Class (base field) to latest EVAS_SMART_CLASS_VERSION
7726 * @see EVAS_OBJECT_BOX_API_INIT_NULL
7727 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
7728 * @see EVAS_OBJECT_BOX_API_INIT
7729 * @ingroup Evas_Object_Box
7731 #define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
7734 * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
7735 * Initializer to zero a whole Evas_Object_Box_Api structure and set
7738 * Similar to EVAS_OBJECT_BOX_API_INIT_NULL, but will set version field of
7739 * Evas_Smart_Class (base field) to latest EVAS_SMART_CLASS_VERSION and name
7740 * to the specific value.
7742 * It will keep a reference to name field as a "const char *", that is,
7743 * name must be available while the structure is used (hint: static or global!)
7744 * and will not be modified.
7746 * @see EVAS_OBJECT_BOX_API_INIT_NULL
7747 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
7748 * @see EVAS_OBJECT_BOX_API_INIT
7749 * @ingroup Evas_Object_Box
7751 #define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
7754 * @struct _Evas_Object_Box_Data
7756 * This structure augments clipped smart object's instance data,
7757 * providing extra members required by generic box implementation. If
7758 * a subclass inherits from #Evas_Object_Box_Api then it may augment
7759 * #Evas_Object_Box_Data to fit its own needs.
7761 * @extends Evas_Object_Smart_Clipped_Data
7762 * @ingroup Evas_Object_Box
7764 struct _Evas_Object_Box_Data
7766 Evas_Object_Smart_Clipped_Data base;
7767 const Evas_Object_Box_Api *api;
7774 Eina_List *children;
7776 Evas_Object_Box_Layout cb;
7778 void (*free_data)(void *data);
7780 Eina_Bool layouting : 1;
7781 Eina_Bool children_changed : 1;
7784 struct _Evas_Object_Box_Option
7787 Eina_Bool max_reached:1;
7788 Eina_Bool min_reached:1;
7789 Evas_Coord alloc_size;
7794 * Set the default box @a api struct (Evas_Object_Box_Api)
7795 * with the default values. May be used to extend that API.
7797 EAPI void evas_object_box_smart_set (Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
7800 * Get Box Smart Class for inheritance purposes
7802 EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get (void) EINA_CONST;
7805 * Set a 'calculate' callback (@a cb) to the @a o box's smart class,
7806 * which here defines its genre (horizontal, vertical, homogeneous,
7809 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);
7815 * Its layout function must be set via evas_object_box_layout_set()
7816 * (defaults to evas_object_box_layout_horizontal()). The other
7817 * properties of the box must be set/retrieved via
7818 * evas_object_box_{h,v}_{align,padding}_{get,set)().
7820 EAPI Evas_Object *evas_object_box_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7823 * Create a box that is child of a given element @a parent.
7825 * @see evas_object_box_add()
7827 EAPI Evas_Object *evas_object_box_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
7831 * Layout function which sets the box @a o to a (basic) horizontal
7832 * box. @a priv must be the smart data of the box.
7834 * The object's overall behavior is controlled by its properties,
7835 * which are set by the evas_object_box_{h,v}_{align,padding}_set()
7836 * family of functions. The properties of the elements in the box --
7837 * set by evas_object_size_hint_{align,padding,weight}_set() functions
7838 * -- also control the way this function works.
7840 * \par box's properties:
7841 * @c align_h controls the horizontal alignment of the child objects
7842 * relative to the containing box. When set to 0, children are aligned
7843 * to the left. A value of 1 lets them aligned to the right border.
7844 * Values in between align them proportionally. Note that if the size
7845 * required by the children, which is given by their widths and the @c
7846 * padding_h property of the box, is bigger than the container width,
7847 * the children will be displayed out of its bounds. A negative value
7848 * of @c align_h makes the box to *justify* its children. The padding
7849 * between them, in this case, is corrected so that the leftmost one
7850 * touches the left border and the rightmost one touches the right
7851 * border (even if they must overlap). The @c align_v and @c
7852 * padding_v properties of the box don't contribute to its behaviour
7853 * when this layout is chosen.
7855 * \par Child element's properties:
7856 * @c align_x does not influence the box's behavior. @c padding_l and
7857 * @c padding_r sum up to the container's horizontal padding between
7858 * elements. The child's @c padding_t, @c padding_b and @c align_y
7859 * properties apply for padding/positioning relative to the overall
7860 * height of the box. Finally, there is the @c weight_x property,
7861 * which, if set to a non-zero value, tells the container that the
7862 * child width is not pre-defined. If the container can't accommodate
7863 * all its children, it sets the widths of the children *with weights*
7864 * to sizes as small as they can all fit into it. If the size
7865 * required by the children is less than the available, the box
7866 * increases its children's (which have weights) widths as to fit the
7867 * remaining space. The @c weight_x property, besides telling the
7868 * element is resizable, gives a *weight* for the resizing process.
7869 * The parent box will try to distribute (or take off) widths
7870 * accordingly to the *normalized* list of weigths: most weighted
7871 * children remain/get larger in this process than the least ones.
7872 * @c weight_y does not influence the layout.
7874 * If one desires that, besides having weights, child elements must be
7875 * resized bounded to a minimum or maximum size, their size hint
7876 * properties must be set (by the
7877 * evas_object_size_hint_{min,max}_set() functions.
7879 EAPI void evas_object_box_layout_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
7882 * Layout function which sets the box @a o to a (basic) vertical box.
7883 * @a priv must be the smart data of the box.
7885 * This function behaves analogously to
7886 * evas_object_box_layout_horizontal(). The description of its
7887 * behaviour can be derived from that function's documentation.
7889 EAPI void evas_object_box_layout_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
7892 * Layout function which sets the box @a o to a *homogeneous* vertical
7893 * box. @a priv must be the smart data of the box.
7895 * This function behaves analogously to
7896 * evas_object_box_layout_homogeneous_horizontal(). The description
7897 * of its behaviour can be derived from that function's documentation.
7899 EAPI void evas_object_box_layout_homogeneous_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
7902 * Layout function which sets the box @a o to a *homogeneous*
7903 * horizontal box. @a priv must be the smart data of the box.
7905 * In a homogeneous horizontal box, its width is divided equally
7906 * between the contained objects. The box's overall behavior is
7907 * controlled by its properties, which are set by the
7908 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
7909 * The properties of the elements in the box -- set by
7910 * evas_object_size_hint_{align,padding,weight}_set() functions --
7911 * also control the way this function works.
7913 * \par box's properties:
7914 * @c align_h has no influence on the box for this layout. @c
7915 * padding_h tells the box to draw empty spaces of that size, in
7916 * pixels, between the (still equal) child objects's cells. The @c
7917 * align_v and @c padding_v properties of the box don't contribute to
7918 * its behaviour when this layout is chosen.
7920 * \par Child element's properties:
7921 * @c padding_l and @c padding_r sum up to the required width of the
7922 * child element. The @c align_x property tells the relative position
7923 * of this overall child width in its allocated cell (0 to extreme
7924 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
7925 * box try to resize this child element to the exact width of its cell
7926 * (respecting the min and max hints on the child's width *and*
7927 * accounting its horizontal padding properties). The child's @c
7928 * padding_t, @c padding_b and @c align_y properties apply for
7929 * padding/positioning relative to the overall height of the box. A
7930 * value of -1.0 to @c align_y makes the box try to resize this child
7931 * element to the exact height of its parent (respecting the max hint
7932 * on the child's height).
7934 EAPI void evas_object_box_layout_homogeneous_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
7937 * Layout function which sets the box @a o to a *max size-homogeneous*
7938 * horizontal box. @a priv must be the smart data of the box.
7940 * In a max size-homogeneous horizontal box, the equal sized cells
7941 * reserved for the child objects have the width of the space required
7942 * by the largest child (in width). The box's overall behavior is
7943 * controlled by its properties, which are set by the
7944 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
7945 * The properties of the elements in the box -- set by
7946 * evas_object_size_hint_{align,padding,weight}_set() functions --
7947 * also control the way this function works.
7949 * \par box's properties:
7950 * @c padding_h tells the box to draw empty spaces of that size, in
7951 * pixels, between the child objects's cells. @c align_h controls the
7952 * horizontal alignment of the child objects relative to the
7953 * containing box. When set to 0, children are aligned to the left. A
7954 * value of 1 lets them aligned to the right border. Values in
7955 * between align them proportionally. A negative value of @c align_h
7956 * makes the box to *justify* its children cells. The padding between
7957 * them, in this case, is corrected so that the leftmost one touches
7958 * the left border and the rightmost one touches the right border
7959 * (even if they must overlap). The @c align_v and @c padding_v
7960 * properties of the box don't contribute to its behaviour when this
7963 * \par Child element's properties:
7964 * @c padding_l and @c padding_r sum up to the required width of the
7965 * child element. The @c align_x property tells the relative position
7966 * of this overall child width in its allocated cell (0 to extreme
7967 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
7968 * box try to resize this child element to the exact width of its cell
7969 * (respecting the min and max hints on the child's width *and*
7970 * accounting its horizontal padding properties). The child's @c
7971 * padding_t, @c padding_b and @c align_y properties apply for
7972 * padding/positioning relative to the overall height of the box. A
7973 * value of -1.0 to @c align_y makes the box try to resize this child
7974 * element to the exact height of its parent (respecting the max hint
7975 * on the child's height).
7977 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);
7980 * Layout function which sets the box @a o to a *max size-homogeneous*
7981 * vertical box. @a priv must be the smart data of the box.
7983 * This function behaves analogously to
7984 * evas_object_box_layout_homogeneous_max_size_horizontal(). The
7985 * description of its behaviour can be derived from that function's
7988 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);
7991 * Layout function which sets the box @a o to a *flow* horizontal box.
7992 * @a priv must be the smart data of the box.
7994 * In a flow horizontal box, the box's child elements are placed in
7995 * rows (think of text as an analogy). A row has as much elements as
7996 * can fit into the box's width. The box's overall behavior is
7997 * controlled by its properties, which are set by the
7998 * evas_object_box_{h,v}_{align,padding}_set() family of functions.
7999 * The properties of the elements in the box -- set by
8000 * evas_object_size_hint_{align,padding,weight}_set() functions --
8001 * also control the way this function works.
8003 * \par box's properties:
8004 * @c padding_h tells the box to draw empty spaces of that size, in
8005 * pixels, between the child objects's cells. @c align_h dictates the
8006 * horizontal alignment of the rows (0 to left align them, 1 to right
8007 * align). A value of -1.0 to @c align_h lets the rows *justified*
8008 * horizontally. @c align_v controls the vertical alignment of the
8009 * entire set of rows (0 to top, 1 to bottom). A value of -1.0 to @c
8010 * align_v makes the box to *justify* the rows vertically. The padding
8011 * between them, in this case, is corrected so that the first row
8012 * touches the top border and the last one touches the bottom border
8013 * (even if they must overlap). @c padding_v has no influence on the
8016 * \par Child element's properties:
8017 * @c padding_l and @c padding_r sum up to the required width of the
8018 * child element. The @c align_x property has no influence on the
8019 * layout. The child's @c padding_t and @c padding_b sum up to the
8020 * required height of the child element and is the only means (besides
8021 * row justifying) of setting space between rows. Note, however, that
8022 * @c align_y dictates positioning relative to the *largest height*
8023 * required by a child object in the actual row.
8025 EAPI void evas_object_box_layout_flow_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8028 * Layout function which sets the box @a o to a *flow* vertical box.
8029 * @a priv must be the smart data of the box.
8031 * This function behaves analogously to
8032 * evas_object_box_layout_flow_horizontal(). The description of its
8033 * behaviour can be derived from that function's documentation.
8035 EAPI void evas_object_box_layout_flow_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8038 * Layout function which sets the box @a o to set all children to the
8039 * size of the object. @a priv must be the smart data of the box.
8041 * In a stack box, all children will be given the same size and they
8042 * will be stacked on above the other, so the first object will be the
8045 * \par box's properties:
8046 * No box option is used.
8048 * \par Child element's properties:
8049 * @c padding_l and @c padding_r sum up to the required width of the
8050 * child element. The @c align_x property tells the relative position
8051 * of this overall child width in its allocated cell (0 to extreme
8052 * left, 1 to extreme right). A value of -1.0 to @c align_x makes the
8053 * box try to resize this child element to the exact width of its cell
8054 * (respecting the min and max hints on the child's width *and*
8055 * accounting its horizontal padding properties). Same applies to
8058 EAPI void evas_object_box_layout_stack (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
8062 * Set the alignment of the whole bounding box of contents.
8064 EAPI void evas_object_box_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
8067 * Get alignment of the whole bounding box of contents.
8069 EAPI void evas_object_box_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
8072 * Set the space (padding) between cells.
8074 EAPI void evas_object_box_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
8077 * Get the (space) padding between cells.
8079 EAPI void evas_object_box_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
8083 * Append a new object @a child to the box @a o. On error, @c NULL is
8086 EAPI Evas_Object_Box_Option *evas_object_box_append (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8089 * Prepend a new object @a child to the box @a o. On error, @c NULL is
8092 EAPI Evas_Object_Box_Option *evas_object_box_prepend (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8095 * Prepend a new object @a child to the box @c o relative to element @a
8096 * reference. If @a reference is not contained in the box or any other
8097 * error occurs, @c NULL is returned.
8099 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);
8102 * Append a new object @a child to the box @c o relative to element @a
8103 * reference. If @a reference is not contained in the box or any other
8104 * error occurs, @c NULL is returend.
8106 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);
8109 * Insert a new object @a child to the box @a o at position @a pos. On
8110 * error, @c NULL is returned.
8112 EAPI Evas_Object_Box_Option *evas_object_box_insert_at (Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2);
8115 * Remove an object @a child from the box @a o. On error, @c 0 is
8118 EAPI Eina_Bool evas_object_box_remove (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8121 * Remove an object from the box @a o which occupies position @a
8122 * pos. On error, @c 0 is returned.
8124 EAPI Eina_Bool evas_object_box_remove_at (Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1);
8127 * Remove all child objects.
8128 * @return 0 on errors
8130 EAPI Eina_Bool evas_object_box_remove_all (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8133 * Get an iterator to walk the list of children for the box.
8135 * @note Do not remove or delete objects while walking the list.
8137 EAPI Eina_Iterator *evas_object_box_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8140 * Get an accessor to get random access to the list of children for the box.
8142 * @note Do not remove or delete objects while walking the list.
8144 EAPI Eina_Accessor *evas_object_box_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8147 * Get the list of children for the box.
8149 * @note This is a duplicate of the list kept by the box internally.
8150 * It's up to the user to destroy it when it no longer needs it.
8151 * It's possible to remove objects from the box when walking this
8152 * list, but these removals won't be reflected on it.
8154 EAPI Eina_List *evas_object_box_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8158 * Get the name of the property of the child elements of the box @a o
8159 * whose id is @a property. On error, @c NULL is returned.
8161 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;
8164 * Get the id of the property of the child elements of the box @a o
8165 * whose name is @a name. On error, @c -1 is returned.
8167 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;
8170 * Set the property (with id @a property) of the child element of the
8171 * box @a o whose property struct is @a opt. The property's values
8172 * must be the last arguments and their type *must* match that of the
8173 * property itself. On error, @c 0 is returned.
8175 EAPI Eina_Bool evas_object_box_option_property_set (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
8178 * Set the property (with id @a property) of the child element of the
8179 * box @a o whose property struct is @a opt. The property's values
8180 * must be the args which the va_list @a args is initialized with and
8181 * their type *must* match that of the property itself. On error, @c 0
8184 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);
8187 * Get the property (with id @a property) of the child element of the
8188 * box @a o whose property struct is @a opt. The last arguments must
8189 * be addresses of variables with the same type of that property. On
8190 * error, @c 0 is returned.
8192 EAPI Eina_Bool evas_object_box_option_property_get (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
8195 * Get the property (with id @a property) of the child element of the
8196 * box @a o whose property struct is @a opt. The args which the
8197 * va_list @a args is initialized with must be addresses of variables
8198 * with the same type of that property. On error, @c 0 is returned.
8200 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);
8203 * @defgroup Evas_Object_Table Table Smart Object.
8205 * Convenience smart object that packs children using a tabular
8206 * layout using children size hints to define their size and
8207 * alignment inside their cell space.
8209 * @see @ref Evas_Object_Group_Size_Hints
8211 * @ingroup Evas_Smart_Object_Group
8215 * Create a new table.
8217 * It's set to non-homogeneous by default, add children with
8218 * evas_object_table_pack().
8220 EAPI Evas_Object *evas_object_table_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8223 * Create a table that is child of a given element @a parent.
8225 * @see evas_object_table_add()
8227 EAPI Evas_Object *evas_object_table_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8230 * Set how this table should layout children.
8232 * @todo consider aspect hint and respect it.
8234 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE
8235 * If table does not use homogeneous mode then columns and rows will
8236 * be calculated based on hints of individual cells. This operation
8237 * mode is more flexible, but more complex and heavy to calculate as
8238 * well. @b Weight properties are handled as a boolean
8239 * expand. Negative alignment will be considered as 0.5.
8241 * @todo @c EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE should balance weight.
8243 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE
8244 * When homogeneous is relative to table the own table size is divided
8245 * equally among children, filling the whole table area. That is, if
8246 * table has @c WIDTH and @c COLUMNS, each cell will get <tt>WIDTH /
8247 * COLUMNS</tt> pixels. If children have minimum size that is larger
8248 * than this amount (including padding), then it will overflow and be
8249 * aligned respecting the alignment hint, possible overlapping sibling
8250 * cells. @b Weight hint is used as a boolean, if greater than zero it
8251 * will make the child expand in that axis, taking as much space as
8252 * possible (bounded to maximum size hint). Negative alignment will be
8253 * considered as 0.5.
8255 * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM
8256 * When homogeneous is relative to item it means the greatest minimum
8257 * cell size will be used. That is, if no element is set to expand,
8258 * the table will have its contents to a minimum size, the bounding
8259 * box of all these children will be aligned relatively to the table
8260 * object using evas_object_table_align_get(). If the table area is
8261 * too small to hold this minimum bounding box, then the objects will
8262 * keep their size and the bounding box will overflow the box area,
8263 * still respecting the alignment. @b Weight hint is used as a
8264 * boolean, if greater than zero it will make that cell expand in that
8265 * axis, toggling the <b>expand mode</b>, which makes the table behave
8266 * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the
8267 * bounding box will overflow and items will not overlap siblings. If
8268 * no minimum size is provided at all then the table will fallback to
8269 * expand mode as well.
8271 EAPI void evas_object_table_homogeneous_set (Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1);
8274 * Get the current layout homogeneous mode.
8276 * @see evas_object_table_homogeneous_set()
8278 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;
8281 * Set padding between cells.
8283 EAPI void evas_object_table_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
8286 * Get padding between cells.
8288 EAPI void evas_object_table_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
8291 * Set the alignment of the whole bounding box of contents.
8293 EAPI void evas_object_table_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
8296 * Get alignment of the whole bounding box of contents.
8298 EAPI void evas_object_table_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
8301 * Sets the mirrored mode of the table. In mirrored mode the table items go
8302 * from right to left instead of left to right. That is, 1,1 is top right, not
8305 * @param obj The table object.
8306 * @param mirrored the mirrored mode to set
8309 EAPI void evas_object_table_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
8312 * Gets the mirrored mode of the table. In mirrored mode the table items go
8313 * from right to left instead of left to right. That is, 1,1 is top right, not
8316 * @param obj The table object.
8317 * @return EINA_TRUE if it's a mirrored table, EINA_FALSE otherwise.
8322 * Get a child from the table using its coordinates
8324 * @note This does not take into account col/row spanning
8326 EAPI Eina_Bool evas_object_table_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
8330 * Add a new child to a table object.
8332 * @param o The given table object.
8333 * @param child The child object to add.
8334 * @param col relative-horizontal position to place child.
8335 * @param row relative-vertical position to place child.
8336 * @param colspan how many relative-horizontal position to use for this child.
8337 * @param rowspan how many relative-vertical position to use for this child.
8339 * @return 1 on success, 0 on failure.
8341 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);
8344 * Remove child from table.
8346 * @note removing a child will immediately call a walk over children in order
8347 * to recalculate numbers of columns and rows. If you plan to remove
8348 * all children, use evas_object_table_clear() instead.
8350 * @return 1 on success, 0 on failure.
8352 EAPI Eina_Bool evas_object_table_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8355 * Faster way to remove all child objects from a table object.
8357 * @param o The given table object.
8358 * @param clear if true, it will delete just removed children.
8360 EAPI void evas_object_table_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8364 * Get the number of columns and rows this table takes.
8366 * @note columns and rows are virtual entities, one can specify a table
8367 * with a single object that takes 4 columns and 5 rows. The only
8368 * difference for a single cell table is that paddings will be
8369 * accounted proportionally.
8371 EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1);
8374 * Get an iterator to walk the list of children for the table.
8376 * @note Do not remove or delete objects while walking the list.
8378 EAPI Eina_Iterator *evas_object_table_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8381 * Get an accessor to get random access to the list of children for the table.
8383 * @note Do not remove or delete objects while walking the list.
8385 EAPI Eina_Accessor *evas_object_table_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8388 * Get the list of children for the table.
8390 * @note This is a duplicate of the list kept by the table internally.
8391 * It's up to the user to destroy it when it no longer needs it.
8392 * It's possible to remove objects from the table when walking this
8393 * list, but these removals won't be reflected on it.
8395 EAPI Eina_List *evas_object_table_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8396 EAPI Evas_Object *evas_object_table_child_get (const Evas_Object *o, unsigned short col, unsigned short row) EINA_ARG_NONNULL(1);
8399 * @defgroup Evas_Object_Grid Grid Smart Object.
8401 * Convenience smart object that packs children using a regular grid
8402 * layout using Their virtual grid location and size to determine
8403 * position inside the grid object
8405 * @ingroup Evas_Smart_Object_Group
8410 * Create a new grid.
8412 * It's set to a virtual size of 1x1 by default and add children with
8413 * evas_object_grid_pack().
8416 EAPI Evas_Object *evas_object_grid_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8419 * Create a grid that is child of a given element @a parent.
8421 * @see evas_object_grid_add()
8424 EAPI Evas_Object *evas_object_grid_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8427 * Set the virtual resolution for the grid
8429 * @param o The grid object to modify
8430 * @param w The virtual horizontal size (resolution) in integer units
8431 * @param h The virtual vertical size (resolution) in integer units
8434 EAPI void evas_object_grid_size_set (Evas_Object *o, int w, int h) EINA_ARG_NONNULL(1);
8437 * Get the current virtual resolution
8439 * @param o The grid object to query
8440 * @param w A pointer to an integer to store the virtual width
8441 * @param h A pointer to an integer to store the virtual height
8442 * @see evas_object_grid_size_set()
8445 EAPI void evas_object_grid_size_get (const Evas_Object *o, int *w, int *h) EINA_ARG_NONNULL(1) EINA_PURE;
8448 * Sets the mirrored mode of the grid. In mirrored mode the grid items go
8449 * from right to left instead of left to right. That is, 0,0 is top right, not
8452 * @param obj The grid object.
8453 * @param mirrored the mirrored mode to set
8456 EAPI void evas_object_grid_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
8459 * Gets the mirrored mode of the grid.
8461 * @param obj The grid object.
8462 * @return EINA_TRUE if it's a mirrored grid, EINA_FALSE otherwise.
8463 * @see evas_object_grid_mirrored_set()
8466 EAPI Eina_Bool evas_object_grid_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1);
8469 * Add a new child to a grid object.
8471 * @param o The given grid object.
8472 * @param child The child object to add.
8473 * @param x The virtual x coordinate of the child
8474 * @param y The virtual y coordinate of the child
8475 * @param w The virtual width of the child
8476 * @param h The virtual height of the child
8477 * @return 1 on success, 0 on failure.
8480 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);
8483 * Remove child from grid.
8485 * @note removing a child will immediately call a walk over children in order
8486 * to recalculate numbers of columns and rows. If you plan to remove
8487 * all children, use evas_object_grid_clear() instead.
8489 * @return 1 on success, 0 on failure.
8492 EAPI Eina_Bool evas_object_grid_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
8495 * Faster way to remove all child objects from a grid object.
8497 * @param o The given grid object.
8498 * @param clear if true, it will delete just removed children.
8501 EAPI void evas_object_grid_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
8504 * Get the pack options for a grid child
8506 * Get the pack x, y, width and height in virtual coordinates set by
8507 * evas_object_grid_pack()
8508 * @param o The grid object
8509 * @param child The grid child to query for coordinates
8510 * @param x The pointer to where the x coordinate will be returned
8511 * @param y The pointer to where the y coordinate will be returned
8512 * @param w The pointer to where the width will be returned
8513 * @param h The pointer to where the height will be returned
8514 * @return 1 on success, 0 on failure.
8517 EAPI Eina_Bool evas_object_grid_pack_get (Evas_Object *o, Evas_Object *child, int *x, int *y, int *w, int *h);
8520 * Get an iterator to walk the list of children for the grid.
8522 * @note Do not remove or delete objects while walking the list.
8525 EAPI Eina_Iterator *evas_object_grid_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8528 * Get an accessor to get random access to the list of children for the grid.
8530 * @note Do not remove or delete objects while walking the list.
8533 EAPI Eina_Accessor *evas_object_grid_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8536 * Get the list of children for the grid.
8538 * @note This is a duplicate of the list kept by the grid internally.
8539 * It's up to the user to destroy it when it no longer needs it.
8540 * It's possible to remove objects from the grid when walking this
8541 * list, but these removals won't be reflected on it.
8544 EAPI Eina_List *evas_object_grid_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
8547 * @defgroup Evas_Cserve Shared Image Cache Server
8549 * Provides client-server infrastructure to share bitmaps across
8550 * multiple processes, saving data and processing power.
8552 typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
8553 typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
8554 typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
8555 typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
8558 * Statistics about server that shares cached bitmaps.
8559 * @ingroup Evas_Cserve
8561 struct _Evas_Cserve_Stats
8563 int saved_memory; /**< current saved memory, in bytes */
8564 int wasted_memory; /**< current wasted memory, in bytes */
8565 int saved_memory_peak; /**< peak of saved memory, in bytes */
8566 int wasted_memory_peak; /**< peak of wasted memory, in bytes */
8567 double saved_time_image_header_load; /**< time, in seconds, saved in header loads by sharing cached loads instead */
8568 double saved_time_image_data_load; /**< time, in seconds, saved in data loads by sharing cached loads instead */
8572 * Cache of images shared by server.
8573 * @ingroup Evas_Cserve
8575 struct _Evas_Cserve_Image_Cache
8585 * An image shared by the server.
8586 * @ingroup Evas_Cserve
8588 struct _Evas_Cserve_Image
8590 const char *file, *key;
8592 time_t file_mod_time;
8593 time_t file_checked_time;
8597 int memory_footprint;
8598 double head_load_time;
8599 double data_load_time;
8600 Eina_Bool alpha : 1;
8601 Eina_Bool data_loaded : 1;
8602 Eina_Bool active : 1;
8604 Eina_Bool useless : 1;
8608 * Configuration that controls the server that shares cached bitmaps.
8609 * @ingroup Evas_Cserve
8611 struct _Evas_Cserve_Config
8613 int cache_max_usage;
8614 int cache_item_timeout;
8615 int cache_item_timeout_check;
8620 * Retrieves if the system wants to share bitmaps using the server.
8621 * @return @c EINA_TRUE if wants, @c EINA_FALSE otherwise.
8622 * @ingroup Evas_Cserve
8624 EAPI Eina_Bool evas_cserve_want_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE;
8627 * Retrieves if the system is connected to the server used to shae bitmaps.
8628 * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise.
8629 * @ingroup Evas_Cserve
8631 EAPI Eina_Bool evas_cserve_connected_get (void) EINA_WARN_UNUSED_RESULT;
8634 * Retrieves if the system wants to share bitmaps using the server.
8635 * @param stats pointer to structure to fill with statistics about
8637 * @return @c EINA_TRUE if @p stats were filled with data,
8638 * @c EINA_FALSE otherwise and @p stats is untouched.
8639 * @ingroup Evas_Cserve
8641 EAPI Eina_Bool evas_cserve_stats_get (Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
8642 EAPI void evas_cserve_image_cache_contents_clean (Evas_Cserve_Image_Cache *cache) EINA_PURE;
8645 * Retrieves the current configuration of the server.
8646 * @param config where to store current server configuration.
8647 * @return @c EINA_TRUE if @p config were filled with data,
8648 * @c EINA_FALSE otherwise and @p config is untouched.
8649 * @ingroup Evas_Cserve
8651 EAPI Eina_Bool evas_cserve_config_get (Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE;
8654 * Changes the configuration of the server.
8655 * @param config where to store current server configuration.
8656 * @return @c EINA_TRUE if @p config were successfully applied,
8657 * @c EINA_FALSE otherwise.
8658 * @ingroup Evas_Cserve
8660 EAPI Eina_Bool evas_cserve_config_set (const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE;
8663 * Force system to disconnect from cache server.
8664 * @ingroup Evas_Cserve
8666 EAPI void evas_cserve_disconnect (void);
8669 * @defgroup Evas_Utils General Utilities
8671 * Some functions that are handy but are not specific of canvas or
8676 * Converts the given Evas image load error code into a string
8677 * describing it in english.
8679 * @param error the error code, a value in ::Evas_Load_Error.
8680 * @return Always returns a valid string. If the given @p error is not
8681 * supported, <code>"Unknown error"</code> is returned.
8683 * Mostly evas_object_image_file_set() would be the function setting
8684 * that error value afterwards, but also evas_object_image_load(),
8685 * evas_object_image_save(), evas_object_image_data_get(),
8686 * evas_object_image_data_convert(), evas_object_image_pixels_import()
8687 * and evas_object_image_is_inside(). This function is meant to be
8688 * used in conjunction with evas_object_image_load_error_get(), as in:
8691 * @dontinclude evas-load-error-str.c
8693 * @until ecore_main_loop_begin(
8695 * Here, being @c valid_path the path to a valid image and @c
8696 * bogus_path a path to a file which does not exist, the two outputs
8697 * of evas_load_error_str() would be (if no other errors occur):
8698 * <code>"No error on load"</code> and <code>"File (or file path) does
8699 * not exist"</code>, respectively. See the full @ref
8700 * Example_Evas_Load_Error_Str "example".
8702 * @ingroup Evas_Utils
8704 EAPI const char *evas_load_error_str (Evas_Load_Error error);
8706 /* Evas utility routines for color space conversions */
8707 /* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
8708 /* rgb color space has r,g,b in the range 0 to 255 */
8711 * Convert a given color from HSV to RGB format.
8713 * @param h The Hue component of the color.
8714 * @param s The Saturation component of the color.
8715 * @param v The Value component of the color.
8716 * @param r The Red component of the color.
8717 * @param g The Green component of the color.
8718 * @param b The Blue component of the color.
8720 * This function converts a given color in HSV color format to RGB
8723 * @ingroup Evas_Utils
8725 EAPI void evas_color_hsv_to_rgb (float h, float s, float v, int *r, int *g, int *b);
8728 * Convert a given color from RGB to HSV format.
8730 * @param r The Red component of the color.
8731 * @param g The Green component of the color.
8732 * @param b The Blue component of the color.
8733 * @param h The Hue component of the color.
8734 * @param s The Saturation component of the color.
8735 * @param v The Value component of the color.
8737 * This function converts a given color in RGB color format to HSV
8740 * @ingroup Evas_Utils
8742 EAPI void evas_color_rgb_to_hsv (int r, int g, int b, float *h, float *s, float *v);
8744 /* argb color space has a,r,g,b in the range 0 to 255 */
8747 * Pre-multiplies a rgb triplet by an alpha factor.
8749 * @param a The alpha factor.
8750 * @param r The Red component of the color.
8751 * @param g The Green component of the color.
8752 * @param b The Blue component of the color.
8754 * This function pre-multiplies a given rbg triplet by an alpha
8755 * factor. Alpha factor is used to define transparency.
8757 * @ingroup Evas_Utils
8759 EAPI void evas_color_argb_premul (int a, int *r, int *g, int *b);
8762 * Undo pre-multiplication of a rgb triplet by an alpha factor.
8764 * @param a The alpha factor.
8765 * @param r The Red component of the color.
8766 * @param g The Green component of the color.
8767 * @param b The Blue component of the color.
8769 * This function undoes pre-multiplication a given rbg triplet by an
8770 * alpha factor. Alpha factor is used to define transparency.
8772 * @see evas_color_argb_premul().
8774 * @ingroup Evas_Utils
8776 EAPI void evas_color_argb_unpremul (int a, int *r, int *g, int *b);
8780 * Pre-multiplies data by an alpha factor.
8782 * @param data The data value.
8783 * @param len The length value.
8785 * This function pre-multiplies a given data by an alpha
8786 * factor. Alpha factor is used to define transparency.
8788 * @ingroup Evas_Utils
8790 EAPI void evas_data_argb_premul (unsigned int *data, unsigned int len);
8793 * Undo pre-multiplication data by an alpha factor.
8795 * @param data The data value.
8796 * @param len The length value.
8798 * This function undoes pre-multiplication of a given data by an alpha
8799 * factor. Alpha factor is used to define transparency.
8801 * @ingroup Evas_Utils
8803 EAPI void evas_data_argb_unpremul (unsigned int *data, unsigned int len);
8805 /* string and font handling */
8808 * Gets the next character in the string
8810 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
8811 * this function will place in @p decoded the decoded code point at @p pos
8812 * and return the byte index for the next character in the string.
8814 * The only boundary check done is that @p pos must be >= 0. Other than that,
8815 * no checks are performed, so passing an index value that's not within the
8816 * length of the string will result in undefined behavior.
8818 * @param str The UTF-8 string
8819 * @param pos The byte index where to start
8820 * @param decoded Address where to store the decoded code point. Optional.
8822 * @return The byte index of the next character
8824 * @ingroup Evas_Utils
8826 EAPI int evas_string_char_next_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
8829 * Gets the previous character in the string
8831 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
8832 * this function will place in @p decoded the decoded code point at @p pos
8833 * and return the byte index for the previous character in the string.
8835 * The only boundary check done is that @p pos must be >= 1. Other than that,
8836 * no checks are performed, so passing an index value that's not within the
8837 * length of the string will result in undefined behavior.
8839 * @param str The UTF-8 string
8840 * @param pos The byte index where to start
8841 * @param decoded Address where to store the decoded code point. Optional.
8843 * @return The byte index of the previous character
8845 * @ingroup Evas_Utils
8847 EAPI int evas_string_char_prev_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
8850 * Get the length in characters of the string.
8851 * @param str The string to get the length of.
8852 * @return The length in characters (not bytes)
8853 * @ingroup Evas_Utils
8855 EAPI int evas_string_char_len_get (const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8858 * @defgroup Evas_Keys Key Input Functions
8860 * Functions which feed key events to the canvas.
8862 * As explained in @ref intro_not_evas, Evas is @b not aware of input
8863 * systems at all. Then, the user, if using it crudely (evas_new()),
8864 * will have to feed it with input events, so that it can react
8865 * somehow. If, however, the user creates a canvas by means of the
8866 * Ecore_Evas wrapper, it will automatically bind the chosen display
8867 * engine's input events to the canvas, for you.
8869 * This group presents the functions dealing with the feeding of key
8870 * events to the canvas. On most of them, one has to reference a given
8871 * key by a name (<code>keyname</code> argument). Those are
8872 * <b>platform dependent</b> symbolic names for the keys. Sometimes
8873 * you'll get the right <code>keyname</code> by simply using an ASCII
8874 * value of the key name, but it won't be like that always.
8876 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
8877 * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
8878 * to your display engine's documentation when using evas through an
8879 * Ecore helper wrapper when you need the <code>keyname</code>s.
8882 * @dontinclude evas-events.c
8883 * @skip mods = evas_key_modifier_get(evas);
8886 * All the other @c evas_key functions behave on the same manner. See
8887 * the full @ref Example_Evas_Events "example".
8889 * @ingroup Evas_Canvas
8893 * @addtogroup Evas_Keys
8898 * Returns a handle to the list of modifier keys registered in the
8899 * canvas @p e. This is required to check for which modifiers are set
8900 * at a given time with the evas_key_modifier_is_set() function.
8902 * @param e The pointer to the Evas canvas
8904 * @see evas_key_modifier_add
8905 * @see evas_key_modifier_del
8906 * @see evas_key_modifier_on
8907 * @see evas_key_modifier_off
8908 * @see evas_key_modifier_is_set
8910 * @return An ::Evas_Modifier handle to query Evas' keys subsystem
8911 * with evas_key_modifier_is_set(), or @c NULL on error.
8913 EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8916 * Returns a handle to the list of lock keys registered in the canvas
8917 * @p e. This is required to check for which locks are set at a given
8918 * time with the evas_key_lock_is_set() function.
8920 * @param e The pointer to the Evas canvas
8922 * @see evas_key_lock_add
8923 * @see evas_key_lock_del
8924 * @see evas_key_lock_on
8925 * @see evas_key_lock_off
8926 * @see evas_key_lock_is_set
8928 * @return An ::Evas_Lock handle to query Evas' keys subsystem with
8929 * evas_key_lock_is_set(), or @c NULL on error.
8931 EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
8935 * Checks the state of a given modifier key, at the time of the
8936 * call. If the modifier is set, such as shift being pressed, this
8937 * function returns @c Eina_True.
8939 * @param m The current modifiers set, as returned by
8940 * evas_key_modifier_get().
8941 * @param keyname The name of the modifier key to check status for.
8943 * @return @c Eina_True if the modifier key named @p keyname is on, @c
8944 * Eina_False otherwise.
8946 * @see evas_key_modifier_add
8947 * @see evas_key_modifier_del
8948 * @see evas_key_modifier_get
8949 * @see evas_key_modifier_on
8950 * @see evas_key_modifier_off
8952 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;
8956 * Checks the state of a given lock key, at the time of the call. If
8957 * the lock is set, such as caps lock, this function returns @c
8960 * @param l The current locks set, as returned by evas_key_lock_get().
8961 * @param keyname The name of the lock key to check status for.
8963 * @return @c Eina_True if the @p keyname lock key is set, @c
8964 * Eina_False otherwise.
8966 * @see evas_key_lock_get
8967 * @see evas_key_lock_add
8968 * @see evas_key_lock_del
8969 * @see evas_key_lock_on
8970 * @see evas_key_lock_off
8972 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;
8976 * Adds the @p keyname key to the current list of modifier keys.
8978 * @param e The pointer to the Evas canvas
8979 * @param keyname The name of the modifier key to add to the list of
8982 * Modifiers are keys like shift, alt and ctrl, i.e., keys which are
8983 * meant to be pressed together with others, altering the behavior of
8984 * the secondly pressed keys somehow. Evas is so that these keys can
8987 * This call allows custom modifiers to be added to the Evas system at
8988 * run time. It is then possible to set and unset modifier keys
8989 * programmatically for other parts of the program to check and act
8990 * on. Programmers using Evas would check for modifier keys on key
8991 * event callbacks using evas_key_modifier_is_set().
8993 * @see evas_key_modifier_del
8994 * @see evas_key_modifier_get
8995 * @see evas_key_modifier_on
8996 * @see evas_key_modifier_off
8997 * @see evas_key_modifier_is_set
8999 * @note If the programmer instantiates the canvas by means of the
9000 * ecore_evas_new() family of helper functions, Ecore will take
9001 * care of registering on it all standard modifiers: "Shift",
9002 * "Control", "Alt", "Meta", "Hyper", "Super".
9004 EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9007 * Removes the @p keyname key from the current list of modifier keys
9010 * @param e The pointer to the Evas canvas
9011 * @param keyname The name of the key to remove from the modifiers list.
9013 * @see evas_key_modifier_add
9014 * @see evas_key_modifier_get
9015 * @see evas_key_modifier_on
9016 * @see evas_key_modifier_off
9017 * @see evas_key_modifier_is_set
9019 EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9022 * Adds the @p keyname key to the current list of lock keys.
9024 * @param e The pointer to the Evas canvas
9025 * @param keyname The name of the key to add to the locks list.
9027 * Locks are keys like caps lock, num lock or scroll lock, i.e., keys
9028 * which are meant to be pressed once -- toggling a binary state which
9029 * is bound to it -- and thus altering the behavior of all
9030 * subsequently pressed keys somehow, depending on its state. Evas is
9031 * so that these keys can be defined by the user.
9033 * This allows custom locks to be added to the evas system at run
9034 * time. It is then possible to set and unset lock keys
9035 * programmatically for other parts of the program to check and act
9036 * on. Programmers using Evas would check for lock keys on key event
9037 * callbacks using evas_key_lock_is_set().
9039 * @see evas_key_lock_get
9040 * @see evas_key_lock_del
9041 * @see evas_key_lock_on
9042 * @see evas_key_lock_off
9043 * @see evas_key_lock_is_set
9045 * @note If the programmer instantiates the canvas by means of the
9046 * ecore_evas_new() family of helper functions, Ecore will take
9047 * care of registering on it all standard lock keys: "Caps_Lock",
9048 * "Num_Lock", "Scroll_Lock".
9050 EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9053 * Removes the @p keyname key from the current list of lock keys on
9056 * @param e The pointer to the Evas canvas
9057 * @param keyname The name of the key to remove from the locks list.
9059 * @see evas_key_lock_get
9060 * @see evas_key_lock_add
9061 * @see evas_key_lock_on
9062 * @see evas_key_lock_off
9064 EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9068 * Enables or turns on programmatically the modifier key with name @p
9071 * @param e The pointer to the Evas canvas
9072 * @param keyname The name of the modifier to enable.
9074 * The effect will be as if the key was pressed for the whole time
9075 * between this call and a matching evas_key_modifier_off().
9077 * @see evas_key_modifier_add
9078 * @see evas_key_modifier_get
9079 * @see evas_key_modifier_off
9080 * @see evas_key_modifier_is_set
9082 EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9085 * Disables or turns off programmatically the modifier key with name
9088 * @param e The pointer to the Evas canvas
9089 * @param keyname The name of the modifier to disable.
9091 * @see evas_key_modifier_add
9092 * @see evas_key_modifier_get
9093 * @see evas_key_modifier_on
9094 * @see evas_key_modifier_is_set
9096 EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9099 * Enables or turns on programmatically the lock key with name @p
9102 * @param e The pointer to the Evas canvas
9103 * @param keyname The name of the lock to enable.
9105 * The effect will be as if the key was put on its active state after
9108 * @see evas_key_lock_get
9109 * @see evas_key_lock_add
9110 * @see evas_key_lock_del
9111 * @see evas_key_lock_off
9113 EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9116 * Disables or turns off programmatically the lock key with name @p
9119 * @param e The pointer to the Evas canvas
9120 * @param keyname The name of the lock to disable.
9122 * The effect will be as if the key was put on its inactive state
9125 * @see evas_key_lock_get
9126 * @see evas_key_lock_add
9127 * @see evas_key_lock_del
9128 * @see evas_key_lock_on
9130 EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
9134 * Creates a bit mask from the @p keyname @b modifier key. Values
9135 * returned from different calls to it may be ORed together,
9138 * @param e The canvas whom to query the bit mask from.
9139 * @param keyname The name of the modifier key to create the mask for.
9141 * @returns the bit mask or 0 if the @p keyname key wasn't registered as a
9142 * modifier for canvas @p e.
9144 * This function is meant to be using in conjunction with
9145 * evas_object_key_grab()/evas_object_key_ungrab(). Go check their
9146 * documentation for more information.
9148 * @see evas_key_modifier_add
9149 * @see evas_key_modifier_get
9150 * @see evas_key_modifier_on
9151 * @see evas_key_modifier_off
9152 * @see evas_key_modifier_is_set
9153 * @see evas_object_key_grab
9154 * @see evas_object_key_ungrab
9156 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;
9160 * Requests @p keyname key events be directed to @p obj.
9162 * Key grabs allow an object to receive key events for specific key
9163 * strokes even if another object has focus. If the grab is
9164 * non-exclusive then all objects that have grabs on the key will get
9165 * the event, however if the grab is exclusive, no other object can
9166 * get a grab on the key and only that object will get the event.
9168 * @p keyname is a platform dependent symbolic name for the key
9169 * pressed. It is sometimes possible to convert the string to an
9170 * ASCII value of the key, but not always for example the enter key
9171 * may be returned as the string 'Enter'.
9173 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
9174 * (Ecore_X) when using Evas with Ecore and Ecore_Evas.
9176 * For a list of keynames for the Linux frame buffer, please refer to
9177 * the Ecore_FB documentation.
9179 * @p modifiers and @p not_modifiers are bit masks of all the
9180 * modifiers that are required and not required respectively for the
9181 * new grab. Modifiers can be things such as shift and ctrl as well
9182 * as user defigned types via evas_key_modifier_add.
9184 * @see evas_object_key_ungrab
9185 * @see evas_object_focus_set
9186 * @see evas_object_focus_get
9187 * @see evas_focus_get
9188 * @see evas_key_modifier_add
9190 * @param obj the object to direct @p keyname events to.
9191 * @param keyname the key to request events for.
9192 * @param modifiers a mask of modifiers that should be present to
9193 * trigger the event.
9194 * @param not_modifiers a mask of modifiers that should not be present
9195 * to trigger the event.
9196 * @param exclusive request that the @p obj is the only object
9197 * receiving the @p keyname events.
9198 * @return Boolean indicating whether the grab succeeded
9200 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);
9203 * Request that the grab on @p obj be removed.
9205 * Removes the grab on @p obj if @p keyname, @p modifiers, and @p not_modifiers
9208 * @see evas_object_key_grab
9209 * @see evas_object_focus_set
9210 * @see evas_object_focus_get
9211 * @see evas_focus_get
9213 * @param obj the object that has an existing grab.
9214 * @param keyname the key the grab is for.
9215 * @param modifiers a mask of modifiers that should be present to
9216 * trigger the event.
9217 * @param not_modifiers a mask of modifiers that should not be present
9218 * to trigger the event.
9220 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);