2 # error You shall not include this header directly
12 * @def EVAS_VERSION_MAJOR
13 * The major number of evas version
15 #define EVAS_VERSION_MAJOR EFL_VERSION_MAJOR
18 * @def EVAS_VERSION_MINOR
19 * The minor number of eet version
21 #define EVAS_VERSION_MINOR EFL_VERSION_MINOR
26 * @typedef Evas_Version
28 * This is the Evas version information structure that can be used at
29 * runtime to detect which version of evas is being used and adapt
30 * appropriately as follows for example:
33 * #if defined(EVAS_VERSION_MAJOR) && (EVAS_VERSION_MAJOR >= 1) && defined(EVAS_VERSION_MINOR) && (EVAS_VERSION_MINOR > 0)
34 * printf("Evas version: %i.%i.%i\n",
35 * evas_version->major,
36 * evas_version->minor,
37 * evas_version->micro);
38 * if (evas_version->revision > 0)
40 * printf(" Built from Git revision # %i\n", evas_version->revision);
47 typedef struct _Evas_Version
49 int major; /**< major (binary or source incompatible changes) */
50 int minor; /**< minor (new features, bugfixes, major improvements version) */
51 int micro; /**< micro (bugfix, internal improvements, no new features version) */
52 int revision; /**< git revision (0 if a proper release or the git revision number Evas is built from) */
55 EAPI extern Evas_Version * evas_version;
59 * @brief These routines are used for Evas library interaction.
61 * @todo check boolean return values and convert to Eina_Bool
62 * @todo change all api to use EINA_SAFETY_*
63 * @todo finish api documentation
66 /* BiDi exposed stuff */
68 typedef enum _Evas_BiDi_Direction
70 EVAS_BIDI_DIRECTION_NATURAL,
71 EVAS_BIDI_DIRECTION_NEUTRAL = EVAS_BIDI_DIRECTION_NATURAL,
72 EVAS_BIDI_DIRECTION_LTR,
73 EVAS_BIDI_DIRECTION_RTL
74 } Evas_BiDi_Direction;
77 * Identifier of callbacks to be set for Evas canvases or Evas
80 * The following figure illustrates some Evas callbacks:
82 * @image html evas-callbacks.png
83 * @image rtf evas-callbacks.png
84 * @image latex evas-callbacks.eps
86 * @see evas_object_event_callback_add()
87 * @see evas_event_callback_add()
89 typedef enum _Evas_Callback_Type
92 * The following events are only for use with Evas objects, with
93 * evas_object_event_callback_add():
95 EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */
96 EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
97 EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
98 EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
99 EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
100 EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
101 EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
102 EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
103 EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
104 EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
105 EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
106 EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
107 EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
108 EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
109 EVAS_CALLBACK_SHOW, /**< Show Event */
110 EVAS_CALLBACK_HIDE, /**< Hide Event */
111 EVAS_CALLBACK_MOVE, /**< Move Event */
112 EVAS_CALLBACK_RESIZE, /**< Resize Event */
113 EVAS_CALLBACK_RESTACK, /**< Restack Event */
114 EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
115 EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
116 EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
117 EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */
120 * The following events are only for use with Evas canvases, with
121 * evas_event_callback_add():
123 EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
124 EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
125 EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */
126 EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
127 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
128 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
131 * More Evas object event types - see evas_object_event_callback_add():
133 EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanism in Evas that throw out original image data) */
135 EVAS_CALLBACK_RENDER_PRE, /**< Called just before rendering starts on the canvas target @since 1.2 */
136 EVAS_CALLBACK_RENDER_POST, /**< Called just after rendering stops on the canvas target @since 1.2 */
138 EVAS_CALLBACK_IMAGE_RESIZE, /**< Image size is changed @since 1.8 */
139 EVAS_CALLBACK_DEVICE_CHANGED, /**< Devices added, removed or changed on canvas @since 1.8 */
141 EVAS_CALLBACK_AXIS_UPDATE, /**< Input device changed value on some axis @since 1.13 */
142 EVAS_CALLBACK_CANVAS_VIEWPORT_RESIZE, /**< Canvas viewport resized @since 1.15 */
143 EVAS_CALLBACK_LAST /**< kept as last element/sentinel -- not really an event */
144 } Evas_Callback_Type; /**< The types of events triggering a callback */
147 * @def EVAS_CALLBACK_PRIORITY_BEFORE
148 * Slightly more prioritized than default.
151 #define EVAS_CALLBACK_PRIORITY_BEFORE -100
153 * @def EVAS_CALLBACK_PRIORITY_DEFAULT
154 * Default callback priority level
157 #define EVAS_CALLBACK_PRIORITY_DEFAULT 0
159 * @def EVAS_CALLBACK_PRIORITY_AFTER
160 * Slightly less prioritized than default.
163 #define EVAS_CALLBACK_PRIORITY_AFTER 100
166 * @typedef Evas_Callback_Priority
168 * Callback priority value. Range is -32k - 32k. The lower the number, the
169 * bigger the priority.
171 * @see EVAS_CALLBACK_PRIORITY_AFTER
172 * @see EVAS_CALLBACK_PRIORITY_BEFORE
173 * @see EVAS_CALLBACK_PRIORITY_DEFAULT
177 typedef Eo_Callback_Priority Evas_Callback_Priority;
180 * Flags for Mouse Button events
182 typedef enum _Evas_Button_Flags
184 EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
185 EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< This mouse button press was the 2nd press of a double click */
186 EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< This mouse button press was the 3rd press of a triple click */
187 } Evas_Button_Flags; /**< Flags for Mouse Button events */
192 typedef enum _Evas_Event_Flags
194 EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
195 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 */
196 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 */
197 } Evas_Event_Flags; /**< Flags for Events */
200 * State of Evas_Coord_Touch_Point
202 typedef enum _Evas_Touch_Point_State
204 EVAS_TOUCH_POINT_DOWN, /**< Touch point is pressed down */
205 EVAS_TOUCH_POINT_UP, /**< Touch point is released */
206 EVAS_TOUCH_POINT_MOVE, /**< Touch point is moved */
207 EVAS_TOUCH_POINT_STILL, /**< Touch point is not moved after pressed */
208 EVAS_TOUCH_POINT_CANCEL /**< Touch point is cancelled */
209 } Evas_Touch_Point_State;
212 * Flags for Font Hinting
213 * @ingroup Evas_Font_Group
215 typedef enum _Evas_Font_Hinting_Flags
217 EVAS_FONT_HINTING_NONE, /**< No font hinting */
218 EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
219 EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
220 } Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */
223 * How to pack items into cells in a table.
224 * @ingroup Evas_Object_Table
226 * @see evas_object_table_homogeneous_set() for an explanation of the function of
229 typedef enum _Evas_Object_Table_Homogeneous_Mode
231 EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0,
232 EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1,
233 EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2
234 } Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode. */
236 typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< A generic rectangle handle */
237 typedef struct _Evas_Point Evas_Point; /**< integer point */
239 typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */
240 typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */
242 typedef struct _Evas_Coord_Size Evas_Coord_Size; /**< Evas_Coord size @since 1.8 */
243 typedef struct _Evas_Coord_Precision_Size Evas_Coord_Precision_Size; /**< Evas_Coord size with sub-pixel precision @since 1.8 */
245 typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */
246 typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */
249 * @typedef Evas_Smart_Class
251 * A smart object's @b base class definition
253 * @ingroup Evas_Smart_Group
255 typedef struct _Evas_Smart_Class Evas_Smart_Class;
258 * @typedef Evas_Smart_Interface
260 * A smart object's @b base interface definition
262 * An Evas interface is exactly like the OO-concept: an 'contract' or
263 * API a given object is declared to support. A smart object may have
264 * more than one interface, thus extending the behavior it gets from
269 * @ingroup Evas_Smart_Group
271 typedef struct _Evas_Smart_Interface Evas_Smart_Interface;
274 * @typedef Evas_Smart_Cb_Description
276 * A smart object callback description, used to provide introspection
278 * @ingroup Evas_Smart_Group
280 typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
285 * An opaque handle to map points
287 * @see evas_map_new()
288 * @see evas_map_free()
289 * @see evas_map_dup()
291 * @ingroup Evas_Object_Group_Map
293 typedef struct _Evas_Map Evas_Map;
298 * An opaque handle to an Evas canvas.
303 * @ingroup Evas_Canvas
308 * @typedef Evas_Public_Data
309 * Public data for an Evas.
310 * @ingroup Evas_Canvas
312 typedef struct _Evas_Public_Data Evas_Public_Data;
315 * @typedef Evas_Object
316 * An Evas Object handle.
317 * @ingroup Evas_Object_Group
319 typedef Eo Evas_Object;
321 /* This define is used in H files generated by Eolian */
322 #define _EVAS_OBJECT_EO_CLASS_TYPE
325 * Type of abstract VG node
329 typedef void Evas_Performance; /**< An Evas Performance handle */
330 typedef struct _Evas_Modifier Evas_Modifier; /**< An opaque type containing information on which modifier keys are registered in an Evas canvas */
331 typedef struct _Evas_Lock Evas_Lock; /**< An opaque type containing information on which lock keys are registered in an Evas canvas */
332 typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
333 typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< A generic datatype for engine specific native surface information */
336 * @typedef Evas_Video_Surface
338 * A generic datatype for video specific surface information
339 * @see evas_object_image_video_surface_set
340 * @see evas_object_image_video_surface_get
343 typedef struct _Evas_Video_Surface Evas_Video_Surface;
345 typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */
347 typedef int Evas_Coord;/**< A type for coordinates */;
348 typedef int Evas_Font_Size; /**< A type for font size */
349 typedef int Evas_Angle; /**< A type for angle */
351 struct _Evas_Coord_Rectangle /** A rectangle in Evas_Coord */
353 Evas_Coord x; /**< top-left x co-ordinate of rectangle */
354 Evas_Coord y; /**< top-left y co-ordinate of rectangle */
355 Evas_Coord w; /**< width of rectangle */
356 Evas_Coord h; /**< height of rectangle */
359 struct _Evas_Coord_Point /** A Point in Evas_Coord */
361 Evas_Coord x; /**< x co-ordinate */
362 Evas_Coord y; /**< y co-ordinate */
365 struct _Evas_Coord_Size /** A size in Evas_Coord */
367 Evas_Coord w; /**< width */
368 Evas_Coord h; /**< height */
372 struct _Evas_Coord_Precision_Size /** A size in Evas_Coord with subpixel precision*/
374 Evas_Coord w; /**< width */
375 Evas_Coord h; /**< height */
376 double wsub; /**< subpixel precision for width */
377 double ysub; /**< subpixel precision for height */
380 struct _Evas_Coord_Precision_Point /** A point in Evas_Coord with subpixel precision*/
382 Evas_Coord x; /**< x co-ordinate */
383 Evas_Coord y; /**< y co-ordinate */
384 double xsub; /**< subpixel precision for x */
385 double ysub; /**< subpixel precision for y */
388 struct _Evas_Point /** A point */
390 int x; /**< x co-ordinate */
391 int y; /**< y co-ordinate */
394 struct _Evas_Position /** A position */
396 Evas_Point output; /**< position on the output */
397 Evas_Coord_Point canvas; /**< position on the canvas */
400 struct _Evas_Precision_Position /** A position with precision*/
402 Evas_Point output; /**< position on the output */
403 Evas_Coord_Precision_Point canvas; /**< position on the canvas */
406 typedef enum _Evas_Aspect_Control
408 EVAS_ASPECT_CONTROL_NONE = 0, /**< Preference on scaling unset */
409 EVAS_ASPECT_CONTROL_NEITHER = 1, /**< Same effect as unset preference on scaling */
410 EVAS_ASPECT_CONTROL_HORIZONTAL = 2, /**< Use all horizontal container space to place an object, using the given aspect */
411 EVAS_ASPECT_CONTROL_VERTICAL = 3, /**< Use all vertical container space to place an object, using the given aspect */
412 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 */
413 } Evas_Aspect_Control; /**< Aspect types/policies for scaling size hints, used for evas_object_size_hint_aspect_set() */
415 typedef enum _Evas_Display_Mode
417 EVAS_DISPLAY_MODE_NONE = 0, /**<Default mode */
418 // TIZEN_ONLY(20151014): add deprecated enum to keep backward compatibility
419 //EVAS_DISPLAY_MODE_COMPRESS = 1, /**< Use this mode when you want to give compress display mode hint to an object */
420 //EVAS_DISPLAY_MODE_EXPAND = 2, /**< Use this mode when you want to give expand display mode hint to an object */
421 //EVAS_DISPLAY_MODE_DONT_CHANGE = 3 /**< Use this mode when an object should not change its display mode */
422 EVAS_DISPLAY_MODE_INHERIT = 1, /** deprecated **/
423 EVAS_DISPLAY_MODE_COMPRESS = 2, /**< Use this mode when you want to give compress display mode hint to an object */
424 EVAS_DISPLAY_MODE_EXPAND = 3, /**< Use this mode when you want to give expand display mode hint to an object */
425 EVAS_DISPLAY_MODE_DONT_CHANGE = 4 /**< Use this mode when an object should not change its display mode */
427 } Evas_Display_Mode; /**< object's display mode type related with compress/expand or etc mode */
429 typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< A source description of pixels for importing pixels */
430 typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< A generic Evas Engine information structure */
431 typedef struct _Evas_Device Evas_Device; /**< A source device handle - where the event came from */
432 typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
433 typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
434 typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
435 typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
436 typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
437 typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
438 typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
439 typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
440 typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
441 typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
442 typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
443 typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< Event structure for #EVAS_CALLBACK_HOLD event callbacks */
444 typedef struct _Evas_Event_Render_Post Evas_Event_Render_Post; /**< Event structure that may come with #EVAS_CALLBACK_RENDER_POST event callbacks @since 1.8 */
445 typedef struct _Evas_Axis Evas_Axis; /**< Details for a single device axis state @since 1.13 */
446 typedef struct _Evas_Event_Axis_Update Evas_Event_Axis_Update; /**< Event structure for #EVAS_CALLBACK_AXIS_UPDATE event callbacks @since 1.13 */
448 typedef enum _Evas_Alloc_Error
450 EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */
451 EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */
452 EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded, but extra memory had to be found by freeing up speculative resources */
453 } Evas_Alloc_Error; /**< Possible allocation errors */
455 typedef Efl_Gfx_Fill_Spread Evas_Fill_Spread;
456 #define EVAS_TEXTURE_REFLECT EFL_GFX_FILL_REFLECT
457 #define EVAS_TEXTURE_REPEAT EFL_GFX_FILL_REPEAT
458 #define EVAS_TEXTURE_RESTRICT EFL_GFX_FILL_RESTRICT
459 #define EVAS_TEXTURE_RESTRICT_REFLECT EFL_GFX_FILL_RESTRICT_REFLECT
460 #define EVAS_TEXTURE_RESTRICT_REPEAT EFL_GFX_FILL_RESTRICT_REPEAT
461 #define EVAS_TEXTURE_PAD EFL_GFX_FILL_PAD
464 * @typedef Evas_Pixel_Import_Pixel_Format
465 * Pixel format for import call. See evas_object_image_pixels_import()
466 * @ingroup Evas_Object_Image
468 typedef enum _Evas_Pixel_Import_Pixel_Format
470 EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
471 EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
472 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 */
473 } Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
476 * @typedef Evas_Pixel_Import_Source
477 * A source description of pixels for importing pixels
478 * @ingroup Evas_Object_Image
480 struct _Evas_Pixel_Import_Source
482 Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
483 int w, h; /**< width and height of source in pixels */
484 void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
488 * @def EVAS_NATIVE_SURFACE_VERSION
489 * Magic version number to know what the native surface struct looks like
492 #define EVAS_NATIVE_SURFACE_VERSION 3
495 * Native surface types that image object supports
497 * @see Evas_Native_Surface
498 * @see evas_object_image_native_surface_set()
500 typedef enum _Evas_Native_Surface_Type
502 EVAS_NATIVE_SURFACE_NONE, /**< No surface type */
503 EVAS_NATIVE_SURFACE_X11, /**< X Window system based type. pixmap id or visual of the pixmap */
504 EVAS_NATIVE_SURFACE_OPENGL, /**< OpenGL system based type. texture or framebuffer id*/
505 // TIZEN_ONLY (20151014): Change the next value from 3 to 6 for backward compatibility
506 // EVAS_NATIVE_SURFACE_WL, /**< Wayland system based type. buffer of surface */
507 // TIZEN ONLY (20150112) : NOT FIXED
508 EVAS_NATIVE_SURFACE_TIZEN, /** deprecated **/
509 EVAS_NATIVE_SURFACE_TBM, /**< Tizen system based type. This is used for tizen buffer manager. */
510 EVAS_NATIVE_SURFACE_EVASGL, /**< Evas GL based type. evas gl surface */
512 // TIZEN_ONLY (20151014): Change the next value from 3 to 6 for backward compatibility
513 EVAS_NATIVE_SURFACE_WL, /**< Wayland system based type. buffer of surface */
514 } Evas_Native_Surface_Type;
517 * @brief A generic datatype for engine specific native surface information.
519 * Please fill up Evas_Native_Surface fields that regarded with current surface
520 * type. If you want to set the native surface type to
521 * EVAS_NATIVE_SURFACE_X11, you need to set union data with x11.visual or
522 * x11.pixmap. If you need to set the native surface as
523 * EVAS_NATIVE_SURFACE_OPENGL, on the other hand, you need to set union data
524 * with opengl.texture_id or opengl.framebuffer_id and so on.
525 * If you need to set the native surface as EVAS_NATIVE_SURFACE_WL,
526 * you need to set union data with wl.legacy_buffer. The version field
527 * should be set with EVAS_NATIVE_SURFACE_VERSION in order to check abi
528 * break in your application on the different efl library versions.
530 * @warning Native surface types totally depend on the system. Please
531 * be aware that the types are supported on your system before using
534 * @note The information stored in an @c Evas_Native_Surface returned by
535 * @ref evas_gl_native_surface_get() is not meant to be used by
536 * applications except for passing it to
537 * @ref evas_object_image_native_surface_set().
539 * @see evas_object_image_native_surface_set()
541 struct _Evas_Native_Surface
543 int version; /**< Current Native Surface Version. Use EVAS_NATIVE_SURFACE_VERSION */
544 Evas_Native_Surface_Type type; /**< Surface type. @see Evas_Native_Surface_Type */
548 void *visual; /**< visual of the pixmap to use (Visual) */
549 unsigned long pixmap; /**< pixmap id to use (Pixmap) */
550 } x11; /**< Set this struct fields if surface data is X11 based. */
554 unsigned int texture_id; /**< opengl texture id to use from glGenTextures() */
555 unsigned int framebuffer_id; /**< 0 if not a FBO, FBO id otherwise from glGenFramebuffers() */
556 unsigned int internal_format; /**< same as 'internalFormat' for glTexImage2D() */
557 unsigned int format; /**< same as 'format' for glTexImage2D() */
558 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) */
559 } opengl; /**< Set this struct fields if surface data is OpenGL based. */
563 void *legacy_buffer; /**< wayland client buffer to use */
564 } wl; /**< Set this struct fields if surface data is Wayland based. */
566 // TIZEN ONLY (20150113) : NOT FIXED
568 * @deprecated use tbm struct
572 void *buffer; /**< tbm surface */
573 int rot; /**< rotation (0, 90, 180, 270) */
574 float ratio; /**< width/height ratio of the source image */
575 int flip; /**< flip (0:none, 1:horizontal, 2:vertical, 3:both) */
576 } tizen; /**< Set this struct fields if your surface data is Tizen based. */
580 void *buffer; /**< tbm surface */
581 int rot; /**< rotation (0, 90, 180, 270) */
582 float ratio; /**< width/height ratio of the source image */
583 int flip; /**< flip (0:none, 1:horizontal, 2:vertical, 3:both) */
584 } tbm; /**< Set this struct fields if your surface data is Tizen based. */
587 void *surface; /**< evas gl surface to use */
588 } evasgl; /**< Set this struct fields if surface data is Evas GL based. */
590 } data; /**< Choose one union data according to your surface. */
594 * @def EVAS_VIDEO_SURFACE_VERSION
595 * Magic version number to know what the video surf struct looks like
598 #define EVAS_VIDEO_SURFACE_VERSION 1
601 typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface); /**< Evas video callback function signature */
602 typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b); /**< Evas video coordinates callback function signature */
604 struct _Evas_Video_Surface
606 int version; /**< The Evas Video surface version in use @see EVAS_VIDEO_SURFACE_VERSION*/
608 Evas_Video_Coord_Cb move; /**< Move the video surface to this position */
609 Evas_Video_Coord_Cb resize; /**< Resize the video surface to that size */
610 Evas_Video_Cb show; /**< Show the video overlay surface */
611 Evas_Video_Cb hide; /**< Hide the video overlay surface */
612 Evas_Video_Cb update_pixels; /**< Please update the Evas_Object_Image pixels when called */
614 Evas_Object *parent; /**< The parent object */
619 * Enum values for the Video surface capabilities
622 typedef enum _Evas_Video_Surface_Caps
624 EVAS_VIDEO_SURFACE_MOVE = 1, /**< Move capability */
625 EVAS_VIDEO_SURFACE_RESIZE = 2, /**< Resize capability */
626 EVAS_VIDEO_SURFACE_CLIP = 4, /**< Clip capability */
627 EVAS_VIDEO_SURFACE_BELOW = 8, /**< Below capability */
628 EVAS_VIDEO_SURFACE_STACKING_CHECK = 16, /**< Stacking capability */
629 EVAS_VIDEO_SURFACE_IGNORE_WINDOW = 32, /**< Ignore window capability */
630 } Evas_Video_Surface_Caps;
632 #define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
633 #define EVAS_LAYER_MAX 32767 /**< top-most layer number */
635 #define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
636 #define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
637 #define EVAS_TEXT_INVALID -1 /**< Not used for anything */
638 #define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
640 #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() */
641 #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() */
644 * @brief Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align)
645 * @if MOBILE @since_tizen 2.3
646 * @elseif WEARABLE @since_tizen 2.3.1
648 * @ingroup Evas_Object_Group_Size_Hints
650 #define evas_object_size_hint_fill_set evas_object_size_hint_align_set
653 * @brief Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align)
654 * @if MOBILE @since_tizen 2.3
655 * @elseif WEARABLE @since_tizen 2.3.1
657 * @ingroup Evas_Object_Group_Size_Hints
659 #define evas_object_size_hint_fill_get evas_object_size_hint_align_get
662 * @brief Convenience macro to make it easier to understand that weight is also used for expand properties
663 * @if MOBILE @since_tizen 2.3
664 * @elseif WEARABLE @since_tizen 2.3.1
666 * @ingroup Evas_Object_Group_Size_Hints
668 #define evas_object_size_hint_expand_set evas_object_size_hint_weight_set
671 * @brief Convenience macro to make it easier to understand that weight is also used for expand properties
672 * @if MOBILE @since_tizen 2.3
673 * @elseif WEARABLE @since_tizen 2.3.1
675 * @ingroup Evas_Object_Group_Size_Hints
677 #define evas_object_size_hint_expand_get evas_object_size_hint_weight_get
680 * How the object should be rendered to output.
681 * @ingroup Evas_Object_Group_Extras
683 typedef enum _Evas_Render_Op
685 EVAS_RENDER_BLEND = 0, /**< default op: d = d*(1-sa) + s */
686 EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
687 EVAS_RENDER_COPY = 2, /**< d = s */
688 EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
689 EVAS_RENDER_ADD = 4, /* d = d + s */
690 EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
691 EVAS_RENDER_SUB = 6, /**< d = d - s */
692 EVAS_RENDER_SUB_REL = 7, /* d = d - s*da */
693 EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
694 EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
695 EVAS_RENDER_MASK = 10, /**< d = d*sa */
696 EVAS_RENDER_MUL = 11 /**< d = d*s */
697 } Evas_Render_Op; /**< How the object should be rendered to output. */
699 typedef enum _Evas_Border_Fill_Mode
701 EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */
702 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 */
703 EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */
704 } Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */
706 typedef enum _Evas_Engine_Render_Mode
708 EVAS_RENDER_MODE_BLOCKING = 0, /**< The rendering is blocking mode*/
709 EVAS_RENDER_MODE_NONBLOCKING = 1, /**< The rendering is non blocking mode*/
710 } Evas_Engine_Render_Mode; /**< behaviour of the renderer*/
712 typedef enum _Evas_Image_Content_Hint
714 EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
715 EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents will change over time */
716 EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents won't change over time */
717 } Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
719 typedef enum _Evas_Device_Class
721 EVAS_DEVICE_CLASS_NONE, /**< Not a device @since 1.8 */
722 EVAS_DEVICE_CLASS_SEAT, /**< The user/seat (the user themselves) @since 1.8 */
723 EVAS_DEVICE_CLASS_KEYBOARD, /**< A regular keyboard, numberpad or attached buttons @since 1.8 */
724 EVAS_DEVICE_CLASS_MOUSE, /**< A mouse, trackball or touchpad relative motion device @since 1.8 */
725 EVAS_DEVICE_CLASS_TOUCH, /**< A touchscreen with fingers or stylus @since 1.8 */
726 EVAS_DEVICE_CLASS_PEN, /**< A special pen device @since 1.8 */
727 EVAS_DEVICE_CLASS_POINTER, /**< A laser pointer, wii-style or minority report pointing device @since 1.8 */
728 EVAS_DEVICE_CLASS_GAMEPAD /**< A gamepad controller or joystick @since 1.8 */
729 } Evas_Device_Class; /**< A general class of device @since 1.8 */
731 typedef enum _Evas_Device_Subclass
733 EVAS_DEVICE_SUBCLASS_NONE, /**< Not a device @since 1.8 */
734 EVAS_DEVICE_SUBCLASS_FINGER, /**< The normal flat of your finger @since 1.8 */
735 EVAS_DEVICE_SUBCLASS_FINGERNAIL, /**< A fingernail @since 1.8 */
736 EVAS_DEVICE_SUBCLASS_KNUCKLE, /**< A Knuckle @since 1.8 */
737 EVAS_DEVICE_SUBCLASS_PALM, /**< The palm of a users hand @since 1.8 */
738 EVAS_DEVICE_SUBCLASS_HAND_SIZE, /**< The side of your hand @since 1.8 */
739 EVAS_DEVICE_SUBCLASS_HAND_FLAT, /**< The flat of your hand @since 1.8 */
740 EVAS_DEVICE_SUBCLASS_PEN_TIP, /**< The tip of a pen @since 1.8 */
741 EVAS_DEVICE_SUBCLASS_TRACKPAD, /**< A trackpad style mouse @since 1.8 */
742 EVAS_DEVICE_SUBCLASS_TRACKPOINT, /**< A trackpoint style mouse @since 1.8 */
743 EVAS_DEVICE_SUBCLASS_TRACKBALL, /**< A trackball style mouse @since 1.8 */
744 } Evas_Device_Subclass; /**< A general class of device @since 1.8 */
746 struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
748 int magic; /**< Magic number */
751 struct _Evas_Event_Mouse_Down /** Mouse button press event */
753 int button; /**< Mouse button number that went down (1 - 32) */
755 Evas_Point output; /**< The X/Y location of the cursor */
756 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
759 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
762 Evas_Button_Flags flags; /**< button flags set during the event */
763 unsigned int timestamp;
764 Evas_Event_Flags event_flags;
766 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
769 struct _Evas_Event_Mouse_Up /** Mouse button release event */
771 int button; /**< Mouse button number that was raised (1 - 32) */
773 Evas_Point output; /**< The X/Y location of the cursor */
774 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
777 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
780 Evas_Button_Flags flags; /**< button flags set during the event */
781 unsigned int timestamp;
782 Evas_Event_Flags event_flags;
784 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
787 struct _Evas_Event_Mouse_In /** Mouse enter event */
789 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
791 Evas_Point output; /**< The X/Y location of the cursor */
792 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
795 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
797 unsigned int timestamp;
798 Evas_Event_Flags event_flags;
800 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
803 struct _Evas_Event_Mouse_Out /** Mouse leave event */
805 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
807 Evas_Point output; /**< The X/Y location of the cursor */
808 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
811 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
813 unsigned int timestamp;
814 Evas_Event_Flags event_flags;
816 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
819 struct _Evas_Event_Mouse_Move /** Mouse move event */
821 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
823 Evas_Position cur; /**< Current mouse position */
824 Evas_Position prev; /**< Previous mouse position */
827 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
829 unsigned int timestamp;
830 Evas_Event_Flags event_flags;
832 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
835 struct _Evas_Event_Mouse_Wheel /** Wheel event */
837 int direction; /* 0 = default up/down wheel FIXME: more wheel types */
838 int z; /* ...,-2,-1 = down, 1,2,... = up */
840 Evas_Point output; /**< The X/Y location of the cursor */
841 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
844 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
846 unsigned int timestamp;
847 Evas_Event_Flags event_flags;
851 struct _Evas_Event_Multi_Down /** Multi button press event */
853 int device; /**< Multi device number that went down (1 or more for extra touches) */
854 double radius, radius_x, radius_y;
855 double pressure, angle;
858 Evas_Coord_Precision_Point canvas;
861 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
864 Evas_Button_Flags flags; /**< button flags set during the event */
865 unsigned int timestamp;
866 Evas_Event_Flags event_flags;
870 struct _Evas_Event_Multi_Up /** Multi button release event */
872 int device; /**< Multi device number that went up (1 or more for extra touches) */
873 double radius, radius_x, radius_y;
874 double pressure, angle;
877 Evas_Coord_Precision_Point canvas;
880 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
883 Evas_Button_Flags flags; /**< button flags set during the event */
884 unsigned int timestamp;
885 Evas_Event_Flags event_flags;
889 struct _Evas_Event_Multi_Move /** Multi button down event */
891 int device; /**< Multi device number that moved (1 or more for extra touches) */
892 double radius, radius_x, radius_y;
893 double pressure, angle;
895 Evas_Precision_Position cur;
898 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
900 unsigned int timestamp;
901 Evas_Event_Flags event_flags;
905 struct _Evas_Event_Key_Down /** Key press event */
907 char *keyname; /**< the name string of the key pressed */
909 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
912 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
913 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
914 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 */
915 unsigned int timestamp;
916 Evas_Event_Flags event_flags;
919 unsigned int keycode; /**< Key scan code numeric value @since 1.10 */
922 struct _Evas_Event_Key_Up /** Key release event */
924 char *keyname; /**< the name string of the key released */
926 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
929 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
930 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
931 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 */
932 unsigned int timestamp;
933 Evas_Event_Flags event_flags;
936 unsigned int keycode; /**< Key scan code numeric value @since 1.10 */
939 struct _Evas_Event_Render_Post /** Send when the frame rendering is done @since 1.8 */
941 Eina_List *updated_area; /**< A list of rectangle that were updated in the canvas */
944 struct _Evas_Event_Hold /** Hold change event */
946 int hold; /**< The hold flag */
949 unsigned int timestamp;
950 Evas_Event_Flags event_flags;
954 typedef enum _Evas_Axis_Label
956 EVAS_AXIS_LABEL_UNKNOWN, /**< Axis containing unknown (or not yet representable) data. Range: Unbounded. Unit: Undefined. @since 1.13 */
957 EVAS_AXIS_LABEL_X, /**< Position along physical X axis; not window relative. Range: Unbounded. Unit: Undefined. @since 1.13 */
958 EVAS_AXIS_LABEL_Y, /**< Position along physical Y axis; not window relative. Range: Unbounded. Unit: Undefined. @since 1.13 */
959 EVAS_AXIS_LABEL_PRESSURE, /**< Force applied to tool tip. Range: [0.0, 1.0]. Unit: Unitless. @since 1.13 */
960 EVAS_AXIS_LABEL_DISTANCE, /**< Relative distance along physical Z axis. Range: [0.0, 1.0]. Unit: Unitless @since 1.13 */
961 EVAS_AXIS_LABEL_AZIMUTH, /**< Angle of tool about the Z axis from positive X axis. Range: [-PI, PI]. Unit: Radians. @since 1.13 */
962 EVAS_AXIS_LABEL_TILT, /**< Angle of tool about plane of sensor from positive Z axis. Range: [0.0, PI]. Unit: Radians. @since 1.13 */
963 EVAS_AXIS_LABEL_TWIST, /**< Rotation of tool about its major axis from its natural position. Range: [-PI, PI] Unit: Radians. @since 1.13 */
964 EVAS_AXIS_LABEL_TOUCH_WIDTH_MAJOR, /**< Length of contact ellipse along AZIMUTH. Range: Unbounded: Unit: Same as EVAS_AXIS_LABEL_{X,Y}. @since 1.13 */
965 EVAS_AXIS_LABEL_TOUCH_WIDTH_MINOR, /**< Length of contact ellipse perpendicular to AZIMUTH. Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}. @since 1.13 */
966 EVAS_AXIS_LABEL_TOOL_WIDTH_MAJOR, /**< Length of tool ellipse along AZIMUTH. Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}. @since 1.13 */
967 EVAS_AXIS_LABEL_TOOL_WIDTH_MINOR /**< Length of tool ellipse perpendicular to AZIMUTH. Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}. @since 1.13 */
968 } Evas_Axis_Label; /**< Types of recognized device axes @since 1.13 */
972 Evas_Axis_Label label;
976 struct _Evas_Event_Axis_Update
980 unsigned int timestamp;
990 * How the mouse pointer should be handled by Evas.
992 * In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button
993 * is pressed down over an object and held, with the mouse pointer
994 * being moved outside of it, the pointer still behaves as being bound
995 * to that object, albeit out of its drawing region. When the button
996 * is released, the event will be fed to the object, that may check if
997 * the final position is over it or not and do something about it.
999 * In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will
1000 * always be bound to the object right below it.
1002 * @ingroup Evas_Object_Group_Extras
1004 typedef enum _Evas_Object_Pointer_Mode
1006 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
1007 EVAS_OBJECT_POINTER_MODE_NOGRAB, /**< pointer always bound to the object right below it */
1008 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 */
1009 } Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
1012 * @brief Evas smart objects' smart callback function signature
1013 * @if MOBILE @since_tizen 2.3
1014 * @elseif WEARABLE @since_tizen 2.3.1
1016 * @ingroup Evas_Smart_Object_Group
1018 typedef void (*Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info);
1021 * @brief Evas event callback function signature
1022 * @if MOBILE @since_tizen 2.3
1023 * @elseif WEARABLE @since_tizen 2.3.1
1025 * @ingroup Evas_Canvas_Events
1027 typedef void (*Evas_Event_Cb)(void *data, Evas *e, void *event_info);
1030 * @brief Evas event callback Post function signature
1031 * @if MOBILE @since_tizen 2.3
1032 * @elseif WEARABLE @since_tizen 2.3.1
1034 * @ingroup Evas_Canvas_Events
1036 typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e);
1039 * @brief Evas object event callback function signature
1040 * @if MOBILE @since_tizen 2.3
1041 * @elseif WEARABLE @since_tizen 2.3.1
1043 * @ingroup Evas_Object_Group_Events
1045 typedef void (*Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info);
1048 * @brief Evas Async events put function signature
1049 * @if MOBILE @since_tizen 2.3
1050 * @elseif WEARABLE @since_tizen 2.3.1
1052 * @ingroup Evas_Top_Group
1054 typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
1062 * @defgroup Evas_Main_Group Top Level Functions
1065 * Functions that affect Evas as a whole.
1071 * Get the path for the cserve binary to execute
1073 * There is little need for anyone except a desktop environment to call this.
1074 * This can be called before evas_init() has been called. It will try and find
1075 * the full path to the to the cserve binary to run to provide cserve image
1076 * and font caching services for evas.
1078 * @return NULL if error, or a string with the full path to the cserve binary.
1082 EAPI const char *evas_cserve_path_get(void);
1087 * @return The init counter value.
1089 * This function initializes Evas and increments a counter of the
1090 * number of calls to it. It returns the new counter's value.
1092 * @if MOBILE @since_tizen 2.3
1093 * @elseif WEARABLE @since_tizen 2.3.1
1096 * @see evas_shutdown().
1098 * Most EFL users wouldn't be using this function directly, because
1099 * they wouldn't access Evas directly by themselves. Instead, they
1100 * would be using higher level helpers, like @c ecore_evas_init().
1103 * You should be using this if your use is something like the
1104 * following. The buffer engine is just one of the many ones Evas
1107 * @dontinclude evas-buffer-simple.c
1110 * And being the canvas creation something like:
1111 * @skip static Evas *create_canvas
1112 * @until evas_output_viewport_set(canvas,
1114 * Note that this is code creating an Evas canvas with no usage of
1115 * Ecore helpers at all -- no linkage with Ecore on this scenario,
1116 * thus. Again, this wouldn't be on Evas common usage for most
1117 * developers. See the full @ref Example_Evas_Buffer_Simple example.
1119 * @ingroup Evas_Main_Group
1121 EAPI int evas_init(void);
1126 * @return Evas' init counter value.
1128 * This function finalizes Evas, decrementing the counter of the
1129 * number of calls to the function evas_init(). This new value for the
1130 * counter is returned.
1132 * @if MOBILE @since_tizen 2.3
1133 * @elseif WEARABLE @since_tizen 2.3.1
1138 * If you were the sole user of Evas, by means of evas_init(), you can
1139 * check if it's being properly shut down by expecting a return value
1142 * Example code follows.
1143 * @dontinclude evas-buffer-simple.c
1144 * @skip // NOTE: use ecore_evas_buffer_new
1145 * @until evas_shutdown
1146 * Where that function would contain:
1147 * @skip evas_free(canvas)
1148 * @until evas_free(canvas)
1150 * Most users would be using ecore_evas_shutdown() instead, like told
1151 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
1154 * @ingroup Evas_Main_Group
1156 EAPI int evas_shutdown(void);
1159 * Return if any allocation errors have occurred during the prior function
1160 * @return The allocation error flag
1162 * @if MOBILE @since_tizen 2.3
1163 * @elseif WEARABLE @since_tizen 2.3.1
1166 * This function will return if any memory allocation errors occurred during,
1167 * and what kind they were. The return value will be one of
1168 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
1169 * with each meaning something different.
1171 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
1172 * worked as expected.
1174 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
1175 * its job and will have exited as cleanly as possible. The programmer
1176 * should consider this as a sign of very low memory and should try and safely
1177 * recover from the prior functions failure (or try free up memory elsewhere
1178 * and try again after more memory is freed).
1180 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
1181 * recovered from by evas finding memory of its own it has allocated and
1182 * freeing what it sees as not really usefully allocated memory. What is freed
1183 * may vary. Evas may reduce the resolution of images, free cached images or
1184 * fonts, throw out pre-rendered data, reduce the complexity of change lists
1185 * etc. Evas and the program will function as per normal after this, but this
1186 * is a sign of low memory, and it is suggested that the program try and
1187 * identify memory it doesn't need, and free it.
1191 * extern Evas_Object *object;
1192 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
1194 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
1195 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
1197 * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
1198 * fprintf(stderr, " destroy object now as it cannot be used.\n");
1199 * evas_object_del(object);
1201 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1202 * my_memory_cleanup();
1204 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
1206 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1207 * my_memory_cleanup();
1211 * @ingroup Evas_Main_Group
1213 EAPI Evas_Alloc_Error evas_alloc_error(void);
1216 * @brief Get evas' internal asynchronous events read file descriptor.
1218 * @if MOBILE @since_tizen 2.3
1219 * @elseif WEARABLE @since_tizen 2.3.1
1222 * @return The canvas' asynchronous events read file descriptor.
1224 * Evas' asynchronous events are meant to be dealt with internally,
1225 * i. e., when building stuff to be glued together into the EFL
1226 * infrastructure -- a module, for example. The context which demands
1227 * its use is when calculations need to be done out of the main
1228 * thread, asynchronously, and some action must be performed after
1231 * An example of actual use of this API is for image asynchronous
1232 * preload inside evas. If the canvas was instantiated through
1233 * ecore-evas usage, ecore itself will take care of calling those
1234 * events' processing.
1236 * This function returns the read file descriptor where to get the
1237 * asynchronous events of the canvas. Naturally, other mainloops,
1238 * apart from ecore, may make use of it.
1240 * @ingroup Evas_Main_Group
1242 EAPI int evas_async_events_fd_get(void) EINA_WARN_UNUSED_RESULT;
1245 * @brief Trigger the processing of all events waiting on the file
1246 * descriptor returned by evas_async_events_fd_get().
1248 * @if MOBILE @since_tizen 2.3
1249 * @elseif WEARABLE @since_tizen 2.3.1
1252 * @return The number of events processed.
1254 * All asynchronous events queued up by evas_async_events_put() are
1255 * processed here. More precisely, the callback functions, informed
1256 * together with other event parameters, when queued, get called (with
1257 * those parameters), in that order.
1259 * @ingroup Evas_Main_Group
1261 EAPI int evas_async_events_process(void);
1264 * Insert asynchronous events on the canvas.
1266 * @if MOBILE @since_tizen 2.3
1267 * @elseif WEARABLE @since_tizen 2.3.1
1270 * @param target The target to be affected by the events.
1271 * @param type The type of callback function.
1272 * @param event_info Information about the event.
1273 * @param func The callback function pointer.
1275 * @return EINA_FALSE if an error occured, EINA_TRUE otherwise.
1277 * This is the way, for a routine running outside evas' main thread,
1278 * to report an asynchronous event. A callback function is informed,
1279 * whose call is to happen after evas_async_events_process() is
1282 * @ingroup Evas_Main_Group
1284 EAPI Eina_Bool evas_async_events_put(const void *target, Evas_Callback_Type type, void *event_info, Evas_Async_Events_Put_Cb func) EINA_ARG_NONNULL(1, 4);
1287 * @defgroup Evas_Canvas Canvas Functions
1290 * Low level Evas canvas functions. Sub groups will present more high
1291 * level ones, though.
1293 * Most of these functions deal with low level Evas actions, like:
1294 * @li create/destroy raw canvases, not bound to any displaying engine
1295 * @li tell a canvas i got focused (in a windowing context, for example)
1296 * @li tell a canvas a region should not be calculated anymore in rendering
1297 * @li tell a canvas to render its contents, immediately
1299 * Most users will be using Evas by means of the @c Ecore_Evas
1300 * wrapper, which deals with all the above mentioned issues
1301 * automatically for them. Thus, you'll be looking at this section
1302 * only if you're building low level stuff.
1304 * The groups within present you functions that deal with the canvas
1305 * directly, too, and not yet with its @b objects. They are the
1306 * functions you need to use at a minimum to get a working canvas.
1308 * Some of the functions in this group are exemplified @ref
1309 * Example_Evas_Events here.
1316 * @defgroup Evas_Output_Method Render Engine Functions
1318 * Functions that are used to set the render engine for a given
1319 * function, and then get that engine working.
1321 * The following code snippet shows how they can be used to
1322 * initialise an evas that uses the X11 software engine:
1324 * @ingroup Evas_Canvas
1330 * @brief Look up a numeric ID from a string name of a rendering engine.
1332 * @if MOBILE @since_tizen 2.3
1333 * @elseif WEARABLE @since_tizen 2.3.1
1336 * @param[in] name the name string of an engine
1337 * @return A numeric (opaque) ID for the rendering engine
1338 * @ingroup Evas_Output_Method
1340 * @remark This function looks up a numeric return value for the named engine
1341 * in the string @p name. This is a normal C string, NUL byte
1342 * terminated. The name is case sensitive. If the rendering engine is
1343 * available, a numeric ID for that engine is returned that is not
1344 * 0. If the engine is not available, 0 is returned, indicating an
1347 * @remark The programmer should NEVER rely on the numeric ID of an engine
1348 * unless it is returned by this function. Programs should NOT be
1349 * written accessing render method ID's directly, without first
1350 * obtaining it from this function.
1352 * @attention it is mandatory that one calls Evas Initialization function before
1353 * looking up the render method.
1357 EAPI int evas_render_method_lookup(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1360 * @brief List all the rendering engines compiled into the copy of the Evas library
1362 * @if MOBILE @since_tizen 2.3
1363 * @elseif WEARABLE @since_tizen 2.3.1
1366 * @return A linked list whose data members are C strings of engine names
1367 * @ingroup Evas_Output_Method
1369 * @remark Calling this will return a handle (pointer) to an Evas linked
1370 * list. Each node in the linked list will have the data pointer be a
1371 * (char *) pointer to the name string of the rendering engine
1372 * available. The strings should never be modified, neither should the
1373 * list be modified. This list should be cleaned up as soon as the
1374 * program no longer needs it using evas_render_method_list_free(). If
1375 * no engines are available from Evas, @c NULL will be returned.
1379 * Eina_List *engine_list, *l;
1380 * char *engine_name;
1382 * engine_list = evas_render_method_list();
1385 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1388 * printf("Available Evas Engines:\n");
1389 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1390 * printf("%s\n", engine_name);
1391 * evas_render_method_list_free(engine_list);
1394 EAPI Eina_List *evas_render_method_list(void) EINA_WARN_UNUSED_RESULT;
1397 * @brief This function should be called to free a list of engine names
1399 * @if MOBILE @since_tizen 2.3
1400 * @elseif WEARABLE @since_tizen 2.3.1
1403 * @param[in] list The Eina_List base pointer for the engine list to be freed
1404 * @ingroup Evas_Output_Method
1406 * @remark When this function is called it will free the engine list passed in
1407 * as @p list. The list should only be a list of engines generated by
1408 * calling evas_render_method_list(). If @p list is NULL, nothing will
1413 * Eina_List *engine_list, *l;
1414 * char *engine_name;
1416 * engine_list = evas_render_method_list();
1419 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1422 * printf("Available Evas Engines:\n");
1423 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1424 * printf("%s\n", engine_name);
1425 * evas_render_method_list_free(engine_list);
1428 EAPI void evas_render_method_list_free(Eina_List *list);
1435 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1437 * Functions that are used to map coordinates from the canvas to the
1438 * screen or the screen to the canvas.
1440 * @ingroup Evas_Canvas
1444 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1446 * Functions that set and retrieve the output and viewport size of an
1449 * @ingroup Evas_Canvas
1453 * @defgroup Evas_Canvas_Events Canvas Events
1455 * Functions relating to canvas events, which are mainly reports on
1456 * its internal states changing (an object got focused, the rendering
1459 * Some of the functions in this group are exemplified @ref
1460 * Example_Evas_Events here.
1462 * @ingroup Evas_Canvas
1468 * @brief Free the rectangles returned by evas_render_updates().
1470 * @if MOBILE @since_tizen 2.3
1471 * @elseif WEARABLE @since_tizen 2.3.1
1474 * @param[in] updates The list of updated rectangles of the canvas.
1476 * @remark This function removes the region from the render updates list. It
1477 * makes the region doesn't be render updated anymore.
1479 * @see evas_render_updates() for an example
1481 * @ingroup Evas_Canvas
1483 EAPI void evas_render_updates_free(Eina_List *updates);
1490 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
1492 * Functions that deal with the freezing of input event processing of
1495 * There might be scenarios during a graphical user interface
1496 * program's use when the developer wishes the users wouldn't be able
1497 * to deliver input events to this application. It may, for example,
1498 * be the time for it to populate a view or to change some
1499 * layout. Assuming proper behavior with user interaction during this
1500 * exact time would be hard, as things are in a changing state. The
1501 * programmer can then tell the canvas to ignore input events,
1502 * bringing it back to normal behavior when he/she wants.
1504 * Most of the time use of freezing events is done like this:
1506 * evas_event_freeze(my_evas_canvas);
1507 * function_that_does_work_which_cant_be_interrupted_by_events();
1508 * evas_event_thaw(my_evas_canvas);
1511 * Some of the functions in this group are exemplified @ref
1512 * Example_Evas_Events here.
1514 * @ingroup Evas_Canvas_Events
1519 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
1521 * Functions to tell Evas that input events happened and should be
1524 * @warning Most of the time these functions are @b not what you're looking for.
1525 * These functions should only be used if you're not working with ecore evas(or
1526 * another input handling system). If you're not using ecore evas please
1527 * consider using it, in most situation it will make life a lot easier.
1529 * As explained in @ref intro_not_evas, Evas does not know how to poll
1530 * for input events, so the developer should do it and then feed such
1531 * events to the canvas to be processed. This is only required if
1532 * operating Evas directly. Modules such as Ecore_Evas do that for
1535 * Some of the functions in this group are exemplified @ref
1536 * Example_Evas_Events here.
1538 * @ingroup Evas_Canvas_Events
1543 * @addtogroup Evas_Event_Feeding_Group
1548 * Add a new device type
1550 * @param e The canvas to create the device node for.
1552 * Adds a new device node to the given canvas @p e. All devices created as
1553 * part of the canvas @p e will automatically be deleted when the canvas
1556 * @return the device node created or NULL if an error occured.
1558 * @see evas_device_del
1561 EAPI Evas_Device *evas_device_add(Evas *e);
1564 * Delete a new device type
1566 * @param dev The device node you want to delete.
1568 * @see evas_device_add
1569 * @see evas_device_push
1570 * @see evas_device_pop
1573 EAPI void evas_device_del(Evas_Device *dev);
1576 * Push the current context device onto the device stack
1578 * @param e The canvas to push the device on to
1579 * @param dev The device to push.
1581 * This pushes the given device @p dev onto the stack for the canvas @p e
1582 * resulting in the dev pointer in all events that get fed to the canvas
1583 * being the device at the top of the device stack for that canvas.
1585 * If a device is pushed onto the device stack, it will not be deleted
1586 * until a canvas free OR until it has been popped from the stack even if
1587 * evas_device_del() is called.
1589 * The device @p dev must have been created as a device for the canvas it
1590 * is pushed onto (and not another canvas).
1594 * evas_device_push(canvas, dev);
1595 * evas_event_feed_mouse_move(canvas, 20, 30, 0, NULL);
1596 * evas_device_pop(canvas);
1599 * @see evas_device_pop
1602 EAPI void evas_device_push(Evas *e, Evas_Device *dev);
1605 * This pops the top of the device stack for the canvas
1607 * @param e The canvas to pop the device stack from
1609 * This pops the top of the device stack making the current device context
1610 * used for device events being what is now at the top of the stack after
1613 * @see evas_device_push
1616 EAPI void evas_device_pop(Evas *e);
1619 * List all current devices attached to the given canvas and/or device
1621 * @param e The canvas to query for a device list
1622 * @param dev A specific device inside the canvas to query for child devices or NULL if just querying the base canvas devices
1623 * @return An internal list of Evas_Device pointers, or NULL if no devices are found
1625 * This will list all devices belonging to a specific evas canvas @p e, at the
1626 * top-level in the device tree if @p dev passed in is NULL. If @p dev is
1627 * a valid device for the given canvas @p e, then a list of child devices
1628 * of @p dev will be returned, allowing you to walk the device tree.
1630 * The list returned is only valid so long as no changes are made to the
1631 * device tree in the given canvas @p e. If there are no devices or children
1632 * then NULL is returned.
1634 * @see evas_device_parent_get
1635 * @see evas_device_name_get
1636 * @see evas_device_description_get
1637 * @see evas_device_class_get
1638 * @see evas_device_subclass_get
1639 * @see evas_device_emulation_source_get
1642 EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev);
1645 * Set the name of a device as a string
1647 * @p dev The device to set the name of
1648 * @p name The name string as a readable C UTF8 string
1652 EAPI void evas_device_name_set(Evas_Device *dev, const char *name);
1655 * Get the name of a device
1657 * @p dev The device to query
1658 * @return The device name string or NULL if none is set
1660 * This gets the name set by evas_device_name_set(). This is a readable UTF8
1661 * C string, or NULL if no name is set.
1663 * The name should be a short name like Wireless Mouse, Joystick,
1664 * Finger, Keyboard or Numberpad etc.
1668 EAPI const char *evas_device_name_get(const Evas_Device *dev);
1671 * Set the description of a device as a string
1673 * @p dev The device to set the description of
1674 * @p name The description string as a readable C UTF8 string
1678 EAPI void evas_device_description_set(Evas_Device *dev, const char *desc);
1681 * Get the description of a device
1683 * @p dev The device to query
1684 * @return The device description string or NULL if none is set
1686 * This gets the description set by evas_device_description_set(). This is
1687 * a readable UTF8 C string, or NULL if no description is set.
1689 * A description is meant to be a longer string describing the device so a
1690 * human may make sense of it. For example Wireless 6 button mouse in Black
1691 * with red buttons would be a good description, so a user may identify
1692 * precisely which device is being talked about.
1696 EAPI const char *evas_device_description_get(const Evas_Device *dev);
1699 * Set the parent of a device
1701 * @p dev The device to set the parent of
1702 * @p parent The new parent device
1704 * This sets the parent of a device @p dev to the parent given by @p parent.
1705 * If the device already has a parent, it is removed from that parent's list.
1706 * If @p parent is NULL then the device is unparented and placed back as a
1707 * root device in the canvas.
1709 * When a device is deleted with evas_device_del(), all children are also
1710 * deleted along with it.
1712 * @see evas_device_del
1713 * @see evas_device_parent_get
1714 * @see evas_device_list
1718 EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent);
1721 * Get the parent of a device
1723 * @param dev The device to query
1724 * @return The parent device or NULL if it is a toplevel
1726 * This returns the parent device of any given device entry, or NULL if no
1727 * parent device exists (is a toplevel device).
1731 EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev);
1734 * Set the major class of device
1736 * @param dev The device whose class to set
1737 * @param clas The class to set it to
1739 * This sets the primary class of device (a broad thing like mouse, keyboard,
1744 EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas);
1747 * Get the major class of a device
1749 * @param dev The devise to query
1750 * @return The device class to set
1752 * This sets the device class set by evas_device_class_set().
1756 EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev);
1759 * Set the sub-class of a device
1761 * @param dev The device to modify
1762 * @param clas The sub-class to set
1764 * This sets the sub-class of a device whihc gives much more detailed usage
1765 * within a broader category.
1769 EAPI void evas_device_subclass_set(Evas_Device *dev, Evas_Device_Subclass clas);
1772 * Get the device sub-class
1774 * @param dev The device to query
1775 * @return The device sub-class set by evas_device_subclass_set().
1779 EAPI Evas_Device_Subclass evas_device_subclass_get(const Evas_Device *dev);
1782 * Set the emulation source device
1784 * @param dev The device being emulated
1785 * @param src The primary source device producing events in the emulated device
1787 * Devices may not be real, but may be emulated by listening to input on other
1788 * devices and modifying or interpeting it to generate output on an emulated
1789 * device (example a fingeron a touchscreen will often emulate a mouse when
1790 * it presses). This allows you to set which device primarily emulates @p dev
1791 * so the user can choose to ignore events from emulated devices if they also
1792 * pay attention to source device events for example.
1796 EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src);
1799 * Get the emulation source device
1801 * @param dev The device to query
1802 * @return The source emulation device set by evas_device_emulation_source_set().
1806 EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev);
1814 * @defgroup Evas_Image_Group Image Functions
1816 * Functions that deals with images at canvas level.
1818 * @ingroup Evas_Canvas
1823 * @defgroup Evas_Font_Group Font Functions
1825 * Functions that deals with fonts.
1827 * @ingroup Evas_Canvas
1831 * @defgroup Evas_Object_Group Generic Object Functions
1834 * Functions that manipulate generic Evas objects.
1836 * All Evas displaying units are Evas objects. One handles them all by
1837 * means of the handle ::Evas_Object. Besides Evas treats their
1838 * objects equally, they have @b types, which define their specific
1839 * behavior (and individual API).
1841 * Evas comes with a set of built-in object types:
1850 * These functions apply to @b any Evas object, whichever type that
1853 * @note The built-in types which are most used are rectangles, text
1854 * and images. In fact, with these ones one can create 2D interfaces
1855 * of arbitrary complexity and EFL makes it easy.
1859 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
1861 * Almost every evas object created will have some generic function used to
1862 * manipulate it. That's because there are a number of basic actions to be done
1863 * to objects that are irrespective of the object's type, things like:
1864 * @li Showing/Hiding
1865 * @li Setting(and getting) geometry
1866 * @li Bring up or down a layer
1867 * @li Color management
1868 * @li Handling focus
1870 * @li Reference counting
1872 * All of this issues are handled through the functions here grouped. Examples
1873 * of these function can be seen in @ref Example_Evas_Object_Manipulation(which
1874 * deals with the most common ones) and in @ref Example_Evas_Stacking(which
1875 * deals with stacking functions).
1877 * @ingroup Evas_Object_Group
1881 * @defgroup Evas_Object_Group_Events Object Events
1883 * Objects generate events when they are moved, resized, when their
1884 * visibility change, when they are deleted and so on. These methods
1885 * allow one to be notified about and to handle such events.
1887 * Objects also generate events on input (keyboard and mouse), if they
1888 * accept them (are visible, focused, etc).
1890 * For each of those events, Evas provides a way for one to register
1891 * callback functions to be issued just after they happen.
1893 * The following figure illustrates some Evas (event) callbacks:
1895 * @image html evas-callbacks.png
1896 * @image rtf evas-callbacks.png
1897 * @image latex evas-callbacks.eps
1899 * These events have their values in the #Evas_Callback_Type
1900 * enumeration, which has also ones happening on the canvas level (see
1901 * @ref Evas_Canvas_Events ).
1903 * Examples on this group of functions can be found @ref
1904 * Example_Evas_Stacking here and @ref Example_Evas_Events here.
1906 * @ingroup Evas_Object_Group
1910 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspective, 3D...)
1912 * Evas allows different transformations to be applied to all kinds of
1913 * objects. These are applied by means of UV mapping.
1915 * With UV mapping, one maps points in the source object to a 3D space
1916 * positioning at target. This allows rotation, perspective, scale and
1917 * lots of other effects, depending on the map that is used.
1919 * Each map point may carry a multiplier color. If properly
1920 * calculated, these can do shading effects on the object, producing
1923 * As usual, Evas provides both the raw and easy to use methods. The
1924 * raw methods allow developers to create their maps somewhere else,
1925 * possibly loading them from some file format. The easy to use methods
1926 * calculate the points given some high-level parameters such as
1927 * rotation angle, ambient light, and so on.
1929 * @note applying mapping will reduce performance, so use with
1930 * care. The impact on performance depends on engine in
1931 * use. Software is quite optimized, but not as fast as OpenGL.
1933 * @section sec-map-points Map points
1934 * @subsection subsec-rotation Rotation
1936 * A map consists of a set of points, currently only four are supported. Each
1937 * of these points contains a set of canvas coordinates @c x and @c y that
1938 * can be used to alter the geometry of the mapped object, and a @c z
1939 * coordinate that indicates the depth of that point. This last coordinate
1940 * does not normally affect the map, but it's used by several of the utility
1941 * functions to calculate the right position of the point given other
1944 * The coordinates for each point are set with evas_map_point_coord_set().
1945 * The following image shows a map set to match the geometry of an existing
1948 * @image html map-set-map-points-1.png
1949 * @image rtf map-set-map-points-1.png
1950 * @image latex map-set-map-points-1.eps
1952 * This is a common practice, so there are a few functions that help make it
1955 * evas_map_util_points_populate_from_geometry() sets the coordinates of each
1956 * point in the given map to match the rectangle defined by the function
1959 * evas_map_util_points_populate_from_object() and
1960 * evas_map_util_points_populate_from_object_full() both take an object and
1961 * set the map points to match its geometry. The difference between the two
1962 * is that the first function sets the @c z value of all points to 0, while
1963 * the latter receives the value to set in said coordinate as a parameter.
1965 * The following lines of code all produce the same result as in the image
1968 * evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
1969 * // Assuming o is our original object
1970 * evas_object_move(o, 100, 100);
1971 * evas_object_resize(o, 200, 200);
1972 * evas_map_util_points_populate_from_object(m, o);
1973 * evas_map_util_points_populate_from_object_full(m, o, 0);
1976 * Several effects can be applied to an object by simply setting each point
1977 * of the map to the right coordinates. For example, a simulated perspective
1978 * could be achieve as follows.
1980 * @image html map-set-map-points-2.png
1981 * @image rtf map-set-map-points-2.png
1982 * @image latex map-set-map-points-2.eps
1984 * As said before, the @c z coordinate is unused here so when setting points
1985 * by hand, its value is of no importance.
1987 * @image html map-set-map-points-3.png
1988 * @image rtf map-set-map-points-3.png
1989 * @image latex map-set-map-points-3.eps
1991 * In all three cases above, setting the map to be used by the object is the
1994 * evas_object_map_set(o, m);
1995 * evas_object_map_enable_set(o, EINA_TRUE);
1998 * Doing things this way, however, is a lot of work that can be avoided by
1999 * using the provided utility functions, as described in the next section.
2001 * @section map-utils Utility functions
2003 * Utility functions take an already set up map and alter it to produce a
2004 * specific effect. For example, to rotate an object around its own center
2005 * you would need to take the rotation angle, the coordinates of each corner
2006 * of the object and do all the math to get the new set of coordinates that
2007 * need to be set in the map.
2009 * Or you can use this code:
2011 * evas_object_geometry_get(o, &x, &y, &w, &h);
2012 * m = evas_map_new(4);
2013 * evas_map_util_points_populate_from_object(m, o);
2014 * evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
2015 * evas_object_map_set(o, m);
2016 * evas_object_map_enable_set(o, EINA_TRUE);
2020 * Which will rotate the object around its center point in a 45 degree angle
2021 * in the clockwise direction, taking it from this
2023 * @image html map-rotation-2d-1.png
2024 * @image rtf map-rotation-2d-1.png
2025 * @image latex map-rotation-2d-1.eps
2029 * @image html map-rotation-2d-2.png
2030 * @image rtf map-rotation-2d-2.png
2031 * @image latex map-rotation-2d-2.eps
2033 * Objects may be rotated around any other point just by setting the last two
2034 * paramaters of the evas_map_util_rotate() function to the right values. A
2035 * circle of roughly the diameter of the object overlaid on each image shows
2036 * where the center of rotation is set for each example.
2038 * For example, this code
2040 * evas_object_geometry_get(o, &x, &y, &w, &h);
2041 * m = evas_map_new(4);
2042 * evas_map_util_points_populate_from_object(m, o);
2043 * evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
2044 * evas_object_map_set(o, m);
2045 * evas_object_map_enable_set(o, EINA_TRUE);
2049 * produces something like
2051 * @image html map-rotation-2d-3.png
2052 * @image rtf map-rotation-2d-3.png
2053 * @image latex map-rotation-2d-3.eps
2057 * evas_output_size_get(evas, &w, &h);
2058 * m = evas_map_new(4);
2059 * evas_map_util_points_populate_from_object(m, o);
2060 * evas_map_util_rotate(m, 45, w, h);
2061 * evas_object_map_set(o, m);
2062 * evas_object_map_enable_set(o, EINA_TRUE);
2066 * rotates the object around the center of the window
2068 * @image html map-rotation-2d-4.png
2069 * @image rtf map-rotation-2d-4.png
2070 * @image latex map-rotation-2d-4.eps
2072 * @subsection subsec-3d 3D Maps
2074 * Maps can also be used to achieve the effect of 3-dimensionality. When doing
2075 * this, the @c z coordinate of each point counts, with higher values meaning
2076 * the point is further into the screen, and smaller values (negative, usually)
2077 * meaning the point is closer towards the user.
2079 * Thinking in 3D also introduces the concept of back-face of an object. An
2080 * object is said to be facing the user when all its points are placed in a
2081 * clockwise fashion. The next image shows this, with each point showing the
2082 * with which is identified within the map.
2084 * @image html map-point-order-face.png
2085 * @image rtf map-point-order-face.png
2086 * @image latex map-point-order-face.eps
2088 * Rotating this map around the @c Y axis would leave the order of the points
2089 * in a counter-clockwise fashion, as seen in the following image.
2091 * @image html map-point-order-back.png
2092 * @image rtf map-point-order-back.png
2093 * @image latex map-point-order-back.eps
2095 * This way we can say that we are looking at the back face of the object.
2096 * This will have stronger implications later when we talk about lighting.
2098 * To know if a map is facing towards the user or not it's enough to use
2099 * the evas_map_util_clockwise_get() function, but this is normally done
2100 * after all the other operations are applied on the map.
2102 * @subsection subsec-3d-rot 3D rotation and perspective
2104 * Much like evas_map_util_rotate(), there's the function
2105 * evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
2106 * to an object. As in its 2D counterpart, the rotation can be applied around
2107 * any point in the canvas, this time with a @c z coordinate too. The rotation
2108 * can also be around any of the 3 axis.
2110 * Starting from this simple setup
2112 * @image html map-3d-basic-1.png
2113 * @image rtf map-3d-basic-1.png
2114 * @image latex map-3d-basic-1.eps
2116 * and setting maps so that the blue square to rotate on all axis around a
2117 * sphere that uses the object as its center, and the red square to rotate
2118 * around the @c Y axis, we get the following. A simple overlay over the image
2119 * shows the original geometry of each object and the axis around which they
2120 * are being rotated, with the @c Z one not appearing due to being orthogonal
2123 * @image html map-3d-basic-2.png
2124 * @image rtf map-3d-basic-2.png
2125 * @image latex map-3d-basic-2.eps
2127 * which doesn't look very real. This can be helped by adding perspective
2128 * to the transformation, which can be simply done by calling
2129 * evas_map_util_3d_perspective() on the map after its position has been set.
2130 * The result in this case, making the vanishing point the center of each
2133 * @image html map-3d-basic-3.png
2134 * @image rtf map-3d-basic-3.png
2135 * @image latex map-3d-basic-3.eps
2137 * @section sec-color Color and lighting
2139 * Each point in a map can be set to a color, which will be multiplied with
2140 * the objects own color and linearly interpolated in between adjacent points.
2141 * This is done with evas_map_point_color_set() for each point of the map,
2142 * or evas_map_util_points_color_set() to set every point to the same color.
2144 * When using 3D effects, colors can be used to improve the looks of them by
2145 * simulating a light source. The evas_map_util_3d_lighting() function makes
2146 * this task easier by taking the coordinates of the light source and its
2147 * color, along with the color of the ambient light. Evas then sets the color
2148 * of each point based on the distance to the light source, the angle with
2149 * which the object is facing the light and the ambient light. Here, the
2150 * orientation of each point as explained before, becomes more important.
2151 * If the map is defined counter-clockwise, the object will be facing away
2152 * from the user and thus become obscured, since no light would be reflecting
2155 * @image html map-light.png
2156 * @image rtf map-light.png
2157 * @image latex map-light.eps
2158 * @note Object facing the light source
2160 * @image html map-light2.png
2161 * @image rtf map-light2.png
2162 * @image latex map-light2.eps
2163 * @note Same object facing away from the user
2165 * @section Image mapping
2167 * @image html map-uv-mapping-1.png
2168 * @image rtf map-uv-mapping-1.png
2169 * @image latex map-uv-mapping-1.eps
2171 * Images need some special handling when mapped. Evas can easily take care
2172 * of objects and do almost anything with them, but it's completely oblivious
2173 * to the content of images, so each point in the map needs to be told to what
2174 * pixel in the source image it belongs. Failing to do may sometimes result
2175 * in the expected behavior, or it may look like a partial work.
2177 * The next image illustrates one possibility of a map being set to an image
2178 * object, without setting the right UV mapping for each point. The objects
2179 * themselves are mapped properly to their new geometry, but the image content
2180 * may not be displayed correctly within the mapped object.
2182 * @image html map-uv-mapping-2.png
2183 * @image rtf map-uv-mapping-2.png
2184 * @image latex map-uv-mapping-2.eps
2186 * Once Evas knows how to handle the source image within the map, it will
2187 * transform it as needed. This is done with evas_map_point_image_uv_set(),
2188 * which tells the map to which pixel in image it maps.
2190 * To match our example images to the maps above all we need is the size of
2191 * each image, which can always be found with evas_object_image_size_get().
2194 * evas_map_point_image_uv_set(m, 0, 0, 0);
2195 * evas_map_point_image_uv_set(m, 1, 150, 0);
2196 * evas_map_point_image_uv_set(m, 2, 150, 200);
2197 * evas_map_point_image_uv_set(m, 3, 0, 200);
2198 * evas_object_map_set(o, m);
2199 * evas_object_map_enable_set(o, EINA_TRUE);
2201 * evas_map_point_image_uv_set(m, 0, 0, 0);
2202 * evas_map_point_image_uv_set(m, 1, 120, 0);
2203 * evas_map_point_image_uv_set(m, 2, 120, 160);
2204 * evas_map_point_image_uv_set(m, 3, 0, 160);
2205 * evas_object_map_set(o2, m);
2206 * evas_object_map_enable_set(o2, EINA_TRUE);
2211 * @image html map-uv-mapping-3.png
2212 * @image rtf map-uv-mapping-3.png
2213 * @image latex map-uv-mapping-3.eps
2215 * Maps can also be set to use part of an image only, or even map them inverted,
2216 * and combined with evas_object_image_source_set() it can be used to achieve
2217 * more interesting results.
2220 * evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
2221 * evas_map_point_image_uv_set(m, 0, 0, h);
2222 * evas_map_point_image_uv_set(m, 1, w, h);
2223 * evas_map_point_image_uv_set(m, 2, w, h / 3);
2224 * evas_map_point_image_uv_set(m, 3, 0, h / 3);
2225 * evas_object_map_set(o, m);
2226 * evas_object_map_enable_set(o, EINA_TRUE);
2229 * @image html map-uv-mapping-4.png
2230 * @image rtf map-uv-mapping-4.png
2231 * @image latex map-uv-mapping-4.eps
2234 * @li @ref Example_Evas_Map_Overview
2236 * @ingroup Evas_Object_Group
2242 * @brief Populate source and destination map points to match exactly object.
2244 * @if MOBILE @since_tizen 2.3
2245 * @elseif WEARABLE @since_tizen 2.3.1
2248 * @remark Usually one initialize map of an object to match it's original
2249 * position and size, then transform these with evas_map_util_*
2250 * functions, such as evas_map_util_rotate() or
2251 * evas_map_util_3d_rotate(). The original set is done by this
2252 * function, avoiding code duplication all around.
2254 * @param[in] m map to change all 4 points (must be of size 4).
2255 * @param[in] obj object to use unmapped geometry to populate map coordinates.
2256 * @param[in] z Point Z Coordinate hint (pre-perspective transform). This value
2257 * will be used for all four points.
2259 * @see evas_map_util_points_populate_from_object()
2260 * @see evas_map_point_coord_set()
2261 * @see evas_map_point_image_uv_set()
2263 EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
2266 * @brief Populate source and destination map points to match exactly object.
2268 * @if MOBILE @since_tizen 2.3
2269 * @elseif WEARABLE @since_tizen 2.3.1
2272 * @remark Usually one initialize map of an object to match it's original
2273 * position and size, then transform these with evas_map_util_*
2274 * functions, such as evas_map_util_rotate() or
2275 * evas_map_util_3d_rotate(). The original set is done by this
2276 * function, avoiding code duplication all around.
2278 * @remark Z Point coordinate is assumed as 0 (zero).
2280 * @param[in] m map to change all 4 points (must be of size 4).
2281 * @param[in] obj object to use unmapped geometry to populate map coordinates.
2283 * @see evas_map_util_points_populate_from_object_full()
2284 * @see evas_map_util_points_populate_from_geometry()
2285 * @see evas_map_point_coord_set()
2286 * @see evas_map_point_image_uv_set()
2288 EAPI void evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj);
2291 * @brief Populate source and destination map points to match given geometry.
2293 * @if MOBILE @since_tizen 2.3
2294 * @elseif WEARABLE @since_tizen 2.3.1
2297 * @remark Similar to evas_map_util_points_populate_from_object_full(), this
2298 * call takes raw values instead of querying object's unmapped
2299 * geometry. The given width will be used to calculate destination
2300 * points (evas_map_point_coord_set()) and set the image uv
2301 * (evas_map_point_image_uv_set()).
2303 * @param[in] m map to change all 4 points (must be of size 4).
2304 * @param[in] x Point X Coordinate
2305 * @param[in] y Point Y Coordinate
2306 * @param[in] w width to use to calculate second and third points.
2307 * @param[in] h height to use to calculate third and fourth points.
2308 * @param[in] z Point Z Coordinate hint (pre-perspective transform). This value
2309 * will be used for all four points.
2311 * @see evas_map_util_points_populate_from_object()
2312 * @see evas_map_point_coord_set()
2313 * @see evas_map_point_image_uv_set()
2315 EAPI void evas_map_util_points_populate_from_geometry(Evas_Map *m, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Evas_Coord z);
2318 * @brief Set color of all points to given color.
2320 * @if MOBILE @since_tizen 2.3
2321 * @elseif WEARABLE @since_tizen 2.3.1
2324 * @remark This call is useful to reuse maps after they had 3d lightning or
2325 * any other colorization applied before.
2327 * @param[in] m map to change the color of.
2328 * @param[in] r red (0 - 255)
2329 * @param[in] g green (0 - 255)
2330 * @param[in] b blue (0 - 255)
2331 * @param[in] a alpha (0 - 255)
2333 * @see evas_map_point_color_set()
2335 EAPI void evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a);
2338 * @brief Change the map to apply the given rotation.
2340 * @if MOBILE @since_tizen 2.3
2341 * @elseif WEARABLE @since_tizen 2.3.1
2344 * @remark This rotates the indicated map's coordinates around the center coordinate
2345 * given by @p cx and @p cy as the rotation center. The points will have their
2346 * X and Y coordinates rotated clockwise by @p degrees degrees (360.0 is a
2347 * full rotation). Negative values for degrees will rotate counter-clockwise
2348 * by that amount. All coordinates are canvas global coordinates.
2350 * @param[in] m map to change.
2351 * @param[in] degrees amount of degrees from 0.0 to 360.0 to rotate.
2352 * @param[in] cx rotation's center horizontal position.
2353 * @param[in] cy rotation's center vertical position.
2355 * @see evas_map_point_coord_set()
2356 * @see evas_map_util_zoom()
2358 EAPI void evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
2361 * @brief Change the map to apply the given zooming.
2363 * @if MOBILE @since_tizen 2.3
2364 * @elseif WEARABLE @since_tizen 2.3.1
2367 * @remark Like evas_map_util_rotate(), this zooms the points of the map from a center
2368 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
2369 * parameters specify how much to zoom in the X and Y direction respectively.
2370 * A value of 1.0 means don't zoom. 2.0 means double the size. 0.5 is
2371 * half the size etc. All coordinates are canvas global coordinates.
2373 * @param[in] m map to change.
2374 * @param[in] zoomx horizontal zoom to use.
2375 * @param[in] zoomy vertical zoom to use.
2376 * @param[in] cx zooming center horizontal position.
2377 * @param[in] cy zooming center vertical position.
2379 * @see evas_map_point_coord_set()
2380 * @see evas_map_util_rotate()
2382 EAPI void evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
2385 * @brief Rotate the map around 3 axes in 3D
2387 * @if MOBILE @since_tizen 2.3
2388 * @elseif WEARABLE @since_tizen 2.3.1
2391 * @remark This will rotate not just around the Z axis as in evas_map_util_rotate()
2392 * (which is a convenience call for those only wanting 2D). This will rotate
2393 * around the X, Y and Z axes. The Z axis points into the screen with low
2394 * values at the screen and higher values further away. The X axis runs from
2395 * left to right on the screen and the Y axis from top to bottom. Like with
2396 * evas_map_util_rotate() you provide a center point to rotate around (in 3D).
2398 * @param[in] m map to change.
2399 * @param[in] dx amount of degrees from 0.0 to 360.0 to rotate around X axis.
2400 * @param[in] dy amount of degrees from 0.0 to 360.0 to rotate around Y axis.
2401 * @param[in] dz amount of degrees from 0.0 to 360.0 to rotate around Z axis.
2402 * @param[in] cx rotation's center horizontal position.
2403 * @param[in] cy rotation's center vertical position.
2404 * @param[in] cz rotation's center vertical position.
2406 EAPI void evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz);
2409 * @brief Rotate the map in 3D using a unit quaternion.
2411 * @if MOBILE @since_tizen 2.3
2412 * @elseif WEARABLE @since_tizen 2.3.1
2415 * @remark This will rotate in 3D using a unit quaternion. Like with
2416 * evas_map_util_3d_rotate() you provide a center point
2417 * to rotate around (in 3D).
2419 * @param[in] m map to change.
2420 * @param[in] qx the x component of the imaginary part of the quaternion.
2421 * @param[in] qy the y component of the imaginary part of the quaternion.
2422 * @param[in] qz the z component of the imaginary part of the quaternion.
2423 * @param[in] qw the w component of the real part of the quaternion.
2424 * @param[in] cx rotation's center x.
2425 * @param[in] cy rotation's center y.
2426 * @param[in] cz rotation's center z.
2428 * @warning Rotations can be done using a unit quaternion. Thus, this
2429 * function expects a unit quaternion (i.e. qx² + qy² + qz² + qw² == 1).
2430 * If this is not the case the behavior is undefined.
2434 EAPI void evas_map_util_quat_rotate(Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz);
2437 * @brief Perform lighting calculations on the given Map
2439 * @if MOBILE @since_tizen 2.3
2440 * @elseif WEARABLE @since_tizen 2.3.1
2443 * @remark This is used to apply lighting calculations (from a single light source)
2444 * to a given map. The R, G and B values of each vertex will be modified to
2445 * reflect the lighting based on the lixth point coordinates, the light
2446 * color and the ambient color, and at what angle the map is facing the
2447 * light source. A surface should have its points be declared in a
2448 * clockwise fashion if the face is facing towards you (as opposed to
2449 * away from you) as faces have a logical side for lighting.
2451 * @image html map-light3.png
2452 * @image rtf map-light3.png
2453 * @image latex map-light3.eps
2454 * @remark Grey object, no lighting used
2456 * @image html map-light4.png
2457 * @image rtf map-light4.png
2458 * @image latex map-light4.eps
2459 * @remark Lights out! Every color set to 0
2461 * @image html map-light5.png
2462 * @image rtf map-light5.png
2463 * @image latex map-light5.eps
2464 * @remark Ambient light to full black, red light coming from close at the
2465 * bottom-left vertex
2467 * @image html map-light6.png
2468 * @image rtf map-light6.png
2469 * @image latex map-light6.eps
2470 * @remark Same light as before, but not the light is set to 0 and ambient light
2473 * @image html map-light7.png
2474 * @image rtf map-light7.png
2475 * @image latex map-light7.eps
2476 * @remark Both lights are on
2478 * @image html map-light8.png
2479 * @image rtf map-light8.png
2480 * @image latex map-light8.eps
2481 * @remark Both lights again, but this time both are the same color.
2483 * @param[in] m map to change.
2484 * @param[in] lx X coordinate in space of light point
2485 * @param[in] ly Y coordinate in space of light point
2486 * @param[in] lz Z coordinate in space of light point
2487 * @param[in] lr light red value (0 - 255)
2488 * @param[in] lg light green value (0 - 255)
2489 * @param[in] lb light blue value (0 - 255)
2490 * @param[in] ar ambient color red value (0 - 255)
2491 * @param[in] ag ambient color green value (0 - 255)
2492 * @param[in] ab ambient color blue value (0 - 255)
2494 EAPI void evas_map_util_3d_lighting(Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab);
2497 * @brief Apply a perspective transform to the map
2499 * @if MOBILE @since_tizen 2.3
2500 * @elseif WEARABLE @since_tizen 2.3.1
2503 * @remark This applies a given perspective (3D) to the map coordinates. X, Y and Z
2504 * values are used. The px and py points specify the infinite distance point
2505 * in the 3D conversion (where all lines converge to like when artists draw
2506 * 3D by hand). The @p z0 value specifies the z value at which there is a 1:1
2507 * mapping between spatial coordinates and screen coordinates. Any points
2508 * on this z value will not have their X and Y values modified in the transform.
2509 * Those further away (Z value higher) will shrink into the distance, and
2510 * those less than this value will expand and become bigger. The @p foc value
2511 * determines the focal length of the camera. This is in reality the distance
2512 * between the camera lens plane itself (at or closer than this rendering
2513 * results are undefined) and the z0 z value. This allows for some depth
2514 * control and @p foc must be greater than 0.
2516 * @param[in] m map to change.
2517 * @param[in] px The perspective distance X coordinate
2518 * @param[in] py The perspective distance Y coordinate
2519 * @param[in] z0 The 0 z plane value
2520 * @param[in] foc The focal distance
2522 EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
2525 * @brief Get the clockwise state of a map
2527 * @if MOBILE @since_tizen 2.3
2528 * @elseif WEARABLE @since_tizen 2.3.1
2531 * @remark This determines if the output points (X and Y. Z is not used) are
2532 * clockwise or counter-clockwise. This can be used for back-face culling. This
2533 * is where you hide objects that face away from you. In this case objects
2534 * that are not clockwise.
2536 * @param[in] m map to query.
2537 * @return 1 if clockwise, 0 otherwise
2539 EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m);
2542 * @brief Create map of transformation points to be later used with an Evas object.
2544 * @if MOBILE @since_tizen 2.3
2545 * @elseif WEARABLE @since_tizen 2.3.1
2548 * @remark This creates a set of points (currently only 4 is supported. no other
2549 * number for @p count will work). That is empty and ready to be modified
2550 * with evas_map calls.
2552 * @param[in] count number of points in the map.
2553 * @return a newly allocated map or @c NULL on errors.
2555 * @see evas_map_free()
2556 * @see evas_map_dup()
2557 * @see evas_map_point_coord_set()
2558 * @see evas_map_point_image_uv_set()
2559 * @see evas_map_util_points_populate_from_object_full()
2560 * @see evas_map_util_points_populate_from_object()
2562 * @see evas_object_map_set()
2564 EAPI Evas_Map *evas_map_new(int count);
2567 * @brief Set the smoothing for map rendering
2569 * @if MOBILE @since_tizen 2.3
2570 * @elseif WEARABLE @since_tizen 2.3.1
2573 * @remark This sets smoothing for map rendering. If the object is a type that has
2574 * its own smoothing settings, then both the smooth settings for this object
2575 * and the map must be turned off. By default smooth maps are enabled.
2577 * @param[in] m map to modify. Must not be NULL.
2578 * @param[in] enabled enable or disable smooth map rendering
2580 EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled);
2583 * @brief Get the smoothing for map rendering
2585 * @if MOBILE @since_tizen 2.3
2586 * @elseif WEARABLE @since_tizen 2.3.1
2589 * @remark This gets smoothing for map rendering.
2591 * @param[in] m map to get the smooth from. Must not be NULL.
2592 * @return @c EINA_TRUE if the smooth is enabled, @c EINA_FALSE otherwise.
2594 EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m);
2597 * @brief Set the alpha flag for map rendering
2599 * @if MOBILE @since_tizen 2.3
2600 * @elseif WEARABLE @since_tizen 2.3.1
2603 * @remark This sets alpha flag for map rendering. If the object is a type that has
2604 * its own alpha settings, then this will take precedence. Only image objects
2605 * have this currently.
2606 * Setting this off stops alpha blending of the map area, and is
2607 * useful if you know the object and/or all sub-objects is 100% solid.
2609 * @param[in] m map to modify. Must not be NULL.
2610 * @param[in] enabled enable or disable alpha map rendering
2612 EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled);
2615 * @brief Get the alpha flag for map rendering
2617 * @if MOBILE @since_tizen 2.3
2618 * @elseif WEARABLE @since_tizen 2.3.1
2621 * @remark This gets the alpha flag for map rendering.
2623 * @param[in] m map to get the alpha from. Must not be NULL.
2624 * @return EINA_FALSE if map is NULL EINA_TRUE otherwise.
2626 EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m);
2631 * Set the flag of the object move synchronization for map rendering
2633 * This sets the flag of the object move synchronization for map rendering.
2634 * If the flag is set as enabled, the map will be moved as the object of the map
2635 * is moved. By default, the flag of the object move synchronization is not
2638 * @param m map to modify. Must not be NULL.
2639 * @param enabled enable or disable the object move synchronization for map
2643 EAPI void evas_map_util_object_move_sync_set(Evas_Map *m, Eina_Bool enabled);
2648 * Get the flag of the object move synchronization for map rendering
2650 * This gets the flag of the object move synchronization for map rendering.
2652 * @param m map to get the flag of the object move synchronization from. Must
2654 * @return EINA_FALSE if map is NULL EINA_TRUE otherwise.
2657 EAPI Eina_Bool evas_map_util_object_move_sync_get(const Evas_Map *m);
2660 * @brief Copy a previously allocated map.
2662 * @if MOBILE @since_tizen 2.3
2663 * @elseif WEARABLE @since_tizen 2.3.1
2666 * @remark This makes a duplicate of the @p m object and returns it.
2668 * @param[in] m map to copy. Must not be NULL.
2669 * @return newly allocated map with the same count and contents as @p m.
2671 EAPI Evas_Map *evas_map_dup(const Evas_Map *m);
2674 * @brief Free a previously allocated map.
2676 * @if MOBILE @since_tizen 2.3
2677 * @elseif WEARABLE @since_tizen 2.3.1
2680 * @remark This frees a given map @p m and all memory associated with it. You must NOT
2681 * free a map returned by evas_object_map_get() as this is internal.
2683 * @param[in] m map to free.
2685 EAPI void evas_map_free(Evas_Map *m);
2688 * @brief Get a maps size.
2690 * @if MOBILE @since_tizen 2.3
2691 * @elseif WEARABLE @since_tizen 2.3.1
2694 * @remark Returns the number of points in a map. Should be at least 4.
2696 * @param[in] m map to get size.
2697 * @return -1 on error, points otherwise.
2699 EAPI int evas_map_count_get(const Evas_Map *m) EINA_CONST;
2702 * @brief Change the map point's coordinate.
2704 * @if MOBILE @since_tizen 2.3
2705 * @elseif WEARABLE @since_tizen 2.3.1
2708 * @remark This sets the fixed point's coordinate in the map. Note that points
2709 * describe the outline of a quadrangle and are ordered either clockwise
2710 * or counter-clockwise. It is suggested to keep your quadrangles concave and
2711 * non-complex, though these polygon modes may work, they may not render
2712 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
2713 * 2 and 3, and 3 and 0 to describe the edges of the quadrangle.
2715 * @remark The X and Y and Z coordinates are in canvas units. Z is optional and may
2716 * or may not be honored in drawing. Z is a hint and does not affect the
2717 * X and Y rendered coordinates. It may be used for calculating fills with
2718 * perspective correct rendering.
2720 * @remark Remember all coordinates are canvas global ones like with move and resize
2723 * @param[in] m map to change point. Must not be @c NULL.
2724 * @param[in] idx index of point to change. Must be smaller than map size.
2725 * @param[in] x Point X Coordinate
2726 * @param[in] y Point Y Coordinate
2727 * @param[in] z Point Z Coordinate hint (pre-perspective transform)
2729 * @see evas_map_util_rotate()
2730 * @see evas_map_util_zoom()
2731 * @see evas_map_util_points_populate_from_object_full()
2732 * @see evas_map_util_points_populate_from_object()
2734 EAPI void evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
2737 * @brief Get the map point's coordinate.
2739 * @if MOBILE @since_tizen 2.3
2740 * @elseif WEARABLE @since_tizen 2.3.1
2743 * @remark This returns the coordinates of the given point in the map.
2745 * @param[in] m map to query point.
2746 * @param[in] idx index of point to query. Must be smaller than map size.
2747 * @param[out] x where to return the X coordinate.
2748 * @param[out] y where to return the Y coordinate.
2749 * @param[out] z where to return the Z coordinate.
2751 EAPI void evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
2754 * @brief Change the map point's U and V texture source point
2756 * @if MOBILE @since_tizen 2.3
2757 * @elseif WEARABLE @since_tizen 2.3.1
2760 * @remark This sets the U and V coordinates for the point. This determines which
2761 * coordinate in the source image is mapped to the given point, much like
2762 * OpenGL and textures. Notes that these points do select the pixel, but
2763 * are double floating point values to allow for accuracy and sub-pixel
2766 * @param[in] m map to change the point of.
2767 * @param[in] idx index of point to change. Must be smaller than map size.
2768 * @param[in] u the X coordinate within the image/texture source
2769 * @param[in] v the Y coordinate within the image/texture source
2771 * @see evas_map_point_coord_set()
2772 * @see evas_object_map_set()
2773 * @see evas_map_util_points_populate_from_object_full()
2774 * @see evas_map_util_points_populate_from_object()
2776 EAPI void evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v);
2779 * @brief Get the map point's U and V texture source points
2781 * @if MOBILE @since_tizen 2.3
2782 * @elseif WEARABLE @since_tizen 2.3.1
2785 * @remark This returns the texture points set by evas_map_point_image_uv_set().
2787 * @param[in] m map to query point.
2788 * @param[in] idx index of point to query. Must be smaller than map size.
2789 * @param[out] u where to write the X coordinate within the image/texture source
2790 * @param[out] v where to write the Y coordinate within the image/texture source
2792 EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v);
2795 * @brief Set the color of a vertex in the map
2797 * @if MOBILE @since_tizen 2.3
2798 * @elseif WEARABLE @since_tizen 2.3.1
2801 * @remark This sets the color of the vertex in the map. Colors will be linearly
2802 * interpolated between vertex points through the map. Color will multiply
2803 * the texture pixels (like GL_MODULATE in OpenGL). The default color of
2804 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
2805 * have no affect on modifying the texture pixels.
2807 * @param[in] m map to change the color of.
2808 * @param[in] idx index of point to change. Must be smaller than map size.
2809 * @param[in] r red (0 - 255)
2810 * @param[in] g green (0 - 255)
2811 * @param[in] b blue (0 - 255)
2812 * @param[in] a alpha (0 - 255)
2814 * @see evas_map_util_points_color_set()
2815 * @see evas_map_point_coord_set()
2816 * @see evas_object_map_set()
2818 EAPI void evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a);
2821 * @brief Get the color set on a vertex in the map
2823 * @if MOBILE @since_tizen 2.3
2824 * @elseif WEARABLE @since_tizen 2.3.1
2827 * @remark This gets the color set by evas_map_point_color_set() on the given vertex
2830 * @param[in] m map to get the color of the vertex from.
2831 * @param[in] idx index of point get. Must be smaller than map size.
2832 * @param[out] r pointer to red return
2833 * @param[out] g pointer to green return
2834 * @param[out] b pointer to blue return
2835 * @param[out] a pointer to alpha return
2837 * @see evas_map_point_coord_set()
2838 * @see evas_object_map_set()
2840 EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
2846 * @defgroup Evas_Object_Group_Size_Hints Size Hints
2848 * Objects may carry hints, so that another object that acts as a
2849 * manager (see @ref Evas_Smart_Object_Group) may know how to properly
2850 * position and resize its subordinate objects. The Size Hints provide
2851 * a common interface that is recommended as the protocol for such
2854 * For example, box objects use alignment hints to align its
2855 * lines/columns inside its container, padding hints to set the
2856 * padding between each individual child, etc.
2858 * Examples on their usage:
2859 * - @ref Example_Evas_Size_Hints evas-hints.c
2860 * - @ref Example_Evas_Aspect_Hints evas-aspect-hints.c
2862 * @ingroup Evas_Object_Group
2866 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
2868 * Miscellaneous functions that also apply to any object, but are less
2869 * used or not implemented by all objects.
2871 * Examples on this group of functions can be found @ref
2872 * Example_Evas_Stacking here and @ref Example_Evas_Events here.
2874 * @ingroup Evas_Object_Group
2879 * @defgroup Evas_Object_Group_Find Finding Objects
2881 * Functions that allows finding objects by their position, name or
2884 * @ingroup Evas_Object_Group
2889 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
2891 * Evas provides a way to intercept method calls. The interceptor
2892 * callback may opt to completely deny the call, or may check and
2893 * change the parameters before continuing. The continuation of an
2894 * intercepted call is done by calling the intercepted call again,
2895 * from inside the interceptor callback.
2897 * @ingroup Evas_Object_Group
2902 * @addtogroup Evas_Object_Group_Interceptors
2907 * Function signature for the resize event of an evas object
2909 * @param data is the pointer passed through the callback.
2910 * @param obj the object being shown.
2912 * @see evas_object_intercept_show_callback_add()
2913 * @see evas_object_intercept_show_callback_del()
2916 typedef void (*Evas_Object_Intercept_Show_Cb)(void *data, Evas_Object *obj);
2919 * Function signature for the hide event of an evas object
2921 * @param data is the pointer passed through the callback.
2922 * @param obj the object being hidden.
2924 * @see evas_object_intercept_hide_callback_add()
2925 * @see evas_object_intercept_hide_callback_del()
2928 typedef void (*Evas_Object_Intercept_Hide_Cb)(void *data, Evas_Object *obj);
2931 * Function signature for the move event of an evas object
2933 * @param data the pointer passed through the callback.
2934 * @param obj the object being moved.
2935 * @param x move x position
2936 * @param y move y position
2938 * @see evas_object_intercept_move_callback_add()
2939 * @see evas_object_intercept_move_callback_del()
2942 typedef void (*Evas_Object_Intercept_Move_Cb)(void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
2945 * Function signature for the resize event of an evas object
2947 * @param data the pointer passed through the callback.
2948 * @param obj the object being resized.
2949 * @param width of the object
2950 * @param height of the object
2952 * @see evas_object_intercept_resize_callback_add()
2953 * @see evas_object_intercept_resize_callback_del()
2956 typedef void (*Evas_Object_Intercept_Resize_Cb)(void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
2959 * Function signature for the raise event of an evas object
2961 * @param data the pointer passed through the callback.
2962 * @param obj the object being raised.
2964 * @see evas_object_intercept_raise_callback_add()
2965 * @see evas_object_intercept_raise_callback_del()
2968 typedef void (*Evas_Object_Intercept_Raise_Cb)(void *data, Evas_Object *obj);
2971 * Function signature for the lower event of an evas object
2973 * @param data the pointer passed through the callback.
2974 * @param obj the object being lowered.
2976 * @see evas_object_intercept_lower_callback_add()
2977 * @see evas_object_intercept_lower_callback_del()
2980 typedef void (*Evas_Object_Intercept_Lower_Cb)(void *data, Evas_Object *obj);
2983 * Function signature for the stack above event of an evas object
2985 * @param data the pointer passed through the callback.
2986 * @param obj the object being stacked above.
2987 * @param above the object above which the object is stacked
2989 * @see evas_object_intercept_stack_above_callback_add()
2990 * @see evas_object_intercept_stack_above_callback_del()
2993 typedef void (*Evas_Object_Intercept_Stack_Above_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
2996 * Function signature for the stack below event of an evas object
2998 * @param data the pointer passed through the callback.
2999 * @param obj the object being stacked below.
3000 * @param above the object below which the object is stacked
3002 * @see evas_object_intercept_stack_below_callback_add()
3003 * @see evas_object_intercept_stack_below_callback_del()
3006 typedef void (*Evas_Object_Intercept_Stack_Below_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
3009 * Function signature for the layer event of an evas object
3011 * @param data the pointer passed through the callback.
3012 * @param obj the object being layered
3013 * @param l the layer value
3015 * @see evas_object_intercept_layer_callback_add()
3016 * @see evas_object_intercept_layer_callback_del()
3019 typedef void (*Evas_Object_Intercept_Layer_Set_Cb)(void *data, Evas_Object *obj, int l);
3022 * Function signature for the focus set event of an evas object
3024 * @param data the pointer passed through the callback.
3025 * @param obj the object being focused
3026 * @param focus the focus value, EINA_TRUE if the object is focused, EINA_FALSE otherwise
3028 * @see evas_object_intercept_focus_set_callback_add()
3029 * @see evas_object_intercept_focus_set_callback_del()
3032 typedef void (*Evas_Object_Intercept_Focus_Set_Cb)(void *data, Evas_Object *obj, Eina_Bool focus);
3035 * Function signature for the color set event of an evas object
3037 * @param data the pointer passed through the callback.
3038 * @param obj the object changing color
3039 * @param r the red component of the color
3040 * @param g the green component of the color
3041 * @param b the blue component of the color
3042 * @param a the alpha component of the color
3044 * @see evas_object_intercept_color_set_callback_add()
3045 * @see evas_object_intercept_color_set_callback_del()
3048 typedef void (*Evas_Object_Intercept_Color_Set_Cb)(void *data, Evas_Object *obj, int r, int g, int b, int a);
3051 * Function signature for the clip set event of an evas object
3053 * @param data the pointer passed through the callback.
3054 * @param obj the object being clipped
3055 * @param clip the evas object on which the object is clipped
3057 * @see evas_object_intercept_clip_set_callback_add()
3058 * @see evas_object_intercept_clip_set_callback_del()
3061 typedef void (*Evas_Object_Intercept_Clip_Set_Cb)(void *data, Evas_Object *obj, Evas_Object *clip);
3064 * Function signature for the clip unset event of an evas object
3066 * @param data the pointer passed through the callback.
3067 * @param obj the object being unclipped
3069 * @see evas_object_intercept_clip_unset_callback_add()
3070 * @see evas_object_intercept_clip_unset_callback_del()
3073 typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj);
3080 * @defgroup Evas_Object_Specific Specific Object Functions
3083 * Functions that work on specific objects.
3088 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
3090 * @brief Function to create evas rectangle objects.
3092 * There is only one function to deal with rectangle objects, this may make this
3093 * function seem useless given there are no functions to manipulate the created
3094 * rectangle, however the rectangle is actually very useful and should be
3095 * manipulated using the generic @ref Evas_Object_Group evas object functions.
3097 * The evas rectangle serves a number of key functions when working on evas
3103 * @section Background
3105 * One extremely common requirement of evas programs is to have a solid color
3106 * background, this can be accomplished with the following very simple code:
3108 * Evas_Object *bg = evas_object_rectangle_add(evas_canvas);
3109 * //Here we set the rectangles red, green, blue and opacity levels
3110 * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
3111 * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
3112 * evas_object_show(bg);
3115 * This however will have issues if the @c evas_canvas is resized, however most
3116 * windows are created using ecore evas and that has a solution to using the
3117 * rectangle as a background
3118 * So this gives us a white background to our window that will be resized
3121 * @section Debugging
3123 * Debugging is a major part of any programmers task and when debugging visual
3124 * issues with evas programs the rectangle is an extremely useful tool. The
3125 * rectangle's simplicity means that it's easier to pinpoint issues with it than
3126 * with more complex objects. Therefore a common technique to use when writing
3127 * an evas program and not getting the desired visual result is to replace the
3128 * misbehaving object for a solid color rectangle and seeing how it interacts
3129 * with the other elements, this often allows us to notice clipping, parenting
3130 * or positioning issues. Once the issues have been identified and corrected the
3131 * rectangle can be replaced for the original part and in all likelihood any
3132 * remaining issues will be specific to that object's type.
3134 * @section clipping Clipping
3136 * Clipping serves two main functions:
3137 * @li Limiting visibility(i.e. hiding portions of an object).
3138 * @li Applying a layer of color to an object.
3140 * @subsection hiding Limiting visibility
3142 * It is often necessary to show only parts of an object, while it may be
3143 * possible to create an object that corresponds only to the part that must be
3144 * shown(and it isn't always possible) it's usually easier to use a a clipper. A
3145 * clipper is a rectangle that defines what's visible and what is not. The way
3146 * to do this is to create a solid white rectangle(which is the default, no need
3147 * to call evas_object_color_set()) and give it a position and size of what
3148 * should be visible. The following code exemplifies showing the center half of
3149 * @c my_evas_object:
3151 * Evas_Object *clipper = evas_object_rectangle_add(evas_canvas);
3152 * evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4);
3153 * evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2);
3154 * evas_object_clip_set(my_evas_object, clipper);
3155 * evas_object_show(clipper);
3158 * @subsection color Layer of color
3160 * In the @ref clipping section we used a solid white clipper, which produced no
3161 * change in the color of the clipped object, it just hid what was outside the
3162 * clippers area. It is however sometimes desirable to change the of color an
3163 * object, this can be accomplished using a clipper that has a non-white color.
3164 * Clippers with color work by multiplying the colors of clipped object. The
3165 * following code will show how to remove all the red from an object:
3167 * Evas_Object *clipper = evas_object_rectangle_add(evas);
3168 * evas_object_move(clipper, my_evas_object_x, my_evas_object_y);
3169 * evas_object_resize(clipper, my_evas_object_width, my_evas_object_height);
3170 * evas_object_color_set(clipper, 0, 255, 255, 255);
3171 * evas_object_clip_set(obj, clipper);
3172 * evas_object_show(clipper);
3175 * @warning We don't guarantee any proper results if you create a Rectangle
3176 * object without setting the evas engine.
3178 * For an example that more fully exercise the use of an evas object rectangle
3179 * see @ref Example_Evas_Object_Manipulation.
3181 * @ingroup Evas_Object_Specific
3185 * @defgroup Evas_Object_Image Image Object Functions
3187 * Here are grouped together functions used to create and manipulate
3188 * image objects. They are available to whichever occasion one needs
3189 * complex imagery on a GUI that could not be achieved by the other
3190 * Evas' primitive object types, or to make image manipulations.
3192 * Evas will support whichever image file types it was compiled with
3193 * support to (its image loaders) -- check your software packager for
3194 * that information and see
3195 * evas_object_image_extension_can_load_get().
3197 * @section Evas_Object_Image_Basics Image object basics
3199 * The most common use of image objects -- to display an image on the
3200 * canvas -- is achieved by a common function triplet:
3202 * img = evas_object_image_add(canvas);
3203 * evas_object_image_file_set(img, "path/to/img", NULL);
3204 * evas_object_image_fill_set(img, 0, 0, w, h);
3206 * The first function, naturally, is creating the image object. Then,
3207 * one must set an source file on it, so that it knows where to fetch
3208 * image data from. Next, one must set <b>how to fill the image
3209 * object's area</b> with that given pixel data. One could use just a
3210 * sub-region of the original image or even have it tiled repeatedly
3211 * on the image object. For the common case of having the whole source
3212 * image to be displayed on the image object, stretched to the
3213 * destination's size, there's also a function helper, to be used
3214 * instead of evas_object_image_fill_set():
3216 * evas_object_image_filled_set(img, EINA_TRUE);
3218 * See those functions' documentation for more details.
3220 * @section Evas_Object_Image_Scale Scale and resizing
3222 * Resizing of image objects will scale their respective source images
3223 * to their areas, if they are set to fill the object's area
3224 * (evas_object_image_filled_set()). If the user wants any control on
3225 * the aspect ratio of an image for different sizes, he/she has to
3226 * take care of that themselves. There are functions to make images to
3227 * get loaded scaled (up or down) in memory, already, if the user is
3228 * going to use them at pre-determined sizes and wants to save
3231 * Evas has even a scale cache, which will take care of caching scaled
3232 * versions of images with more often usage/hits. Finally, one can
3233 * have images being rescaled @b smoothly by Evas (more
3234 * computationally expensive) or not.
3236 * @section Evas_Object_Image_Performance Performance hints
3238 * When dealing with image objects, there are some tricks to boost the
3239 * performance of your application, if it does intense image loading
3240 * and/or manipulations, as in animations on a UI.
3242 * @subsection Evas_Object_Image_Load Load hints
3244 * In image viewer applications, for example, the user will be looking
3245 * at a given image, at full size, and will desire that the navigation
3246 * to the adjacent images on his/her album be fluid and fast. Thus,
3247 * while displaying a given image, the program can be on the
3248 * background loading the next and previous images already, so that
3249 * displaying them on the sequence is just a matter of repainting the
3250 * screen (and not decoding image data).
3252 * Evas addresses this issue with <b>image pre-loading</b>. The code
3253 * for the situation above would be something like the following:
3255 * prev = evas_object_image_filled_add(canvas);
3256 * evas_object_image_file_set(prev, "/path/to/prev", NULL);
3257 * evas_object_image_preload(prev, EINA_TRUE);
3259 * next = evas_object_image_filled_add(canvas);
3260 * evas_object_image_file_set(next, "/path/to/next", NULL);
3261 * evas_object_image_preload(next, EINA_TRUE);
3264 * If you're loading images which are too big, consider setting
3265 * previously it's loading size to something smaller, in case you
3266 * won't expose them in real size. It may speed up the loading
3269 * //to load a scaled down version of the image in memory, if that's
3270 * //the size you'll be displaying it anyway
3271 * evas_object_image_load_scale_down_set(img, zoom);
3273 * //optional: if you know you'll be showing a sub-set of the image's
3274 * //pixels, you can avoid loading the complementary data
3275 * evas_object_image_load_region_set(img, x, y, w, h);
3277 * Refer to Elementary's Photocam widget for a high level (smart)
3278 * object which does lots of loading speed-ups for you.
3280 * @subsection Evas_Object_Image_Animation Animation hints
3282 * If you want to animate image objects on a UI (what you'd get by
3283 * concomitant usage of other libraries, like Ecore and Edje), there
3284 * are also some tips on how to boost the performance of your
3285 * application. If the animation involves resizing of an image (thus,
3286 * re-scaling), you'd better turn off smooth scaling on it @b during
3287 * the animation, turning it back on afterwards, for less
3288 * computations. Also, in this case you'd better flag the image object
3289 * in question not to cache scaled versions of it:
3291 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC);
3293 * // resizing takes place in between
3295 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC);
3298 * Finally, movement of opaque images through the canvas is less
3299 * expensive than of translucid ones, because of blending
3302 * @section Evas_Object_Image_Borders Borders
3304 * Evas provides facilities for one to specify an image's region to be
3305 * treated specially -- as borders. This will make those regions be
3306 * treated specially on resizing scales, by keeping their aspect. This
3307 * makes setting frames around other objects on UIs easy.
3308 * See the following figures for a visual explanation:
3310 * <img src="image-borders.png" style="max-width: 100%;" />
3311 * <a href="image-borders.png">Full-size</a>
3313 * @image rtf image-borders.png
3314 * @image latex image-borders.eps width=\textwidth
3316 * <img src="border-effect.png" style="max-width: 100%;" />
3317 * <a href="border-effect.png">Full-size</a>
3319 * @image rtf border-effect.png
3320 * @image latex border-effect.eps width=\textwidth
3322 * @section Evas_Object_Image_Manipulation Manipulating pixels
3324 * Evas image objects can be used to manipulate raw pixels in many
3325 * ways. The meaning of the data in the pixel arrays will depend on
3326 * the image's color space, be warned (see next section). You can set
3327 * your own data as an image's pixel data, fetch an image's pixel data
3328 * for saving/altering, convert images between different color spaces
3329 * and even advanced operations like setting a native surface as image
3332 * @section Evas_Object_Image_Color_Spaces Color spaces
3334 * Image objects may return or accept image data in multiple
3335 * formats. This is based on the color space of an object. Here is a
3336 * rundown on formats:
3338 * - #EVAS_COLORSPACE_ARGB8888:
3339 * This pixel format is a linear block of pixels, starting at the
3340 * top-left row by row until the bottom right of the image or pixel
3341 * region. All pixels are 32-bit unsigned int's with the high-byte
3342 * being alpha and the low byte being blue in the format ARGB. Alpha
3343 * may or may not be used by evas depending on the alpha flag of the
3344 * image, but if not used, should be set to 0xff anyway.
3345 * This colorspace uses premultiplied alpha. That means that R, G
3346 * and B cannot exceed A in value. The conversion from
3347 * non-premultiplied colorspace is:
3348 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
3349 * So 50% transparent blue will be: 0x80000080. This will not be
3350 * dark - just 50% transparent. Values are 0 == black, 255 ==
3351 * solid or full red, green or blue.
3353 * - #EVAS_COLORSPACE_YCBCR422P601_PL:
3354 * This is a pointer-list indirected set of YUV (YCbCr) pixel
3355 * data. This means that the data returned or set is not actual
3356 * pixel data, but pointers TO lines of pixel data. The list of
3357 * pointers will first be N rows of pointers to the Y plane -
3358 * pointing to the first pixel at the start of each row in the Y
3359 * plane. N is the height of the image data in pixels. Each pixel in
3360 * the Y, U and V planes is 1 byte exactly, packed. The next N / 2
3361 * pointers will point to rows in the U plane, and the next N / 2
3362 * pointers will point to the V plane rows. U and V planes are half
3363 * the horizontal and vertical resolution of the Y plane.
3364 * Row order is top to bottom and row pixels are stored left to
3366 * There is a limitation that these images MUST be a multiple of 2
3367 * pixels in size horizontally or vertically. This is due to the U
3368 * and V planes being half resolution. Also note that this assumes
3369 * the itu601 YUV colorspace specification. This is defined for
3370 * standard television and mpeg streams. HDTV may use the itu709
3372 * Values are 0 to 255, indicating full or no signal in that plane
3375 * - #EVAS_COLORSPACE_YCBCR422P709_PL:
3376 * Not implemented yet.
3378 * - #EVAS_COLORSPACE_RGB565_A5P:
3379 * In the process of being implemented in 1 engine only. This may
3381 * This is a pointer to image data for 16-bit half-word pixel data
3382 * in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue),
3383 * with the high-byte containing red and the low byte containing
3384 * blue, per pixel. This data is packed row by row from the top-left
3385 * to the bottom right.
3386 * If the image has an alpha channel enabled there will be an extra
3387 * alpha plane after the color pixel plane. If not, then this data
3388 * will not exist and should not be accessed in any way. This plane
3389 * is a set of pixels with 1 byte per pixel defining the alpha
3390 * values of all pixels in the image from the top-left to the bottom
3391 * right of the image, row by row. Even though the values of the
3392 * alpha pixels can be 0 to 255, only values 0 through to 32 are
3393 * used, 32 being solid and 0 being transparent.
3394 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
3395 * with 0 being black and 31 or 63 being full red, green or blue
3396 * respectively. This colorspace is also pre-multiplied like
3397 * EVAS_COLORSPACE_ARGB8888 so:
3398 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
3400 * - #EVAS_COLORSPACE_GRY8:
3401 * The image is just a alpha mask (8 bit's per pixel). This is used
3402 * for alpha masking.
3404 * @warning We don't guarantee any proper results if you create a Image object
3405 * without setting the evas engine.
3407 * Some examples on this group of functions can be found @ref
3408 * Example_Evas_Images here.
3410 * @ingroup Evas_Object_Specific
3415 * Function signature for the evas object pixels get callback function
3416 * @see evas_object_image_pixels_get()
3418 * By @a data it will be passed the private data. By @a o it will be passed the
3419 * Evas_Object image on which the pixels are requested.
3422 typedef void (*Evas_Object_Image_Pixels_Get_Cb)(void *data, Evas_Object *o);
3425 * Check if a file extension may be supported by @ref Evas_Object_Image.
3429 * @param file The file to check
3430 * @return @c EINA_TRUE if we may be able to open it, @c EINA_FALSE if it's
3434 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
3436 * This functions is threadsafe.
3438 EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
3441 * Check if a file extension may be supported by @ref Evas_Object_Image.
3445 * @param file The file to check, it should be an Eina_Stringshare.
3446 * @return @c EINA_TRUE if we may be able to open it, @c EINA_FALSE if it's
3450 * This functions is threadsafe.
3452 EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
3458 * @defgroup Evas_Object_Text Text Object Functions
3460 * Functions that operate on single line, single style text objects.
3462 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
3464 * See some @ref Example_Evas_Text examples on this group of functions.
3466 * @warning We don't guarantee any proper results if you create a Text object
3467 * without setting the evas engine.
3469 * @ingroup Evas_Object_Specific
3473 /* basic styles (4 bits allocated use 0->10 now, 5 left) */
3474 #define EVAS_TEXT_STYLE_MASK_BASIC 0xf
3477 * Text style type creation macro. Use style types on the 's'
3478 * arguments, being 'x' your style variable.
3480 #define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
3481 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
3483 #define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
3486 * Text style type creation macro. This one will impose shadow
3487 * directions on the style type variable -- use the @c
3488 * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* values on 's', incrementally.
3490 #define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
3491 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
3494 * @typedef Evas_Text_Style_Type
3496 * Types of styles to be applied on text objects. The @c
3497 * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* ones are to be ORed together with others
3498 * imposing shadow, to change shadow's direction
3500 typedef enum _Evas_Text_Style_Type
3502 EVAS_TEXT_STYLE_PLAIN, /**< plain, standard text */
3503 EVAS_TEXT_STYLE_SHADOW, /**< text with shadow underneath */
3504 EVAS_TEXT_STYLE_OUTLINE, /**< text with an outline */
3505 EVAS_TEXT_STYLE_SOFT_OUTLINE, /**< text with a soft outline */
3506 EVAS_TEXT_STYLE_GLOW, /**< text with a glow effect */
3507 EVAS_TEXT_STYLE_OUTLINE_SHADOW, /**< text with both outline and shadow effects */
3508 EVAS_TEXT_STYLE_FAR_SHADOW, /**< text with (far) shadow underneath */
3509 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW, /**< text with outline and soft shadow effects combined */
3510 EVAS_TEXT_STYLE_SOFT_SHADOW, /**< text with (soft) shadow underneath */
3511 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW, /**< text with (far soft) shadow underneath */
3513 /* OR these to modify shadow direction (3 bits needed) */
3514 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< shadow growing to bottom right */
3515 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< shadow growing to the bottom */
3516 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< shadow growing to bottom left */
3517 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< shadow growing to the left */
3518 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< shadow growing to top left */
3519 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< shadow growing to the top */
3520 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< shadow growing to top right */
3521 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< shadow growing to the right */
3522 } Evas_Text_Style_Type;
3528 * @defgroup Evas_Object_Textblock Textblock Object Functions
3530 * Functions used to create and manipulate textblock objects. Unlike
3531 * @ref Evas_Object_Text, these handle complex text, doing multiple
3532 * styles and multiline text based on HTML-like tags. Of these extra
3533 * features will be heavier on memory and processing cost.
3535 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
3537 * This part explains about the textblock object's API and proper usage.
3538 * The main user of the textblock object is the edje entry object in Edje, so
3539 * that's a good place to learn from, but I think this document is more than
3540 * enough, if it's not, please contact me and I'll update it.
3542 * @subsection textblock_intro Introduction
3543 * The textblock objects is, as implied, an object that can show big chunks of
3544 * text. Textblock supports many features including: Text formatting, automatic
3545 * and manual text alignment, embedding items (for example icons) and more.
3546 * Textblock has three important parts, the text paragraphs, the format nodes
3549 * You can use markup to format text, for example: "<font_size=50>Big!</font_size>".
3550 * You can also put more than one style directive in one tag:
3551 * "<font_size=50 color=#F00>Big and Red!</font_size>".
3552 * Please notice that we used </font_size> although the format also included
3553 * color, this is because the first format determines the matching closing tag's
3554 * name. You can also use anonymous tags, like: "<font_size=30>Big</>" which
3555 * just pop any type of format, but it's advised to use the named alternatives
3558 * @subsection textblock_cursors Textblock Object Cursors
3559 * A textblock Cursor is data type that represents
3560 * a position in a textblock. Each cursor contains information about the
3561 * paragraph it points to, the position in that paragraph and the object itself.
3562 * Cursors register to textblock objects upon creation, this means that once
3563 * you created a cursor, it belongs to a specific obj and you can't for example
3564 * copy a cursor into a cursor of a different object. Registered cursors
3565 * also have the added benefit of updating automatically upon textblock changes,
3566 * this means that if you have a cursor pointing to a specific character, it'll
3567 * still point to it even after you change the whole object completely (as long
3568 * as the char was not deleted), this is not possible without updating, because
3569 * as mentioned, each cursor holds a character position. There are many
3570 * functions that handle cursors, just check out the evas_textblock_cursor*
3571 * functions. For creation and deletion of cursors check out:
3572 * @see evas_object_textblock_cursor_new()
3573 * @see evas_textblock_cursor_free()
3574 * @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).
3576 * @subsection textblock_paragraphs Textblock Object Paragraphs
3577 * The textblock object is made out of text splitted to paragraphs (delimited
3578 * by the paragraph separation character). Each paragraph has many (or none)
3579 * format nodes associated with it which are responsible for the formatting
3580 * of that paragraph.
3582 * @subsection textblock_format_nodes Textblock Object Format Nodes
3583 * As explained in @ref textblock_paragraphs each one of the format nodes
3584 * is associated with a paragraph.
3585 * There are two types of format nodes, visible and invisible:
3586 * Visible: formats that a cursor can point to, i.e formats that
3587 * occupy space, for example: newlines, tabs, items and etc. Some visible items
3588 * are made of two parts, in this case, only the opening tag is visible.
3589 * A closing tag (i.e a \</tag\> tag) should NEVER be visible.
3590 * Invisible: formats that don't occupy space, for example: bold and underline.
3591 * Being able to access format nodes is very important for some uses. For
3592 * example, edje uses the <a> format to create links in the text (and pop
3593 * popups above them when clicked). For the textblock object a is just a
3594 * formatting instruction (how to color the text), but edje utilizes the access
3595 * to the format nodes to make it do more.
3596 * For more information, take a look at all the evas_textblock_node_format_*
3598 * The translation of <tag> tags to actual format is done according to the
3599 * tags defined in the style, see @ref evas_textblock_style_set
3601 * @subsection textblock_special_formats Special Formats
3602 * Textblock supports various format directives that can be used in markup. In
3603 * addition to the mentioned format directives, textblock allows creating
3604 * additional format directives using tags that can be set in the style see
3605 * @ref evas_textblock_style_set .
3607 * For more details see @ref evas_textblock_style_page
3609 * Textblock supports the following formats:
3610 * @li font - Font description in fontconfig like format, e.g: Sans:style=Italic:lang=hi. or Serif:style=Bold.
3611 * @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.
3612 * @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.
3613 * @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.
3614 * @li lang - Overrides the language defined in font. E.g: lang=he is the same as font=:lang=he.
3615 * @li font_fallbacks - A comma delimited list of fonts to try if finding the main font fails.
3616 * @li font_size - The font size in points.
3617 * @li font_source - The source of the font, e.g an eet file.
3618 * @li color - Text color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3619 * @li underline_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3620 * @li underline2_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3621 * @li outline_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3622 * @li shadow_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3623 * @li glow_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3624 * @li glow2_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3625 * @li strikethrough_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3626 * @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%.
3627 * @li valign - Either top, bottom, middle, center, baseline, base, a value between 0.0 and 1.0, or a value between 0% to 100%.
3628 * @li wrap - word, char, mixed, or none.
3629 * @li left_margin - Either reset, or a pixel value indicating the margin.
3630 * @li right_margin - Either reset, or a pixel value indicating the margin.
3631 * @li underline - on, off, single, or double.
3632 * @li strikethrough - on or off
3633 * @li backing_color - Background color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3634 * @li backing - Enable/disable background color. ex) on or off
3635 * @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.
3636 * @li tabstops - Pixel value for tab width.
3637 * @li linesize - Force a line size in pixels.
3638 * @li linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
3639 * @li linegap - Force a line gap in pixels.
3640 * @li linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
3641 * @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.
3642 * @li linefill - Either a float value or percentage indicating how much to fill the line.
3643 * @li ellipsis - Value between 0.0-1.0 to indicate the type of ellipsis, or -1.0 to indicate ellipsis isn't wanted.
3644 * @li password - on or off. This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off.
3646 * @warning We don't guarantee any proper results if you create a Textblock
3648 * without setting the evas engine.
3650 * @todo put here some usage examples
3652 * @ingroup Evas_Object_Specific
3658 * @typedef Evas_Textblock_Style
3660 * A textblock style object.
3661 * @see evas_textblock_style_new()
3662 * @see evas_textblock_style_get()
3663 * @see evas_textblock_style_set()
3666 typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
3669 * @typedef Evas_Textblock_Cursor
3671 * A textblock cursor object, used to maipulate the cursor of an evas textblock
3672 * @see evas_object_textblock_cursor_new
3675 typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
3678 * @typedef Evas_Object_Textblock_Node_Format
3681 typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
3683 typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
3684 struct _Evas_Textblock_Rectangle
3686 Evas_Coord x, y, w, h;
3690 * Text type for evas textblock.
3692 typedef enum _Evas_Textblock_Text_Type
3694 EVAS_TEXTBLOCK_TEXT_RAW, /**< textblock text of type raw */
3695 EVAS_TEXTBLOCK_TEXT_PLAIN, /**< textblock text of type plain */
3696 EVAS_TEXTBLOCK_TEXT_MARKUP /**< textblock text of type markup */
3697 } Evas_Textblock_Text_Type;
3700 * Cursor type for evas textblock.
3702 typedef enum _Evas_Textblock_Cursor_Type
3704 EVAS_TEXTBLOCK_CURSOR_UNDER, /**< cursor type is under */
3705 EVAS_TEXTBLOCK_CURSOR_BEFORE /**< cursor type is before */
3706 } Evas_Textblock_Cursor_Type;
3709 * @brief Returns the unescaped version of escape.
3710 * @param[in] escape the string to be escaped
3712 * @if MOBILE @since_tizen 2.3
3713 * @elseif WEARABLE @since_tizen 2.3.1
3716 * @return the unescaped version of escape
3718 EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3721 * @brief Returns the escaped version of the string.
3722 * @param[in] string to escape
3723 * @param[out] len_ret the len of the part of the string that was used.
3725 * @if MOBILE @since_tizen 2.3
3726 * @elseif WEARABLE @since_tizen 2.3.1
3729 * @return the escaped string.
3731 EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3734 * @brief Return the unescaped version of the string between start and end.
3736 * @if MOBILE @since_tizen 2.3
3737 * @elseif WEARABLE @since_tizen 2.3.1
3740 * @param[in] escape_start the start of the string.
3741 * @param[in] escape_end the end of the string.
3742 * @return the unescaped version of the range
3744 EAPI const char *evas_textblock_escape_string_range_get(const char *escape_start, const char *escape_end) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
3747 * @brief Creates a new textblock style.
3749 * @if MOBILE @since_tizen 2.3
3750 * @elseif WEARABLE @since_tizen 2.3.1
3753 * @return The new textblock style.
3755 EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
3758 * @brief Destroys a textblock style.
3759 * @param[in] ts The textblock style to free.
3761 * @if MOBILE @since_tizen 2.3
3762 * @elseif WEARABLE @since_tizen 2.3.1
3766 EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
3769 * @brief Sets the style ts to the style passed as text by text.
3770 * Expected a string consisting of many (or none) tag='format' pairs.
3772 * @if MOBILE @since_tizen 2.3
3773 * @elseif WEARABLE @since_tizen 2.3.1
3776 * @param[in] ts the style to set.
3777 * @param[in] text the text to parse - NOT NULL.
3778 * @return Returns no value.
3780 EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
3783 * @brief Return the text of the style ts.
3784 * @param[in] ts the style to get it's text.
3786 * @if MOBILE @since_tizen 2.3
3787 * @elseif WEARABLE @since_tizen 2.3.1
3790 * @return the text of the style or null on error.
3792 EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3795 * @brief Prepends markup to the cursor cur.
3797 * @if MOBILE @since_tizen 2.3
3798 * @elseif WEARABLE @since_tizen 2.3.1
3801 * @remark assumes text does not include the unicode object replacement char (0xFFFC)
3803 * @param[in] cur the cursor to prepend to.
3804 * @param[in] text the markup text to prepend.
3805 * @return Return no value.
3807 EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
3810 * @brief Free the cursor and unassociate it from the object.
3811 * @note do not use it to free unassociated cursors.
3813 * @if MOBILE @since_tizen 2.3
3814 * @elseif WEARABLE @since_tizen 2.3.1
3817 * @param[in] cur the cursor to free.
3818 * @return Returns no value.
3820 EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3823 * @brief Sets the cursor to the start of the first text node.
3825 * @if MOBILE @since_tizen 2.3
3826 * @elseif WEARABLE @since_tizen 2.3.1
3829 * @param[in] cur the cursor to update.
3830 * @return Returns no value.
3832 EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3835 * @brief sets the cursor to the end of the last text node.
3837 * @if MOBILE @since_tizen 2.3
3838 * @elseif WEARABLE @since_tizen 2.3.1
3841 * @param[in] cur the cursor to set.
3842 * @return Returns no value.
3844 EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3847 * @brief Advances to the start of the next text node
3849 * @if MOBILE @since_tizen 2.3
3850 * @elseif WEARABLE @since_tizen 2.3.1
3853 * @param[in] cur the cursor to update
3854 * @return @c EINA_TRUE if it managed to advance a paragraph, @c EINA_FALSE
3857 EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3860 * @brief Advances to the end of the previous text node
3862 * @if MOBILE @since_tizen 2.3
3863 * @elseif WEARABLE @since_tizen 2.3.1
3866 * @param[in] cur the cursor to update
3867 * @return @c EINA_TRUE if it managed to advance a paragraph, @c EINA_FALSE
3870 EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3873 * @brief Returns the next format node (after n)
3875 * @if MOBILE @since_tizen 2.3
3876 * @elseif WEARABLE @since_tizen 2.3.1
3879 * @param[in] n the current format node - not null.
3880 * @return Returns the next format node, may be null.
3882 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
3885 * @brief Returns the prev format node (after n)
3887 * @if MOBILE @since_tizen 2.3
3888 * @elseif WEARABLE @since_tizen 2.3.1
3891 * @param[in] n the current format node - not null.
3892 * @return Returns the prev format node, may be null.
3894 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
3897 * @brief Sets the cursor to point to the place where format points to.
3899 * @if MOBILE @since_tizen 2.3
3900 * @elseif WEARABLE @since_tizen 2.3.1
3903 * @param[in] cur the cursor to update.
3904 * @param[in] n the format node to update according.
3905 * @deprecated Use evas_textblock_cursor_at_format_set instead
3906 * Deprecated since Tizen 2.4
3908 EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
3911 * @brief Return the format node at the position pointed by cur.
3913 * @if MOBILE @since_tizen 2.3
3914 * @elseif WEARABLE @since_tizen 2.3.1
3917 * @param[in] cur the position to look at.
3918 * @return the format node if found, @c NULL otherwise.
3919 * @see evas_textblock_cursor_format_is_visible_get()
3921 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3924 * @brief Get the text format representation of the format node.
3926 * @if MOBILE @since_tizen 2.3
3927 * @elseif WEARABLE @since_tizen 2.3.1
3930 * @param[in] fnode the format node.
3931 * @return the textual format of the format node.
3933 EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fnode) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3936 * @brief Set the cursor to point to the position of fmt.
3938 * @if MOBILE @since_tizen 2.3
3939 * @elseif WEARABLE @since_tizen 2.3.1
3942 * @param[in] cur the cursor to update
3943 * @param[in] fmt the format to update according to.
3945 EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
3948 * @brief Check if the current cursor position is a visible format. This way is more
3949 * efficient than evas_textblock_cursor_format_get() to check for the existence
3950 * of a visible format.
3952 * @if MOBILE @since_tizen 2.3
3953 * @elseif WEARABLE @since_tizen 2.3.1
3956 * @param[in] cur the cursor to look at.
3957 * @return @c EINA_TRUE if the cursor points to a visible format, @c EINA_FALSE
3959 * @see evas_textblock_cursor_format_get()
3961 EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3964 * @brief Advances to the next format node
3966 * @if MOBILE @since_tizen 2.3
3967 * @elseif WEARABLE @since_tizen 2.3.1
3970 * @param[in] cur the cursor to be updated.
3971 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3973 EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3976 * @brief Advances to the previous format node.
3978 * @if MOBILE @since_tizen 2.3
3979 * @elseif WEARABLE @since_tizen 2.3.1
3982 * @param[in] cur the cursor to update.
3983 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3985 EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3988 * @brief Returns true if the cursor points to a format.
3990 * @if MOBILE @since_tizen 2.3
3991 * @elseif WEARABLE @since_tizen 2.3.1
3994 * @param[in] cur the cursor to check.
3995 * @return @c EINA_TRUE if a cursor points to a format @c EINA_FALSE
3998 EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4001 * @brief Advances 1 char forward.
4003 * @if MOBILE @since_tizen 2.3
4004 * @elseif WEARABLE @since_tizen 2.3.1
4007 * @param[in] cur the cursor to advance.
4008 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4010 EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4013 * @brief Advances 1 char backward.
4015 * @if MOBILE @since_tizen 2.3
4016 * @elseif WEARABLE @since_tizen 2.3.1
4019 * @param[in] cur the cursor to advance.
4020 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4022 EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4026 * TIZEN_ONLY(20150127): Add evas_textblock_cursor_cluster_* APIs.
4027 * Advances 1 cluster forward.
4028 * Cluster is an text ligature.
4030 * @param cur the cursor to advance.
4031 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4033 EAPI Eina_Bool evas_textblock_cursor_cluster_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4037 * TIZEN_ONLY(20150127): Add evas_textblock_cursor_cluster_* APIs.
4038 * Advances 1 cluster backward.
4039 * Cluster is an text ligature.
4041 * @param cur the cursor to advance.
4042 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4044 EAPI Eina_Bool evas_textblock_cursor_cluster_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4047 * @brief Moves the cursor to the start of the word under the cursor.
4049 * @if MOBILE @since_tizen 2.3
4050 * @elseif WEARABLE @since_tizen 2.3.1
4053 * @param[in] cur the cursor to move.
4054 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4057 EAPI Eina_Bool evas_textblock_cursor_word_start(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4060 * @brief Moves the cursor to the end of the word under the cursor.
4062 * @if MOBILE @since_tizen 2.3
4063 * @elseif WEARABLE @since_tizen 2.3.1
4066 * @param[in] cur the cursor to move.
4067 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4070 EAPI Eina_Bool evas_textblock_cursor_word_end(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4073 * @brief Go to the first char in the node the cursor is pointing on.
4075 * @if MOBILE @since_tizen 2.3
4076 * @elseif WEARABLE @since_tizen 2.3.1
4079 * @param[in] cur the cursor to update.
4080 * @return Returns no value.
4082 EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4085 * @brief Go to the last char in a text node.
4087 * @if MOBILE @since_tizen 2.3
4088 * @elseif WEARABLE @since_tizen 2.3.1
4091 * @param[in] cur the cursor to update.
4092 * @return Returns no value.
4094 EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4097 * @brief Go to the start of the current line
4099 * @if MOBILE @since_tizen 2.3
4100 * @elseif WEARABLE @since_tizen 2.3.1
4103 * @param[in] cur the cursor to update.
4104 * @return Returns no value.
4106 EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4109 * @brief Go to the end of the current line.
4111 * @if MOBILE @since_tizen 2.3
4112 * @elseif WEARABLE @since_tizen 2.3.1
4115 * @param[in] cur the cursor to update.
4116 * @return Returns no value.
4118 EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4121 * @brief Return the current cursor pos.
4123 * @if MOBILE @since_tizen 2.3
4124 * @elseif WEARABLE @since_tizen 2.3.1
4127 * @param[in] cur the cursor to take the position from.
4128 * @return the position or -1 on error
4130 EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4133 * @brief Set the cursor pos.
4135 * @if MOBILE @since_tizen 2.3
4136 * @elseif WEARABLE @since_tizen 2.3.1
4139 * @param[in] cur the cursor to be set.
4140 * @param[in] pos the pos to set.
4142 EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
4145 * @brief Go to the start of the line passed
4147 * @if MOBILE @since_tizen 2.3
4148 * @elseif WEARABLE @since_tizen 2.3.1
4151 * @param[in] cur cursor to update.
4152 * @param[in] line numer to set.
4153 * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
4155 EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
4158 * @brief Compare two cursors.
4160 * @if MOBILE @since_tizen 2.3
4161 * @elseif WEARABLE @since_tizen 2.3.1
4164 * @param[in] cur1 the first cursor.
4165 * @param[in] cur2 the second cursor.
4166 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
4168 EAPI int evas_textblock_cursor_compare(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
4171 * @brief Make cur_dest point to the same place as cur. Does not work if they don't
4172 * point to the same object.
4174 * @if MOBILE @since_tizen 2.3
4175 * @elseif WEARABLE @since_tizen 2.3.1
4178 * @param[in] cur the source cursor.
4179 * @param[in] cur_dest destination cursor.
4180 * @return Returns no value.
4182 EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
4185 * @brief Adds text to the current cursor position and set the cursor to *before*
4186 * the start of the text just added.
4188 * @if MOBILE @since_tizen 2.3
4189 * @elseif WEARABLE @since_tizen 2.3.1
4192 * @param[in] cur the cursor to where to add text at.
4193 * @param[in] text the text to add.
4194 * @return Returns the len of the text added.
4195 * @see evas_textblock_cursor_text_prepend()
4197 EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
4200 * @brief Adds text to the current cursor position and set the cursor to *after*
4201 * the start of the text just added.
4203 * @if MOBILE @since_tizen 2.3
4204 * @elseif WEARABLE @since_tizen 2.3.1
4207 * @param[in] cur the cursor to where to add text at.
4208 * @param[in] text the text to add.
4209 * @return Returns the len of the text added.
4210 * @see evas_textblock_cursor_text_append()
4212 EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
4215 * Adds format to the current cursor position. If the format being added is a
4216 * visible format, add it *before* the cursor position, otherwise, add it after.
4217 * This behavior is because visible formats are like characters and invisible
4218 * should be stacked in a way that the last one is added last.
4220 * This function works with native formats, that means that style defined
4221 * tags like <br> won't work here. For those kind of things use markup prepend.
4223 * @param cur the cursor to where to add format at.
4224 * @param format the format to add.
4225 * @return Returns true if a visible format was added, false otherwise.
4226 * @see evas_textblock_cursor_format_prepend()
4230 * @brief Check if the current cursor position points to the terminating null of the
4231 * last paragraph. (shouldn't be allowed to point to the terminating null of
4232 * any previous paragraph anyway.
4234 * @if MOBILE @since_tizen 2.3
4235 * @elseif WEARABLE @since_tizen 2.3.1
4238 * @param[in] cur the cursor to look at.
4239 * @return @c EINA_TRUE if the cursor points to the terminating null, @c EINA_FALSE otherwise.
4241 EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
4244 * @brief Adds format to the current cursor position. If the format being added is a
4245 * visible format, add it *before* the cursor position, otherwise, add it after.
4246 * This behavior is because visible formats are like characters and invisible
4247 * should be stacked in a way that the last one is added last.
4248 * If the format is visible the cursor is advanced after it.
4250 * @if MOBILE @since_tizen 2.3
4251 * @elseif WEARABLE @since_tizen 2.3.1
4254 * @remark This function works with native formats, that means that style defined
4255 * tags like <br> won't work here. For those kind of things use markup prepend.
4257 * @param[in] cur the cursor to where to add format at.
4258 * @param[in] format the format to add.
4259 * @return Returns true if a visible format was added, false otherwise.
4260 * @see evas_textblock_cursor_format_prepend()
4262 EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
4265 * @brief Delete the character at the location of the cursor. If there's a format
4266 * pointing to this position, delete it as well.
4268 * @if MOBILE @since_tizen 2.3
4269 * @elseif WEARABLE @since_tizen 2.3.1
4272 * @param[in] cur the cursor pointing to the current location.
4273 * @return Returns no value.
4275 EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4278 * @brief Delete the range between cur1 and cur2.
4280 * @if MOBILE @since_tizen 2.3
4281 * @elseif WEARABLE @since_tizen 2.3.1
4284 * @param[in] cur1 one side of the range.
4285 * @param[in] cur2 the second side of the range
4286 * @return Returns no value.
4288 EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
4291 * @brief Return the text of the paragraph cur points to - returns the text in markup.
4293 * @if MOBILE @since_tizen 2.3
4294 * @elseif WEARABLE @since_tizen 2.3.1
4297 * @param[in] cur the cursor pointing to the paragraph.
4298 * @return the text on success, @c NULL otherwise.
4300 EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4303 * @brief Return the length of the paragraph, cheaper the eina_unicode_strlen()
4305 * @if MOBILE @since_tizen 2.3
4306 * @elseif WEARABLE @since_tizen 2.3.1
4309 * @param[in] cur the position of the paragraph.
4310 * @return the length of the paragraph on success, -1 otehrwise.
4312 EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4315 * @brief Return the currently visible range.
4317 * @if MOBILE @since_tizen 2.3
4318 * @elseif WEARABLE @since_tizen 2.3.1
4321 * @param[in] start the start of the range.
4322 * @param[in] end the end of the range.
4323 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
4326 EAPI Eina_Bool evas_textblock_cursor_visible_range_get(Evas_Textblock_Cursor *start, Evas_Textblock_Cursor *end) EINA_ARG_NONNULL(1, 2);
4329 * @brief Return the format nodes in the range between cur1 and cur2.
4331 * @if MOBILE @since_tizen 2.3
4332 * @elseif WEARABLE @since_tizen 2.3.1
4335 * @param[in] cur1 one side of the range.
4336 * @param[in] cur2 the other side of the range
4337 * @return the foramt nodes in the range. You have to free it.
4340 EAPI 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);
4343 * @brief Return the text in the range between cur1 and cur2
4345 * @if MOBILE @since_tizen 2.3
4346 * @elseif WEARABLE @since_tizen 2.3.1
4349 * @param[in] cur1 one side of the range.
4350 * @param[in] cur2 the other side of the range
4351 * @param[in] format The form on which to return the text. Markup - in textblock markup. Plain - UTF8.
4352 * @return the text in the range
4353 * @see elm_entry_markup_to_utf8()
4355 EAPI char *evas_textblock_cursor_range_text_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2, Evas_Textblock_Text_Type format) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
4359 * // TIZEN_ONLY(20150128): Add evas_textblock_cursor_range_text_valid_markup_get API.
4360 * @brief Gets the text and markup tags in the range between @a cur1 and @a cur2.
4362 * @param cur1 The start of the range
4363 * @param cur2 The end of the range
4364 * @return The text in the range and the markup tags that affect the text
4365 * @see elm_entry_markup_to_utf8()
4367 EAPI char *evas_textblock_cursor_range_text_valid_markup_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
4370 * @brief Return the content of the cursor.
4372 * @if MOBILE @since_tizen 2.3
4373 * @elseif WEARABLE @since_tizen 2.3.1
4376 * @remark Free the returned string pointer when done (if it is not NULL).
4378 * @param[in] cur the cursor
4379 * @return the text in the range, terminated by a nul byte (may be utf8).
4381 EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
4384 * @brief Returns the geometry of two cursors (split cursor), if logical cursor is
4385 * between LTR/RTL text, also considering paragraph direction.
4386 * Upper cursor is shown for the text of the same direction as paragraph,
4387 * lower cursor - for opposite.
4389 * @if MOBILE @since_tizen 2.3
4390 * @elseif WEARABLE @since_tizen 2.3.1
4393 * @remark Split cursor geometry is valid only in '|' cursor mode.
4394 * In this case @c EINA_TRUE is returned and cx2, cy2, cw2, ch2 are set,
4395 * otherwise it behaves like cursor_geometry_get.
4397 * @param[in] cur the cursor.
4398 * @param[out] cx the x of the cursor (or upper cursor)
4399 * @param[out] cy the y of the cursor (or upper cursor)
4400 * @param[out] cw the width of the cursor (or upper cursor)
4401 * @param[out] ch the height of the cursor (or upper cursor)
4402 * @param[out] cx2 the x of the lower cursor
4403 * @param[out] cy2 the y of the lower cursor
4404 * @param[out] cw2 the width of the lower cursor
4405 * @param[out] ch2 the height of the lower cursor
4406 * @param[in] ctype the type of the cursor.
4407 * @return @c EINA_TRUE for split cursor, @c EINA_FALSE otherwise
4411 evas_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);
4414 * @brief Returns the geometry of the cursor. Depends on the type of cursor requested.
4415 * This should be used instead of char_geometry_get because there are weird
4416 * special cases with BiDi text.
4417 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
4418 * get, except for the case of the last char of a line which depends on the
4419 * paragraph direction.
4421 * @if MOBILE @since_tizen 2.3
4422 * @elseif WEARABLE @since_tizen 2.3.1
4425 * @remark in '|' cursor mode (i.e a line between two chars) it is very variable.
4426 * For example consider the following visual string:
4427 * abcCBA (ABC are rtl chars), a cursor pointing on A should actually draw
4428 * a '|' between the c and the C.
4430 * @param[in] cur the cursor.
4431 * @param[out] cx the x of the cursor
4432 * @param[out] cy the y of the cursor
4433 * @param[out] cw the width of the cursor
4434 * @param[out] ch the height of the cursor
4435 * @param[out] dir the direction of the cursor, can be NULL.
4436 * @param[in] ctype the type of the cursor.
4437 * @return line number of the char on success, -1 on error.
4439 EAPI int evas_textblock_cursor_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch, Evas_BiDi_Direction *dir, Evas_Textblock_Cursor_Type ctype) EINA_ARG_NONNULL(1);
4442 * @brief Returns the geometry of the char at cur.
4444 * @if MOBILE @since_tizen 2.3
4445 * @elseif WEARABLE @since_tizen 2.3.1
4448 * @param[in] cur the position of the char.
4449 * @param[out] cx the x of the char.
4450 * @param[out] cy the y of the char.
4451 * @param[out] cw the w of the char.
4452 * @param[out] ch the h of the char.
4453 * @return line number of the char on success, -1 on error.
4455 EAPI int evas_textblock_cursor_char_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
4458 * @brief Returns the geometry of the pen at cur.
4460 * @if MOBILE @since_tizen 2.3
4461 * @elseif WEARABLE @since_tizen 2.3.1
4464 * @param[in] cur the position of the char.
4465 * @param[out] cpen_x the pen_x of the char.
4466 * @param[out] cy the y of the char.
4467 * @param[out] cadv the adv of the char.
4468 * @param[out] ch the h of the char.
4469 * @return line number of the char on success, -1 on error.
4471 EAPI int evas_textblock_cursor_pen_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cpen_x, Evas_Coord *cy, Evas_Coord *cadv, Evas_Coord *ch) EINA_ARG_NONNULL(1);
4474 * @brief Returns the geometry of the line at cur.
4476 * @if MOBILE @since_tizen 2.3
4477 * @elseif WEARABLE @since_tizen 2.3.1
4480 * @param[in] cur the position of the line.
4481 * @param[out] cx the x of the line.
4482 * @param[out] cy the y of the line.
4483 * @param[out] cw the width of the line.
4484 * @param[out] ch the height of the line.
4485 * @return line number of the line on success, -1 on error.
4487 EAPI int evas_textblock_cursor_line_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
4490 * @brief Set the position of the cursor according to the X and Y coordinates.
4492 * @if MOBILE @since_tizen 2.3
4493 * @elseif WEARABLE @since_tizen 2.3.1
4496 * @param[in] cur the cursor to set.
4497 * @param[in] x coord to set by.
4498 * @param[in] y coord to set by.
4499 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
4501 EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
4505 * TIZEN_ONLY(20150127): Add evas_textblock_cursor_cluster_* APIs.
4506 * Set the position of the cursor according to the X and Y coordinates and text ligature.
4508 * @param cur the cursor to set.
4509 * @param x coord to set by.
4510 * @param y coord to set by.
4511 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
4513 EAPI Eina_Bool evas_textblock_cursor_cluster_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
4516 * @brief Set the cursor position according to the y coord.
4518 * @if MOBILE @since_tizen 2.3
4519 * @elseif WEARABLE @since_tizen 2.3.1
4522 * @param[in] cur the cur to be set.
4523 * @param[in] y the coord to set by.
4524 * @return the line number found, -1 on error.
4526 EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
4529 * @brief Get the geometry of a range.
4531 * @if MOBILE @since_tizen 2.3
4532 * @elseif WEARABLE @since_tizen 2.3.1
4535 * @param[in] cur1 one side of the range.
4536 * @param[in] cur2 other side of the range.
4537 * @return a list of Rectangles representing the geometry of the range.
4539 EAPI Eina_List *evas_textblock_cursor_range_geometry_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
4544 * Get the simple geometry of a range.
4545 * The simple geometry is the geomtry in which rectangles in middle
4546 * lines of range are merged into one big rectangle.
4549 * @param cur1 one side of the range.
4550 * @param cur2 other side of the range.
4551 * @return an iterator of rectangles representing the geometry of the range.
4553 EAPI Eina_Iterator *evas_textblock_cursor_range_simple_geometry_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
4558 * Get the geometry of ?
4560 * @param cur one side of the range.
4561 * @param cur2 other side of the range.
4563 EAPI Eina_Bool evas_textblock_cursor_format_item_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
4566 * @brief Checks if the cursor points to the end of the line.
4568 * @if MOBILE @since_tizen 2.3
4569 * @elseif WEARABLE @since_tizen 2.3.1
4572 * @param[in] cur the cursor to check.
4573 * @return @c EINA_TRUE if true, @c EINA_FALSE otherwise.
4575 EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4583 * @defgroup Evas_Object_Textgrid Textgrid Object Functions
4585 * @todo put here some usage examples
4589 * @ingroup Evas_Object_Specific
4595 * @typedef Evas_Textgrid_Palette
4597 * The palette to use for the foreground and background colors.
4603 EVAS_TEXTGRID_PALETTE_NONE, /**< No palette is used */
4604 EVAS_TEXTGRID_PALETTE_STANDARD, /**< standard palette (around 16 colors) */
4605 EVAS_TEXTGRID_PALETTE_EXTENDED, /**< extended palette (at max 256 colors) */
4606 EVAS_TEXTGRID_PALETTE_LAST /**< ignore it */
4607 } Evas_Textgrid_Palette;
4610 * @typedef Evas_Textgrid_Font_Style
4612 * The style to give to each character of the grid.
4618 EVAS_TEXTGRID_FONT_STYLE_NORMAL = (1 << 0), /**< Normal style */
4619 EVAS_TEXTGRID_FONT_STYLE_BOLD = (1 << 1), /**< Bold style */
4620 EVAS_TEXTGRID_FONT_STYLE_ITALIC = (1 << 2) /**< Oblique style */
4621 } Evas_Textgrid_Font_Style;
4624 * @typedef Evas_Textgrid_Cell
4626 * The values that describes each cell.
4630 typedef struct _Evas_Textgrid_Cell Evas_Textgrid_Cell;
4633 * @struct _Evas_Textgrid_Cell
4635 * The values that describes each cell.
4639 struct _Evas_Textgrid_Cell
4641 Eina_Unicode codepoint; /**< the UNICODE value of the character */
4642 unsigned char fg; /**< the index of the palette for the foreground color */
4643 unsigned char bg; /**< the index of the palette for the background color */
4644 unsigned short bold : 1; /**< whether the character is bold */
4645 unsigned short italic : 1; /**< whether the character is oblique */
4646 unsigned short underline : 1; /**< whether the character is underlined */
4647 unsigned short strikethrough : 1; /**< whether the character is strikethrough'ed */
4648 unsigned short fg_extended : 1; /**< whether the extended palette is used for the foreground color */
4649 unsigned short bg_extended : 1; /**< whether the extended palette is used for the background color */
4650 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) */
4658 * @defgroup Evas_Line_Group Line Object Functions
4660 * Functions used to deal with evas line objects.
4662 * @warning We don't guarantee any proper results if you create a Line object
4663 * without setting the evas engine.
4665 * @ingroup Evas_Object_Specific
4670 * @defgroup Evas_Object_Polygon Polygon Object Functions
4672 * Functions that operate on evas polygon objects.
4674 * Hint: as evas does not provide ellipse, smooth paths or circle, one
4675 * can calculate points and convert these to a polygon.
4677 * @warning We don't guarantee any proper results if you create a Polygon
4678 * object without setting the evas engine.
4680 * @ingroup Evas_Object_Specific
4686 * @defgroup Evas_Smart_Group Smart Functions
4689 * Functions that deal with #Evas_Smart structs, creating definition
4690 * (classes) of objects that will have customized behavior for methods
4691 * like evas_object_move(), evas_object_resize(),
4692 * evas_object_clip_set() and others.
4694 * These objects will accept the generic methods defined in @ref
4695 * Evas_Object_Group and the extensions defined in @ref
4696 * Evas_Smart_Object_Group. There are a couple of existent smart
4697 * objects in Evas itself (see @ref Evas_Object_Box, @ref
4698 * Evas_Object_Table and @ref Evas_Smart_Object_Clipped).
4700 * See also some @ref Example_Evas_Smart_Objects examples of this
4701 * group of functions.
4708 * @def EVAS_SMART_CLASS_VERSION
4710 * The version you have to put into the version field in the
4711 * #Evas_Smart_Class struct. Used to safeguard from binaries with old
4712 * smart object intefaces running with newer ones.
4714 * @ingroup Evas_Smart_Group
4716 #define EVAS_SMART_CLASS_VERSION 4
4718 * @struct _Evas_Smart_Class
4720 * A smart object's @b base class definition
4722 * @ingroup Evas_Smart_Group
4724 struct _Evas_Smart_Class
4726 const char *name; /**< the name string of the class */
4728 void (*add)(Evas_Object *o); /**< code to be run when adding object to a canvas */
4729 void (*del)(Evas_Object *o); /**< code to be run when removing object from a canvas */
4730 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. */
4731 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. */
4732 void (*show)(Evas_Object *o); /**< code to be run when showing object on a canvas */
4733 void (*hide)(Evas_Object *o); /**< code to be run when hiding object on a canvas */
4734 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. */
4735 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. */
4736 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. */
4737 void (*calculate)(Evas_Object *o); /**< code to be run when object has rendering updates on a canvas */
4738 void (*member_add)(Evas_Object *o, Evas_Object *child); /**< code to be run when a child member is added to object */
4739 void (*member_del)(Evas_Object *o, Evas_Object *child); /**< code to be run when a child member is removed from object */
4741 const Evas_Smart_Class *parent; /**< this class inherits from this parent */
4742 const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, @c NULL terminated */
4743 const Evas_Smart_Interface **interfaces; /**< #Evas_Smart_Interface pointers array, @c NULL terminated. These will be the interfaces supported at this level for an object (parents may have others) @since 1.7 */
4748 * @struct _Evas_Smart_Interface
4750 * A smart object's @b base interface definition
4752 * Every Evas interface must have a name field, pointing to a global,
4753 * constant string variable. This string pointer will be the only way
4754 * of retrieving back a given interface from a smart object. Two
4755 * function pointers must be defined, too, which will be called at
4756 * object creation and deletion times.
4758 * See also some @ref Example_Evas_Smart_Interfaces examples on
4763 * @ingroup Evas_Smart_Group
4765 struct _Evas_Smart_Interface
4767 const char *name; /**< Name of the given interface */
4768 unsigned private_size; /**< Size, in bytes, of the interface's private dada blob. This will be allocated and freed automatically for you. */
4769 Eina_Bool (*add)(Evas_Object *obj); /**< Function to be called at object creation time. This will take place @b before the object's smart @c add() function. */
4770 void (*del)(Evas_Object *obj); /**< Function to be called at object deletion time. This will take place @b after the object's smart @c del() function. */
4774 * @struct _Evas_Smart_Cb_Description
4776 * Describes a callback issued by a smart object
4777 * (evas_object_smart_callback_call()), as defined in its smart object
4778 * class. This is particularly useful to explain to end users and
4779 * their code (i.e., introspection) what the parameter @c event_info
4782 * @ingroup Evas_Smart_Group
4784 struct _Evas_Smart_Cb_Description
4786 const char *name; /**< callback name ("changed", for example) */
4789 * @brief Hint on the type of @c event_info parameter's contents on
4790 * a #Evas_Smart_Cb callback.
4792 * The type string uses the pattern similar to
4793 * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures,
4794 * but extended to optionally include variable names within
4795 * brackets preceding types. Example:
4797 * @li Structure with two integers:
4800 * @li Structure called 'x' with two integers named 'a' and 'b':
4803 * @li Array of integers:
4806 * @li Array called 'x' of struct with two integers:
4809 * @note This type string is used as a hint and is @b not validated
4810 * or enforced in any way. Implementors should make the best
4811 * use of it to help bindings, documentation and other users
4812 * of introspection features.
4818 * @def EVAS_SMART_CLASS_INIT_NULL
4819 * Initializer to zero a whole Evas_Smart_Class structure.
4821 * @see EVAS_SMART_CLASS_INIT_VERSION
4822 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4823 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4824 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4825 * @ingroup Evas_Smart_Group
4827 #define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
4830 * @def EVAS_SMART_CLASS_INIT_VERSION
4831 * Initializer to zero a whole Evas_Smart_Class structure and set version.
4833 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4834 * latest EVAS_SMART_CLASS_VERSION.
4836 * @see EVAS_SMART_CLASS_INIT_NULL
4837 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4838 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4839 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4840 * @ingroup Evas_Smart_Group
4842 #define EVAS_SMART_CLASS_INIT_VERSION {NULL, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
4845 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
4846 * Initializer to zero a whole Evas_Smart_Class structure and set name
4849 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4850 * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
4852 * It will keep a reference to name field as a const char *, that is,
4853 * name must be available while the structure is used (hint: static or global!)
4854 * and will not be modified.
4856 * @see EVAS_SMART_CLASS_INIT_NULL
4857 * @see EVAS_SMART_CLASS_INIT_VERSION
4858 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4859 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4860 * @ingroup Evas_Smart_Group
4862 #define EVAS_SMART_CLASS_INIT_NAME_VERSION(name) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
4865 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4866 * Initializer to zero a whole Evas_Smart_Class structure and set name,
4867 * version and parent class.
4869 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4870 * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
4873 * It will keep a reference to name field as a const char *, that is,
4874 * name must be available while the structure is used (hint: static or global!)
4875 * and will not be modified. Similarly, parent reference will be kept.
4877 * @see EVAS_SMART_CLASS_INIT_NULL
4878 * @see EVAS_SMART_CLASS_INIT_VERSION
4879 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4880 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4881 * @ingroup Evas_Smart_Group
4883 #define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT(name, parent) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, NULL, NULL}
4886 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4887 * Initializer to zero a whole Evas_Smart_Class structure and set name,
4888 * version, parent class and callbacks definition.
4890 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4891 * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
4892 * class and callbacks at this level.
4894 * It will keep a reference to name field as a const char *, that is,
4895 * name must be available while the structure is used (hint: static or global!)
4896 * and will not be modified. Similarly, parent and callbacks reference
4899 * @see EVAS_SMART_CLASS_INIT_NULL
4900 * @see EVAS_SMART_CLASS_INIT_VERSION
4901 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4902 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4903 * @ingroup Evas_Smart_Group
4905 #define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS(name, parent, callbacks) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, callbacks, NULL}
4908 * @def EVAS_SMART_SUBCLASS_NEW
4910 * Convenience macro to subclass a given Evas smart class.
4912 * @param smart_name The name used for the smart class. e.g:
4913 * @c Evas_Object_Box.
4914 * @param prefix Prefix used for all variables and functions defined
4915 * and referenced by this macro.
4916 * @param api_type Type of the structure used as API for the smart
4917 * class. Either #Evas_Smart_Class or something derived from it.
4918 * @param parent_type Type of the parent class API.
4919 * @param parent_func Function that gets the parent class. e.g:
4920 * evas_object_box_smart_class_get().
4921 * @param cb_desc Array of callback descriptions for this smart class.
4923 * This macro saves some typing when writing a smart class derived
4924 * from another one. In order to work, the user @b must provide some
4925 * functions adhering to the following guidelines:
4926 * - @<prefix@>_smart_set_user(): the @b internal @c _smart_set
4927 * function (defined by this macro) will call this one, provided by
4928 * the user, after inheriting everything from the parent, which
4929 * should <b>take care of setting the right member functions for
4930 * the class</b>, both overrides and extensions, if any.
4931 * - If this new class should be subclassable as well, a @b public
4932 * @c _smart_set() function is desirable to fill in the class used as
4933 * parent by the children. It's up to the user to provide this
4934 * interface, which will most likely call @<prefix@>_smart_set() to
4937 * After the macro's usage, the following will be defined for use:
4938 * - @<prefix@>_parent_sc: A pointer to the @b parent smart
4939 * class. When calling parent functions from overloaded ones, use
4940 * this global variable.
4941 * - @<prefix@>_smart_class_new(): this function returns the
4942 * #Evas_Smart needed to create smart objects with this class,
4943 * which should be passed to evas_object_smart_add().
4945 * @warning @p smart_name has to be a pointer to a globally available
4946 * string! The smart class created here will just have a pointer set
4947 * to that, and all object instances will depend on it for smart class
4950 * @ingroup Evas_Smart_Group
4952 #define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
4953 static const parent_type * prefix##_parent_sc = NULL; \
4954 static void prefix##_smart_set_user(api_type * api); \
4955 static void prefix##_smart_set(api_type * api) \
4957 Evas_Smart_Class *sc; \
4958 if (!(sc = (Evas_Smart_Class *)api)) \
4960 if (!prefix##_parent_sc) \
4961 prefix##_parent_sc = parent_func(); \
4962 evas_smart_class_inherit(sc, prefix##_parent_sc); \
4963 prefix##_smart_set_user(api); \
4965 static Evas_Smart *prefix##_smart_class_new(void) \
4967 static Evas_Smart *smart = NULL; \
4968 static api_type api; \
4971 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
4972 memset(&api, 0, sizeof(api_type)); \
4973 sc->version = EVAS_SMART_CLASS_VERSION; \
4974 sc->name = smart_name; \
4975 sc->callbacks = cb_desc; \
4976 prefix##_smart_set(&api); \
4977 smart = evas_smart_class_new(sc); \
4983 * @def EVAS_SMART_SUBCLASS_IFACE_NEW
4987 * Convenience macro to subclass a given Evas smart class. This is the
4988 * same as #EVAS_SMART_SUBCLASS_NEW, but now <b>declaring smart
4989 * interfaces</b> besides the smart callbacks.
4991 * @param smart_name The name used for the smart class. e.g:
4992 * @c Evas_Object_Box.
4993 * @param prefix Prefix used for all variables and functions defined
4994 * and referenced by this macro.
4995 * @param api_type Type of the structure used as API for the smart
4996 * class. Either #Evas_Smart_Class or something
4998 * @param parent_type Type of the parent class API.
4999 * @param parent_func Function that gets the parent class. e.g:
5000 * evas_object_box_smart_class_get().
5001 * @param cb_desc Array of smart callback descriptions for this smart
5003 * @param ifaces Array of Evas smart interafaces for this smart
5006 * This macro saves some typing when writing a smart class derived
5007 * from another one. In order to work, the user @b must provide some
5008 * functions adhering to the following guidelines:
5009 * - @<prefix@>_smart_set_user(): the @b internal @c _smart_set
5010 * function (defined by this macro) will call this one, provided by
5011 * the user, after inheriting everything from the parent, which
5012 * should <b>take care of setting the right member functions for
5013 * the class</b>, both overrides and extensions, if any.
5014 * - If this new class should be subclassable as well, a @b public
5015 * @c _smart_set() function is desirable to fill in the class used as
5016 * parent by the children. It's up to the user to provide this
5017 * interface, which will most likely call @<prefix@>_smart_set() to
5020 * After the macro's usage, the following will be defined for use:
5021 * - @<prefix@>_parent_sc: A pointer to the @b parent smart
5022 * class. When calling parent functions from overloaded ones, use
5023 * this global variable.
5024 * - @<prefix@>_smart_class_new(): this function returns the
5025 * #Evas_Smart needed to create smart objects with this class,
5026 * which should be passed to evas_object_smart_add().
5028 * @warning @p smart_name has to be a pointer to a globally available
5029 * string! The smart class created here will just have a pointer set
5030 * to that, and all object instances will depend on it for smart class
5033 * @ingroup Evas_Smart_Group
5035 #define EVAS_SMART_SUBCLASS_IFACE_NEW(smart_name, \
5042 static const parent_type * prefix##_parent_sc = NULL; \
5043 static void prefix##_smart_set_user(api_type * api); \
5044 static void prefix##_smart_set(api_type * api) \
5046 Evas_Smart_Class *sc; \
5047 if (!(sc = (Evas_Smart_Class *)api)) \
5049 if (!prefix##_parent_sc) \
5050 prefix##_parent_sc = parent_func(); \
5051 evas_smart_class_inherit(sc, prefix##_parent_sc); \
5052 prefix##_smart_set_user(api); \
5054 static Evas_Smart *prefix##_smart_class_new(void) \
5056 static Evas_Smart *smart = NULL; \
5057 static api_type api; \
5060 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
5061 memset(&api, 0, sizeof(api_type)); \
5062 sc->version = EVAS_SMART_CLASS_VERSION; \
5063 sc->name = smart_name; \
5064 sc->callbacks = cb_desc; \
5065 sc->interfaces = ifaces; \
5066 prefix##_smart_set(&api); \
5067 smart = evas_smart_class_new(sc); \
5073 * @def EVAS_SMART_DATA_ALLOC
5075 * Convenience macro to allocate smart data only if needed.
5077 * When writing a subclassable smart object, the @c .add() function
5078 * will need to check if the smart private data was already allocated
5079 * by some child object or not. This macro makes it easier to do it.
5081 * @note This is an idiom used when one calls the parent's @c .add()
5082 * after the specialized code. Naturally, the parent's base smart data
5083 * has to be contemplated as the specialized one's first member, for
5086 * @param o Evas object passed to the @c .add() function
5087 * @param priv_type The type of the data to allocate
5089 * @ingroup Evas_Smart_Group
5091 #define EVAS_SMART_DATA_ALLOC(o, priv_type) \
5093 priv = evas_object_smart_data_get(o); \
5095 priv = (priv_type *)calloc(1, sizeof(priv_type)); \
5096 if (!priv) return; \
5097 evas_object_smart_data_set(o, priv); \
5101 * Free an #Evas_Smart struct
5103 * @param s the #Evas_Smart struct to free
5105 * @warning If this smart handle was created using
5106 * evas_smart_class_new(), the associated #Evas_Smart_Class will not
5109 * @note If you're using the #EVAS_SMART_SUBCLASS_NEW schema to create your
5110 * smart object, note that an #Evas_Smart handle will be shared amongst all
5111 * instances of the given smart class, through a static variable.
5112 * Evas will internally count references on #Evas_Smart handles and free them
5113 * when they are not referenced anymore. Thus, this function is of no use
5114 * for Evas users, most probably.
5116 EAPI void evas_smart_free(Evas_Smart *s) EINA_ARG_NONNULL(1);
5119 * Creates a new #Evas_Smart from a given #Evas_Smart_Class struct
5121 * @param sc the smart class definition
5122 * @return a new #Evas_Smart pointer
5124 * #Evas_Smart handles are necessary to create new @b instances of
5125 * smart objects belonging to the class described by @p sc. That
5126 * handle will contain, besides the smart class interface definition,
5127 * all its smart callbacks infrastructure set, too.
5129 * @note If you are willing to subclass a given smart class to
5130 * construct yours, consider using the #EVAS_SMART_SUBCLASS_NEW macro,
5131 * which will make use of this function automatically for you.
5133 EAPI Evas_Smart *evas_smart_class_new(const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5136 * Get the #Evas_Smart_Class handle of an #Evas_Smart struct
5138 * @param s a valid #Evas_Smart pointer
5139 * @return the #Evas_Smart_Class in it
5141 EAPI const Evas_Smart_Class *evas_smart_class_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5144 * @brief Get the data pointer set on an #Evas_Smart struct
5146 * @param s a valid #Evas_Smart handle
5148 * This data pointer is set as the data field in the #Evas_Smart_Class
5149 * passed in to evas_smart_class_new().
5151 EAPI void *evas_smart_data_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5154 * Get the smart callbacks known by this #Evas_Smart handle's smart
5157 * @param s A valid #Evas_Smart handle.
5158 * @param[out] count Returns the number of elements in the returned
5160 * @return The array with callback descriptions known by this smart
5161 * class, with its size returned in @a count parameter. It
5162 * should not be modified in any way. If no callbacks are
5163 * known, @c NULL is returned. The array is sorted by event
5164 * names and elements refer to the original values given to
5165 * evas_smart_class_new()'s Evas_Smart_Class::callbacks
5166 * (pointer to them).
5168 * This is likely different from
5169 * evas_object_smart_callbacks_descriptions_get() as it will contain
5170 * the callbacks of @b all this class hierarchy sorted, while the
5171 * direct smart class member refers only to that specific class and
5172 * should not include parent's.
5174 * If no callbacks are known, this function returns @c NULL.
5176 * The array elements and thus their contents will be @b references to
5177 * original values given to evas_smart_class_new() as
5178 * Evas_Smart_Class::callbacks.
5180 * The array is sorted by Evas_Smart_Cb_Description::name. The last
5181 * array element is a @c NULL pointer and is not accounted for in @a
5182 * count. Loop iterations can check any of these size indicators.
5184 * @note objects may provide per-instance callbacks, use
5185 * evas_object_smart_callbacks_descriptions_get() to get those
5187 * @see evas_object_smart_callbacks_descriptions_get()
5189 EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
5192 * Find a callback description for the callback named @a name.
5194 * @param s The #Evas_Smart where to search for class registered smart
5196 * @param name Name of the desired callback, which must @b not be @c
5197 * NULL. The search has a special case for @a name being the
5198 * same pointer as registered with #Evas_Smart_Cb_Description.
5199 * One can use it to avoid excessive use of strcmp().
5200 * @return A reference to the description if found, or @c NULL, otherwise
5202 * @see evas_smart_callbacks_descriptions_get()
5204 EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2);
5207 * Sets one class to inherit from the other.
5209 * Copy all function pointers, set @c parent to @a parent_sc and copy
5210 * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
5211 * using @a parent_sc_size as reference.
5213 * This is recommended instead of a single memcpy() since it will take
5214 * care to not modify @a sc name, version, callbacks and possible
5217 * @param sc child class.
5218 * @param parent_sc parent class, will provide attributes.
5219 * @param parent_sc_size size of parent_sc structure, child should be at least
5220 * this size. Everything after @c Evas_Smart_Class size is copied
5221 * using regular memcpy().
5223 EAPI Eina_Bool evas_smart_class_inherit_full(Evas_Smart_Class *sc, const Evas_Smart_Class *parent_sc, unsigned int parent_sc_size) EINA_ARG_NONNULL(1, 2);
5226 * Get the number of users of the smart instance
5228 * @param s The Evas_Smart to get the usage count of
5229 * @return The number of uses of the smart instance
5231 * This function tells you how many more uses of the smart instance are in
5232 * existence. This should be used before freeing/clearing any of the
5233 * Evas_Smart_Class that was used to create the smart instance. The smart
5234 * instance will refer to data in the Evas_Smart_Class used to create it and
5235 * thus you cannot remove the original data until all users of it are gone.
5236 * When the usage count goes to 0, you can evas_smart_free() the smart
5237 * instance @p s and remove from memory any of the Evas_Smart_Class that
5238 * was used to create the smart instance, if you desire. Removing it from
5239 * memory without doing this will cause problems (crashes, undefined
5240 * behavior etc. etc.), so either never remove the original
5241 * Evas_Smart_Class data from memory (have it be a constant structure and
5242 * data), or use this API call and be very careful.
5244 EAPI int evas_smart_usage_get(const Evas_Smart *s);
5247 * @def evas_smart_class_inherit
5248 * Easy to use version of evas_smart_class_inherit_full().
5250 * This version will use sizeof(parent_sc), copying everything.
5252 * @param sc child class, will have methods copied from @a parent_sc
5253 * @param parent_sc parent class, will provide contents to be copied.
5254 * @return 1 on success, 0 on failure.
5255 * @ingroup Evas_Smart_Group
5257 #define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, (Evas_Smart_Class *)parent_sc, sizeof(*parent_sc))
5263 * @defgroup Evas_Smart_Object_Group Smart Object Functions
5266 * Functions dealing with Evas smart objects (instances).
5268 * Smart objects are groupings of primitive Evas objects that behave
5269 * as a cohesive group. For instance, a file manager icon may be a
5270 * smart object composed of an image object, a text label and two
5271 * rectangles that appear behind the image and text when the icon is
5272 * selected. As a smart object, the normal Evas object API could be
5273 * used on the icon object.
5275 * Besides that, generally smart objects implement a <b>specific
5276 * API</b>, so that users interact with its own custom features. The
5277 * API takes form of explicit exported functions one may call and
5278 * <b>smart callbacks</b>.
5280 * @section Evas_Smart_Object_Group_Callbacks Smart events and callbacks
5282 * Smart objects can elect events (smart events, from now on) occurring
5283 * inside of them to be reported back to their users via callback
5284 * functions (smart callbacks). This way, you can extend Evas' own
5285 * object events. They are defined by an <b>event string</b>, which
5286 * identifies them uniquely. There's also a function prototype
5287 * definition for the callback functions: #Evas_Smart_Cb.
5289 * When defining an #Evas_Smart_Class, smart object implementors are
5290 * strongly encouraged to properly set the Evas_Smart_Class::callbacks
5291 * callbacks description array, so that the users of the smart object
5292 * can have introspection on its events API <b>at run time</b>.
5294 * See some @ref Example_Evas_Smart_Objects examples of this group
5297 * @see @ref Evas_Smart_Group for class definitions.
5301 * @addtogroup Evas_Smart_Object_Group
5307 * Registers an object type and its associated class. LEGACY MECHANISM SUPPORT.
5309 * This function is invoked in the class constructor of smart classes. It will
5310 * add the type and the class into a hash table that will then be used to check
5311 * the type of an object.
5312 * This function has been implemented to support legacy mechanism that checks
5313 * objects types by name.
5314 * USE IT ONLY FOR LEGACY SUPPORT.
5315 * Otherwise, it is HIGHLY recommended to use eo_isa.
5317 * @param type The type (name string) to add.
5318 * @param klass The class to associate to the type.
5322 * @ingroup Evas_Smart_Object_Group
5324 EAPI void evas_smart_legacy_type_register(const char *type, const Eo_Class *klass) EINA_ARG_NONNULL(1, 2);
5332 * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
5334 * Clipped smart object is a base to construct other smart objects
5335 * based on the concept of having an internal clipper that is applied
5336 * to all children objects. This clipper will control the visibility,
5337 * clipping and color of sibling objects (remember that the clipping
5338 * is recursive, and clipper color modulates the color of its
5339 * clippees). By default, this base will also move children relatively
5340 * to the parent, and delete them when parent is deleted. In other
5341 * words, it is the base for simple object grouping.
5343 * See some @ref Example_Evas_Smart_Objects examples of this group
5346 * @see evas_object_smart_clipped_smart_set()
5348 * @ingroup Evas_Smart_Object_Group
5354 * Every subclass should provide this at the beginning of their own
5355 * data set with evas_object_smart_data_set().
5357 typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
5358 struct _Evas_Object_Smart_Clipped_Data
5360 Evas_Object *clipper;
5365 * Set a given smart class' callbacks so it implements the <b>clipped smart
5366 * object </b>'s interface.
5368 * @param sc The smart class handle to operate on
5370 * This call will assign all the required methods of the @p sc
5371 * #Evas_Smart_Class instance to the implementations set for clipped
5372 * smart objects. If one wants to subclass it, call this function
5373 * and then override desired values. If one wants to call any original
5374 * method, save it somewhere. Example:
5377 * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
5379 * static void my_class_smart_add(Evas_Object *o)
5382 * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
5386 * Evas_Smart_Class *my_class_new(void)
5388 * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
5389 * if (!parent_sc.name)
5391 * evas_object_smart_clipped_smart_set(&sc);
5393 * sc.add = my_class_smart_add;
5399 * Default behavior for each of #Evas_Smart_Class functions on a
5400 * clipped smart object are:
5401 * - @c add: creates a hidden clipper with infinite size, to clip
5402 * any incoming members;
5403 * - @c del: delete all children objects;
5404 * - @c move: move all objects relative relatively;
5405 * - @c resize: <b>not defined</b>;
5406 * - @c show: if there are children objects, show clipper;
5407 * - @c hide: hides clipper;
5408 * - @c color_set: set the color of clipper;
5409 * - @c clip_set: set clipper of clipper;
5410 * - @c clip_unset: unset the clipper of clipper;
5412 * @note There are other means of assigning parent smart classes to
5413 * child ones, like the #EVAS_SMART_SUBCLASS_NEW macro or the
5414 * evas_smart_class_inherit_full() function.
5416 EAPI void evas_object_smart_clipped_smart_set(Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
5419 * Get a pointer to the <b>clipped smart object's</b> class, to use
5420 * for proper inheritance
5422 * @see #Evas_Smart_Object_Clipped for more information on this smart
5425 EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get(void) EINA_CONST;
5431 * @defgroup Evas_Object_Box Box Smart Object
5433 * A box is a convenience smart object that packs children inside it
5434 * in @b sequence, using a layouting function specified by the
5435 * user. There are a couple of pre-made layouting functions <b>built-in
5436 * in Evas</b>, all of them using children size hints to define their
5437 * size and alignment inside their cell space.
5439 * Examples on this smart object's usage:
5440 * - @ref Example_Evas_Box
5441 * - @ref Example_Evas_Size_Hints
5443 * @see @ref Evas_Object_Group_Size_Hints
5445 * @ingroup Evas_Smart_Object_Group
5451 * @typedef Evas_Object_Box_Api
5453 * Smart class extension, providing extra box object requirements.
5455 * @ingroup Evas_Object_Box
5457 typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
5460 * @typedef Evas_Object_Box_Data
5462 * Smart object instance data, providing box object requirements.
5464 * @ingroup Evas_Object_Box
5466 typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
5469 * @typedef Evas_Object_Box_Option
5471 * The base structure for a box option. Box options are a way of
5472 * extending box items properties, which will be taken into account
5473 * for layouting decisions. The box layouting functions provided by
5474 * Evas will only rely on objects' canonical size hints to layout
5475 * them, so the basic box option has @b no (custom) property set.
5477 * Users creating their own layouts, but not depending on extra child
5478 * items' properties, would be fine just using
5479 * evas_object_box_layout_set(). But if one desires a layout depending
5480 * on extra child properties, he/she has to @b subclass the box smart
5481 * object. Thus, by using evas_object_box_smart_class_get() and
5482 * evas_object_box_smart_set(), the @c option_new() and @c
5483 * option_free() smart class functions should be properly
5484 * redefined/extended.
5486 * Object properties are bound to an integer identifier and must have
5487 * a name string. Their values are open to any data. See the API on
5488 * option properties for more details.
5490 * @ingroup Evas_Object_Box
5492 typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
5495 * @typedef Evas_Object_Box_Layout
5497 * Function signature for an Evas box object layouting routine. By
5498 * @a o it will be passed the box object in question, by @a priv it will
5499 * be passed the box's internal data and, by @a user_data, it will be
5500 * passed any custom data one could have set to a given box layouting
5501 * function, with evas_object_box_layout_set().
5503 * @ingroup Evas_Object_Box
5505 typedef void (*Evas_Object_Box_Layout)(Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
5508 * @def EVAS_OBJECT_BOX_API_VERSION
5510 * Current version for Evas box object smart class, a value which goes
5511 * to _Evas_Object_Box_Api::version.
5513 * @ingroup Evas_Object_Box
5515 #define EVAS_OBJECT_BOX_API_VERSION 1
5518 * @struct _Evas_Object_Box_Api
5520 * This structure should be used by any smart class inheriting from
5521 * the box's one, to provide custom box behavior which could not be
5522 * achieved only by providing a layout function, with
5523 * evas_object_box_layout_set().
5525 * @extends Evas_Smart_Class
5526 * @ingroup Evas_Object_Box
5528 struct _Evas_Object_Box_Api
5530 Evas_Smart_Class base; /**< Base smart class struct, need for all smart objects */
5531 int version; /**< Version of this smart class definition */
5532 Evas_Object_Box_Option *(*append)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to append child elements in boxes */
5533 Evas_Object_Box_Option *(*prepend)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to prepend child elements in boxes */
5534 Evas_Object_Box_Option *(*insert_before)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child, const Evas_Object * reference); /**< Smart function to insert a child element before another in boxes */
5535 Evas_Object_Box_Option *(*insert_after)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child, const Evas_Object * reference); /**< Smart function to insert a child element after another in boxes */
5536 Evas_Object_Box_Option *(*insert_at)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child, unsigned int pos); /**< Smart function to insert a child element at a given position on boxes */
5537 Evas_Object *(*remove)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to remove a child element from boxes */
5538 Evas_Object *(*remove_at)(Evas_Object * o, Evas_Object_Box_Data * priv, unsigned int pos); /**< Smart function to remove a child element from boxes, by its position */
5539 Eina_Bool (*property_set)(Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args); /**< Smart function to set a custom property on a box child */
5540 Eina_Bool (*property_get)(const Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args); /**< Smart function to retrieve a custom property from a box child */
5541 const char *(*property_name_get)(const Evas_Object * o, int property); /**< Smart function to get the name of a custom property of box children */
5542 int (*property_id_get)(const Evas_Object *o, const char *name); /**< Smart function to get the numerical ID of a custom property of box children */
5543 Evas_Object_Box_Option *(*option_new)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to create a new box option struct */
5544 void (*option_free)(Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt); /**< Smart function to delete a box option struct */
5548 * @def EVAS_OBJECT_BOX_API_INIT
5550 * Initializer for a whole #Evas_Object_Box_Api structure, with
5551 * @c NULL values on its specific fields.
5553 * @param smart_class_init initializer to use for the base field
5554 * (#Evas_Smart_Class).
5556 * @see EVAS_SMART_CLASS_INIT_NULL
5557 * @see EVAS_SMART_CLASS_INIT_VERSION
5558 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
5559 * @see EVAS_OBJECT_BOX_API_INIT_NULL
5560 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
5561 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
5562 * @ingroup Evas_Object_Box
5564 #define EVAS_OBJECT_BOX_API_INIT(smart_class_init) {smart_class_init, EVAS_OBJECT_BOX_API_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
5567 * @def EVAS_OBJECT_BOX_API_INIT_NULL
5569 * Initializer to zero out a whole #Evas_Object_Box_Api structure.
5571 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
5572 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
5573 * @see EVAS_OBJECT_BOX_API_INIT
5574 * @ingroup Evas_Object_Box
5576 #define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
5579 * @def EVAS_OBJECT_BOX_API_INIT_VERSION
5581 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
5582 * set a specific version on it.
5584 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will set
5585 * the version field of #Evas_Smart_Class (base field) to the latest
5586 * #EVAS_SMART_CLASS_VERSION.
5588 * @see EVAS_OBJECT_BOX_API_INIT_NULL
5589 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
5590 * @see EVAS_OBJECT_BOX_API_INIT
5591 * @ingroup Evas_Object_Box
5593 #define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
5596 * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
5598 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
5599 * set its name and version.
5601 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will also
5602 * set the version field of #Evas_Smart_Class (base field) to the
5603 * latest #EVAS_SMART_CLASS_VERSION and name it to the specific value.
5605 * It will keep a reference to the name field as a <c>const char *</c>,
5606 * i.e., the name must be available while the structure is
5607 * used (hint: static or global variable!) and must not be modified.
5609 * @see EVAS_OBJECT_BOX_API_INIT_NULL
5610 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
5611 * @see EVAS_OBJECT_BOX_API_INIT
5612 * @ingroup Evas_Object_Box
5614 #define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
5617 * @struct _Evas_Object_Box_Data
5619 * This structure augments clipped smart object's instance data,
5620 * providing extra members required by generic box implementation. If
5621 * a subclass inherits from #Evas_Object_Box_Api, then it may augment
5622 * #Evas_Object_Box_Data to fit its own needs.
5624 * @extends Evas_Object_Smart_Clipped_Data
5625 * @ingroup Evas_Object_Box
5627 struct _Evas_Object_Box_Data
5629 Evas_Object_Smart_Clipped_Data base;
5630 const Evas_Object_Box_Api *api;
5639 Eina_List *children;
5642 Evas_Object_Box_Layout cb;
5644 void (*free_data)(void *data);
5646 Eina_Bool layouting : 1;
5647 Eina_Bool children_changed : 1;
5650 struct _Evas_Object_Box_Option
5652 Evas_Object *obj; /**< Pointer to the box child object, itself */
5653 Eina_Bool max_reached : 1;
5654 Eina_Bool min_reached : 1;
5655 Evas_Coord alloc_size;
5656 }; /**< #Evas_Object_Box_Option struct fields */
5659 * @brief Set the default box @a api struct (Evas_Object_Box_Api)
5660 * with the default values. May be used to extend that API.
5662 * @if MOBILE @since_tizen 2.3
5663 * @elseif WEARABLE @since_tizen 2.3.1
5666 * @param[in] api The box API struct to set back, most probably with
5667 * overridden fields (on class extensions scenarios)
5669 EAPI void evas_object_box_smart_set(Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
5672 * @brief Get the Evas box smart class, for inheritance purposes.
5674 * @if MOBILE @since_tizen 2.3
5675 * @elseif WEARABLE @since_tizen 2.3.1
5678 * @return the (canonical) Evas box smart class.
5680 * @remark The returned value is @b not to be modified, just use it as your
5683 EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get(void) EINA_CONST;
5690 * @defgroup Evas_Object_Table Table Smart Object.
5692 * Convenience smart object that packs children using a tabular
5693 * layout using children size hints to define their size and
5694 * alignment inside their cell space.
5696 * @ref tutorial_table shows how to use this Evas_Object.
5698 * @see @ref Evas_Object_Group_Size_Hints
5700 * @ingroup Evas_Smart_Object_Group
5705 * @defgroup Evas_Object_Grid Grid Smart Object.
5707 * Convenience smart object that packs children under a regular grid
5708 * layout, using their virtual grid location and size to determine
5709 * children's positions inside the grid object's area.
5711 * @ingroup Evas_Smart_Object_Group
5717 * @defgroup Evas_Cserve Shared Image Cache Server
5720 * Evas has an (optional) module which provides client-server
5721 * infrastructure to <b>share bitmaps across multiple processes</b>,
5722 * saving data and processing power.
5724 * Be warned that it @b doesn't work when <b>threaded image
5725 * preloading</b> is enabled for Evas, though.
5729 typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
5730 typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
5731 typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
5732 typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
5735 * Statistics about the server that shares cached bitmaps.
5736 * @ingroup Evas_Cserve
5738 struct _Evas_Cserve_Stats
5740 int saved_memory; /**< current amount of saved memory, in bytes */
5741 int wasted_memory; /**< current amount of wasted memory, in bytes */
5742 int saved_memory_peak; /**< peak amount of saved memory, in bytes */
5743 int wasted_memory_peak; /**< peak amount of wasted memory, in bytes */
5744 double saved_time_image_header_load; /**< time, in seconds, saved in header loads by sharing cached loads instead */
5745 double saved_time_image_data_load; /**< time, in seconds, saved in data loads by sharing cached loads instead */
5749 * A handle of a cache of images shared by a server.
5750 * @ingroup Evas_Cserve
5752 struct _Evas_Cserve_Image_Cache
5763 * A handle to an image shared by a server.
5764 * @ingroup Evas_Cserve
5766 struct _Evas_Cserve_Image
5768 const char *file, *key;
5770 time_t file_mod_time;
5771 time_t file_checked_time;
5775 int memory_footprint;
5776 double head_load_time;
5777 double data_load_time;
5778 Eina_Bool alpha : 1;
5779 Eina_Bool data_loaded : 1;
5780 Eina_Bool active : 1;
5782 Eina_Bool useless : 1;
5786 * Configuration that controls the server that shares cached bitmaps.
5787 * @ingroup Evas_Cserve
5789 struct _Evas_Cserve_Config
5791 int cache_max_usage;
5792 int cache_item_timeout;
5793 int cache_item_timeout_check;
5797 * Retrieves if the system wants to share bitmaps using the server.
5798 * @return @c EINA_TRUE if it wants, @c EINA_FALSE otherwise.
5799 * @ingroup Evas_Cserve
5801 EAPI Eina_Bool evas_cserve_want_get(void) EINA_WARN_UNUSED_RESULT;
5804 * Retrieves if the system is connected to the server used to share
5807 * @return @c EINA_TRUE if it's connected, @c EINA_FALSE otherwise.
5808 * @ingroup Evas_Cserve
5810 EAPI Eina_Bool evas_cserve_connected_get(void) EINA_WARN_UNUSED_RESULT;
5813 * Retrieves statistics from a running bitmap sharing server.
5814 * @param stats pointer to structure to fill with statistics about the
5815 * bitmap cache server.
5817 * @return @c EINA_TRUE if @p stats were filled with data,
5818 * @c EINA_FALSE otherwise (when @p stats is untouched)
5819 * @ingroup Evas_Cserve
5821 EAPI Eina_Bool evas_cserve_stats_get(Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
5824 * Completely discard/clean a given images cache, thus re-setting it.
5826 * @param cache A handle to the given images cache.
5828 EAPI void evas_cserve_image_cache_contents_clean(Evas_Cserve_Image_Cache *cache);
5831 * Retrieves the current configuration of the Evas image caching
5834 * @param config where to store current image caching server's
5837 * @return @c EINA_TRUE if @p config was filled with data,
5838 * @c EINA_FALSE otherwise (when @p config is untouched)
5840 * The fields of @p config will be altered to reflect the current
5841 * configuration's values.
5843 * @see evas_cserve_config_set()
5845 * @ingroup Evas_Cserve
5847 EAPI Eina_Bool evas_cserve_config_get(Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
5850 * Changes the configurations of the Evas image caching server.
5852 * @param config A bitmap cache configuration handle with fields set
5853 * to desired configuration values.
5854 * @return @c EINA_TRUE if @p config was successfully applied,
5855 * @c EINA_FALSE otherwise.
5857 * @see evas_cserve_config_get()
5859 * @ingroup Evas_Cserve
5861 EAPI Eina_Bool evas_cserve_config_set(const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
5864 * Force the system to disconnect from the bitmap caching server.
5866 * @ingroup Evas_Cserve
5868 EAPI void evas_cserve_disconnect(void);
5875 * @defgroup Evas_Utils General Utilities
5878 * Some functions that are handy but are not specific of canvas or
5885 * @brief Converts the given Evas image load error code into a string
5886 * describing it in english.
5888 * @if MOBILE @since_tizen 2.3
5889 * @elseif WEARABLE @since_tizen 2.3.1
5892 * @param[in] error the error code, a value in ::Evas_Load_Error.
5893 * @return Always returns a valid string. If the given @p error is not
5894 * supported, <code>Unknown error</code> is returned.
5896 * @remark Mostly evas_object_image_file_set() would be the function setting
5897 * that error value afterwards, but also evas_object_image_load(),
5898 * evas_object_image_save(), evas_object_image_data_get(),
5899 * evas_object_image_data_convert(), evas_object_image_pixels_import()
5900 * and evas_object_image_is_inside(). This function is meant to be
5901 * used in conjunction with evas_object_image_load_error_get(), as in:
5903 * @remark Example code:
5904 * @dontinclude evas-images.c
5906 * @until ecore_main_loop_begin(
5908 * @remark Here, being @c valid_path the path to a valid image and @c
5909 * bogus_path a path to a file which does not exist, the two outputs
5910 * of evas_load_error_str() would be (if no other errors occur):
5911 * <code>No error on load</code> and <code>File (or file path) does
5912 * not exist</code>, respectively. See the full @ref
5913 * Example_Evas_Images example.
5915 * @ingroup Evas_Utils
5917 EAPI const char *evas_load_error_str(Evas_Load_Error error);
5919 /* Evas utility routines for color space conversions */
5920 /* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
5921 /* rgb color space has r,g,b in the range 0 to 255 */
5924 * @brief Convert a given color from HSV to RGB format.
5926 * @if MOBILE @since_tizen 2.3
5927 * @elseif WEARABLE @since_tizen 2.3.1
5930 * @param[in] h The Hue component of the color.
5931 * @param[in] s The Saturation component of the color.
5932 * @param[in] v The Value component of the color.
5933 * @param[out] r The Red component of the color.
5934 * @param[out] g The Green component of the color.
5935 * @param[out] b The Blue component of the color.
5937 * @remark This function converts a given color in HSV color format to RGB
5940 * @ingroup Evas_Utils
5942 EAPI void evas_color_hsv_to_rgb(float h, float s, float v, int *r, int *g, int *b);
5945 * @brief Convert a given color from RGB to HSV format.
5947 * @if MOBILE @since_tizen 2.3
5948 * @elseif WEARABLE @since_tizen 2.3.1
5951 * @param[in] r The Red component of the color.
5952 * @param[in] g The Green component of the color.
5953 * @param[in] b The Blue component of the color.
5954 * @param[out] h The Hue component of the color.
5955 * @param[out] s The Saturation component of the color.
5956 * @param[out] v The Value component of the color.
5958 * @remark This function converts a given color in RGB color format to HSV
5961 * @ingroup Evas_Utils
5963 EAPI void evas_color_rgb_to_hsv(int r, int g, int b, float *h, float *s, float *v);
5965 /* argb color space has a,r,g,b in the range 0 to 255 */
5968 * @brief Pre-multiplies a rgb triplet by an alpha factor.
5970 * @if MOBILE @since_tizen 2.3
5971 * @elseif WEARABLE @since_tizen 2.3.1
5974 * @param[in] a The alpha factor.
5975 * @param[out] r The Red component of the color.
5976 * @param[out] g The Green component of the color.
5977 * @param[out] b The Blue component of the color.
5979 * @remark This function pre-multiplies a given rgb triplet by an alpha
5980 * factor. Alpha factor is used to define transparency.
5982 * @ingroup Evas_Utils
5984 EAPI void evas_color_argb_premul(int a, int *r, int *g, int *b);
5987 * @brief Undo pre-multiplication of a rgb triplet by an alpha factor.
5989 * @if MOBILE @since_tizen 2.3
5990 * @elseif WEARABLE @since_tizen 2.3.1
5993 * @param[in] a The alpha factor.
5994 * @param[out] r The Red component of the color.
5995 * @param[out] g The Green component of the color.
5996 * @param[out] b The Blue component of the color.
5998 * @remark This function undoes pre-multiplication a given rbg triplet by an
5999 * alpha factor. Alpha factor is used to define transparency.
6001 * @see evas_color_argb_premul().
6003 * @ingroup Evas_Utils
6005 EAPI void evas_color_argb_unpremul(int a, int *r, int *g, int *b);
6008 * @brief Pre-multiplies data by an alpha factor.
6010 * @if MOBILE @since_tizen 2.3
6011 * @elseif WEARABLE @since_tizen 2.3.1
6014 * @param[in] data The data value.
6015 * @param[in] len The length value.
6017 * @remark This function pre-multiplies a given data by an alpha
6018 * factor. Alpha factor is used to define transparency.
6020 * @ingroup Evas_Utils
6022 EAPI void evas_data_argb_premul(unsigned int *data, unsigned int len);
6025 * @brief Undo pre-multiplication data by an alpha factor.
6027 * @if MOBILE @since_tizen 2.3
6028 * @elseif WEARABLE @since_tizen 2.3.1
6031 * @param[in] data The data value.
6032 * @param[in] len The length value.
6034 * @remark This function undoes pre-multiplication of a given data by an alpha
6035 * factor. Alpha factor is used to define transparency.
6037 * @ingroup Evas_Utils
6039 EAPI void evas_data_argb_unpremul(unsigned int *data, unsigned int len);
6041 /* string and font handling */
6044 * @brief Gets the next character in the string
6046 * @if MOBILE @since_tizen 2.3
6047 * @elseif WEARABLE @since_tizen 2.3.1
6050 * @remark Given the UTF-8 string in @p str, and starting byte position in @p pos,
6051 * this function will place in @p decoded the decoded code point at @p pos
6052 * and return the byte index for the next character in the string.
6054 * @remark The only boundary check done is that @p pos must be >= 0. Other than that,
6055 * no checks are performed, so passing an index value that's not within the
6056 * length of the string will result in undefined behavior.
6058 * @param[in] str The UTF-8 string
6059 * @param[in] pos The byte index where to start
6060 * @param[out] decoded Address where to store the decoded code point. Optional.
6062 * @return The byte index of the next character
6064 * @ingroup Evas_Utils
6066 EAPI int evas_string_char_next_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
6069 * @brief Gets the previous character in the string
6071 * @if MOBILE @since_tizen 2.3
6072 * @elseif WEARABLE @since_tizen 2.3.1
6075 * @remark Given the UTF-8 string in @p str, and starting byte position in @p pos,
6076 * this function will place in @p decoded the decoded code point at @p pos
6077 * and return the byte index for the previous character in the string.
6079 * @remark The only boundary check done is that @p pos must be >= 1. Other than that,
6080 * no checks are performed, so passing an index value that's not within the
6081 * length of the string will result in undefined behavior.
6083 * @param[in] str The UTF-8 string
6084 * @param[in] pos The byte index where to start
6085 * @param[out] decoded Address where to store the decoded code point. Optional.
6087 * @return The byte index of the previous character
6089 * @ingroup Evas_Utils
6091 EAPI int evas_string_char_prev_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
6094 * @brief Get the length in characters of the string.
6095 * @param[in] str The string to get the length of.
6097 * @if MOBILE @since_tizen 2.3
6098 * @elseif WEARABLE @since_tizen 2.3.1
6101 * @return The length in characters (not bytes)
6102 * @ingroup Evas_Utils
6104 EAPI int evas_string_char_len_get(const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6111 * @defgroup Evas_Keys Key Input Functions
6113 * Functions which feed key events to the canvas.
6115 * As explained in @ref intro_not_evas, Evas is @b not aware of input
6116 * systems at all. Then, the user, if using it crudely (evas_new()),
6117 * will have to feed it with input events, so that it can react
6118 * somehow. If, however, the user creates a canvas by means of the
6119 * Ecore_Evas wrapper, it will automatically bind the chosen display
6120 * engine's input events to the canvas, for you.
6122 * This group presents the functions dealing with the feeding of key
6123 * events to the canvas. On most of them, one has to reference a given
6124 * key by a name (<code>keyname</code> argument). Those are
6125 * <b>platform dependent</b> symbolic names for the keys. Sometimes
6126 * you'll get the right <code>keyname</code> by simply using an ASCII
6127 * value of the key name, but it won't be like that always.
6129 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
6130 * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
6131 * to your display engine's documentation when using evas through an
6132 * Ecore helper wrapper when you need the <code>keyname</code>s.
6135 * @dontinclude evas-events.c
6136 * @skip mods = evas_key_modifier_get(evas);
6139 * All the other @c evas_key functions behave on the same manner. See
6140 * the full @ref Example_Evas_Events example.
6142 * @ingroup Evas_Canvas
6146 * @addtogroup Evas_Keys
6150 * @brief Checks the state of a given modifier key, at the time of the
6151 * call. If the modifier is set, such as shift being pressed, this
6152 * function returns @c Eina_True.
6154 * @if MOBILE @since_tizen 2.3
6155 * @elseif WEARABLE @since_tizen 2.3.1
6158 * @param[in] m The current modifiers set, as returned by
6159 * evas_key_modifier_get().
6160 * @param[in] keyname The name of the modifier key to check status for.
6162 * @return @c Eina_True if the modifier key named @p keyname is on, @c
6163 * Eina_False otherwise.
6165 * @see evas_key_modifier_add
6166 * @see evas_key_modifier_del
6167 * @see evas_key_modifier_get
6168 * @see evas_key_modifier_on
6169 * @see evas_key_modifier_off
6171 EAPI Eina_Bool evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
6174 * @brief Checks the state of a given lock key, at the time of the call. If
6175 * the lock is set, such as caps lock, this function returns @c
6178 * @if MOBILE @since_tizen 2.3
6179 * @elseif WEARABLE @since_tizen 2.3.1
6182 * @param[in] l The current locks set, as returned by evas_key_lock_get().
6183 * @param[in] keyname The name of the lock key to check status for.
6185 * @return @c Eina_True if the @p keyname lock key is set, @c
6186 * Eina_False otherwise.
6188 * @see evas_key_lock_get
6189 * @see evas_key_lock_add
6190 * @see evas_key_lock_del
6191 * @see evas_key_lock_on
6192 * @see evas_key_lock_off
6194 EAPI Eina_Bool evas_key_lock_is_set(const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
6202 * @defgroup Evas_Touch_Point_List Touch Point List Functions
6204 * Functions to get information of touched points in the Evas.
6206 * Evas maintains list of touched points on the canvas. Each point has
6207 * its co-ordinates, id and state. You can get the number of touched
6208 * points and information of each point using evas_touch_point_list
6211 * @ingroup Evas_Canvas
6215 * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
6216 * @ingroup Evas_Canvas
6218 * @brief This group provides functions that deal with the status of the pointer (mouse cursor).
6223 typedef Eo Evas_Out;
6225 #define _EVAS_OUT_EO_CLASS_TYPE
6228 * @ingroup Evas_Font_Group
6235 * @defgroup Evas_Font_Path_Group Font Path Functions
6237 * Functions that edit the paths being used to load fonts.
6239 * @ingroup Evas_Font_Group
6243 * Removes all font paths loaded into memory by evas_font_path_app_* APIs
6244 * for the application.
6245 * @ingroup Evas_Font_Path_Group
6248 EAPI void evas_font_path_global_clear(void);
6251 * Appends a font path to the list of font paths used by the application.
6252 * @param path The new font path.
6253 * @ingroup Evas_Font_Path_Group
6256 EAPI void evas_font_path_global_append(const char *path) EINA_ARG_NONNULL(1);
6259 * Prepends a font path to the list of font paths used by the application.
6260 * @param path The new font path.
6261 * @ingroup Evas_Font_Path_Group
6264 EAPI void evas_font_path_global_prepend(const char *path) EINA_ARG_NONNULL(1);
6267 * Retrieves the list of font paths used by the application.
6268 * @return The list of font paths used.
6269 * @ingroup Evas_Font_Path_Group
6272 EAPI const Eina_List *evas_font_path_global_list(void) EINA_WARN_UNUSED_RESULT;