summaryrefslogtreecommitdiff
path: root/src/lib/evas/Evas_Common.h
diff options
context:
space:
mode:
authorDaniel Zaoui <daniel.zaoui@samsung.com>2013-04-28 14:22:02 +0300
committerDaniel Zaoui <daniel.zaoui@samsung.com>2013-04-28 14:22:21 +0300
commit57461dc6a1189285e9b1d662173a71215df5730c (patch)
treeb6644faa222efc5a08263384708b85b81b8f9207 /src/lib/evas/Evas_Common.h
parent994318eebe032447f9457a77fe446b5978480cd7 (diff)
Evas: rename Evas_Common.h to Evas_Common_Header.h
This change is due to EFL compilation failing in Windows. This file was conflicting with evas_common.h. Case sensitive issue...
Diffstat (limited to 'src/lib/evas/Evas_Common.h')
-rw-r--r--src/lib/evas/Evas_Common.h5263
1 files changed, 0 insertions, 5263 deletions
diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h
deleted file mode 100644
index e5d1c37107..0000000000
--- a/src/lib/evas/Evas_Common.h
+++ /dev/null
@@ -1,5263 +0,0 @@
1
2#define EVAS_VERSION_MAJOR 1
3#define EVAS_VERSION_MINOR 8
4
5typedef struct _Evas_Version
6{
7 int major;
8 int minor;
9 int micro;
10 int revision;
11} Evas_Version;
12
13EAPI extern Evas_Version * evas_version;
14
15/**
16 * @file
17 * @brief These routines are used for Evas library interaction.
18 *
19 * @todo check boolean return values and convert to Eina_Bool
20 * @todo change all api to use EINA_SAFETY_*
21 * @todo finish api documentation
22 */
23
24/* BiDi exposed stuff */
25/*FIXME: document */
26typedef enum _Evas_BiDi_Direction
27{
28 EVAS_BIDI_DIRECTION_NATURAL,
29 EVAS_BIDI_DIRECTION_NEUTRAL = EVAS_BIDI_DIRECTION_NATURAL,
30 EVAS_BIDI_DIRECTION_LTR,
31 EVAS_BIDI_DIRECTION_RTL
32} Evas_BiDi_Direction;
33
34/**
35 * Identifier of callbacks to be set for Evas canvases or Evas
36 * objects.
37 *
38 * The following figure illustrates some Evas callbacks:
39 *
40 * @image html evas-callbacks.png
41 * @image rtf evas-callbacks.png
42 * @image latex evas-callbacks.eps
43 *
44 * @see evas_object_event_callback_add()
45 * @see evas_event_callback_add()
46 */
47typedef enum _Evas_Callback_Type
48{
49 /*
50 * The following events are only for use with Evas objects, with
51 * evas_object_event_callback_add():
52 */
53 EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */
54 EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
55 EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
56 EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
57 EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
58 EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
59 EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
60 EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
61 EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
62 EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
63 EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
64 EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
65 EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
66 EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
67 EVAS_CALLBACK_SHOW, /**< Show Event */
68 EVAS_CALLBACK_HIDE, /**< Hide Event */
69 EVAS_CALLBACK_MOVE, /**< Move Event */
70 EVAS_CALLBACK_RESIZE, /**< Resize Event */
71 EVAS_CALLBACK_RESTACK, /**< Restack Event */
72 EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
73 EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
74 EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
75 EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */
76
77 /*
78 * The following events are only for use with Evas canvases, with
79 * evas_event_callback_add():
80 */
81 EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
82 EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
83 EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */
84 EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
85 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
86 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
87
88 /*
89 * More Evas object event types - see evas_object_event_callback_add():
90 */
91 EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanism in Evas that throw out original image data) */
92
93 EVAS_CALLBACK_RENDER_PRE, /**< Called just before rendering starts on the canvas target @since 1.2 */
94 EVAS_CALLBACK_RENDER_POST, /**< Called just after rendering stops on the canvas target @since 1.2 */
95
96 EVAS_CALLBACK_IMAGE_RESIZE, /**< Image size is changed @since 1.8 */
97 EVAS_CALLBACK_DEVICE_CHANGED, /**< Devices added, removed or changed on canvas @since 1.8 */
98 EVAS_CALLBACK_LAST /**< kept as last element/sentinel -- not really an event */
99} Evas_Callback_Type; /**< The types of events triggering a callback */
100
101/**
102 * @def EVAS_CALLBACK_PRIORITY_BEFORE
103 * Slightly more prioritized than default.
104 * @since 1.1
105 */
106#define EVAS_CALLBACK_PRIORITY_BEFORE -100
107/**
108 * @def EVAS_CALLBACK_PRIORITY_DEFAULT
109 * Default callback priority level
110 * @since 1.1
111 */
112#define EVAS_CALLBACK_PRIORITY_DEFAULT 0
113/**
114 * @def EVAS_CALLBACK_PRIORITY_AFTER
115 * Slightly less prioritized than default.
116 * @since 1.1
117 */
118#define EVAS_CALLBACK_PRIORITY_AFTER 100
119
120/**
121 * @typedef Evas_Callback_Priority
122 *
123 * Callback priority value. Range is -32k - 32k. The lower the number, the
124 * bigger the priority.
125 *
126 * @see EVAS_CALLBACK_PRIORITY_AFTER
127 * @see EVAS_CALLBACK_PRIORITY_BEFORE
128 * @see EVAS_CALLBACK_PRIORITY_DEFAULT
129 *
130 * @since 1.1
131 */
132typedef Eo_Callback_Priority Evas_Callback_Priority;
133
134/**
135 * Flags for Mouse Button events
136 */
137typedef enum _Evas_Button_Flags
138{
139 EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
140 EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< This mouse button press was the 2nd press of a double click */
141 EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< This mouse button press was the 3rd press of a triple click */
142} Evas_Button_Flags; /**< Flags for Mouse Button events */
143
144/**
145 * Flags for Events
146 */
147typedef enum _Evas_Event_Flags
148{
149 EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
150 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 */
151 EVAS_EVENT_FLAG_ON_SCROLL = (1 << 1) /**< This event flag indicates the event occurs while scrolling; for example, DOWN event occurs during scrolling; the event should be used for informational purposes and maybe some indications visually, but not actually perform anything */
152} Evas_Event_Flags; /**< Flags for Events */
153
154/**
155 * State of Evas_Coord_Touch_Point
156 */
157typedef enum _Evas_Touch_Point_State
158{
159 EVAS_TOUCH_POINT_DOWN, /**< Touch point is pressed down */
160 EVAS_TOUCH_POINT_UP, /**< Touch point is released */
161 EVAS_TOUCH_POINT_MOVE, /**< Touch point is moved */
162 EVAS_TOUCH_POINT_STILL, /**< Touch point is not moved after pressed */
163 EVAS_TOUCH_POINT_CANCEL /**< Touch point is cancelled */
164} Evas_Touch_Point_State;
165
166/**
167 * Flags for Font Hinting
168 * @ingroup Evas_Font_Group
169 */
170typedef enum _Evas_Font_Hinting_Flags
171{
172 EVAS_FONT_HINTING_NONE, /**< No font hinting */
173 EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
174 EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
175} Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */
176
177/**
178 * Colorspaces for pixel data supported by Evas
179 * @ingroup Evas_Object_Image
180 */
181typedef enum _Evas_Colorspace
182{
183 EVAS_COLORSPACE_ARGB8888, /**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */
184 /* these are not currently supported - but planned for the future */
185 EVAS_COLORSPACE_YCBCR422P601_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */
186 EVAS_COLORSPACE_YCBCR422P709_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-709 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */
187 EVAS_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */
188 EVAS_COLORSPACE_GRY8, /**< 8bit grayscale */
189 EVAS_COLORSPACE_YCBCR422601_PL, /**< YCbCr 4:2:2, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to line of Y,Cb,Y,Cr bytes */
190 EVAS_COLORSPACE_YCBCR420NV12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb,Cr rows. */
191 EVAS_COLORSPACE_YCBCR420TM12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of tiled row pointer, pointing to the Y rows, then the Cb,Cr rows. */
192} Evas_Colorspace; /**< Colorspaces for pixel data supported by Evas */
193
194/**
195 * How to pack items into cells in a table.
196 * @ingroup Evas_Object_Table
197 *
198 * @see evas_object_table_homogeneous_set() for an explanation of the function of
199 * each one.
200 */
201typedef enum _Evas_Object_Table_Homogeneous_Mode
202{
203 EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0,
204 EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1,
205 EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2
206} Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode. */
207
208typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< A generic rectangle handle */
209typedef struct _Evas_Point Evas_Point; /**< integer point */
210
211typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */
212typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */
213
214typedef struct _Evas_Coord_Size Evas_Coord_Size; /** <Evas_Coord size @since 1.8 */
215typedef struct _Evas_Coord_Precision_Size Evas_Coord_Precision_Size; /** <Evas_Coord size with sub-pixel precision @since 1.8 */
216
217typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */
218typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */
219
220/**
221 * @typedef Evas_Smart_Class
222 *
223 * A smart object's @b base class definition
224 *
225 * @ingroup Evas_Smart_Group
226 */
227typedef struct _Evas_Smart_Class Evas_Smart_Class;
228
229/**
230 * @typedef Evas_Smart_Interface
231 *
232 * A smart object's @b base interface definition
233 *
234 * An Evas interface is exactly like the OO-concept: an 'contract' or
235 * API a given object is declared to support. A smart object may have
236 * more than one interface, thus extending the behavior it gets from
237 * sub-classing.
238 *
239 * @since 1.7
240 *
241 * @ingroup Evas_Smart_Group
242 */
243typedef struct _Evas_Smart_Interface Evas_Smart_Interface;
244
245/**
246 * @typedef Evas_Smart_Cb_Description
247 *
248 * A smart object callback description, used to provide introspection
249 *
250 * @ingroup Evas_Smart_Group
251 */
252typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
253
254/**
255 * @typedef Evas_Map
256 *
257 * An opaque handle to map points
258 *
259 * @see evas_map_new()
260 * @see evas_map_free()
261 * @see evas_map_dup()
262 *
263 * @ingroup Evas_Object_Group_Map
264 */
265typedef struct _Evas_Map Evas_Map;
266
267/**
268 * @typedef Evas
269 *
270 * An opaque handle to an Evas canvas.
271 *
272 * @see evas_new()
273 * @see evas_free()
274 *
275 * @ingroup Evas_Canvas
276 */
277typedef Eo Evas;
278
279/**
280 * @typedef Evas_Public_Data
281 * Public data for an Evas.
282 * @ingroup Evas_Canvas
283 */
284typedef struct _Evas_Public_Data Evas_Public_Data;
285
286/**
287 * @typedef Evas_Object
288 * An Evas Object handle.
289 * @ingroup Evas_Object_Group
290 */
291typedef Eo Evas_Object;
292
293typedef void Evas_Performance; /**< An Evas Performance handle */
294typedef struct _Evas_Modifier Evas_Modifier; /**< An opaque type containing information on which modifier keys are registered in an Evas canvas */
295typedef struct _Evas_Lock Evas_Lock; /**< An opaque type containing information on which lock keys are registered in an Evas canvas */
296typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
297typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< A generic datatype for engine specific native surface information */
298
299/**
300 * @typedef Evas_Video_Surface
301 *
302 * A generic datatype for video specific surface information
303 * @see evas_object_image_video_surface_set
304 * @see evas_object_image_video_surface_get
305 * @since 1.1
306 */
307typedef struct _Evas_Video_Surface Evas_Video_Surface;
308
309typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */
310
311typedef int Evas_Coord;
312typedef int Evas_Font_Size;
313typedef int Evas_Angle;
314
315struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */
316{
317 Evas_Coord x; /**< top-left x co-ordinate of rectangle */
318 Evas_Coord y; /**< top-left y co-ordinate of rectangle */
319 Evas_Coord w; /**< width of rectangle */
320 Evas_Coord h; /**< height of rectangle */
321};
322
323struct _Evas_Coord_Point
324{
325 Evas_Coord x; /**< x co-ordinate */
326 Evas_Coord y; /**< y co-ordinate */
327};
328
329struct _Evas_Coord_Size
330{
331 Evas_Coord w; /**< width */
332 Evas_Coord h; /**< height */
333};
334
335struct _Evas_Coord_Precision_Size
336{
337 Evas_Coord w; /** < width */
338 Evas_Coord h; /** < height */
339 double wsub; /** < subpixel precision for width */
340 double ysub; /** < subpixel precision for height */
341};
342
343struct _Evas_Coord_Precision_Point
344{
345 Evas_Coord x, y;
346 double xsub, ysub;
347};
348
349struct _Evas_Point
350{
351 int x, y;
352};
353
354struct _Evas_Position
355{
356 Evas_Point output;
357 Evas_Coord_Point canvas; /**< position on the canvas */
358};
359
360struct _Evas_Precision_Position
361{
362 Evas_Point output;
363 Evas_Coord_Precision_Point canvas;
364};
365
366typedef enum _Evas_Aspect_Control
367{
368 EVAS_ASPECT_CONTROL_NONE = 0, /**< Preference on scaling unset */
369 EVAS_ASPECT_CONTROL_NEITHER = 1, /**< Same effect as unset preference on scaling */
370 EVAS_ASPECT_CONTROL_HORIZONTAL = 2, /**< Use all horizontal container space to place an object, using the given aspect */
371 EVAS_ASPECT_CONTROL_VERTICAL = 3, /**< Use all vertical container space to place an object, using the given aspect */
372 EVAS_ASPECT_CONTROL_BOTH = 4 /**< Use all horizontal @b and vertical container spaces to place an object (never growing it out of those bounds), using the given aspect */
373} Evas_Aspect_Control; /**< Aspect types/policies for scaling size hints, used for evas_object_size_hint_aspect_set() */
374
375typedef enum _Evas_Display_Mode
376{
377 EVAS_DISPLAY_MODE_NONE = 0, /**<Default mode */
378 EVAS_DISPLAY_MODE_INHERIT = 1, /**< Use this mode when object's display mode depend on ancestor's */
379 EVAS_DISPLAY_MODE_COMPRESS = 2, /**< Use this mode want to give comppress display mode hint to object */
380 EVAS_DISPLAY_MODE_EXPAND = 3, /**< Use this mode want to give expand display mode hint to object */
381 EVAS_DISPLAY_MODE_DONT_CHANGE = 4 /**< Use this mode when object should not change display mode */
382} Evas_Display_Mode; /**< object's display mode type related with compress/expand or etc mode */
383
384typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< A source description of pixels for importing pixels */
385typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< A generic Evas Engine information structure */
386typedef struct _Evas_Device Evas_Device; /**< A source device handle - where the event came from */
387typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
388typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
389typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
390typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
391typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
392typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
393typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
394typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
395typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
396typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
397typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
398typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< Event structure for #EVAS_CALLBACK_HOLD event callbacks */
399typedef struct _Evas_Event_Render_Post Evas_Event_Render_Post; /**< Event structure that may come with #EVAS_CALLBACK_RENDER_POST event callbacks @since 1.8 */
400
401typedef enum _Evas_Load_Error
402{
403 EVAS_LOAD_ERROR_NONE = 0, /**< No error on load */
404 EVAS_LOAD_ERROR_GENERIC = 1, /**< A non-specific error occurred */
405 EVAS_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< File (or file path) does not exist */
406 EVAS_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission denied to an existing file (or path) */
407 EVAS_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Allocation of resources failure prevented load */
408 EVAS_LOAD_ERROR_CORRUPT_FILE = 5, /**< File corrupt (but was detected as a known format) */
409 EVAS_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */
410} Evas_Load_Error; /**< Evas image load error codes one can get - see evas_load_error_str() too. */
411
412typedef enum _Evas_Alloc_Error
413{
414 EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */
415 EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */
416 EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded, but extra memory had to be found by freeing up speculative resources */
417} Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */
418
419typedef enum _Evas_Fill_Spread
420{
421 EVAS_TEXTURE_REFLECT = 0, /**< image fill tiling mode - tiling reflects */
422 EVAS_TEXTURE_REPEAT = 1, /**< tiling repeats */
423 EVAS_TEXTURE_RESTRICT = 2, /**< tiling clamps - range offset ignored */
424 EVAS_TEXTURE_RESTRICT_REFLECT = 3, /**< tiling clamps and any range offset reflects */
425 EVAS_TEXTURE_RESTRICT_REPEAT = 4, /**< tiling clamps and any range offset repeats */
426 EVAS_TEXTURE_PAD = 5 /**< tiling extends with end values */
427} Evas_Fill_Spread; /**< Fill types used for evas_object_image_fill_spread_set() */
428
429typedef enum _Evas_Pixel_Import_Pixel_Format
430{
431 EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
432 EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
433 EVAS_PIXEL_FORMAT_YUV420P_601 = 2 /**< YUV 420 Planar format with CCIR 601 color encoding with contiguous planes in the order Y, U and V */
434} Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
435
436struct _Evas_Pixel_Import_Source
437{
438 Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
439 int w, h; /**< width and height of source in pixels */
440 void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
441};
442
443/* magic version number to know what the native surf struct looks like */
444#define EVAS_NATIVE_SURFACE_VERSION 2
445
446typedef enum _Evas_Native_Surface_Type
447{
448 EVAS_NATIVE_SURFACE_NONE,
449 EVAS_NATIVE_SURFACE_X11,
450 EVAS_NATIVE_SURFACE_OPENGL
451} Evas_Native_Surface_Type;
452
453struct _Evas_Native_Surface
454{
455 int version;
456 Evas_Native_Surface_Type type;
457 union {
458 struct
459 {
460 void *visual; /**< visual of the pixmap to use (Visual) */
461 unsigned long pixmap; /**< pixmap id to use (Pixmap) */
462 } x11;
463 struct
464 {
465 unsigned int texture_id; /**< opengl texture id to use from glGenTextures() */
466 unsigned int framebuffer_id; /**< 0 if not a FBO, FBO id otherwise from glGenFramebuffers() */
467 unsigned int internal_format; /**< same as 'internalFormat' for glTexImage2D() */
468 unsigned int format; /**< same as 'format' for glTexImage2D() */
469 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) */
470 } opengl;
471 } data;
472};
473
474/**
475 * @def EVAS_VIDEO_SURFACE_VERSION
476 * Magic version number to know what the video surf struct looks like
477 * @since 1.1
478 */
479#define EVAS_VIDEO_SURFACE_VERSION 1
480
481typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface);
482typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b);
483
484struct _Evas_Video_Surface
485{
486 int version;
487
488 Evas_Video_Coord_Cb move; /**< Move the video surface to this position */
489 Evas_Video_Coord_Cb resize; /**< Resize the video surface to that size */
490 Evas_Video_Cb show; /**< Show the video overlay surface */
491 Evas_Video_Cb hide; /**< Hide the video overlay surface */
492 Evas_Video_Cb update_pixels; /**< Please update the Evas_Object_Image pixels when called */
493
494 Evas_Object *parent;
495 void *data;
496};
497
498#define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
499#define EVAS_LAYER_MAX 32767 /**< top-most layer number */
500
501#define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
502#define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
503#define EVAS_TEXT_INVALID -1 /**< Not used for anything */
504#define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
505
506#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() */
507#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() */
508#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) */
509#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) */
510#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 */
511#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 */
512
513/**
514 * How the object should be rendered to output.
515 * @ingroup Evas_Object_Group_Extras
516 */
517typedef enum _Evas_Render_Op
518{
519 EVAS_RENDER_BLEND = 0, /**< default op: d = d*(1-sa) + s */
520 EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
521 EVAS_RENDER_COPY = 2, /**< d = s */
522 EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
523 EVAS_RENDER_ADD = 4, /* d = d + s */
524 EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
525 EVAS_RENDER_SUB = 6, /**< d = d - s */
526 EVAS_RENDER_SUB_REL = 7, /* d = d - s*da */
527 EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
528 EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
529 EVAS_RENDER_MASK = 10, /**< d = d*sa */
530 EVAS_RENDER_MUL = 11 /**< d = d*s */
531} Evas_Render_Op; /**< How the object should be rendered to output. */
532
533typedef enum _Evas_Border_Fill_Mode
534{
535 EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */
536 EVAS_BORDER_FILL_DEFAULT = 1, /**< Image's center region is to be @b blended with objects underneath it, if it has transparency. This is the default behavior for image objects */
537 EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */
538} Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */
539
540typedef enum _Evas_Image_Scale_Hint
541{
542 EVAS_IMAGE_SCALE_HINT_NONE = 0, /**< No scale hint at all */
543 EVAS_IMAGE_SCALE_HINT_DYNAMIC = 1, /**< Image is being re-scaled over time, thus turning scaling cache @b off for its data */
544 EVAS_IMAGE_SCALE_HINT_STATIC = 2 /**< Image is not being re-scaled over time, thus turning scaling cache @b on for its data */
545} Evas_Image_Scale_Hint; /**< How an image's data is to be treated by Evas, with regard to scaling cache */
546
547typedef enum _Evas_Image_Animated_Loop_Hint
548{
549 EVAS_IMAGE_ANIMATED_HINT_NONE = 0,
550 EVAS_IMAGE_ANIMATED_HINT_LOOP = 1, /**< Image's animation mode is loop like 1->2->3->1->2->3 */
551 EVAS_IMAGE_ANIMATED_HINT_PINGPONG = 2 /**< Image's animation mode is pingpong like 1->2->3->2->1-> ... */
552} Evas_Image_Animated_Loop_Hint;
553
554typedef enum _Evas_Engine_Render_Mode
555{
556 EVAS_RENDER_MODE_BLOCKING = 0,
557 EVAS_RENDER_MODE_NONBLOCKING = 1,
558} Evas_Engine_Render_Mode;
559
560typedef enum _Evas_Image_Content_Hint
561{
562 EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
563 EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents will change over time */
564 EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents won't change over time */
565} Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
566
567typedef enum _Evas_Device_Class
568{
569 EVAS_DEVICE_CLASS_NONE, /**< Not a device @since 1.8 */
570 EVAS_DEVICE_CLASS_SEAT, /**< The user/seat (the user themselves) @since 1.8 */
571 EVAS_DEVICE_CLASS_KEYBOARD, /**< A regular keyboard, numberpad or attached buttons @since 1.8 */
572 EVAS_DEVICE_CLASS_MOUSE, /**< A mouse, trackball or touchpad relative motion device @since 1.8 */
573 EVAS_DEVICE_CLASS_TOUCH, /**< A touchscreen with fingers or stylus @since 1.8 */
574 EVAS_DEVICE_CLASS_PEN, /**< A special pen device @since 1.8 */
575 EVAS_DEVICE_CLASS_POINTER, /**< A laser pointer, wii-style or "minority report" pointing device @since 1.8 */
576 EVAS_DEVICE_CLASS_GAMEPAD /**< A gamepad controller or joystick @since 1.8 */
577} Evas_Device_Class; /**< A general class of device @since 1.8 */
578
579typedef enum _Evas_Device_Subclass
580{
581 EVAS_DEVICE_SUBCLASS_NONE, /**< Not a device @since 1.8 */
582 EVAS_DEVICE_SUBCLASS_FINGER, /**< The normal flat of your finger @since 1.8 */
583 EVAS_DEVICE_SUBCLASS_FINGERNAIL, /**< A fingernail @since 1.8 */
584 EVAS_DEVICE_SUBCLASS_KNUCKLE, /**< A Knuckle @since 1.8 */
585 EVAS_DEVICE_SUBCLASS_PALM, /**< The palm of a users hand @since 1.8 */
586 EVAS_DEVICE_SUBCLASS_HAND_SIZE, /**< The side of your hand @since 1.8 */
587 EVAS_DEVICE_SUBCLASS_HAND_FLAT, /**< The flat of your hand @since 1.8 */
588 EVAS_DEVICE_SUBCLASS_PEN_TIP, /**< The tip of a pen @since 1.8 */
589 EVAS_DEVICE_SUBCLASS_TRACKPAD, /**< A trackpad style mouse @since 1.8 */
590 EVAS_DEVICE_SUBCLASS_TRACKPOINT, /**< A trackpoint style mouse @since 1.8 */
591 EVAS_DEVICE_SUBCLASS_TRACKBALL, /**< A trackball style mouse @since 1.8 */
592} Evas_Device_Subclass; /**< A general class of device @since 1.8 */
593
594struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
595{
596 int magic; /**< Magic number */
597};
598
599struct _Evas_Event_Mouse_Down /** Mouse button press event */
600{
601 int button; /**< Mouse button number that went down (1 - 32) */
602
603 Evas_Point output; /**< The X/Y location of the cursor */
604 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
605
606 void *data;
607 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
608 Evas_Lock *locks;
609
610 Evas_Button_Flags flags; /**< button flags set during the event */
611 unsigned int timestamp;
612 Evas_Event_Flags event_flags;
613 Evas_Device *dev;
614 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
615};
616
617struct _Evas_Event_Mouse_Up /** Mouse button release event */
618{
619 int button; /**< Mouse button number that was raised (1 - 32) */
620
621 Evas_Point output; /**< The X/Y location of the cursor */
622 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
623
624 void *data;
625 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
626 Evas_Lock *locks;
627
628 Evas_Button_Flags flags; /**< button flags set during the event */
629 unsigned int timestamp;
630 Evas_Event_Flags event_flags;
631 Evas_Device *dev;
632 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
633};
634
635struct _Evas_Event_Mouse_In /** Mouse enter event */
636{
637 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
638
639 Evas_Point output; /**< The X/Y location of the cursor */
640 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
641
642 void *data;
643 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
644 Evas_Lock *locks;
645 unsigned int timestamp;
646 Evas_Event_Flags event_flags;
647 Evas_Device *dev;
648 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
649};
650
651struct _Evas_Event_Mouse_Out /** Mouse leave event */
652{
653 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
654
655 Evas_Point output; /**< The X/Y location of the cursor */
656 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
657
658 void *data;
659 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
660 Evas_Lock *locks;
661 unsigned int timestamp;
662 Evas_Event_Flags event_flags;
663 Evas_Device *dev;
664 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
665};
666
667struct _Evas_Event_Mouse_Move /** Mouse move event */
668{
669 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
670
671 Evas_Position cur; /**< Current mouse position */
672 Evas_Position prev; /**< Previous mouse position */
673
674 void *data;
675 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
676 Evas_Lock *locks;
677 unsigned int timestamp;
678 Evas_Event_Flags event_flags;
679 Evas_Device *dev;
680 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
681};
682
683struct _Evas_Event_Mouse_Wheel /** Wheel event */
684{
685 int direction; /* 0 = default up/down wheel FIXME: more wheel types */
686 int z; /* ...,-2,-1 = down, 1,2,... = up */
687
688 Evas_Point output; /**< The X/Y location of the cursor */
689 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
690
691 void *data;
692 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
693 Evas_Lock *locks;
694 unsigned int timestamp;
695 Evas_Event_Flags event_flags;
696 Evas_Device *dev;
697};
698
699struct _Evas_Event_Multi_Down /** Multi button press event */
700{
701 int device; /**< Multi device number that went down (1 or more for extra touches) */
702 double radius, radius_x, radius_y;
703 double pressure, angle;
704
705 Evas_Point output;
706 Evas_Coord_Precision_Point canvas;
707
708 void *data;
709 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
710 Evas_Lock *locks;
711
712 Evas_Button_Flags flags; /**< button flags set during the event */
713 unsigned int timestamp;
714 Evas_Event_Flags event_flags;
715 Evas_Device *dev;
716};
717
718struct _Evas_Event_Multi_Up /** Multi button release event */
719{
720 int device; /**< Multi device number that went up (1 or more for extra touches) */
721 double radius, radius_x, radius_y;
722 double pressure, angle;
723
724 Evas_Point output;
725 Evas_Coord_Precision_Point canvas;
726
727 void *data;
728 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
729 Evas_Lock *locks;
730
731 Evas_Button_Flags flags; /**< button flags set during the event */
732 unsigned int timestamp;
733 Evas_Event_Flags event_flags;
734 Evas_Device *dev;
735};
736
737struct _Evas_Event_Multi_Move /** Multi button down event */
738{
739 int device; /**< Multi device number that moved (1 or more for extra touches) */
740 double radius, radius_x, radius_y;
741 double pressure, angle;
742
743 Evas_Precision_Position cur;
744
745 void *data;
746 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
747 Evas_Lock *locks;
748 unsigned int timestamp;
749 Evas_Event_Flags event_flags;
750 Evas_Device *dev;
751};
752
753struct _Evas_Event_Key_Down /** Key press event */
754{
755 char *keyname; /**< the name string of the key pressed */
756 void *data;
757 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
758 Evas_Lock *locks;
759
760 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
761 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
762 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 */
763 unsigned int timestamp;
764 Evas_Event_Flags event_flags;
765 Evas_Device *dev;
766};
767
768struct _Evas_Event_Key_Up /** Key release event */
769{
770 char *keyname; /**< the name string of the key released */
771 void *data;
772 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
773 Evas_Lock *locks;
774
775 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
776 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
777 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 */
778 unsigned int timestamp;
779 Evas_Event_Flags event_flags;
780 Evas_Device *dev;
781};
782
783struct _Evas_Event_Render_Post /** Send when the frame rendering is done @since 1.8 */
784{
785 Eina_List *updated_area; /**< A list of rectangle that were updated in the canvas */
786};
787
788struct _Evas_Event_Hold /** Hold change event */
789{
790 int hold; /**< The hold flag */
791 void *data;
792
793 unsigned int timestamp;
794 Evas_Event_Flags event_flags;
795 Evas_Device *dev;
796};
797
798/**
799 * How the mouse pointer should be handled by Evas.
800 *
801 * In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button
802 * is pressed down over an object and held, with the mouse pointer
803 * being moved outside of it, the pointer still behaves as being bound
804 * to that object, albeit out of its drawing region. When the button
805 * is released, the event will be fed to the object, that may check if
806 * the final position is over it or not and do something about it.
807 *
808 * In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will
809 * always be bound to the object right below it.
810 *
811 * @ingroup Evas_Object_Group_Extras
812 */
813typedef enum _Evas_Object_Pointer_Mode
814{
815 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
816 EVAS_OBJECT_POINTER_MODE_NOGRAB, /**< pointer always bound to the object right below it */
817 EVAS_OBJECT_POINTER_MODE_NOGRAB_NO_REPEAT_UPDOWN /**< useful on object with "repeat events" enabled, where mouse/touch up and down events WONT be repeated to objects and these objects wont be auto-grabbed. @since 1.2 */
818} Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
819
820typedef void (*Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info); /**< Evas smart objects' "smart callback" function signature */
821typedef void (*Evas_Event_Cb)(void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
822typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e);
823typedef void (*Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info); /**< Evas object event callback function signature */
824typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
825
826/**
827 * @defgroup Evas_Main_Group Top Level Functions
828 * @ingroup Evas
829 *
830 * Functions that affect Evas as a whole.
831 */
832
833/**
834 * Get the path for the cserve binary to execute
835 *
836 * There is little need for anyone except a desktop nevironment to call this.
837 * This can be called before evas_init() has been called. It will try and find
838 * the full path to the to the cserve binary to run to provide cserve image
839 * and font caching services for evas.
840 *
841 * @return NULL if error, or a string with the full path to the cserve binary.
842 *
843 * @since 1.8
844 */
845EAPI const char *evas_cserve_path_get(void);
846
847/**
848 * Initialize Evas
849 *
850 * @return The init counter value.
851 *
852 * This function initializes Evas and increments a counter of the
853 * number of calls to it. It returns the new counter's value.
854 *
855 * @see evas_shutdown().
856 *
857 * Most EFL users wouldn't be using this function directly, because
858 * they wouldn't access Evas directly by themselves. Instead, they
859 * would be using higher level helpers, like @c ecore_evas_init().
860 * See @ref Ecore.
861 *
862 * You should be using this if your use is something like the
863 * following. The buffer engine is just one of the many ones Evas
864 * provides.
865 *
866 * @dontinclude evas-buffer-simple.c
867 * @skip int main
868 * @until return -1;
869 * And being the canvas creation something like:
870 * @skip static Evas *create_canvas
871 * @until evas_output_viewport_set(canvas,
872 *
873 * Note that this is code creating an Evas canvas with no usage of
874 * Ecore helpers at all -- no linkage with Ecore on this scenario,
875 * thus. Again, this wouldn't be on Evas common usage for most
876 * developers. See the full @ref Example_Evas_Buffer_Simple "example".
877 *
878 * @ingroup Evas_Main_Group
879 */
880EAPI int evas_init(void);
881
882/**
883 * Shutdown Evas
884 *
885 * @return Evas' init counter value.
886 *
887 * This function finalizes Evas, decrementing the counter of the
888 * number of calls to the function evas_init(). This new value for the
889 * counter is returned.
890 *
891 * @see evas_init().
892 *
893 * If you were the sole user of Evas, by means of evas_init(), you can
894 * check if it's being properly shut down by expecting a return value
895 * of 0.
896 *
897 * Example code follows.
898 * @dontinclude evas-buffer-simple.c
899 * @skip // NOTE: use ecore_evas_buffer_new
900 * @until evas_shutdown
901 * Where that function would contain:
902 * @skip evas_free(canvas)
903 * @until evas_free(canvas)
904 *
905 * Most users would be using ecore_evas_shutdown() instead, like told
906 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
907 * "example".
908 *
909 * @ingroup Evas_Main_Group
910 */
911EAPI int evas_shutdown(void);
912
913/**
914 * Return if any allocation errors have occurred during the prior function
915 * @return The allocation error flag
916 *
917 * This function will return if any memory allocation errors occurred during,
918 * and what kind they were. The return value will be one of
919 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
920 * with each meaning something different.
921 *
922 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
923 * worked as expected.
924 *
925 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
926 * its job and will have exited as cleanly as possible. The programmer
927 * should consider this as a sign of very low memory and should try and safely
928 * recover from the prior functions failure (or try free up memory elsewhere
929 * and try again after more memory is freed).
930 *
931 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
932 * recovered from by evas finding memory of its own it has allocated and
933 * freeing what it sees as not really usefully allocated memory. What is freed
934 * may vary. Evas may reduce the resolution of images, free cached images or
935 * fonts, trhow out pre-rendered data, reduce the complexity of change lists
936 * etc. Evas and the program will function as per normal after this, but this
937 * is a sign of low memory, and it is suggested that the program try and
938 * identify memory it doesn't need, and free it.
939 *
940 * Example:
941 * @code
942 * extern Evas_Object *object;
943 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
944 *
945 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
946 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
947 * {
948 * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
949 * fprintf(stderr, " destroy object now as it cannot be used.\n");
950 * evas_object_del(object);
951 * object = NULL;
952 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
953 * my_memory_cleanup();
954 * }
955 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
956 * {
957 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
958 * my_memory_cleanup();
959 * }
960 * @endcode
961 *
962 * @ingroup Evas_Main_Group
963 */
964EAPI Evas_Alloc_Error evas_alloc_error(void);
965
966/**
967 * @brief Get evas' internal asynchronous events read file descriptor.
968 *
969 * @return The canvas' asynchronous events read file descriptor.
970 *
971 * Evas' asynchronous events are meant to be dealt with internally,
972 * i. e., when building stuff to be glued together into the EFL
973 * infrastructure -- a module, for example. The context which demands
974 * its use is when calculations need to be done out of the main
975 * thread, asynchronously, and some action must be performed after
976 * that.
977 *
978 * An example of actual use of this API is for image asynchronous
979 * preload inside evas. If the canvas was instantiated through
980 * ecore-evas usage, ecore itself will take care of calling those
981 * events' processing.
982 *
983 * This function returns the read file descriptor where to get the
984 * asynchronous events of the canvas. Naturally, other mainloops,
985 * apart from ecore, may make use of it.
986 *
987 * @ingroup Evas_Main_Group
988 */
989EAPI int evas_async_events_fd_get(void) EINA_WARN_UNUSED_RESULT;
990
991/**
992 * @brief Trigger the processing of all events waiting on the file
993 * descriptor returned by evas_async_events_fd_get().
994 *
995 * @return The number of events processed.
996 *
997 * All asynchronous events queued up by evas_async_events_put() are
998 * processed here. More precisely, the callback functions, informed
999 * together with other event parameters, when queued, get called (with
1000 * those parameters), in that order.
1001 *
1002 * @ingroup Evas_Main_Group
1003 */
1004EAPI int evas_async_events_process(void);
1005
1006/**
1007 * Insert asynchronous events on the canvas.
1008 *
1009 * @param target The target to be affected by the events.
1010 * @param type The type of callback function.
1011 * @param event_info Information about the event.
1012 * @param func The callback function pointer.
1013 *
1014 * This is the way, for a routine running outside evas' main thread,
1015 * to report an asynchronous event. A callback function is informed,
1016 * whose call is to happen after evas_async_events_process() is
1017 * called.
1018 *
1019 * @ingroup Evas_Main_Group
1020 */
1021EAPI 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);
1022
1023/**
1024 * @defgroup Evas_Canvas Canvas Functions
1025 * @ingroup Evas
1026 *
1027 * Low level Evas canvas functions. Sub groups will present more high
1028 * level ones, though.
1029 *
1030 * Most of these functions deal with low level Evas actions, like:
1031 * @li create/destroy raw canvases, not bound to any displaying engine
1032 * @li tell a canvas i got focused (in a windowing context, for example)
1033 * @li tell a canvas a region should not be calculated anymore in rendering
1034 * @li tell a canvas to render its contents, immediately
1035 *
1036 * Most users will be using Evas by means of the @c Ecore_Evas
1037 * wrapper, which deals with all the above mentioned issues
1038 * automatically for them. Thus, you'll be looking at this section
1039 * only if you're building low level stuff.
1040 *
1041 * The groups within present you functions that deal with the canvas
1042 * directly, too, and not yet with its @b objects. They are the
1043 * functions you need to use at a minimum to get a working canvas.
1044 *
1045 * Some of the functions in this group are exemplified @ref
1046 * Example_Evas_Events "here".
1047 */
1048/**
1049 * @}
1050 */
1051
1052/**
1053 * @defgroup Evas_Output_Method Render Engine Functions
1054 *
1055 * Functions that are used to set the render engine for a given
1056 * function, and then get that engine working.
1057 *
1058 * The following code snippet shows how they can be used to
1059 * initialise an evas that uses the X11 software engine:
1060 * @code
1061 * Evas *evas;
1062 * Evas_Engine_Info_Software_X11 *einfo;
1063 * extern Display *display;
1064 * extern Window win;
1065 *
1066 * evas_init();
1067 *
1068 * evas = evas_new();
1069 * evas_output_method_set(evas, evas_render_method_lookup("software_x11"));
1070 * evas_output_size_set(evas, 640, 480);
1071 * evas_output_viewport_set(evas, 0, 0, 640, 480);
1072 * einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas);
1073 * einfo->info.display = display;
1074 * einfo->info.visual = DefaultVisual(display, DefaultScreen(display));
1075 * einfo->info.colormap = DefaultColormap(display, DefaultScreen(display));
1076 * einfo->info.drawable = win;
1077 * einfo->info.depth = DefaultDepth(display, DefaultScreen(display));
1078 * evas_engine_info_set(evas, (Evas_Engine_Info *)einfo);
1079 * @endcode
1080 *
1081 * @ingroup Evas_Canvas
1082 */
1083
1084/**
1085 * Look up a numeric ID from a string name of a rendering engine.
1086 *
1087 * @param name the name string of an engine
1088 * @return A numeric (opaque) ID for the rendering engine
1089 * @ingroup Evas_Output_Method
1090 *
1091 * This function looks up a numeric return value for the named engine
1092 * in the string @p name. This is a normal C string, NUL byte
1093 * terminated. The name is case sensitive. If the rendering engine is
1094 * available, a numeric ID for that engine is returned that is not
1095 * 0. If the engine is not available, 0 is returned, indicating an
1096 * invalid engine.
1097 *
1098 * The programmer should NEVER rely on the numeric ID of an engine
1099 * unless it is returned by this function. Programs should NOT be
1100 * written accessing render method ID's directly, without first
1101 * obtaining it from this function.
1102 *
1103 * @attention it is mandatory that one calls evas_init() before
1104 * looking up the render method.
1105 *
1106 * Example:
1107 * @code
1108 * int engine_id;
1109 * Evas *evas;
1110 *
1111 * evas_init();
1112 *
1113 * evas = evas_new();
1114 * if (!evas)
1115 * {
1116 * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
1117 * exit(-1);
1118 * }
1119 * engine_id = evas_render_method_lookup("software_x11");
1120 * if (!engine_id)
1121 * {
1122 * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
1123 * exit(-1);
1124 * }
1125 * evas_output_method_set(evas, engine_id);
1126 * @endcode
1127 */
1128EAPI int evas_render_method_lookup(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1129
1130/**
1131 * List all the rendering engines compiled into the copy of the Evas library
1132 *
1133 * @return A linked list whose data members are C strings of engine names
1134 * @ingroup Evas_Output_Method
1135 *
1136 * Calling this will return a handle (pointer) to an Evas linked
1137 * list. Each node in the linked list will have the data pointer be a
1138 * (char *) pointer to the name string of the rendering engine
1139 * available. The strings should never be modified, neither should the
1140 * list be modified. This list should be cleaned up as soon as the
1141 * program no longer needs it using evas_render_method_list_free(). If
1142 * no engines are available from Evas, @c NULL will be returned.
1143 *
1144 * Example:
1145 * @code
1146 * Eina_List *engine_list, *l;
1147 * char *engine_name;
1148 *
1149 * engine_list = evas_render_method_list();
1150 * if (!engine_list)
1151 * {
1152 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1153 * exit(-1);
1154 * }
1155 * printf("Available Evas Engines:\n");
1156 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1157 * printf("%s\n", engine_name);
1158 * evas_render_method_list_free(engine_list);
1159 * @endcode
1160 */
1161EAPI Eina_List *evas_render_method_list(void) EINA_WARN_UNUSED_RESULT;
1162
1163/**
1164 * This function should be called to free a list of engine names
1165 *
1166 * @param list The Eina_List base pointer for the engine list to be freed
1167 * @ingroup Evas_Output_Method
1168 *
1169 * When this function is called it will free the engine list passed in
1170 * as @p list. The list should only be a list of engines generated by
1171 * calling evas_render_method_list(). If @p list is NULL, nothing will
1172 * happen.
1173 *
1174 * Example:
1175 * @code
1176 * Eina_List *engine_list, *l;
1177 * char *engine_name;
1178 *
1179 * engine_list = evas_render_method_list();
1180 * if (!engine_list)
1181 * {
1182 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1183 * exit(-1);
1184 * }
1185 * printf("Available Evas Engines:\n");
1186 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1187 * printf("%s\n", engine_name);
1188 * evas_render_method_list_free(engine_list);
1189 * @endcode
1190 */
1191EAPI void evas_render_method_list_free(Eina_List *list);
1192
1193/**
1194 * @}
1195 */
1196
1197/**
1198 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1199 *
1200 * Functions that are used to map coordinates from the canvas to the
1201 * screen or the screen to the canvas.
1202 *
1203 * @ingroup Evas_Canvas
1204 */
1205
1206/**
1207 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1208 *
1209 * Functions that set and retrieve the output and viewport size of an
1210 * evas.
1211 *
1212 * @ingroup Evas_Canvas
1213 */
1214
1215/**
1216 * @defgroup Evas_Canvas_Events Canvas Events
1217 *
1218 * Functions relating to canvas events, which are mainly reports on
1219 * its internal states changing (an object got focused, the rendering
1220 * is updated, etc).
1221 *
1222 * Some of the functions in this group are exemplified @ref
1223 * Example_Evas_Events "here".
1224 *
1225 * @ingroup Evas_Canvas
1226 */
1227
1228/**
1229 * Free the rectangles returned by evas_render_updates().
1230 *
1231 * @param updates The list of updated rectangles of the canvas.
1232 *
1233 * This function removes the region from the render updates list. It
1234 * makes the region doesn't be render updated anymore.
1235 *
1236 * @see evas_render_updates() for an example
1237 *
1238 * @ingroup Evas_Canvas
1239 */
1240EAPI void evas_render_updates_free(Eina_List *updates);
1241
1242
1243/**
1244 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
1245 *
1246 * Functions that deal with the freezing of input event processing of
1247 * an Evas canvas.
1248 *
1249 * There might be scenarios during a graphical user interface
1250 * program's use when the developer wishes the users wouldn't be able
1251 * to deliver input events to this application. It may, for example,
1252 * be the time for it to populate a view or to change some
1253 * layout. Assuming proper behavior with user interaction during this
1254 * exact time would be hard, as things are in a changing state. The
1255 * programmer can then tell the canvas to ignore input events,
1256 * bringing it back to normal behavior when he/she wants.
1257 *
1258 * Most of the time use of freezing events is done like this:
1259 * @code
1260 * evas_event_freeze(my_evas_canvas);
1261 * function_that_does_work_which_cant_be_interrupted_by_events();
1262 * evas_event_thaw(my_evas_canvas);
1263 * @endcode
1264 *
1265 * Some of the functions in this group are exemplified @ref
1266 * Example_Evas_Events "here".
1267 *
1268 * @ingroup Evas_Canvas_Events
1269 */
1270
1271/**
1272 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
1273 *
1274 * Functions to tell Evas that input events happened and should be
1275 * processed.
1276 *
1277 * @warning Most of the time these functions are @b not what you're looking for.
1278 * These functions should only be used if you're not working with ecore evas(or
1279 * another input handling system). If you're not using ecore evas please
1280 * consider using it, in most situation it will make life a lot easier.
1281 *
1282 * As explained in @ref intro_not_evas, Evas does not know how to poll
1283 * for input events, so the developer should do it and then feed such
1284 * events to the canvas to be processed. This is only required if
1285 * operating Evas directly. Modules such as Ecore_Evas do that for
1286 * you.
1287 *
1288 * Some of the functions in this group are exemplified @ref
1289 * Example_Evas_Events "here".
1290 *
1291 * @ingroup Evas_Canvas_Events
1292 */
1293
1294/**
1295 * @addtogroup Evas_Event_Feeding_Group
1296 * @{
1297 */
1298
1299/**
1300 * Add a new device type
1301 *
1302 * @param e The canvas to create the device node for.
1303 *
1304 * Adds a new device nod to the given canvas @p e. All devices created as
1305 * part of the canvas @p e will automatically be deleted when the canvas
1306 * is freed.
1307 *
1308 * @see evas_device_del
1309 * @since 1.8
1310 */
1311EAPI Evas_Device *evas_device_add(Evas *e);
1312
1313/**
1314 * Delete a new device type
1315 *
1316 * @see evas_device_add
1317 * @see evas_device_push
1318 * @see evas_device_pop
1319 * @since 1.8
1320 */
1321EAPI void evas_device_del(Evas_Device *dev);
1322
1323/**
1324 * Push the current context device onto the device stack
1325 *
1326 * @param e The canvas to push the device on to
1327 * @param dev The device to push.
1328 *
1329 * This pushes the given device @p dev onto the stack for the canvas @p e
1330 * resulting in the dev pointer in all events that get fed to the canvas
1331 * being the device at the top of the device stack for that canvas.
1332 *
1333 * If a device is pushed onto the device stack, it will not be deleted
1334 * until a canvas free OR until it has been popped from the stack even if
1335 * evas_device_del() is called.
1336 *
1337 * The device @p dev must have been created as a device for the canvas it
1338 * is pushed onto (and not another canvas).
1339 *
1340 * Example:
1341 * @code
1342 * evas_device_push(canvas, dev);
1343 * evas_event_feed_mouse_move(canvas, 20, 30, 0, NULL);
1344 * evas_device_pop(canvas);
1345 * @endcode
1346 *
1347 * @see evas_device_pop
1348 * @since 1.8
1349 */
1350EAPI void evas_device_push(Evas *e, Evas_Device *dev);
1351
1352/**
1353 * This pops the top of the device stack for the canvas
1354 *
1355 * @param e The canvas to pop the device stack from
1356 *
1357 * This pops the top of the device stack making the current device context
1358 * used for device events being what is now at the top of the stack after
1359 * popping.
1360 *
1361 * @see evas_device_push
1362 * @since 1.8
1363 */
1364EAPI void evas_device_pop(Evas *e);
1365
1366/**
1367 * List all current devices attached to the given canvas and/or device
1368 *
1369 * @param e The canvas to query for a device list
1370 * @param dev A specific device inside the canvas to query for child devices or NULL if just querying the base canvas devices
1371 * @return An internal list of Evas_Device pointers, or NULL if no devices are found
1372 *
1373 * This will list all devices belonging to a specific evas canvas @p e, at the
1374 * top-level in the device tree if @p dev passed in is NULL. If @p dev is
1375 * a valid device for the given canvas @p e, then a list of child devices
1376 * of @p dev will be returned, allowing you to walk the device tree.
1377 *
1378 * The list returned is only valid so long as no changes are made to the
1379 * device tree in the given canvas @p e. If there are no devices or children
1380 * then NULL is returned.
1381 *
1382 * @see evas_device_parent_get
1383 * @see evas_device_name_get
1384 * @see evas_device_description_get
1385 * @see evas_device_class_get
1386 * @see evas_device_subclass_get
1387 * @see evas_device_emulation_source_get
1388 * @since 1.8
1389 */
1390EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev);
1391
1392/**
1393 * Set the name of a device as a string
1394 *
1395 * @p dev The device to set the name of
1396 * @p name The name string as a readable C UTF8 string
1397 *
1398 * @since 1.8
1399 */
1400EAPI void evas_device_name_set(Evas_Device *dev, const char *name);
1401
1402/**
1403 * Get the name of a device
1404 *
1405 * @p dev The device to query
1406 * @return The device name string or NULL if none is set
1407 *
1408 * This gets the name set by evas_device_name_set(). This is a readable UTF8
1409 * C string, or NULL if no name is set.
1410 *
1411 * The name should be a short name like "Wireless Mouse", "Joystick",
1412 * "Finger", "Keyboard" or "Numberpad" etc.
1413 *
1414 * @since 1.8
1415 */
1416EAPI const char *evas_device_name_get(const Evas_Device *dev);
1417
1418/**
1419 * Set the description of a device as a string
1420 *
1421 * @p dev The device to set the description of
1422 * @p name The description string as a readable C UTF8 string
1423 *
1424 * @since 1.8
1425 */
1426EAPI void evas_device_description_set(Evas_Device *dev, const char *desc);
1427
1428/**
1429 * Get the description of a device
1430 *
1431 * @p dev The device to query
1432 * @return The device description string or NULL if none is set
1433 *
1434 * This gets the description set by evas_device_description_set(). This is
1435 * a readable UTF8 C string, or NULL if no description is set.
1436 *
1437 * A description is meant to be a longer string describing the device so a
1438 * human may make sense of it. For example "Wireless 6 button mouse in Black
1439 * with red buttons" would be a good description, so a user may identify
1440 * precisely which device is being talked about.
1441 *
1442 * @since 1.8
1443 */
1444EAPI const char *evas_device_description_get(const Evas_Device *dev);
1445
1446/**
1447 * Set the parent of a device
1448 *
1449 * @p dev The device to set the parent of
1450 * @p parent The new parent device
1451 *
1452 * This sets the parent of a device @p dev to the parent given by @p parent.
1453 * If the device already has a parent, it is removed from that parent's list.
1454 * If @p parent is NULL then the device is unparented and placed back as a
1455 * root device in the canvas.
1456 *
1457 * When a device is deleted with evas_device_del(), all children are also
1458 * deleted along with it.
1459 *
1460 * @see evas_device_del
1461 * @see evas_device_parent_get
1462 * @see evas_device_list
1463 *
1464 * @since 1.8
1465 */
1466EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent);
1467
1468/**
1469 * Get the parent of a device
1470 *
1471 * @param dev The device to query
1472 * @return The parent device or NULL if it is a toplevel
1473 *
1474 * This returns the parent device of any given device entry, or NULL if no
1475 * parent device exists (is a toplevel device).
1476 *
1477 * @since 1.8
1478 */
1479EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev);
1480
1481/**
1482 * Set the major class of device
1483 *
1484 * @param dev The device whose class to set
1485 * @param clas The class to set it to
1486 *
1487 * This sets the "primary" class of device (a broad thing like mouse, keyboard,
1488 * touch, pen etc.).
1489 *
1490 * @since 1.8
1491 */
1492EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas);
1493
1494/**
1495 * Get the major class of a device
1496 *
1497 * @param dev The devise to query
1498 * @return The device class to set
1499 *
1500 * This sets the device class set by evas_device_class_set().
1501 *
1502 * @since 1.8
1503 */
1504EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev);
1505
1506/**
1507 * Set the sub-class of a device
1508 *
1509 * @param dev The device to modify
1510 * @param clas The sub-class to set
1511 *
1512 * This sets the sub-class of a device whihc gives much more detailed usage
1513 * within a broader category.
1514 *
1515 * @since 1.8
1516 */
1517EAPI void evas_device_subclass_set(Evas_Device *dev, Evas_Device_Subclass clas);
1518
1519/**
1520 * Get the device sub-class
1521 *
1522 * @param dev The device to query
1523 * @return The device sub-class set by evas_device_subclass_set().
1524 *
1525 * @since 1.8
1526 */
1527EAPI Evas_Device_Subclass evas_device_subclass_get(const Evas_Device *dev);
1528
1529/**
1530 * Set the emulation source device
1531 *
1532 * @param dev The device being emulated
1533 * @param src The primary source device producing events in the emulated device
1534 *
1535 * Devices may not be real, but may be emulated by listening to input on other
1536 * devices and modifying or interpeting it to generate output on an emulated
1537 * device (example a fingeron a touchscreen will often emulate a mouse when
1538 * it presses). This allows you to set which device primarily emulates @p dev
1539 * so the user can choose to ignore events from emulated devices if they also
1540 * pay attention to source device events for example.
1541 *
1542 * @since 1.8
1543 */
1544EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src);
1545
1546/**
1547 * Get the emulation source device
1548 *
1549 * @param dev The device to query
1550 * @return The source emulation device set by evas_device_emulation_source_set().
1551 *
1552 * @since 1.8
1553 */
1554EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev);
1555
1556/**
1557 * @}
1558 */
1559
1560/**
1561 * @defgroup Evas_Image_Group Image Functions
1562 *
1563 * Functions that deals with images at canvas level.
1564 *
1565 * @ingroup Evas_Canvas
1566 */
1567
1568/**
1569 * @defgroup Evas_Font_Group Font Functions
1570 *
1571 * Functions that deals with fonts.
1572 *
1573 * @ingroup Evas_Canvas
1574 */
1575
1576/**
1577 * @defgroup Evas_Object_Group Generic Object Functions
1578 * @ingroup Evas
1579 *
1580 * Functions that manipulate generic Evas objects.
1581 *
1582 * All Evas displaying units are Evas objects. One handles them all by
1583 * means of the handle ::Evas_Object. Besides Evas treats their
1584 * objects equally, they have @b types, which define their specific
1585 * behavior (and individual API).
1586 *
1587 * Evas comes with a set of built-in object types:
1588 * - rectangle,
1589 * - line,
1590 * - polygon,
1591 * - text,
1592 * - textblock and
1593 * - image.
1594 *
1595 * These functions apply to @b any Evas object, whichever type that
1596 * may have.
1597 *
1598 * @note The built-in types which are most used are rectangles, text
1599 * and images. In fact, with these ones one can create 2D interfaces
1600 * of arbitrary complexity and EFL makes it easy.
1601 */
1602
1603/**
1604 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
1605 *
1606 * Almost every evas object created will have some generic function used to
1607 * manipulate it. That's because there are a number of basic actions to be done
1608 * to objects that are irrespective of the object's type, things like:
1609 * @li Showing/Hiding
1610 * @li Setting(and getting) geometry
1611 * @li Bring up or down a layer
1612 * @li Color management
1613 * @li Handling focus
1614 * @li Clipping
1615 * @li Reference counting
1616 *
1617 * All of this issues are handled through the functions here grouped. Examples
1618 * of these function can be seen in @ref Example_Evas_Object_Manipulation(which
1619 * deals with the most common ones) and in @ref Example_Evas_Stacking(which
1620 * deals with stacking functions).
1621 *
1622 * @ingroup Evas_Object_Group
1623 */
1624
1625/**
1626 * @defgroup Evas_Object_Group_Events Object Events
1627 *
1628 * Objects generate events when they are moved, resized, when their
1629 * visibility change, when they are deleted and so on. These methods
1630 * allow one to be notified about and to handle such events.
1631 *
1632 * Objects also generate events on input (keyboard and mouse), if they
1633 * accept them (are visible, focused, etc).
1634 *
1635 * For each of those events, Evas provides a way for one to register
1636 * callback functions to be issued just after they happen.
1637 *
1638 * The following figure illustrates some Evas (event) callbacks:
1639 *
1640 * @image html evas-callbacks.png
1641 * @image rtf evas-callbacks.png
1642 * @image latex evas-callbacks.eps
1643 *
1644 * These events have their values in the #Evas_Callback_Type
1645 * enumeration, which has also ones happening on the canvas level (see
1646 * @ref Evas_Canvas_Events ).
1647 *
1648 * Examples on this group of functions can be found @ref
1649 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
1650 *
1651 * @ingroup Evas_Object_Group
1652 */
1653
1654/**
1655 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspective, 3D...)
1656 *
1657 * Evas allows different transformations to be applied to all kinds of
1658 * objects. These are applied by means of UV mapping.
1659 *
1660 * With UV mapping, one maps points in the source object to a 3D space
1661 * positioning at target. This allows rotation, perspective, scale and
1662 * lots of other effects, depending on the map that is used.
1663 *
1664 * Each map point may carry a multiplier color. If properly
1665 * calculated, these can do shading effects on the object, producing
1666 * 3D effects.
1667 *
1668 * As usual, Evas provides both the raw and easy to use methods. The
1669 * raw methods allow developers to create their maps somewhere else,
1670 * possibly loading them from some file format. The easy to use methods
1671 * calculate the points given some high-level parameters such as
1672 * rotation angle, ambient light, and so on.
1673 *
1674 * @note applying mapping will reduce performance, so use with
1675 * care. The impact on performance depends on engine in
1676 * use. Software is quite optimized, but not as fast as OpenGL.
1677 *
1678 * @section sec-map-points Map points
1679 * @subsection subsec-rotation Rotation
1680 *
1681 * A map consists of a set of points, currently only four are supported. Each
1682 * of these points contains a set of canvas coordinates @c x and @c y that
1683 * can be used to alter the geometry of the mapped object, and a @c z
1684 * coordinate that indicates the depth of that point. This last coordinate
1685 * does not normally affect the map, but it's used by several of the utility
1686 * functions to calculate the right position of the point given other
1687 * parameters.
1688 *
1689 * The coordinates for each point are set with evas_map_point_coord_set().
1690 * The following image shows a map set to match the geometry of an existing
1691 * object.
1692 *
1693 * @image html map-set-map-points-1.png
1694 * @image rtf map-set-map-points-1.png
1695 * @image latex map-set-map-points-1.eps
1696 *
1697 * This is a common practice, so there are a few functions that help make it
1698 * easier.
1699 *
1700 * evas_map_util_points_populate_from_geometry() sets the coordinates of each
1701 * point in the given map to match the rectangle defined by the function
1702 * parameters.
1703 *
1704 * evas_map_util_points_populate_from_object() and
1705 * evas_map_util_points_populate_from_object_full() both take an object and
1706 * set the map points to match its geometry. The difference between the two
1707 * is that the first function sets the @c z value of all points to 0, while
1708 * the latter receives the value to set in said coordinate as a parameter.
1709 *
1710 * The following lines of code all produce the same result as in the image
1711 * above.
1712 * @code
1713 * evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
1714 * // Assuming o is our original object
1715 * evas_object_move(o, 100, 100);
1716 * evas_object_resize(o, 200, 200);
1717 * evas_map_util_points_populate_from_object(m, o);
1718 * evas_map_util_points_populate_from_object_full(m, o, 0);
1719 * @endcode
1720 *
1721 * Several effects can be applied to an object by simply setting each point
1722 * of the map to the right coordinates. For example, a simulated perspective
1723 * could be achieve as follows.
1724 *
1725 * @image html map-set-map-points-2.png
1726 * @image rtf map-set-map-points-2.png
1727 * @image latex map-set-map-points-2.eps
1728 *
1729 * As said before, the @c z coordinate is unused here so when setting points
1730 * by hand, its value is of no importance.
1731 *
1732 * @image html map-set-map-points-3.png
1733 * @image rtf map-set-map-points-3.png
1734 * @image latex map-set-map-points-3.eps
1735 *
1736 * In all three cases above, setting the map to be used by the object is the
1737 * same.
1738 * @code
1739 * evas_object_map_set(o, m);
1740 * evas_object_map_enable_set(o, EINA_TRUE);
1741 * @endcode
1742 *
1743 * Doing things this way, however, is a lot of work that can be avoided by
1744 * using the provided utility functions, as described in the next section.
1745 *
1746 * @section map-utils Utility functions
1747 *
1748 * Utility functions take an already set up map and alter it to produce a
1749 * specific effect. For example, to rotate an object around its own center
1750 * you would need to take the rotation angle, the coordinates of each corner
1751 * of the object and do all the math to get the new set of coordinates that
1752 * need to be set in the map.
1753 *
1754 * Or you can use this code:
1755 * @code
1756 * evas_object_geometry_get(o, &x, &y, &w, &h);
1757 * m = evas_map_new(4);
1758 * evas_map_util_points_populate_from_object(m, o);
1759 * evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
1760 * evas_object_map_set(o, m);
1761 * evas_object_map_enable_set(o, EINA_TRUE);
1762 * evas_map_free(m);
1763 * @endcode
1764 *
1765 * Which will rotate the object around its center point in a 45 degree angle
1766 * in the clockwise direction, taking it from this
1767 *
1768 * @image html map-rotation-2d-1.png
1769 * @image rtf map-rotation-2d-1.png
1770 * @image latex map-rotation-2d-1.eps
1771 *
1772 * to this
1773 *
1774 * @image html map-rotation-2d-2.png
1775 * @image rtf map-rotation-2d-2.png
1776 * @image latex map-rotation-2d-2.eps
1777 *
1778 * Objects may be rotated around any other point just by setting the last two
1779 * paramaters of the evas_map_util_rotate() function to the right values. A
1780 * circle of roughly the diameter of the object overlaid on each image shows
1781 * where the center of rotation is set for each example.
1782 *
1783 * For example, this code
1784 * @code
1785 * evas_object_geometry_get(o, &x, &y, &w, &h);
1786 * m = evas_map_new(4);
1787 * evas_map_util_points_populate_from_object(m, o);
1788 * evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
1789 * evas_object_map_set(o, m);
1790 * evas_object_map_enable_set(o, EINA_TRUE);
1791 * evas_map_free(m);
1792 * @endcode
1793 *
1794 * produces something like
1795 *
1796 * @image html map-rotation-2d-3.png
1797 * @image rtf map-rotation-2d-3.png
1798 * @image latex map-rotation-2d-3.eps
1799 *
1800 * And the following
1801 * @code
1802 * evas_output_size_get(evas, &w, &h);
1803 * m = evas_map_new(4);
1804 * evas_map_util_points_populate_from_object(m, o);
1805 * evas_map_util_rotate(m, 45, w, h);
1806 * evas_object_map_set(o, m);
1807 * evas_object_map_enable_set(o, EINA_TRUE);
1808 * evas_map_free(m);
1809 * @endcode
1810 *
1811 * rotates the object around the center of the window
1812 *
1813 * @image html map-rotation-2d-4.png
1814 * @image rtf map-rotation-2d-4.png
1815 * @image latex map-rotation-2d-4.eps
1816 *
1817 * @subsection subsec-3d 3D Maps
1818 *
1819 * Maps can also be used to achieve the effect of 3-dimensionality. When doing
1820 * this, the @c z coordinate of each point counts, with higher values meaning
1821 * the point is further into the screen, and smaller values (negative, usually)
1822 * meaning the point is closer towards the user.
1823 *
1824 * Thinking in 3D also introduces the concept of back-face of an object. An
1825 * object is said to be facing the user when all its points are placed in a
1826 * clockwise fashion. The next image shows this, with each point showing the
1827 * with which is identified within the map.
1828 *
1829 * @image html map-point-order-face.png
1830 * @image rtf map-point-order-face.png
1831 * @image latex map-point-order-face.eps
1832 *
1833 * Rotating this map around the @c Y axis would leave the order of the points
1834 * in a counter-clockwise fashion, as seen in the following image.
1835 *
1836 * @image html map-point-order-back.png
1837 * @image rtf map-point-order-back.png
1838 * @image latex map-point-order-back.eps
1839 *
1840 * This way we can say that we are looking at the back face of the object.
1841 * This will have stronger implications later when we talk about lighting.
1842 *
1843 * To know if a map is facing towards the user or not it's enough to use
1844 * the evas_map_util_clockwise_get() function, but this is normally done
1845 * after all the other operations are applied on the map.
1846 *
1847 * @subsection subsec-3d-rot 3D rotation and perspective
1848 *
1849 * Much like evas_map_util_rotate(), there's the function
1850 * evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
1851 * to an object. As in its 2D counterpart, the rotation can be applied around
1852 * any point in the canvas, this time with a @c z coordinate too. The rotation
1853 * can also be around any of the 3 axis.
1854 *
1855 * Starting from this simple setup
1856 *
1857 * @image html map-3d-basic-1.png
1858 * @image rtf map-3d-basic-1.png
1859 * @image latex map-3d-basic-1.eps
1860 *
1861 * and setting maps so that the blue square to rotate on all axis around a
1862 * sphere that uses the object as its center, and the red square to rotate
1863 * around the @c Y axis, we get the following. A simple overlay over the image
1864 * shows the original geometry of each object and the axis around which they
1865 * are being rotated, with the @c Z one not appearing due to being orthogonal
1866 * to the screen.
1867 *
1868 * @image html map-3d-basic-2.png
1869 * @image rtf map-3d-basic-2.png
1870 * @image latex map-3d-basic-2.eps
1871 *
1872 * which doesn't look very real. This can be helped by adding perspective
1873 * to the transformation, which can be simply done by calling
1874 * evas_map_util_3d_perspective() on the map after its position has been set.
1875 * The result in this case, making the vanishing point the center of each
1876 * object:
1877 *
1878 * @image html map-3d-basic-3.png
1879 * @image rtf map-3d-basic-3.png
1880 * @image latex map-3d-basic-3.eps
1881 *
1882 * @section sec-color Color and lighting
1883 *
1884 * Each point in a map can be set to a color, which will be multiplied with
1885 * the objects own color and linearly interpolated in between adjacent points.
1886 * This is done with evas_map_point_color_set() for each point of the map,
1887 * or evas_map_util_points_color_set() to set every point to the same color.
1888 *
1889 * When using 3D effects, colors can be used to improve the looks of them by
1890 * simulating a light source. The evas_map_util_3d_lighting() function makes
1891 * this task easier by taking the coordinates of the light source and its
1892 * color, along with the color of the ambient light. Evas then sets the color
1893 * of each point based on the distance to the light source, the angle with
1894 * which the object is facing the light and the ambient light. Here, the
1895 * orientation of each point as explained before, becomes more important.
1896 * If the map is defined counter-clockwise, the object will be facing away
1897 * from the user and thus become obscured, since no light would be reflecting
1898 * from it.
1899 *
1900 * @image html map-light.png
1901 * @image rtf map-light.png
1902 * @image latex map-light.eps
1903 * @note Object facing the light source
1904 *
1905 * @image html map-light2.png
1906 * @image rtf map-light2.png
1907 * @image latex map-light2.eps
1908 * @note Same object facing away from the user
1909 *
1910 * @section Image mapping
1911 *
1912 * @image html map-uv-mapping-1.png
1913 * @image rtf map-uv-mapping-1.png
1914 * @image latex map-uv-mapping-1.eps
1915 *
1916 * Images need some special handling when mapped. Evas can easily take care
1917 * of objects and do almost anything with them, but it's completely oblivious
1918 * to the content of images, so each point in the map needs to be told to what
1919 * pixel in the source image it belongs. Failing to do may sometimes result
1920 * in the expected behavior, or it may look like a partial work.
1921 *
1922 * The next image illustrates one possibility of a map being set to an image
1923 * object, without setting the right UV mapping for each point. The objects
1924 * themselves are mapped properly to their new geometry, but the image content
1925 * may not be displayed correctly within the mapped object.
1926 *
1927 * @image html map-uv-mapping-2.png
1928 * @image rtf map-uv-mapping-2.png
1929 * @image latex map-uv-mapping-2.eps
1930 *
1931 * Once Evas knows how to handle the source image within the map, it will
1932 * transform it as needed. This is done with evas_map_point_image_uv_set(),
1933 * which tells the map to which pixel in image it maps.
1934 *
1935 * To match our example images to the maps above all we need is the size of
1936 * each image, which can always be found with evas_object_image_size_get().
1937 *
1938 * @code
1939 * evas_map_point_image_uv_set(m, 0, 0, 0);
1940 * evas_map_point_image_uv_set(m, 1, 150, 0);
1941 * evas_map_point_image_uv_set(m, 2, 150, 200);
1942 * evas_map_point_image_uv_set(m, 3, 0, 200);
1943 * evas_object_map_set(o, m);
1944 * evas_object_map_enable_set(o, EINA_TRUE);
1945 *
1946 * evas_map_point_image_uv_set(m, 0, 0, 0);
1947 * evas_map_point_image_uv_set(m, 1, 120, 0);
1948 * evas_map_point_image_uv_set(m, 2, 120, 160);
1949 * evas_map_point_image_uv_set(m, 3, 0, 160);
1950 * evas_object_map_set(o2, m);
1951 * evas_object_map_enable_set(o2, EINA_TRUE);
1952 * @endcode
1953 *
1954 * To get
1955 *
1956 * @image html map-uv-mapping-3.png
1957 * @image rtf map-uv-mapping-3.png
1958 * @image latex map-uv-mapping-3.eps
1959 *
1960 * Maps can also be set to use part of an image only, or even map them inverted,
1961 * and combined with evas_object_image_source_set() it can be used to achieve
1962 * more interesting results.
1963 *
1964 * @code
1965 * evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
1966 * evas_map_point_image_uv_set(m, 0, 0, h);
1967 * evas_map_point_image_uv_set(m, 1, w, h);
1968 * evas_map_point_image_uv_set(m, 2, w, h / 3);
1969 * evas_map_point_image_uv_set(m, 3, 0, h / 3);
1970 * evas_object_map_set(o, m);
1971 * evas_object_map_enable_set(o, EINA_TRUE);
1972 * @endcode
1973 *
1974 * @image html map-uv-mapping-4.png
1975 * @image rtf map-uv-mapping-4.png
1976 * @image latex map-uv-mapping-4.eps
1977 *
1978 * Examples:
1979 * @li @ref Example_Evas_Map_Overview
1980 *
1981 * @ingroup Evas_Object_Group
1982 *
1983 * @{
1984 */
1985
1986/**
1987 * Populate source and destination map points to match exactly object.
1988 *
1989 * Usually one initialize map of an object to match it's original
1990 * position and size, then transform these with evas_map_util_*
1991 * functions, such as evas_map_util_rotate() or
1992 * evas_map_util_3d_rotate(). The original set is done by this
1993 * function, avoiding code duplication all around.
1994 *
1995 * @param m map to change all 4 points (must be of size 4).
1996 * @param obj object to use unmapped geometry to populate map coordinates.
1997 * @param z Point Z Coordinate hint (pre-perspective transform). This value
1998 * will be used for all four points.
1999 *
2000 * @see evas_map_util_points_populate_from_object()
2001 * @see evas_map_point_coord_set()
2002 * @see evas_map_point_image_uv_set()
2003 */
2004EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
2005
2006/**
2007 * Populate source and destination map points to match exactly object.
2008 *
2009 * Usually one initialize map of an object to match it's original
2010 * position and size, then transform these with evas_map_util_*
2011 * functions, such as evas_map_util_rotate() or
2012 * evas_map_util_3d_rotate(). The original set is done by this
2013 * function, avoiding code duplication all around.
2014 *
2015 * Z Point coordinate is assumed as 0 (zero).
2016 *
2017 * @param m map to change all 4 points (must be of size 4).
2018 * @param obj object to use unmapped geometry to populate map coordinates.
2019 *
2020 * @see evas_map_util_points_populate_from_object_full()
2021 * @see evas_map_util_points_populate_from_geometry()
2022 * @see evas_map_point_coord_set()
2023 * @see evas_map_point_image_uv_set()
2024 */
2025EAPI void evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj);
2026
2027/**
2028 * Populate source and destination map points to match given geometry.
2029 *
2030 * Similar to evas_map_util_points_populate_from_object_full(), this
2031 * call takes raw values instead of querying object's unmapped
2032 * geometry. The given width will be used to calculate destination
2033 * points (evas_map_point_coord_set()) and set the image uv
2034 * (evas_map_point_image_uv_set()).
2035 *
2036 * @param m map to change all 4 points (must be of size 4).
2037 * @param x Point X Coordinate
2038 * @param y Point Y Coordinate
2039 * @param w width to use to calculate second and third points.
2040 * @param h height to use to calculate third and fourth points.
2041 * @param z Point Z Coordinate hint (pre-perspective transform). This value
2042 * will be used for all four points.
2043 *
2044 * @see evas_map_util_points_populate_from_object()
2045 * @see evas_map_point_coord_set()
2046 * @see evas_map_point_image_uv_set()
2047 */
2048EAPI 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);
2049
2050/**
2051 * Set color of all points to given color.
2052 *
2053 * This call is useful to reuse maps after they had 3d lightning or
2054 * any other colorization applied before.
2055 *
2056 * @param m map to change the color of.
2057 * @param r red (0 - 255)
2058 * @param g green (0 - 255)
2059 * @param b blue (0 - 255)
2060 * @param a alpha (0 - 255)
2061 *
2062 * @see evas_map_point_color_set()
2063 */
2064EAPI void evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a);
2065
2066/**
2067 * Change the map to apply the given rotation.
2068 *
2069 * This rotates the indicated map's coordinates around the center coordinate
2070 * given by @p cx and @p cy as the rotation center. The points will have their
2071 * X and Y coordinates rotated clockwise by @p degrees degrees (360.0 is a
2072 * full rotation). Negative values for degrees will rotate counter-clockwise
2073 * by that amount. All coordinates are canvas global coordinates.
2074 *
2075 * @param m map to change.
2076 * @param degrees amount of degrees from 0.0 to 360.0 to rotate.
2077 * @param cx rotation's center horizontal position.
2078 * @param cy rotation's center vertical position.
2079 *
2080 * @see evas_map_point_coord_set()
2081 * @see evas_map_util_zoom()
2082 */
2083EAPI void evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
2084
2085/**
2086 * Change the map to apply the given zooming.
2087 *
2088 * Like evas_map_util_rotate(), this zooms the points of the map from a center
2089 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
2090 * parameters specify how much to zoom in the X and Y direction respectively.
2091 * A value of 1.0 means "don't zoom". 2.0 means "double the size". 0.5 is
2092 * "half the size" etc. All coordinates are canvas global coordinates.
2093 *
2094 * @param m map to change.
2095 * @param zoomx horizontal zoom to use.
2096 * @param zoomy vertical zoom to use.
2097 * @param cx zooming center horizontal position.
2098 * @param cy zooming center vertical position.
2099 *
2100 * @see evas_map_point_coord_set()
2101 * @see evas_map_util_rotate()
2102 */
2103EAPI void evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
2104
2105/**
2106 * Rotate the map around 3 axes in 3D
2107 *
2108 * This will rotate not just around the "Z" axis as in evas_map_util_rotate()
2109 * (which is a convenience call for those only wanting 2D). This will rotate
2110 * around the X, Y and Z axes. The Z axis points "into" the screen with low
2111 * values at the screen and higher values further away. The X axis runs from
2112 * left to right on the screen and the Y axis from top to bottom. Like with
2113 * evas_map_util_rotate() you provide a center point to rotate around (in 3D).
2114 *
2115 * @param m map to change.
2116 * @param dx amount of degrees from 0.0 to 360.0 to rotate around X axis.
2117 * @param dy amount of degrees from 0.0 to 360.0 to rotate around Y axis.
2118 * @param dz amount of degrees from 0.0 to 360.0 to rotate around Z axis.
2119 * @param cx rotation's center horizontal position.
2120 * @param cy rotation's center vertical position.
2121 * @param cz rotation's center vertical position.
2122 */
2123EAPI void evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz);
2124
2125/**
2126 * Rotate the map in 3D using a unit quaternion.
2127 *
2128 * This will rotate in 3D using a unit quaternion. Like with
2129 * evas_map_util_3d_rotate() you provide a center point
2130 * to rotate around (in 3D).
2131 *
2132 * @param m map to change.
2133 * @param qx the x component of the imaginary part of the quaternion.
2134 * @param qy the y component of the imaginary part of the quaternion.
2135 * @param qz the z component of the imaginary part of the quaternion.
2136 * @param qw the w component of the real part of the quaternion.
2137 * @param cx rotation's center x.
2138 * @param cy rotation's center y.
2139 * @param cz rotation's center z.
2140 *
2141 * @warning Rotations can be done using a unit quaternion. Thus, this
2142 * function expects a unit quaternion (i.e. qx² + qy² + qz² + qw² == 1).
2143 * If this is not the case the behavior is undefined.
2144 *
2145 * @since 1.8
2146 */
2147EAPI void evas_map_util_quat_rotate(Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz);
2148
2149/**
2150 * Perform lighting calculations on the given Map
2151 *
2152 * This is used to apply lighting calculations (from a single light source)
2153 * to a given map. The R, G and B values of each vertex will be modified to
2154 * reflect the lighting based on the lixth point coordinates, the light
2155 * color and the ambient color, and at what angle the map is facing the
2156 * light source. A surface should have its points be declared in a
2157 * clockwise fashion if the face is "facing" towards you (as opposed to
2158 * away from you) as faces have a "logical" side for lighting.
2159 *
2160 * @image html map-light3.png
2161 * @image rtf map-light3.png
2162 * @image latex map-light3.eps
2163 * @note Grey object, no lighting used
2164 *
2165 * @image html map-light4.png
2166 * @image rtf map-light4.png
2167 * @image latex map-light4.eps
2168 * @note Lights out! Every color set to 0
2169 *
2170 * @image html map-light5.png
2171 * @image rtf map-light5.png
2172 * @image latex map-light5.eps
2173 * @note Ambient light to full black, red light coming from close at the
2174 * bottom-left vertex
2175 *
2176 * @image html map-light6.png
2177 * @image rtf map-light6.png
2178 * @image latex map-light6.eps
2179 * @note Same light as before, but not the light is set to 0 and ambient light
2180 * is cyan
2181 *
2182 * @image html map-light7.png
2183 * @image rtf map-light7.png
2184 * @image latex map-light7.eps
2185 * @note Both lights are on
2186 *
2187 * @image html map-light8.png
2188 * @image rtf map-light8.png
2189 * @image latex map-light8.eps
2190 * @note Both lights again, but this time both are the same color.
2191 *
2192 * @param m map to change.
2193 * @param lx X coordinate in space of light point
2194 * @param ly Y coordinate in space of light point
2195 * @param lz Z coordinate in space of light point
2196 * @param lr light red value (0 - 255)
2197 * @param lg light green value (0 - 255)
2198 * @param lb light blue value (0 - 255)
2199 * @param ar ambient color red value (0 - 255)
2200 * @param ag ambient color green value (0 - 255)
2201 * @param ab ambient color blue value (0 - 255)
2202 */
2203EAPI 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);
2204
2205/**
2206 * Apply a perspective transform to the map
2207 *
2208 * This applies a given perspective (3D) to the map coordinates. X, Y and Z
2209 * values are used. The px and py points specify the "infinite distance" point
2210 * in the 3D conversion (where all lines converge to like when artists draw
2211 * 3D by hand). The @p z0 value specifies the z value at which there is a 1:1
2212 * mapping between spatial coordinates and screen coordinates. Any points
2213 * on this z value will not have their X and Y values modified in the transform.
2214 * Those further away (Z value higher) will shrink into the distance, and
2215 * those less than this value will expand and become bigger. The @p foc value
2216 * determines the "focal length" of the camera. This is in reality the distance
2217 * between the camera lens plane itself (at or closer than this rendering
2218 * results are undefined) and the "z0" z value. This allows for some "depth"
2219 * control and @p foc must be greater than 0.
2220 *
2221 * @param m map to change.
2222 * @param px The perspective distance X coordinate
2223 * @param py The perspective distance Y coordinate
2224 * @param z0 The "0" z plane value
2225 * @param foc The focal distance
2226 */
2227EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
2228
2229/**
2230 * Get the clockwise state of a map
2231 *
2232 * This determines if the output points (X and Y. Z is not used) are
2233 * clockwise or counter-clockwise. This can be used for "back-face culling". This
2234 * is where you hide objects that "face away" from you. In this case objects
2235 * that are not clockwise.
2236 *
2237 * @param m map to query.
2238 * @return 1 if clockwise, 0 otherwise
2239 */
2240EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m);
2241
2242/**
2243 * Create map of transformation points to be later used with an Evas object.
2244 *
2245 * This creates a set of points (currently only 4 is supported. no other
2246 * number for @p count will work). That is empty and ready to be modified
2247 * with evas_map calls.
2248 *
2249 * @param count number of points in the map.
2250 * @return a newly allocated map or @c NULL on errors.
2251 *
2252 * @see evas_map_free()
2253 * @see evas_map_dup()
2254 * @see evas_map_point_coord_set()
2255 * @see evas_map_point_image_uv_set()
2256 * @see evas_map_util_points_populate_from_object_full()
2257 * @see evas_map_util_points_populate_from_object()
2258 *
2259 * @see evas_object_map_set()
2260 */
2261EAPI Evas_Map *evas_map_new(int count);
2262
2263/**
2264 * Set the smoothing for map rendering
2265 *
2266 * This sets smoothing for map rendering. If the object is a type that has
2267 * its own smoothing settings, then both the smooth settings for this object
2268 * and the map must be turned off. By default smooth maps are enabled.
2269 *
2270 * @param m map to modify. Must not be NULL.
2271 * @param enabled enable or disable smooth map rendering
2272 */
2273EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled);
2274
2275/**
2276 * Get the smoothing for map rendering
2277 *
2278 * This gets smoothing for map rendering.
2279 *
2280 * @param m map to get the smooth from. Must not be NULL.
2281 * @return @c EINA_TRUE if the smooth is enabled, @c EINA_FALSE otherwise.
2282 */
2283EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m);
2284
2285/**
2286 * Set the alpha flag for map rendering
2287 *
2288 * This sets alpha flag for map rendering. If the object is a type that has
2289 * its own alpha settings, then this will take precedence. Only image objects
2290 * have this currently.
2291 * Setting this off stops alpha blending of the map area, and is
2292 * useful if you know the object and/or all sub-objects is 100% solid.
2293 *
2294 * @param m map to modify. Must not be NULL.
2295 * @param enabled enable or disable alpha map rendering
2296 */
2297EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled);
2298
2299/**
2300 * Get the alpha flag for map rendering
2301 *
2302 * This gets the alpha flag for map rendering.
2303 *
2304 * @param m map to get the alpha from. Must not be NULL.
2305 */
2306EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m);
2307
2308/**
2309 * Copy a previously allocated map.
2310 *
2311 * This makes a duplicate of the @p m object and returns it.
2312 *
2313 * @param m map to copy. Must not be NULL.
2314 * @return newly allocated map with the same count and contents as @p m.
2315 */
2316EAPI Evas_Map *evas_map_dup(const Evas_Map *m);
2317
2318/**
2319 * Free a previously allocated map.
2320 *
2321 * This frees a given map @p m and all memory associated with it. You must NOT
2322 * free a map returned by evas_object_map_get() as this is internal.
2323 *
2324 * @param m map to free.
2325 */
2326EAPI void evas_map_free(Evas_Map *m);
2327
2328/**
2329 * Get a maps size.
2330 *
2331 * Returns the number of points in a map. Should be at least 4.
2332 *
2333 * @param m map to get size.
2334 * @return -1 on error, points otherwise.
2335 */
2336EAPI int evas_map_count_get(const Evas_Map *m) EINA_CONST;
2337
2338/**
2339 * Change the map point's coordinate.
2340 *
2341 * This sets the fixed point's coordinate in the map. Note that points
2342 * describe the outline of a quadrangle and are ordered either clockwise
2343 * or counter-clockwise. It is suggested to keep your quadrangles concave and
2344 * non-complex, though these polygon modes may work, they may not render
2345 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
2346 * 2 and 3, and 3 and 0 to describe the edges of the quadrangle.
2347 *
2348 * The X and Y and Z coordinates are in canvas units. Z is optional and may
2349 * or may not be honored in drawing. Z is a hint and does not affect the
2350 * X and Y rendered coordinates. It may be used for calculating fills with
2351 * perspective correct rendering.
2352 *
2353 * Remember all coordinates are canvas global ones like with move and resize
2354 * in evas.
2355 *
2356 * @param m map to change point. Must not be @c NULL.
2357 * @param idx index of point to change. Must be smaller than map size.
2358 * @param x Point X Coordinate
2359 * @param y Point Y Coordinate
2360 * @param z Point Z Coordinate hint (pre-perspective transform)
2361 *
2362 * @see evas_map_util_rotate()
2363 * @see evas_map_util_zoom()
2364 * @see evas_map_util_points_populate_from_object_full()
2365 * @see evas_map_util_points_populate_from_object()
2366 */
2367EAPI void evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
2368
2369/**
2370 * Get the map point's coordinate.
2371 *
2372 * This returns the coordinates of the given point in the map.
2373 *
2374 * @param m map to query point.
2375 * @param idx index of point to query. Must be smaller than map size.
2376 * @param x where to return the X coordinate.
2377 * @param y where to return the Y coordinate.
2378 * @param z where to return the Z coordinate.
2379 */
2380EAPI void evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
2381
2382/**
2383 * Change the map point's U and V texture source point
2384 *
2385 * This sets the U and V coordinates for the point. This determines which
2386 * coordinate in the source image is mapped to the given point, much like
2387 * OpenGL and textures. Notes that these points do select the pixel, but
2388 * are double floating point values to allow for accuracy and sub-pixel
2389 * selection.
2390 *
2391 * @param m map to change the point of.
2392 * @param idx index of point to change. Must be smaller than map size.
2393 * @param u the X coordinate within the image/texture source
2394 * @param v the Y coordinate within the image/texture source
2395 *
2396 * @see evas_map_point_coord_set()
2397 * @see evas_object_map_set()
2398 * @see evas_map_util_points_populate_from_object_full()
2399 * @see evas_map_util_points_populate_from_object()
2400 */
2401EAPI void evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v);
2402
2403/**
2404 * Get the map point's U and V texture source points
2405 *
2406 * This returns the texture points set by evas_map_point_image_uv_set().
2407 *
2408 * @param m map to query point.
2409 * @param idx index of point to query. Must be smaller than map size.
2410 * @param u where to write the X coordinate within the image/texture source
2411 * @param v where to write the Y coordinate within the image/texture source
2412 */
2413EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v);
2414
2415/**
2416 * Set the color of a vertex in the map
2417 *
2418 * This sets the color of the vertex in the map. Colors will be linearly
2419 * interpolated between vertex points through the map. Color will multiply
2420 * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
2421 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
2422 * have no affect on modifying the texture pixels.
2423 *
2424 * @param m map to change the color of.
2425 * @param idx index of point to change. Must be smaller than map size.
2426 * @param r red (0 - 255)
2427 * @param g green (0 - 255)
2428 * @param b blue (0 - 255)
2429 * @param a alpha (0 - 255)
2430 *
2431 * @see evas_map_util_points_color_set()
2432 * @see evas_map_point_coord_set()
2433 * @see evas_object_map_set()
2434 */
2435EAPI void evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a);
2436
2437/**
2438 * Get the color set on a vertex in the map
2439 *
2440 * This gets the color set by evas_map_point_color_set() on the given vertex
2441 * of the map.
2442 *
2443 * @param m map to get the color of the vertex from.
2444 * @param idx index of point get. Must be smaller than map size.
2445 * @param r pointer to red return
2446 * @param g pointer to green return
2447 * @param b pointer to blue return
2448 * @param a pointer to alpha return (0 - 255)
2449 *
2450 * @see evas_map_point_coord_set()
2451 * @see evas_object_map_set()
2452 */
2453EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
2454/**
2455 * @}
2456 */
2457
2458/**
2459 * @defgroup Evas_Object_Group_Size_Hints Size Hints
2460 *
2461 * Objects may carry hints, so that another object that acts as a
2462 * manager (see @ref Evas_Smart_Object_Group) may know how to properly
2463 * position and resize its subordinate objects. The Size Hints provide
2464 * a common interface that is recommended as the protocol for such
2465 * information.
2466 *
2467 * For example, box objects use alignment hints to align its
2468 * lines/columns inside its container, padding hints to set the
2469 * padding between each individual child, etc.
2470 *
2471 * Examples on their usage:
2472 * - @ref Example_Evas_Size_Hints "evas-hints.c"
2473 * - @ref Example_Evas_Aspect_Hints "evas-aspect-hints.c"
2474 *
2475 * @ingroup Evas_Object_Group
2476 */
2477
2478/**
2479 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
2480 *
2481 * Miscellaneous functions that also apply to any object, but are less
2482 * used or not implemented by all objects.
2483 *
2484 * Examples on this group of functions can be found @ref
2485 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
2486 *
2487 * @ingroup Evas_Object_Group
2488 */
2489
2490/**
2491 * @defgroup Evas_Object_Group_Find Finding Objects
2492 *
2493 * Functions that allows finding objects by their position, name or
2494 * other properties.
2495 *
2496 * @ingroup Evas_Object_Group
2497 */
2498
2499/**
2500 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
2501 *
2502 * Evas provides a way to intercept method calls. The interceptor
2503 * callback may opt to completely deny the call, or may check and
2504 * change the parameters before continuing. The continuation of an
2505 * intercepted call is done by calling the intercepted call again,
2506 * from inside the interceptor callback.
2507 *
2508 * @ingroup Evas_Object_Group
2509 */
2510
2511/**
2512 * @addtogroup Evas_Object_Group_Interceptors
2513 * @{
2514 */
2515
2516typedef void (*Evas_Object_Intercept_Show_Cb)(void *data, Evas_Object *obj);
2517typedef void (*Evas_Object_Intercept_Hide_Cb)(void *data, Evas_Object *obj);
2518typedef void (*Evas_Object_Intercept_Move_Cb)(void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
2519typedef void (*Evas_Object_Intercept_Resize_Cb)(void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
2520typedef void (*Evas_Object_Intercept_Raise_Cb)(void *data, Evas_Object *obj);
2521typedef void (*Evas_Object_Intercept_Lower_Cb)(void *data, Evas_Object *obj);
2522typedef void (*Evas_Object_Intercept_Stack_Above_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
2523typedef void (*Evas_Object_Intercept_Stack_Below_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
2524typedef void (*Evas_Object_Intercept_Layer_Set_Cb)(void *data, Evas_Object *obj, int l);
2525typedef void (*Evas_Object_Intercept_Color_Set_Cb)(void *data, Evas_Object *obj, int r, int g, int b, int a);
2526typedef void (*Evas_Object_Intercept_Clip_Set_Cb)(void *data, Evas_Object *obj, Evas_Object *clip);
2527typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj);
2528
2529/**
2530 * @}
2531 */
2532
2533/**
2534 * @defgroup Evas_Object_Specific Specific Object Functions
2535 * @ingroup Evas
2536 *
2537 * Functions that work on specific objects.
2538 *
2539 */
2540
2541/**
2542 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
2543 *
2544 * @brief Function to create evas rectangle objects.
2545 *
2546 * There is only one function to deal with rectangle objects, this may make this
2547 * function seem useless given there are no functions to manipulate the created
2548 * rectangle, however the rectangle is actually very useful and should be
2549 * manipulated using the generic @ref Evas_Object_Group "evas object functions".
2550 *
2551 * The evas rectangle serves a number of key functions when working on evas
2552 * programs:
2553 * @li Background
2554 * @li Debugging
2555 * @li Clipper
2556 *
2557 * @section Background
2558 *
2559 * One extremely common requirement of evas programs is to have a solid color
2560 * background, this can be accomplished with the following very simple code:
2561 * @code
2562 * Evas_Object *bg = evas_object_rectangle_add(evas_canvas);
2563 * //Here we set the rectangles red, green, blue and opacity levels
2564 * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
2565 * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
2566 * evas_object_show(bg);
2567 * @endcode
2568 *
2569 * This however will have issues if the @c evas_canvas is resized, however most
2570 * windows are created using ecore evas and that has a solution to using the
2571 * rectangle as a background:
2572 * @code
2573 * Evas_Object *bg = evas_object_rectangle_add(ecore_evas_get(ee));
2574 * //Here we set the rectangles red, green, blue and opacity levels
2575 * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
2576 * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
2577 * evas_object_show(bg);
2578 * ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE);
2579 * @endcode
2580 * So this gives us a white background to our window that will be resized
2581 * together with it.
2582 *
2583 * @section Debugging
2584 *
2585 * Debugging is a major part of any programmers task and when debugging visual
2586 * issues with evas programs the rectangle is an extremely useful tool. The
2587 * rectangle's simplicity means that it's easier to pinpoint issues with it than
2588 * with more complex objects. Therefore a common technique to use when writing
2589 * an evas program and not getting the desired visual result is to replace the
2590 * misbehaving object for a solid color rectangle and seeing how it interacts
2591 * with the other elements, this often allows us to notice clipping, parenting
2592 * or positioning issues. Once the issues have been identified and corrected the
2593 * rectangle can be replaced for the original part and in all likelihood any
2594 * remaining issues will be specific to that object's type.
2595 *
2596 * @section clipping Clipping
2597 *
2598 * Clipping serves two main functions:
2599 * @li Limiting visibility(i.e. hiding portions of an object).
2600 * @li Applying a layer of color to an object.
2601 *
2602 * @subsection hiding Limiting visibility
2603 *
2604 * It is often necessary to show only parts of an object, while it may be
2605 * possible to create an object that corresponds only to the part that must be
2606 * shown(and it isn't always possible) it's usually easier to use a a clipper. A
2607 * clipper is a rectangle that defines what's visible and what is not. The way
2608 * to do this is to create a solid white rectangle(which is the default, no need
2609 * to call evas_object_color_set()) and give it a position and size of what
2610 * should be visible. The following code exemplifies showing the center half of
2611 * @c my_evas_object:
2612 * @code
2613 * Evas_Object *clipper = evas_object_rectangle_add(evas_canvas);
2614 * evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4);
2615 * evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2);
2616 * evas_object_clip_set(my_evas_object, clipper);
2617 * evas_object_show(clipper);
2618 * @endcode
2619 *
2620 * @subsection color Layer of color
2621 *
2622 * In the @ref clipping section we used a solid white clipper, which produced no
2623 * change in the color of the clipped object, it just hid what was outside the
2624 * clippers area. It is however sometimes desirable to change the of color an
2625 * object, this can be accomplished using a clipper that has a non-white color.
2626 * Clippers with color work by multiplying the colors of clipped object. The
2627 * following code will show how to remove all the red from an object:
2628 * @code
2629 * Evas_Object *clipper = evas_object_rectangle_add(evas);
2630 * evas_object_move(clipper, my_evas_object_x, my_evas_object_y);
2631 * evas_object_resize(clipper, my_evas_object_width, my_evas_object_height);
2632 * evas_object_color_set(clipper, 0, 255, 255, 255);
2633 * evas_object_clip_set(obj, clipper);
2634 * evas_object_show(clipper);
2635 * @endcode
2636 *
2637 * @warning We don't guarantee any proper results if you create a Rectangle
2638 * object without setting the evas engine.
2639 *
2640 * For an example that more fully exercise the use of an evas object rectangle
2641 * see @ref Example_Evas_Object_Manipulation.
2642 *
2643 * @ingroup Evas_Object_Specific
2644 */
2645
2646/**
2647 * @defgroup Evas_Object_Image Image Object Functions
2648 *
2649 * Here are grouped together functions used to create and manipulate
2650 * image objects. They are available to whichever occasion one needs
2651 * complex imagery on a GUI that could not be achieved by the other
2652 * Evas' primitive object types, or to make image manipulations.
2653 *
2654 * Evas will support whichever image file types it was compiled with
2655 * support to (its image loaders) -- check your software packager for
2656 * that information and see
2657 * evas_object_image_extension_can_load_get().
2658 *
2659 * @section Evas_Object_Image_Basics Image object basics
2660 *
2661 * The most common use of image objects -- to display an image on the
2662 * canvas -- is achieved by a common function triplet:
2663 * @code
2664 * img = evas_object_image_add(canvas);
2665 * evas_object_image_file_set(img, "path/to/img", NULL);
2666 * evas_object_image_fill_set(img, 0, 0, w, h);
2667 * @endcode
2668 * The first function, naturally, is creating the image object. Then,
2669 * one must set an source file on it, so that it knows where to fetch
2670 * image data from. Next, one must set <b>how to fill the image
2671 * object's area</b> with that given pixel data. One could use just a
2672 * sub-region of the original image or even have it tiled repeatedly
2673 * on the image object. For the common case of having the whole source
2674 * image to be displayed on the image object, stretched to the
2675 * destination's size, there's also a function helper, to be used
2676 * instead of evas_object_image_fill_set():
2677 * @code
2678 * evas_object_image_filled_set(img, EINA_TRUE);
2679 * @endcode
2680 * See those functions' documentation for more details.
2681 *
2682 * @section Evas_Object_Image_Scale Scale and resizing
2683 *
2684 * Resizing of image objects will scale their respective source images
2685 * to their areas, if they are set to "fill" the object's area
2686 * (evas_object_image_filled_set()). If the user wants any control on
2687 * the aspect ratio of an image for different sizes, he/she has to
2688 * take care of that themselves. There are functions to make images to
2689 * get loaded scaled (up or down) in memory, already, if the user is
2690 * going to use them at pre-determined sizes and wants to save
2691 * computations.
2692 *
2693 * Evas has even a scale cache, which will take care of caching scaled
2694 * versions of images with more often usage/hits. Finally, one can
2695 * have images being rescaled @b smoothly by Evas (more
2696 * computationally expensive) or not.
2697 *
2698 * @section Evas_Object_Image_Performance Performance hints
2699 *
2700 * When dealing with image objects, there are some tricks to boost the
2701 * performance of your application, if it does intense image loading
2702 * and/or manipulations, as in animations on a UI.
2703 *
2704 * @subsection Evas_Object_Image_Load Load hints
2705 *
2706 * In image viewer applications, for example, the user will be looking
2707 * at a given image, at full size, and will desire that the navigation
2708 * to the adjacent images on his/her album be fluid and fast. Thus,
2709 * while displaying a given image, the program can be on the
2710 * background loading the next and previous images already, so that
2711 * displaying them on the sequence is just a matter of repainting the
2712 * screen (and not decoding image data).
2713 *
2714 * Evas addresses this issue with <b>image pre-loading</b>. The code
2715 * for the situation above would be something like the following:
2716 * @code
2717 * prev = evas_object_image_filled_add(canvas);
2718 * evas_object_image_file_set(prev, "/path/to/prev", NULL);
2719 * evas_object_image_preload(prev, EINA_TRUE);
2720 *
2721 * next = evas_object_image_filled_add(canvas);
2722 * evas_object_image_file_set(next, "/path/to/next", NULL);
2723 * evas_object_image_preload(next, EINA_TRUE);
2724 * @endcode
2725 *
2726 * If you're loading images which are too big, consider setting
2727 * previously it's loading size to something smaller, in case you
2728 * won't expose them in real size. It may speed up the loading
2729 * considerably:
2730 * @code
2731 * //to load a scaled down version of the image in memory, if that's
2732 * //the size you'll be displaying it anyway
2733 * evas_object_image_load_scale_down_set(img, zoom);
2734 *
2735 * //optional: if you know you'll be showing a sub-set of the image's
2736 * //pixels, you can avoid loading the complementary data
2737 * evas_object_image_load_region_set(img, x, y, w, h);
2738 * @endcode
2739 * Refer to Elementary's Photocam widget for a high level (smart)
2740 * object which does lots of loading speed-ups for you.
2741 *
2742 * @subsection Evas_Object_Image_Animation Animation hints
2743 *
2744 * If you want to animate image objects on a UI (what you'd get by
2745 * concomitant usage of other libraries, like Ecore and Edje), there
2746 * are also some tips on how to boost the performance of your
2747 * application. If the animation involves resizing of an image (thus,
2748 * re-scaling), you'd better turn off smooth scaling on it @b during
2749 * the animation, turning it back on afterwards, for less
2750 * computations. Also, in this case you'd better flag the image object
2751 * in question not to cache scaled versions of it:
2752 * @code
2753 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC);
2754 *
2755 * // resizing takes place in between
2756 *
2757 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC);
2758 * @endcode
2759 *
2760 * Finally, movement of opaque images through the canvas is less
2761 * expensive than of translucid ones, because of blending
2762 * computations.
2763 *
2764 * @section Evas_Object_Image_Borders Borders
2765 *
2766 * Evas provides facilities for one to specify an image's region to be
2767 * treated specially -- as "borders". This will make those regions be
2768 * treated specially on resizing scales, by keeping their aspect. This
2769 * makes setting frames around other objects on UIs easy.
2770 * See the following figures for a visual explanation:\n
2771 * @htmlonly
2772 * <img src="image-borders.png" style="max-width: 100%;" />
2773 * <a href="image-borders.png">Full-size</a>
2774 * @endhtmlonly
2775 * @image rtf image-borders.png
2776 * @image latex image-borders.eps width=\textwidth
2777 * @htmlonly
2778 * <img src="border-effect.png" style="max-width: 100%;" />
2779 * <a href="border-effect.png">Full-size</a>
2780 * @endhtmlonly
2781 * @image rtf border-effect.png
2782 * @image latex border-effect.eps width=\textwidth
2783 *
2784 * @section Evas_Object_Image_Manipulation Manipulating pixels
2785 *
2786 * Evas image objects can be used to manipulate raw pixels in many
2787 * ways. The meaning of the data in the pixel arrays will depend on
2788 * the image's color space, be warned (see next section). You can set
2789 * your own data as an image's pixel data, fetch an image's pixel data
2790 * for saving/altering, convert images between different color spaces
2791 * and even advanced operations like setting a native surface as image
2792 * objects' data.
2793 *
2794 * @section Evas_Object_Image_Color_Spaces Color spaces
2795 *
2796 * Image objects may return or accept "image data" in multiple
2797 * formats. This is based on the color space of an object. Here is a
2798 * rundown on formats:
2799 *
2800 * - #EVAS_COLORSPACE_ARGB8888:
2801 * This pixel format is a linear block of pixels, starting at the
2802 * top-left row by row until the bottom right of the image or pixel
2803 * region. All pixels are 32-bit unsigned int's with the high-byte
2804 * being alpha and the low byte being blue in the format ARGB. Alpha
2805 * may or may not be used by evas depending on the alpha flag of the
2806 * image, but if not used, should be set to 0xff anyway.
2807 * \n\n
2808 * This colorspace uses premultiplied alpha. That means that R, G
2809 * and B cannot exceed A in value. The conversion from
2810 * non-premultiplied colorspace is:
2811 * \n\n
2812 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
2813 * \n\n
2814 * So 50% transparent blue will be: 0x80000080. This will not be
2815 * "dark" - just 50% transparent. Values are 0 == black, 255 ==
2816 * solid or full red, green or blue.
2817 * .
2818 * - #EVAS_COLORSPACE_YCBCR422P601_PL:
2819 * This is a pointer-list indirected set of YUV (YCbCr) pixel
2820 * data. This means that the data returned or set is not actual
2821 * pixel data, but pointers TO lines of pixel data. The list of
2822 * pointers will first be N rows of pointers to the Y plane -
2823 * pointing to the first pixel at the start of each row in the Y
2824 * plane. N is the height of the image data in pixels. Each pixel in
2825 * the Y, U and V planes is 1 byte exactly, packed. The next N / 2
2826 * pointers will point to rows in the U plane, and the next N / 2
2827 * pointers will point to the V plane rows. U and V planes are half
2828 * the horizontal and vertical resolution of the Y plane.
2829 * \n\n
2830 * Row order is top to bottom and row pixels are stored left to
2831 * right.
2832 * \n\n
2833 * There is a limitation that these images MUST be a multiple of 2
2834 * pixels in size horizontally or vertically. This is due to the U
2835 * and V planes being half resolution. Also note that this assumes
2836 * the itu601 YUV colorspace specification. This is defined for
2837 * standard television and mpeg streams. HDTV may use the itu709
2838 * specification.
2839 * \n\n
2840 * Values are 0 to 255, indicating full or no signal in that plane
2841 * respectively.
2842 * .
2843 * - #EVAS_COLORSPACE_YCBCR422P709_PL:
2844 * Not implemented yet.
2845 * .
2846 * - #EVAS_COLORSPACE_RGB565_A5P:
2847 * In the process of being implemented in 1 engine only. This may
2848 * change.
2849 * \n\n
2850 * This is a pointer to image data for 16-bit half-word pixel data
2851 * in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue),
2852 * with the high-byte containing red and the low byte containing
2853 * blue, per pixel. This data is packed row by row from the top-left
2854 * to the bottom right.
2855 * \n\n
2856 * If the image has an alpha channel enabled there will be an extra
2857 * alpha plane after the color pixel plane. If not, then this data
2858 * will not exist and should not be accessed in any way. This plane
2859 * is a set of pixels with 1 byte per pixel defining the alpha
2860 * values of all pixels in the image from the top-left to the bottom
2861 * right of the image, row by row. Even though the values of the
2862 * alpha pixels can be 0 to 255, only values 0 through to 32 are
2863 * used, 32 being solid and 0 being transparent.
2864 * \n\n
2865 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
2866 * with 0 being black and 31 or 63 being full red, green or blue
2867 * respectively. This colorspace is also pre-multiplied like
2868 * EVAS_COLORSPACE_ARGB8888 so:
2869 * \n\n
2870 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
2871 * .
2872 * - #EVAS_COLORSPACE_GRY8:
2873 * The image is just a alpha mask (8 bit's per pixel). This is used
2874 * for alpha masking.
2875 *
2876 * @warning We don't guarantee any proper results if you create a Image object
2877 * without setting the evas engine.
2878 *
2879 * Some examples on this group of functions can be found @ref
2880 * Example_Evas_Images "here".
2881 *
2882 * @ingroup Evas_Object_Specific
2883 * @{
2884 */
2885
2886
2887typedef void (*Evas_Object_Image_Pixels_Get_Cb)(void *data, Evas_Object *o);
2888
2889/**
2890 * Check if a file extension may be supported by @ref Evas_Object_Image.
2891 *
2892 * @param file The file to check
2893 * @return @c EINA_TRUE if we may be able to open it, @c EINA_FALSE if it's
2894 * unlikely.
2895 * @since 1.1
2896 *
2897 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
2898 *
2899 * This functions is threadsafe.
2900 */
2901EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
2902
2903/**
2904 * Check if a file extension may be supported by @ref Evas_Object_Image.
2905 *
2906 * @param file The file to check, it should be an Eina_Stringshare.
2907 * @return @c EINA_TRUE if we may be able to open it, @c EINA_FALSE if it's
2908 * unlikely.
2909 * @since 1.1
2910 *
2911 * This functions is threadsafe.
2912 */
2913EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
2914/**
2915 * @}
2916 */
2917
2918/**
2919 * @defgroup Evas_Object_Text Text Object Functions
2920 *
2921 * Functions that operate on single line, single style text objects.
2922 *
2923 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
2924 *
2925 * See some @ref Example_Evas_Text "examples" on this group of functions.
2926 *
2927 * @warning We don't guarantee any proper results if you create a Text object
2928 * without setting the evas engine.
2929 *
2930 * @ingroup Evas_Object_Specific
2931 * @{
2932 */
2933
2934/* basic styles (4 bits allocated use 0->10 now, 5 left) */
2935#define EVAS_TEXT_STYLE_MASK_BASIC 0xf
2936
2937/**
2938 * Text style type creation macro. Use style types on the 's'
2939 * arguments, being 'x' your style variable.
2940 */
2941#define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
2942 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
2943
2944#define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
2945
2946/**
2947 * Text style type creation macro. This one will impose shadow
2948 * directions on the style type variable -- use the @c
2949 * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* values on 's', incrementally.
2950 */
2951#define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
2952 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
2953
2954typedef enum _Evas_Text_Style_Type
2955{
2956 EVAS_TEXT_STYLE_PLAIN, /**< plain, standard text */
2957 EVAS_TEXT_STYLE_SHADOW, /**< text with shadow underneath */
2958 EVAS_TEXT_STYLE_OUTLINE, /**< text with an outline */
2959 EVAS_TEXT_STYLE_SOFT_OUTLINE, /**< text with a soft outline */
2960 EVAS_TEXT_STYLE_GLOW, /**< text with a glow effect */
2961 EVAS_TEXT_STYLE_OUTLINE_SHADOW, /**< text with both outline and shadow effects */
2962 EVAS_TEXT_STYLE_FAR_SHADOW, /**< text with (far) shadow underneath */
2963 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW, /**< text with outline and soft shadow effects combined */
2964 EVAS_TEXT_STYLE_SOFT_SHADOW, /**< text with (soft) shadow underneath */
2965 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW, /**< text with (far soft) shadow underneath */
2966
2967 /* OR these to modify shadow direction (3 bits needed) */
2968 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< shadow growing to bottom right */
2969 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< shadow growing to the bottom */
2970 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< shadow growing to bottom left */
2971 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< shadow growing to the left */
2972 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< shadow growing to top left */
2973 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< shadow growing to the top */
2974 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< shadow growing to top right */
2975 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< shadow growing to the right */
2976} Evas_Text_Style_Type; /**< Types of styles to be applied on text objects. The @c EVAS_TEXT_STYLE_SHADOW_DIRECTION_* ones are to be ORed together with others imposing shadow, to change shadow's direction */
2977
2978/**
2979 * @}
2980 */
2981
2982/**
2983 * @defgroup Evas_Object_Textblock Textblock Object Functions
2984 *
2985 * Functions used to create and manipulate textblock objects. Unlike
2986 * @ref Evas_Object_Text, these handle complex text, doing multiple
2987 * styles and multiline text based on HTML-like tags. Of these extra
2988 * features will be heavier on memory and processing cost.
2989 *
2990 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
2991 *
2992 * This part explains about the textblock object's API and proper usage.
2993 * The main user of the textblock object is the edje entry object in Edje, so
2994 * that's a good place to learn from, but I think this document is more than
2995 * enough, if it's not, please contact me and I'll update it.
2996 *
2997 * @subsection textblock_intro Introduction
2998 * The textblock objects is, as implied, an object that can show big chunks of
2999 * text. Textblock supports many features including: Text formatting, automatic
3000 * and manual text alignment, embedding items (for example icons) and more.
3001 * Textblock has three important parts, the text paragraphs, the format nodes
3002 * and the cursors.
3003 *
3004 * You can use markup to format text, for example: "<font_size=50>Big!</font_size>".
3005 * You can also put more than one style directive in one tag:
3006 * "<font_size=50 color=#F00>Big and Red!</font_size>".
3007 * Please notice that we used "</font_size>" although the format also included
3008 * color, this is because the first format determines the matching closing tag's
3009 * name. You can also use anonymous tags, like: "<font_size=30>Big</>" which
3010 * just pop any type of format, but it's advised to use the named alternatives
3011 * instead.
3012 *
3013 * @subsection textblock_cursors Textblock Object Cursors
3014 * A textblock Cursor is data type that represents
3015 * a position in a textblock. Each cursor contains information about the
3016 * paragraph it points to, the position in that paragraph and the object itself.
3017 * Cursors register to textblock objects upon creation, this means that once
3018 * you created a cursor, it belongs to a specific obj and you can't for example
3019 * copy a cursor "into" a cursor of a different object. Registered cursors
3020 * also have the added benefit of updating automatically upon textblock changes,
3021 * this means that if you have a cursor pointing to a specific character, it'll
3022 * still point to it even after you change the whole object completely (as long
3023 * as the char was not deleted), this is not possible without updating, because
3024 * as mentioned, each cursor holds a character position. There are many
3025 * functions that handle cursors, just check out the evas_textblock_cursor*
3026 * functions. For creation and deletion of cursors check out:
3027 * @see evas_object_textblock_cursor_new()
3028 * @see evas_textblock_cursor_free()
3029 * @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).
3030 *
3031 * @subsection textblock_paragraphs Textblock Object Paragraphs
3032 * The textblock object is made out of text splitted to paragraphs (delimited
3033 * by the paragraph separation character). Each paragraph has many (or none)
3034 * format nodes associated with it which are responsible for the formatting
3035 * of that paragraph.
3036 *
3037 * @subsection textblock_format_nodes Textblock Object Format Nodes
3038 * As explained in @ref textblock_paragraphs each one of the format nodes
3039 * is associated with a paragraph.
3040 * There are two types of format nodes, visible and invisible:
3041 * Visible: formats that a cursor can point to, i.e formats that
3042 * occupy space, for example: newlines, tabs, items and etc. Some visible items
3043 * are made of two parts, in this case, only the opening tag is visible.
3044 * A closing tag (i.e a \</tag\> tag) should NEVER be visible.
3045 * Invisible: formats that don't occupy space, for example: bold and underline.
3046 * Being able to access format nodes is very important for some uses. For
3047 * example, edje uses the "<a>" format to create links in the text (and pop
3048 * popups above them when clicked). For the textblock object a is just a
3049 * formatting instruction (how to color the text), but edje utilizes the access
3050 * to the format nodes to make it do more.
3051 * For more information, take a look at all the evas_textblock_node_format_*
3052 * functions.
3053 * The translation of "<tag>" tags to actual format is done according to the
3054 * tags defined in the style, see @ref evas_textblock_style_set
3055 *
3056 * @subsection textblock_special_formats Special Formats
3057 * Textblock supports various format directives that can be used in markup. In
3058 * addition to the mentioned format directives, textblock allows creating
3059 * additional format directives using "tags" that can be set in the style see
3060 * @ref evas_textblock_style_set .
3061 *
3062 * For more details see @ref evas_textblock_style_page
3063 *
3064 * Textblock supports the following formats:
3065 * @li font - Font description in fontconfig like format, e.g: "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
3066 * @li font_weight - Overrides the weight defined in "font". E.g: "font_weight=Bold" is the same as "font=:style=Bold". Supported weights: "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack".
3067 * @li font_style - Overrides the style defined in "font". E.g: "font_style=Italic" is the same as "font=:style=Italic". Supported styles: "normal", "oblique", and "italic".
3068 * @li font_width - Overrides the width defined in "font". E.g: "font_width=Condensed" is the same as "font=:style=Condensed". Supported widths: "normal", "ultracondensed", "extracondensed", "condensed", "semicondensed", "semiexpanded", "expanded", "extraexpanded", and "ultraexpanded".
3069 * @li lang - Overrides the language defined in "font". E.g: "lang=he" is the same as "font=:lang=he".
3070 * @li font_fallbacks - A comma delimited list of fonts to try if finding the main font fails.
3071 * @li font_size - The font size in points.
3072 * @li font_source - The source of the font, e.g an eet file.
3073 * @li color - Text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3074 * @li underline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3075 * @li underline2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3076 * @li outline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3077 * @li shadow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3078 * @li glow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3079 * @li glow2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3080 * @li strikethrough_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3081 * @li align - Either "auto" (meaning according to text direction), "left", "right", "center", "middle", a value between 0.0 and 1.0, or a value between 0% to 100%.
3082 * @li valign - Either "top", "bottom", "middle", "center", "baseline", "base", a value between 0.0 and 1.0, or a value between 0% to 100%.
3083 * @li wrap - "word", "char", "mixed", or "none".
3084 * @li left_margin - Either "reset", or a pixel value indicating the margin.
3085 * @li right_margin - Either "reset", or a pixel value indicating the margin.
3086 * @li underline - "on", "off", "single", or "double".
3087 * @li strikethrough - "on" or "off"
3088 * @li backing_color - Background color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3089 * @li backing - Enable/disable background color. ex) "on" or "off"
3090 * @li style - Either "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow", or "far_soft_shadow". Direction can be selected by adding "bottom_right", "bottom", "bottom_left", "left", "top_left", "top", "top_right", or "right". E.g: "style=shadow,bottom_right".
3091 * @li tabstops - Pixel value for tab width.
3092 * @li linesize - Force a line size in pixels.
3093 * @li linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
3094 * @li linegap - Force a line gap in pixels.
3095 * @li linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
3096 * @li item - Creates an empty space that should be filled by an upper layer. Use "size", "abssize", or "relsize". To define the items size, and an optional: vsize=full/ascent to define the item's position in the line.
3097 * @li linefill - Either a float value or percentage indicating how much to fill the line.
3098 * @li ellipsis - Value between 0.0-1.0 to indicate the type of ellipsis, or -1.0 to indicate ellipsis isn't wanted.
3099 * @li password - "on" or "off". This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off.
3100 *
3101 * @warning We don't guarantee any proper results if you create a Textblock
3102 * object
3103 * without setting the evas engine.
3104 *
3105 * @todo put here some usage examples
3106 *
3107 * @ingroup Evas_Object_Specific
3108 *
3109 * @{
3110 */
3111
3112typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
3113typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
3114/**
3115 * @typedef Evas_Object_Textblock_Node_Format
3116 * A format node.
3117 */
3118typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
3119typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
3120
3121struct _Evas_Textblock_Rectangle
3122{
3123 Evas_Coord x, y, w, h;
3124};
3125
3126typedef enum _Evas_Textblock_Text_Type
3127{
3128 EVAS_TEXTBLOCK_TEXT_RAW,
3129 EVAS_TEXTBLOCK_TEXT_PLAIN,
3130 EVAS_TEXTBLOCK_TEXT_MARKUP
3131} Evas_Textblock_Text_Type;
3132
3133typedef enum _Evas_Textblock_Cursor_Type
3134{
3135 EVAS_TEXTBLOCK_CURSOR_UNDER,
3136 EVAS_TEXTBLOCK_CURSOR_BEFORE
3137} Evas_Textblock_Cursor_Type;
3138
3139/**
3140 * Returns the unescaped version of escape.
3141 * @param escape the string to be escaped
3142 * @return the unescaped version of escape
3143 */
3144EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3145
3146/**
3147 * Returns the escaped version of the string.
3148 * @param string to escape
3149 * @param len_ret the len of the part of the string that was used.
3150 * @return the escaped string.
3151 */
3152EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3153
3154/**
3155 * Return the unescaped version of the string between start and end.
3156 *
3157 * @param escape_start the start of the string.
3158 * @param escape_end the end of the string.
3159 * @return the unescaped version of the range
3160 */
3161EAPI 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);
3162
3163/**
3164 * Creates a new textblock style.
3165 * @return The new textblock style.
3166 */
3167EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
3168
3169/**
3170 * Destroys a textblock style.
3171 * @param ts The textblock style to free.
3172 */
3173EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
3174
3175/**
3176 * Sets the style ts to the style passed as text by text.
3177 * Expected a string consisting of many (or none) tag='format' pairs.
3178 *
3179 * @param ts the style to set.
3180 * @param text the text to parse - NOT NULL.
3181 * @return Returns no value.
3182 */
3183EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
3184
3185/**
3186 * Return the text of the style ts.
3187 * @param ts the style to get it's text.
3188 * @return the text of the style or null on error.
3189 */
3190EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3191
3192/**
3193 * Prepends markup to the cursor cur.
3194 *
3195 * @note assumes text does not include the unicode object replacement char (0xFFFC)
3196 *
3197 * @param cur the cursor to prepend to.
3198 * @param text the markup text to prepend.
3199 * @return Return no value.
3200 */
3201EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
3202
3203/**
3204 * Free the cursor and unassociate it from the object.
3205 * @note do not use it to free unassociated cursors.
3206 *
3207 * @param cur the cursor to free.
3208 * @return Returns no value.
3209 */
3210EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3211
3212/**
3213 * Sets the cursor to the start of the first text node.
3214 *
3215 * @param cur the cursor to update.
3216 * @return Returns no value.
3217 */
3218EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3219
3220/**
3221 * sets the cursor to the end of the last text node.
3222 *
3223 * @param cur the cursor to set.
3224 * @return Returns no value.
3225 */
3226EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3227
3228/**
3229 * Advances to the start of the next text node
3230 *
3231 * @param cur the cursor to update
3232 * @return @c EINA_TRUE if it managed to advance a paragraph, @c EINA_FALSE
3233 * otherwise.
3234 */
3235EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3236
3237/**
3238 * Advances to the end of the previous text node
3239 *
3240 * @param cur the cursor to update
3241 * @return @c EINA_TRUE if it managed to advance a paragraph, @c EINA_FALSE
3242 * otherwise.
3243 */
3244EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3245
3246/**
3247 * Returns the next format node (after n)
3248 *
3249 * @param n the current format node - not null.
3250 * @return Returns the next format node, may be null.
3251 */
3252EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
3253
3254/**
3255 * Returns the prev format node (after n)
3256 *
3257 * @param n the current format node - not null.
3258 * @return Returns the prev format node, may be null.
3259 */
3260EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
3261
3262/**
3263 * Sets the cursor to point to the place where format points to.
3264 *
3265 * @param cur the cursor to update.
3266 * @param n the format node to update according.
3267 * @deprecated duplicate of evas_textblock_cursor_at_format_set
3268 */
3269EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
3270
3271/**
3272 * Return the format node at the position pointed by cur.
3273 *
3274 * @param cur the position to look at.
3275 * @return the format node if found, @c NULL otherwise.
3276 * @see evas_textblock_cursor_format_is_visible_get()
3277 */
3278EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3279
3280/**
3281 * Get the text format representation of the format node.
3282 *
3283 * @param fnode the format node.
3284 * @return the textual format of the format node.
3285 */
3286EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fnode) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3287
3288/**
3289 * Set the cursor to point to the position of fmt.
3290 *
3291 * @param cur the cursor to update
3292 * @param fmt the format to update according to.
3293 */
3294EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
3295
3296/**
3297 * Check if the current cursor position is a visible format. This way is more
3298 * efficient than evas_textblock_cursor_format_get() to check for the existence
3299 * of a visible format.
3300 *
3301 * @param cur the cursor to look at.
3302 * @return @c EINA_TRUE if the cursor points to a visible format, @c EINA_FALSE
3303 * otherwise.
3304 * @see evas_textblock_cursor_format_get()
3305 */
3306EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3307
3308/**
3309 * Advances to the next format node
3310 *
3311 * @param cur the cursor to be updated.
3312 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3313 */
3314EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3315
3316/**
3317 * Advances to the previous format node.
3318 *
3319 * @param cur the cursor to update.
3320 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3321 */
3322EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3323
3324/**
3325 * Returns true if the cursor points to a format.
3326 *
3327 * @param cur the cursor to check.
3328 * @return @c EINA_TRUE if a cursor points to a format @c EINA_FALSE
3329 * otherwise.
3330 */
3331EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3332
3333/**
3334 * Advances 1 char forward.
3335 *
3336 * @param cur the cursor to advance.
3337 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3338 */
3339EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3340
3341/**
3342 * Advances 1 char backward.
3343 *
3344 * @param cur the cursor to advance.
3345 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3346 */
3347EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3348
3349/**
3350 * Moves the cursor to the start of the word under the cursor.
3351 *
3352 * @param cur the cursor to move.
3353 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3354 * @since 1.2
3355 */
3356EAPI Eina_Bool evas_textblock_cursor_word_start(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3357
3358/**
3359 * Moves the cursor to the end of the word under the cursor.
3360 *
3361 * @param cur the cursor to move.
3362 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3363 * @since 1.2
3364 */
3365EAPI Eina_Bool evas_textblock_cursor_word_end(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3366
3367/**
3368 * Go to the first char in the node the cursor is pointing on.
3369 *
3370 * @param cur the cursor to update.
3371 * @return Returns no value.
3372 */
3373EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3374
3375/**
3376 * Go to the last char in a text node.
3377 *
3378 * @param cur the cursor to update.
3379 * @return Returns no value.
3380 */
3381EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3382
3383/**
3384 * Go to the start of the current line
3385 *
3386 * @param cur the cursor to update.
3387 * @return Returns no value.
3388 */
3389EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3390
3391/**
3392 * Go to the end of the current line.
3393 *
3394 * @param cur the cursor to update.
3395 * @return Returns no value.
3396 */
3397EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3398
3399/**
3400 * Return the current cursor pos.
3401 *
3402 * @param cur the cursor to take the position from.
3403 * @return the position or -1 on error
3404 */
3405EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3406
3407/**
3408 * Set the cursor pos.
3409 *
3410 * @param cur the cursor to be set.
3411 * @param pos the pos to set.
3412 */
3413EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
3414
3415/**
3416 * Go to the start of the line passed
3417 *
3418 * @param cur cursor to update.
3419 * @param line numer to set.
3420 * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
3421 */
3422EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
3423
3424/**
3425 * Compare two cursors.
3426 *
3427 * @param cur1 the first cursor.
3428 * @param cur2 the second cursor.
3429 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
3430 */
3431EAPI int evas_textblock_cursor_compare(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
3432
3433/**
3434 * Make cur_dest point to the same place as cur. Does not work if they don't
3435 * point to the same object.
3436 *
3437 * @param cur the source cursor.
3438 * @param cur_dest destination cursor.
3439 * @return Returns no value.
3440 */
3441EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
3442
3443/**
3444 * Adds text to the current cursor position and set the cursor to *before*
3445 * the start of the text just added.
3446 *
3447 * @param cur the cursor to where to add text at.
3448 * @param text the text to add.
3449 * @return Returns the len of the text added.
3450 * @see evas_textblock_cursor_text_prepend()
3451 */
3452EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
3453
3454/**
3455 * Adds text to the current cursor position and set the cursor to *after*
3456 * the start of the text just added.
3457 *
3458 * @param cur the cursor to where to add text at.
3459 * @param text the text to add.
3460 * @return Returns the len of the text added.
3461 * @see evas_textblock_cursor_text_append()
3462 */
3463EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
3464
3465/**
3466 * Adds format to the current cursor position. If the format being added is a
3467 * visible format, add it *before* the cursor position, otherwise, add it after.
3468 * This behavior is because visible formats are like characters and invisible
3469 * should be stacked in a way that the last one is added last.
3470 *
3471 * This function works with native formats, that means that style defined
3472 * tags like <br> won't work here. For those kind of things use markup prepend.
3473 *
3474 * @param cur the cursor to where to add format at.
3475 * @param format the format to add.
3476 * @return Returns true if a visible format was added, false otherwise.
3477 * @see evas_textblock_cursor_format_prepend()
3478 */
3479
3480/**
3481 * Check if the current cursor position points to the terminating null of the
3482 * last paragraph. (shouldn't be allowed to point to the terminating null of
3483 * any previous paragraph anyway.
3484 *
3485 * @param cur the cursor to look at.
3486 * @return @c EINA_TRUE if the cursor points to the terminating null, @c EINA_FALSE otherwise.
3487 */
3488EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
3489
3490/**
3491 * Adds format to the current cursor position. If the format being added is a
3492 * visible format, add it *before* the cursor position, otherwise, add it after.
3493 * This behavior is because visible formats are like characters and invisible
3494 * should be stacked in a way that the last one is added last.
3495 * If the format is visible the cursor is advanced after it.
3496 *
3497 * This function works with native formats, that means that style defined
3498 * tags like <br> won't work here. For those kind of things use markup prepend.
3499 *
3500 * @param cur the cursor to where to add format at.
3501 * @param format the format to add.
3502 * @return Returns true if a visible format was added, false otherwise.
3503 * @see evas_textblock_cursor_format_prepend()
3504 */
3505EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
3506
3507/**
3508 * Delete the character at the location of the cursor. If there's a format
3509 * pointing to this position, delete it as well.
3510 *
3511 * @param cur the cursor pointing to the current location.
3512 * @return Returns no value.
3513 */
3514EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3515
3516/**
3517 * Delete the range between cur1 and cur2.
3518 *
3519 * @param cur1 one side of the range.
3520 * @param cur2 the second side of the range
3521 * @return Returns no value.
3522 */
3523EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
3524
3525/**
3526 * Return the text of the paragraph cur points to - returns the text in markup.
3527 *
3528 * @param cur the cursor pointing to the paragraph.
3529 * @return the text on success, @c NULL otherwise.
3530 */
3531EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3532
3533/**
3534 * Return the length of the paragraph, cheaper the eina_unicode_strlen()
3535 *
3536 * @param cur the position of the paragraph.
3537 * @return the length of the paragraph on success, -1 otehrwise.
3538 */
3539EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3540
3541/**
3542 * Return the currently visible range.
3543 *
3544 * @param start the start of the range.
3545 * @param end the end of the range.
3546 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
3547 * @since 1.1
3548 */
3549EAPI Eina_Bool evas_textblock_cursor_visible_range_get(Evas_Textblock_Cursor *start, Evas_Textblock_Cursor *end) EINA_ARG_NONNULL(1, 2);
3550
3551/**
3552 * Return the format nodes in the range between cur1 and cur2.
3553 *
3554 * @param cur1 one side of the range.
3555 * @param cur2 the other side of the range
3556 * @return the foramt nodes in the range. You have to free it.
3557 * @since 1.1
3558 */
3559EAPI Eina_List *evas_textblock_cursor_range_formats_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
3560
3561/**
3562 * Return the text in the range between cur1 and cur2
3563 *
3564 * @param cur1 one side of the range.
3565 * @param cur2 the other side of the range
3566 * @param format The form on which to return the text. Markup - in textblock markup. Plain - UTF8.
3567 * @return the text in the range
3568 * @see elm_entry_markup_to_utf8()
3569 */
3570EAPI 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);
3571
3572/**
3573 * Return the content of the cursor.
3574 *
3575 * Free the returned string pointer when done (if it is not NULL).
3576 *
3577 * @param cur the cursor
3578 * @return the text in the range, terminated by a nul byte (may be utf8).
3579 */
3580EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
3581
3582/**
3583 * Returns the geometry of two cursors ("split cursor"), if logical cursor is
3584 * between LTR/RTL text, also considering paragraph direction.
3585 * Upper cursor is shown for the text of the same direction as paragraph,
3586 * lower cursor - for opposite.
3587 *
3588 * Split cursor geometry is valid only in '|' cursor mode.
3589 * In this case @c EINA_TRUE is returned and cx2, cy2, cw2, ch2 are set,
3590 * otherwise it behaves like cursor_geometry_get.
3591 *
3592 * @param[in] cur the cursor.
3593 * @param[out] cx the x of the cursor (or upper cursor)
3594 * @param[out] cy the y of the cursor (or upper cursor)
3595 * @param[out] cw the width of the cursor (or upper cursor)
3596 * @param[out] ch the height of the cursor (or upper cursor)
3597 * @param[out] cx2 the x of the lower cursor
3598 * @param[out] cy2 the y of the lower cursor
3599 * @param[out] cw2 the width of the lower cursor
3600 * @param[out] ch2 the height of the lower cursor
3601 * @param[in] dir the direction of the cursor, can be NULL.
3602 * @param[in] ctype the type of the cursor.
3603 * @return @c EINA_TRUE for split cursor, @c EINA_FALSE otherwise
3604 * @since 1.8
3605 */
3606EAPI Eina_Bool
3607evas_textblock_cursor_geometry_bidi_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch, Evas_Coord *cx2, Evas_Coord *cy2, Evas_Coord *cw2, Evas_Coord *ch2, Evas_Textblock_Cursor_Type ctype);
3608
3609/**
3610 * Returns the geometry of the cursor. Depends on the type of cursor requested.
3611 * This should be used instead of char_geometry_get because there are weird
3612 * special cases with BiDi text.
3613 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
3614 * get, except for the case of the last char of a line which depends on the
3615 * paragraph direction.
3616 *
3617 * in '|' cursor mode (i.e a line between two chars) it is very variable.
3618 * For example consider the following visual string:
3619 * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
3620 * a '|' between the c and the C.
3621 *
3622 * @param cur the cursor.
3623 * @param cx the x of the cursor
3624 * @param cy the y of the cursor
3625 * @param cw the width of the cursor
3626 * @param ch the height of the cursor
3627 * @param dir the direction of the cursor, can be NULL.
3628 * @param ctype the type of the cursor.
3629 * @return line number of the char on success, -1 on error.
3630 */
3631EAPI 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);
3632
3633/**
3634 * Returns the geometry of the char at cur.
3635 *
3636 * @param cur the position of the char.
3637 * @param cx the x of the char.
3638 * @param cy the y of the char.
3639 * @param cw the w of the char.
3640 * @param ch the h of the char.
3641 * @return line number of the char on success, -1 on error.
3642 */
3643EAPI 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);
3644
3645/**
3646 * Returns the geometry of the pen at cur.
3647 *
3648 * @param cur the position of the char.
3649 * @param cpen_x the pen_x of the char.
3650 * @param cy the y of the char.
3651 * @param cadv the adv of the char.
3652 * @param ch the h of the char.
3653 * @return line number of the char on success, -1 on error.
3654 */
3655EAPI 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);
3656
3657/**
3658 * Returns the geometry of the line at cur.
3659 *
3660 * @param cur the position of the line.
3661 * @param cx the x of the line.
3662 * @param cy the y of the line.
3663 * @param cw the width of the line.
3664 * @param ch the height of the line.
3665 * @return line number of the line on success, -1 on error.
3666 */
3667EAPI 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);
3668
3669/**
3670 * Set the position of the cursor according to the X and Y coordinates.
3671 *
3672 * @param cur the cursor to set.
3673 * @param x coord to set by.
3674 * @param y coord to set by.
3675 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
3676 */
3677EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
3678
3679/**
3680 * Set the cursor position according to the y coord.
3681 *
3682 * @param cur the cur to be set.
3683 * @param y the coord to set by.
3684 * @return the line number found, -1 on error.
3685 */
3686EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
3687
3688/**
3689 * Get the geometry of a range.
3690 *
3691 * @param cur1 one side of the range.
3692 * @param cur2 other side of the range.
3693 * @return a list of Rectangles representing the geometry of the range.
3694 */
3695EAPI 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);
3696EAPI 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);
3697
3698/**
3699 * Checks if the cursor points to the end of the line.
3700 *
3701 * @param cur the cursor to check.
3702 * @return @c EINA_TRUE if true, @c EINA_FALSE otherwise.
3703 */
3704EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3705
3706/**
3707 * @}
3708 */
3709
3710/**
3711 * @defgroup Evas_Object_Textgrid Textgrid Object Functions
3712 *
3713 * @todo put here some usage examples
3714 *
3715 * @since 1.7
3716 *
3717 * @ingroup Evas_Object_Specific
3718 *
3719 * @{
3720 */
3721
3722/**
3723 * @typedef Evas_Textgrid_Palette
3724 *
3725 * The palette to use for the forgraound and background colors.
3726 *
3727 * @since 1.7
3728 */
3729typedef enum
3730{
3731 EVAS_TEXTGRID_PALETTE_NONE, /**< No palette is used */
3732 EVAS_TEXTGRID_PALETTE_STANDARD, /**< standard palette (around 16 colors) */
3733 EVAS_TEXTGRID_PALETTE_EXTENDED, /**< extended palette (at max 256 colors) */
3734 EVAS_TEXTGRID_PALETTE_LAST /**< ignore it */
3735} Evas_Textgrid_Palette;
3736
3737/**
3738 * @typedef Evas_Textgrid_Font_Style
3739 *
3740 * The style to give to each character of the grid.
3741 *
3742 * @since 1.7
3743 */
3744typedef enum
3745{
3746 EVAS_TEXTGRID_FONT_STYLE_NORMAL = (1 << 0), /**< Normal style */
3747 EVAS_TEXTGRID_FONT_STYLE_BOLD = (1 << 1), /**< Bold style */
3748 EVAS_TEXTGRID_FONT_STYLE_ITALIC = (1 << 2) /**< Oblique style */
3749} Evas_Textgrid_Font_Style;
3750
3751/**
3752 * @typedef Evas_Textgrid_Cell
3753 *
3754 * The values that describes each cell.
3755 *
3756 * @since 1.7
3757 */
3758typedef struct _Evas_Textgrid_Cell Evas_Textgrid_Cell;
3759
3760/**
3761 * @struct _Evas_Textgrid_Cell
3762 *
3763 * The values that describes each cell.
3764 *
3765 * @since 1.7
3766 */
3767struct _Evas_Textgrid_Cell
3768{
3769 Eina_Unicode codepoint; /**< the UNICODE value of the character */
3770 unsigned char fg; /**< the index of the palette for the foreground color */
3771 unsigned char bg; /**< the index of the palette for the background color */
3772 unsigned short bold : 1; /**< whether the character is bold */
3773 unsigned short italic : 1; /**< whether the character is oblique */
3774 unsigned short underline : 1; /**< whether the character is underlined */
3775 unsigned short strikethrough : 1; /**< whether the character is strikethrough'ed */
3776 unsigned short fg_extended : 1; /**< whether the extended palette is used for the foreground color */
3777 unsigned short bg_extended : 1; /**< whether the extended palette is used for the background color */
3778 unsigned short double_width : 1; /**< if the codepoint is merged with the following cell to the right visually (cells must be in pairs with 2nd cell being a duplicate in all ways except codepoint is 0) */
3779};
3780
3781/**
3782 * @}
3783 */
3784
3785/**
3786 * @defgroup Evas_Line_Group Line Object Functions
3787 *
3788 * Functions used to deal with evas line objects.
3789 *
3790 * @warning We don't guarantee any proper results if you create a Line object
3791 * without setting the evas engine.
3792 *
3793 * @ingroup Evas_Object_Specific
3794 *
3795 */
3796
3797/**
3798 * @defgroup Evas_Object_Polygon Polygon Object Functions
3799 *
3800 * Functions that operate on evas polygon objects.
3801 *
3802 * Hint: as evas does not provide ellipse, smooth paths or circle, one
3803 * can calculate points and convert these to a polygon.
3804 *
3805 * @warning We don't guarantee any proper results if you create a Polygon
3806 * object without setting the evas engine.
3807 *
3808 * @ingroup Evas_Object_Specific
3809 *
3810 */
3811
3812/**
3813 * @defgroup Evas_Smart_Group Smart Functions
3814 * @ingroup Evas
3815 *
3816 * Functions that deal with #Evas_Smart structs, creating definition
3817 * (classes) of objects that will have customized behavior for methods
3818 * like evas_object_move(), evas_object_resize(),
3819 * evas_object_clip_set() and others.
3820 *
3821 * These objects will accept the generic methods defined in @ref
3822 * Evas_Object_Group and the extensions defined in @ref
3823 * Evas_Smart_Object_Group. There are a couple of existent smart
3824 * objects in Evas itself (see @ref Evas_Object_Box, @ref
3825 * Evas_Object_Table and @ref Evas_Smart_Object_Clipped).
3826 *
3827 * See also some @ref Example_Evas_Smart_Objects "examples" of this
3828 * group of functions.
3829 *
3830 * @{
3831 */
3832
3833
3834/**
3835 * @def EVAS_SMART_CLASS_VERSION
3836 *
3837 * The version you have to put into the version field in the
3838 * #Evas_Smart_Class struct. Used to safeguard from binaries with old
3839 * smart object intefaces running with newer ones.
3840 *
3841 * @ingroup Evas_Smart_Group
3842 */
3843#define EVAS_SMART_CLASS_VERSION 4
3844/**
3845 * @struct _Evas_Smart_Class
3846 *
3847 * A smart object's @b base class definition
3848 *
3849 * @ingroup Evas_Smart_Group
3850 */
3851struct _Evas_Smart_Class
3852{
3853 const char *name; /**< the name string of the class */
3854 int version;
3855 void (*add)(Evas_Object *o); /**< code to be run when adding object to a canvas */
3856 void (*del)(Evas_Object *o); /**< code to be run when removing object from a canvas */
3857 void (*move)(Evas_Object *o, Evas_Coord x, Evas_Coord y); /**< code to be run when moving object on a canvas. @a x and @a y will be new coordinates one applied to the object. use evas_object_geometry_get() if you need the old values, during this call. after that, the old values will be lost. */
3858 void (*resize)(Evas_Object *o, Evas_Coord w, Evas_Coord h); /**< code to be run when resizing object on a canvas. @a w and @a h will be new dimensions one applied to the object. use evas_object_geometry_get() if you need the old values, during this call. after that, the old values will be lost. */
3859 void (*show)(Evas_Object *o); /**< code to be run when showing object on a canvas */
3860 void (*hide)(Evas_Object *o); /**< code to be run when hiding object on a canvas */
3861 void (*color_set)(Evas_Object *o, int r, int g, int b, int a); /**< code to be run when setting color of object on a canvas. @a r, @a g, @a b and @a y will be new color components one applied to the object. use evas_object_color_get() if you need the old values, during this call. after that, the old values will be lost. */
3862 void (*clip_set)(Evas_Object *o, Evas_Object *clip); /**< code to be run when setting clipper of object on a canvas. @a clip will be new clipper one applied to the object. use evas_object_clip_get() if you need the old one, during this call. after that, the old (object pointer) value will be lost. */
3863 void (*clip_unset)(Evas_Object *o); /**< code to be run when unsetting clipper of object on a canvas. if you need the pointer to a previous set clipper, during this call, use evas_object_clip_get(). after that, the old (object pointer) value will be lost. */
3864 void (*calculate)(Evas_Object *o); /**< code to be run when object has rendering updates on a canvas */
3865 void (*member_add)(Evas_Object *o, Evas_Object *child); /**< code to be run when a child member is added to object */
3866 void (*member_del)(Evas_Object *o, Evas_Object *child); /**< code to be run when a child member is removed from object */
3867
3868 const Evas_Smart_Class *parent; /**< this class inherits from this parent */