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
463 typedef enum _Evas_Pixel_Import_Pixel_Format
465 EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
466 EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
467 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 */
468 } Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
470 struct _Evas_Pixel_Import_Source
472 Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
473 int w, h; /**< width and height of source in pixels */
474 void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
478 * @def EVAS_NATIVE_SURFACE_VERSION
479 * Magic version number to know what the native surface struct looks like
482 #define EVAS_NATIVE_SURFACE_VERSION 3
485 * Native surface types that image object supports
487 * @see Evas_Native_Surface
488 * @see evas_object_image_native_surface_set()
490 typedef enum _Evas_Native_Surface_Type
492 EVAS_NATIVE_SURFACE_NONE, /**< No surface type */
493 EVAS_NATIVE_SURFACE_X11, /**< X Window system based type. pixmap id or visual of the pixmap */
494 EVAS_NATIVE_SURFACE_OPENGL, /**< OpenGL system based type. texture or framebuffer id*/
495 // TIZEN_ONLY (20151014): Change the next value from 3 to 6 for backward compatibility
496 // EVAS_NATIVE_SURFACE_WL, /**< Wayland system based type. buffer of surface */
497 // TIZEN ONLY (20150112) : NOT FIXED
498 EVAS_NATIVE_SURFACE_TIZEN, /** deprecated **/
499 EVAS_NATIVE_SURFACE_TBM, /**< Tizen system based type. This is used for tizen buffer manager. */
500 EVAS_NATIVE_SURFACE_EVASGL, /**< Evas GL based type. evas gl surface */
502 // TIZEN_ONLY (20151014): Change the next value from 3 to 6 for backward compatibility
503 EVAS_NATIVE_SURFACE_WL, /**< Wayland system based type. buffer of surface */
504 } Evas_Native_Surface_Type;
507 * @brief A generic datatype for engine specific native surface information.
509 * Please fill up Evas_Native_Surface fields that regarded with current surface
510 * type. If you want to set the native surface type to
511 * EVAS_NATIVE_SURFACE_X11, you need to set union data with x11.visual or
512 * x11.pixmap. If you need to set the native surface as
513 * EVAS_NATIVE_SURFACE_OPENGL, on the other hand, you need to set union data
514 * with opengl.texture_id or opengl.framebuffer_id and so on.
515 * If you need to set the native surface as EVAS_NATIVE_SURFACE_WL,
516 * you need to set union data with wl.legacy_buffer. The version field
517 * should be set with EVAS_NATIVE_SURFACE_VERSION in order to check abi
518 * break in your application on the different efl library versions.
520 * @warning Native surface types totally depend on the system. Please
521 * be aware that the types are supported on your system before using
524 * @note The information stored in an @c Evas_Native_Surface returned by
525 * @ref evas_gl_native_surface_get() is not meant to be used by
526 * applications except for passing it to
527 * @ref evas_object_image_native_surface_set().
529 * @see evas_object_image_native_surface_set()
531 struct _Evas_Native_Surface
533 int version; /**< Current Native Surface Version. Use EVAS_NATIVE_SURFACE_VERSION */
534 Evas_Native_Surface_Type type; /**< Surface type. @see Evas_Native_Surface_Type */
538 void *visual; /**< visual of the pixmap to use (Visual) */
539 unsigned long pixmap; /**< pixmap id to use (Pixmap) */
540 } x11; /**< Set this struct fields if surface data is X11 based. */
544 unsigned int texture_id; /**< opengl texture id to use from glGenTextures() */
545 unsigned int framebuffer_id; /**< 0 if not a FBO, FBO id otherwise from glGenFramebuffers() */
546 unsigned int internal_format; /**< same as 'internalFormat' for glTexImage2D() */
547 unsigned int format; /**< same as 'format' for glTexImage2D() */
548 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) */
549 } opengl; /**< Set this struct fields if surface data is OpenGL based. */
553 void *legacy_buffer; /**< wayland client buffer to use */
554 } wl; /**< Set this struct fields if surface data is Wayland based. */
556 // TIZEN ONLY (20150113) : NOT FIXED
558 * @deprecated use tbm struct
562 void *buffer; /**< tbm surface */
563 int rot; /**< rotation (0, 90, 180, 270) */
564 float ratio; /**< width/height ratio of the source image */
565 int flip; /**< flip (0:none, 1:horizontal, 2:vertical, 3:both) */
566 } tizen; /**< Set this struct fields if your surface data is Tizen based. */
570 void *buffer; /**< tbm surface */
571 int rot; /**< rotation (0, 90, 180, 270) */
572 float ratio; /**< width/height ratio of the source image */
573 int flip; /**< flip (0:none, 1:horizontal, 2:vertical, 3:both) */
574 } tbm; /**< Set this struct fields if your surface data is Tizen based. */
577 void *surface; /**< evas gl surface to use */
578 } evasgl; /**< Set this struct fields if surface data is Evas GL based. */
580 } data; /**< Choose one union data according to your surface. */
584 * @def EVAS_VIDEO_SURFACE_VERSION
585 * Magic version number to know what the video surf struct looks like
588 #define EVAS_VIDEO_SURFACE_VERSION 1
591 typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface); /**< Evas video callback function signature */
592 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 */
594 struct _Evas_Video_Surface
596 int version; /**< The Evas Video surface version in use @see EVAS_VIDEO_SURFACE_VERSION*/
598 Evas_Video_Coord_Cb move; /**< Move the video surface to this position */
599 Evas_Video_Coord_Cb resize; /**< Resize the video surface to that size */
600 Evas_Video_Cb show; /**< Show the video overlay surface */
601 Evas_Video_Cb hide; /**< Hide the video overlay surface */
602 Evas_Video_Cb update_pixels; /**< Please update the Evas_Object_Image pixels when called */
604 Evas_Object *parent; /**< The parent object */
609 * Enum values for the Video surface capabilities
612 typedef enum _Evas_Video_Surface_Caps
614 EVAS_VIDEO_SURFACE_MOVE = 1, /**< Move capability */
615 EVAS_VIDEO_SURFACE_RESIZE = 2, /**< Resize capability */
616 EVAS_VIDEO_SURFACE_CLIP = 4, /**< Clip capability */
617 EVAS_VIDEO_SURFACE_BELOW = 8, /**< Below capability */
618 EVAS_VIDEO_SURFACE_STACKING_CHECK = 16, /**< Stacking capability */
619 EVAS_VIDEO_SURFACE_IGNORE_WINDOW = 32, /**< Ignore window capability */
620 } Evas_Video_Surface_Caps;
622 #define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
623 #define EVAS_LAYER_MAX 32767 /**< top-most layer number */
625 #define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
626 #define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
627 #define EVAS_TEXT_INVALID -1 /**< Not used for anything */
628 #define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
630 #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() */
631 #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() */
634 * @brief Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align)
635 * @if MOBILE @since_tizen 2.3
636 * @elseif WEARABLE @since_tizen 2.3.1
638 * @ingroup Evas_Object_Group_Size_Hints
640 #define evas_object_size_hint_fill_set evas_object_size_hint_align_set
643 * @brief Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align)
644 * @if MOBILE @since_tizen 2.3
645 * @elseif WEARABLE @since_tizen 2.3.1
647 * @ingroup Evas_Object_Group_Size_Hints
649 #define evas_object_size_hint_fill_get evas_object_size_hint_align_get
652 * @brief Convenience macro to make it easier to understand that weight is also used for expand properties
653 * @if MOBILE @since_tizen 2.3
654 * @elseif WEARABLE @since_tizen 2.3.1
656 * @ingroup Evas_Object_Group_Size_Hints
658 #define evas_object_size_hint_expand_set evas_object_size_hint_weight_set
661 * @brief Convenience macro to make it easier to understand that weight is also used for expand properties
662 * @if MOBILE @since_tizen 2.3
663 * @elseif WEARABLE @since_tizen 2.3.1
665 * @ingroup Evas_Object_Group_Size_Hints
667 #define evas_object_size_hint_expand_get evas_object_size_hint_weight_get
670 * How the object should be rendered to output.
671 * @ingroup Evas_Object_Group_Extras
673 typedef enum _Evas_Render_Op
675 EVAS_RENDER_BLEND = 0, /**< default op: d = d*(1-sa) + s */
676 EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
677 EVAS_RENDER_COPY = 2, /**< d = s */
678 EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
679 EVAS_RENDER_ADD = 4, /* d = d + s */
680 EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
681 EVAS_RENDER_SUB = 6, /**< d = d - s */
682 EVAS_RENDER_SUB_REL = 7, /* d = d - s*da */
683 EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
684 EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
685 EVAS_RENDER_MASK = 10, /**< d = d*sa */
686 EVAS_RENDER_MUL = 11 /**< d = d*s */
687 } Evas_Render_Op; /**< How the object should be rendered to output. */
689 typedef enum _Evas_Border_Fill_Mode
691 EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */
692 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 */
693 EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */
694 } Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */
696 typedef enum _Evas_Engine_Render_Mode
698 EVAS_RENDER_MODE_BLOCKING = 0, /**< The rendering is blocking mode*/
699 EVAS_RENDER_MODE_NONBLOCKING = 1, /**< The rendering is non blocking mode*/
700 } Evas_Engine_Render_Mode; /**< behaviour of the renderer*/
702 typedef enum _Evas_Image_Content_Hint
704 EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
705 EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents will change over time */
706 EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents won't change over time */
707 } Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
709 typedef enum _Evas_Device_Class
711 EVAS_DEVICE_CLASS_NONE, /**< Not a device @since 1.8 */
712 EVAS_DEVICE_CLASS_SEAT, /**< The user/seat (the user themselves) @since 1.8 */
713 EVAS_DEVICE_CLASS_KEYBOARD, /**< A regular keyboard, numberpad or attached buttons @since 1.8 */
714 EVAS_DEVICE_CLASS_MOUSE, /**< A mouse, trackball or touchpad relative motion device @since 1.8 */
715 EVAS_DEVICE_CLASS_TOUCH, /**< A touchscreen with fingers or stylus @since 1.8 */
716 EVAS_DEVICE_CLASS_PEN, /**< A special pen device @since 1.8 */
717 EVAS_DEVICE_CLASS_POINTER, /**< A laser pointer, wii-style or minority report pointing device @since 1.8 */
718 EVAS_DEVICE_CLASS_GAMEPAD /**< A gamepad controller or joystick @since 1.8 */
719 } Evas_Device_Class; /**< A general class of device @since 1.8 */
721 typedef enum _Evas_Device_Subclass
723 EVAS_DEVICE_SUBCLASS_NONE, /**< Not a device @since 1.8 */
724 EVAS_DEVICE_SUBCLASS_FINGER, /**< The normal flat of your finger @since 1.8 */
725 EVAS_DEVICE_SUBCLASS_FINGERNAIL, /**< A fingernail @since 1.8 */
726 EVAS_DEVICE_SUBCLASS_KNUCKLE, /**< A Knuckle @since 1.8 */
727 EVAS_DEVICE_SUBCLASS_PALM, /**< The palm of a users hand @since 1.8 */
728 EVAS_DEVICE_SUBCLASS_HAND_SIZE, /**< The side of your hand @since 1.8 */
729 EVAS_DEVICE_SUBCLASS_HAND_FLAT, /**< The flat of your hand @since 1.8 */
730 EVAS_DEVICE_SUBCLASS_PEN_TIP, /**< The tip of a pen @since 1.8 */
731 EVAS_DEVICE_SUBCLASS_TRACKPAD, /**< A trackpad style mouse @since 1.8 */
732 EVAS_DEVICE_SUBCLASS_TRACKPOINT, /**< A trackpoint style mouse @since 1.8 */
733 EVAS_DEVICE_SUBCLASS_TRACKBALL, /**< A trackball style mouse @since 1.8 */
734 } Evas_Device_Subclass; /**< A general class of device @since 1.8 */
736 struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
738 int magic; /**< Magic number */
741 struct _Evas_Event_Mouse_Down /** Mouse button press event */
743 int button; /**< Mouse button number that went down (1 - 32) */
745 Evas_Point output; /**< The X/Y location of the cursor */
746 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
749 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
752 Evas_Button_Flags flags; /**< button flags set during the event */
753 unsigned int timestamp;
754 Evas_Event_Flags event_flags;
756 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
759 struct _Evas_Event_Mouse_Up /** Mouse button release event */
761 int button; /**< Mouse button number that was raised (1 - 32) */
763 Evas_Point output; /**< The X/Y location of the cursor */
764 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
767 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
770 Evas_Button_Flags flags; /**< button flags set during the event */
771 unsigned int timestamp;
772 Evas_Event_Flags event_flags;
774 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
777 struct _Evas_Event_Mouse_In /** Mouse enter event */
779 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
781 Evas_Point output; /**< The X/Y location of the cursor */
782 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
785 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
787 unsigned int timestamp;
788 Evas_Event_Flags event_flags;
790 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
793 struct _Evas_Event_Mouse_Out /** Mouse leave event */
795 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
797 Evas_Point output; /**< The X/Y location of the cursor */
798 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
801 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
803 unsigned int timestamp;
804 Evas_Event_Flags event_flags;
806 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
809 struct _Evas_Event_Mouse_Move /** Mouse move event */
811 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
813 Evas_Position cur; /**< Current mouse position */
814 Evas_Position prev; /**< Previous mouse position */
817 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
819 unsigned int timestamp;
820 Evas_Event_Flags event_flags;
822 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
825 struct _Evas_Event_Mouse_Wheel /** Wheel event */
827 int direction; /* 0 = default up/down wheel FIXME: more wheel types */
828 int z; /* ...,-2,-1 = down, 1,2,... = up */
830 Evas_Point output; /**< The X/Y location of the cursor */
831 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
834 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
836 unsigned int timestamp;
837 Evas_Event_Flags event_flags;
841 struct _Evas_Event_Multi_Down /** Multi button press event */
843 int device; /**< Multi device number that went down (1 or more for extra touches) */
844 double radius, radius_x, radius_y;
845 double pressure, angle;
848 Evas_Coord_Precision_Point canvas;
851 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
854 Evas_Button_Flags flags; /**< button flags set during the event */
855 unsigned int timestamp;
856 Evas_Event_Flags event_flags;
860 struct _Evas_Event_Multi_Up /** Multi button release event */
862 int device; /**< Multi device number that went up (1 or more for extra touches) */
863 double radius, radius_x, radius_y;
864 double pressure, angle;
867 Evas_Coord_Precision_Point canvas;
870 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
873 Evas_Button_Flags flags; /**< button flags set during the event */
874 unsigned int timestamp;
875 Evas_Event_Flags event_flags;
879 struct _Evas_Event_Multi_Move /** Multi button down event */
881 int device; /**< Multi device number that moved (1 or more for extra touches) */
882 double radius, radius_x, radius_y;
883 double pressure, angle;
885 Evas_Precision_Position cur;
888 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
890 unsigned int timestamp;
891 Evas_Event_Flags event_flags;
895 struct _Evas_Event_Key_Down /** Key press event */
897 char *keyname; /**< the name string of the key pressed */
899 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
902 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
903 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
904 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 */
905 unsigned int timestamp;
906 Evas_Event_Flags event_flags;
909 unsigned int keycode; /**< Key scan code numeric value @since 1.10 */
912 struct _Evas_Event_Key_Up /** Key release event */
914 char *keyname; /**< the name string of the key released */
916 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
919 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
920 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
921 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 */
922 unsigned int timestamp;
923 Evas_Event_Flags event_flags;
926 unsigned int keycode; /**< Key scan code numeric value @since 1.10 */
929 struct _Evas_Event_Render_Post /** Send when the frame rendering is done @since 1.8 */
931 Eina_List *updated_area; /**< A list of rectangle that were updated in the canvas */
934 struct _Evas_Event_Hold /** Hold change event */
936 int hold; /**< The hold flag */
939 unsigned int timestamp;
940 Evas_Event_Flags event_flags;
944 typedef enum _Evas_Axis_Label
946 EVAS_AXIS_LABEL_UNKNOWN, /**< Axis containing unknown (or not yet representable) data. Range: Unbounded. Unit: Undefined. @since 1.13 */
947 EVAS_AXIS_LABEL_X, /**< Position along physical X axis; not window relative. Range: Unbounded. Unit: Undefined. @since 1.13 */
948 EVAS_AXIS_LABEL_Y, /**< Position along physical Y axis; not window relative. Range: Unbounded. Unit: Undefined. @since 1.13 */
949 EVAS_AXIS_LABEL_PRESSURE, /**< Force applied to tool tip. Range: [0.0, 1.0]. Unit: Unitless. @since 1.13 */
950 EVAS_AXIS_LABEL_DISTANCE, /**< Relative distance along physical Z axis. Range: [0.0, 1.0]. Unit: Unitless @since 1.13 */
951 EVAS_AXIS_LABEL_AZIMUTH, /**< Angle of tool about the Z axis from positive X axis. Range: [-PI, PI]. Unit: Radians. @since 1.13 */
952 EVAS_AXIS_LABEL_TILT, /**< Angle of tool about plane of sensor from positive Z axis. Range: [0.0, PI]. Unit: Radians. @since 1.13 */
953 EVAS_AXIS_LABEL_TWIST, /**< Rotation of tool about its major axis from its natural position. Range: [-PI, PI] Unit: Radians. @since 1.13 */
954 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 */
955 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 */
956 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 */
957 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 */
958 } Evas_Axis_Label; /**< Types of recognized device axes @since 1.13 */
962 Evas_Axis_Label label;
966 struct _Evas_Event_Axis_Update
970 unsigned int timestamp;
980 * How the mouse pointer should be handled by Evas.
982 * In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button
983 * is pressed down over an object and held, with the mouse pointer
984 * being moved outside of it, the pointer still behaves as being bound
985 * to that object, albeit out of its drawing region. When the button
986 * is released, the event will be fed to the object, that may check if
987 * the final position is over it or not and do something about it.
989 * In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will
990 * always be bound to the object right below it.
992 * @ingroup Evas_Object_Group_Extras
994 typedef enum _Evas_Object_Pointer_Mode
996 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
997 EVAS_OBJECT_POINTER_MODE_NOGRAB, /**< pointer always bound to the object right below it */
998 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 */
999 } Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
1002 * @brief Evas smart objects' smart callback function signature
1003 * @if MOBILE @since_tizen 2.3
1004 * @elseif WEARABLE @since_tizen 2.3.1
1006 * @ingroup Evas_Smart_Object_Group
1008 typedef void (*Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info);
1011 * @brief Evas event callback function signature
1012 * @if MOBILE @since_tizen 2.3
1013 * @elseif WEARABLE @since_tizen 2.3.1
1015 * @ingroup Evas_Canvas_Events
1017 typedef void (*Evas_Event_Cb)(void *data, Evas *e, void *event_info);
1020 * @brief Evas event callback Post function signature
1021 * @if MOBILE @since_tizen 2.3
1022 * @elseif WEARABLE @since_tizen 2.3.1
1024 * @ingroup Evas_Canvas_Events
1026 typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e);
1029 * @brief Evas object event callback function signature
1030 * @if MOBILE @since_tizen 2.3
1031 * @elseif WEARABLE @since_tizen 2.3.1
1033 * @ingroup Evas_Object_Group_Events
1035 typedef void (*Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info);
1038 * @brief Evas Async events put function signature
1039 * @if MOBILE @since_tizen 2.3
1040 * @elseif WEARABLE @since_tizen 2.3.1
1042 * @ingroup Evas_Top_Group
1044 typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
1052 * @defgroup Evas_Main_Group Top Level Functions
1055 * Functions that affect Evas as a whole.
1061 * Get the path for the cserve binary to execute
1063 * There is little need for anyone except a desktop environment to call this.
1064 * This can be called before evas_init() has been called. It will try and find
1065 * the full path to the to the cserve binary to run to provide cserve image
1066 * and font caching services for evas.
1068 * @return NULL if error, or a string with the full path to the cserve binary.
1072 EAPI const char *evas_cserve_path_get(void);
1077 * @return The init counter value.
1079 * This function initializes Evas and increments a counter of the
1080 * number of calls to it. It returns the new counter's value.
1082 * @if MOBILE @since_tizen 2.3
1083 * @elseif WEARABLE @since_tizen 2.3.1
1086 * @see evas_shutdown().
1088 * Most EFL users wouldn't be using this function directly, because
1089 * they wouldn't access Evas directly by themselves. Instead, they
1090 * would be using higher level helpers, like @c ecore_evas_init().
1093 * You should be using this if your use is something like the
1094 * following. The buffer engine is just one of the many ones Evas
1097 * @dontinclude evas-buffer-simple.c
1100 * And being the canvas creation something like:
1101 * @skip static Evas *create_canvas
1102 * @until evas_output_viewport_set(canvas,
1104 * Note that this is code creating an Evas canvas with no usage of
1105 * Ecore helpers at all -- no linkage with Ecore on this scenario,
1106 * thus. Again, this wouldn't be on Evas common usage for most
1107 * developers. See the full @ref Example_Evas_Buffer_Simple example.
1109 * @ingroup Evas_Main_Group
1111 EAPI int evas_init(void);
1116 * @return Evas' init counter value.
1118 * This function finalizes Evas, decrementing the counter of the
1119 * number of calls to the function evas_init(). This new value for the
1120 * counter is returned.
1122 * @if MOBILE @since_tizen 2.3
1123 * @elseif WEARABLE @since_tizen 2.3.1
1128 * If you were the sole user of Evas, by means of evas_init(), you can
1129 * check if it's being properly shut down by expecting a return value
1132 * Example code follows.
1133 * @dontinclude evas-buffer-simple.c
1134 * @skip // NOTE: use ecore_evas_buffer_new
1135 * @until evas_shutdown
1136 * Where that function would contain:
1137 * @skip evas_free(canvas)
1138 * @until evas_free(canvas)
1140 * Most users would be using ecore_evas_shutdown() instead, like told
1141 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
1144 * @ingroup Evas_Main_Group
1146 EAPI int evas_shutdown(void);
1149 * Return if any allocation errors have occurred during the prior function
1150 * @return The allocation error flag
1152 * @if MOBILE @since_tizen 2.3
1153 * @elseif WEARABLE @since_tizen 2.3.1
1156 * This function will return if any memory allocation errors occurred during,
1157 * and what kind they were. The return value will be one of
1158 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
1159 * with each meaning something different.
1161 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
1162 * worked as expected.
1164 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
1165 * its job and will have exited as cleanly as possible. The programmer
1166 * should consider this as a sign of very low memory and should try and safely
1167 * recover from the prior functions failure (or try free up memory elsewhere
1168 * and try again after more memory is freed).
1170 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
1171 * recovered from by evas finding memory of its own it has allocated and
1172 * freeing what it sees as not really usefully allocated memory. What is freed
1173 * may vary. Evas may reduce the resolution of images, free cached images or
1174 * fonts, throw out pre-rendered data, reduce the complexity of change lists
1175 * etc. Evas and the program will function as per normal after this, but this
1176 * is a sign of low memory, and it is suggested that the program try and
1177 * identify memory it doesn't need, and free it.
1181 * extern Evas_Object *object;
1182 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
1184 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
1185 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
1187 * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
1188 * fprintf(stderr, " destroy object now as it cannot be used.\n");
1189 * evas_object_del(object);
1191 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1192 * my_memory_cleanup();
1194 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
1196 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
1197 * my_memory_cleanup();
1201 * @ingroup Evas_Main_Group
1203 EAPI Evas_Alloc_Error evas_alloc_error(void);
1206 * @brief Get evas' internal asynchronous events read file descriptor.
1208 * @if MOBILE @since_tizen 2.3
1209 * @elseif WEARABLE @since_tizen 2.3.1
1212 * @return The canvas' asynchronous events read file descriptor.
1214 * Evas' asynchronous events are meant to be dealt with internally,
1215 * i. e., when building stuff to be glued together into the EFL
1216 * infrastructure -- a module, for example. The context which demands
1217 * its use is when calculations need to be done out of the main
1218 * thread, asynchronously, and some action must be performed after
1221 * An example of actual use of this API is for image asynchronous
1222 * preload inside evas. If the canvas was instantiated through
1223 * ecore-evas usage, ecore itself will take care of calling those
1224 * events' processing.
1226 * This function returns the read file descriptor where to get the
1227 * asynchronous events of the canvas. Naturally, other mainloops,
1228 * apart from ecore, may make use of it.
1230 * @ingroup Evas_Main_Group
1232 EAPI int evas_async_events_fd_get(void) EINA_WARN_UNUSED_RESULT;
1235 * @brief Trigger the processing of all events waiting on the file
1236 * descriptor returned by evas_async_events_fd_get().
1238 * @if MOBILE @since_tizen 2.3
1239 * @elseif WEARABLE @since_tizen 2.3.1
1242 * @return The number of events processed.
1244 * All asynchronous events queued up by evas_async_events_put() are
1245 * processed here. More precisely, the callback functions, informed
1246 * together with other event parameters, when queued, get called (with
1247 * those parameters), in that order.
1249 * @ingroup Evas_Main_Group
1251 EAPI int evas_async_events_process(void);
1254 * Insert asynchronous events on the canvas.
1256 * @if MOBILE @since_tizen 2.3
1257 * @elseif WEARABLE @since_tizen 2.3.1
1260 * @param target The target to be affected by the events.
1261 * @param type The type of callback function.
1262 * @param event_info Information about the event.
1263 * @param func The callback function pointer.
1265 * @return EINA_FALSE if an error occured, EINA_TRUE otherwise.
1267 * This is the way, for a routine running outside evas' main thread,
1268 * to report an asynchronous event. A callback function is informed,
1269 * whose call is to happen after evas_async_events_process() is
1272 * @ingroup Evas_Main_Group
1274 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);
1277 * @defgroup Evas_Canvas Canvas Functions
1280 * Low level Evas canvas functions. Sub groups will present more high
1281 * level ones, though.
1283 * Most of these functions deal with low level Evas actions, like:
1284 * @li create/destroy raw canvases, not bound to any displaying engine
1285 * @li tell a canvas i got focused (in a windowing context, for example)
1286 * @li tell a canvas a region should not be calculated anymore in rendering
1287 * @li tell a canvas to render its contents, immediately
1289 * Most users will be using Evas by means of the @c Ecore_Evas
1290 * wrapper, which deals with all the above mentioned issues
1291 * automatically for them. Thus, you'll be looking at this section
1292 * only if you're building low level stuff.
1294 * The groups within present you functions that deal with the canvas
1295 * directly, too, and not yet with its @b objects. They are the
1296 * functions you need to use at a minimum to get a working canvas.
1298 * Some of the functions in this group are exemplified @ref
1299 * Example_Evas_Events here.
1306 * @defgroup Evas_Output_Method Render Engine Functions
1308 * Functions that are used to set the render engine for a given
1309 * function, and then get that engine working.
1311 * The following code snippet shows how they can be used to
1312 * initialise an evas that uses the X11 software engine:
1314 * @ingroup Evas_Canvas
1320 * @brief Look up a numeric ID from a string name of a rendering engine.
1322 * @if MOBILE @since_tizen 2.3
1323 * @elseif WEARABLE @since_tizen 2.3.1
1326 * @param[in] name the name string of an engine
1327 * @return A numeric (opaque) ID for the rendering engine
1328 * @ingroup Evas_Output_Method
1330 * @remark This function looks up a numeric return value for the named engine
1331 * in the string @p name. This is a normal C string, NUL byte
1332 * terminated. The name is case sensitive. If the rendering engine is
1333 * available, a numeric ID for that engine is returned that is not
1334 * 0. If the engine is not available, 0 is returned, indicating an
1337 * @remark The programmer should NEVER rely on the numeric ID of an engine
1338 * unless it is returned by this function. Programs should NOT be
1339 * written accessing render method ID's directly, without first
1340 * obtaining it from this function.
1342 * @attention it is mandatory that one calls Evas Initialization function before
1343 * looking up the render method.
1347 EAPI int evas_render_method_lookup(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1350 * @brief List all the rendering engines compiled into the copy of the Evas library
1352 * @if MOBILE @since_tizen 2.3
1353 * @elseif WEARABLE @since_tizen 2.3.1
1356 * @return A linked list whose data members are C strings of engine names
1357 * @ingroup Evas_Output_Method
1359 * @remark Calling this will return a handle (pointer) to an Evas linked
1360 * list. Each node in the linked list will have the data pointer be a
1361 * (char *) pointer to the name string of the rendering engine
1362 * available. The strings should never be modified, neither should the
1363 * list be modified. This list should be cleaned up as soon as the
1364 * program no longer needs it using evas_render_method_list_free(). If
1365 * no engines are available from Evas, @c NULL will be returned.
1369 * Eina_List *engine_list, *l;
1370 * char *engine_name;
1372 * engine_list = evas_render_method_list();
1375 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1378 * printf("Available Evas Engines:\n");
1379 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1380 * printf("%s\n", engine_name);
1381 * evas_render_method_list_free(engine_list);
1384 EAPI Eina_List *evas_render_method_list(void) EINA_WARN_UNUSED_RESULT;
1387 * @brief This function should be called to free a list of engine names
1389 * @if MOBILE @since_tizen 2.3
1390 * @elseif WEARABLE @since_tizen 2.3.1
1393 * @param[in] list The Eina_List base pointer for the engine list to be freed
1394 * @ingroup Evas_Output_Method
1396 * @remark When this function is called it will free the engine list passed in
1397 * as @p list. The list should only be a list of engines generated by
1398 * calling evas_render_method_list(). If @p list is NULL, nothing will
1403 * Eina_List *engine_list, *l;
1404 * char *engine_name;
1406 * engine_list = evas_render_method_list();
1409 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1412 * printf("Available Evas Engines:\n");
1413 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1414 * printf("%s\n", engine_name);
1415 * evas_render_method_list_free(engine_list);
1418 EAPI void evas_render_method_list_free(Eina_List *list);
1425 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1427 * Functions that are used to map coordinates from the canvas to the
1428 * screen or the screen to the canvas.
1430 * @ingroup Evas_Canvas
1434 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1436 * Functions that set and retrieve the output and viewport size of an
1439 * @ingroup Evas_Canvas
1443 * @defgroup Evas_Canvas_Events Canvas Events
1445 * Functions relating to canvas events, which are mainly reports on
1446 * its internal states changing (an object got focused, the rendering
1449 * Some of the functions in this group are exemplified @ref
1450 * Example_Evas_Events here.
1452 * @ingroup Evas_Canvas
1458 * @brief Free the rectangles returned by evas_render_updates().
1460 * @if MOBILE @since_tizen 2.3
1461 * @elseif WEARABLE @since_tizen 2.3.1
1464 * @param[in] updates The list of updated rectangles of the canvas.
1466 * @remark This function removes the region from the render updates list. It
1467 * makes the region doesn't be render updated anymore.
1469 * @see evas_render_updates() for an example
1471 * @ingroup Evas_Canvas
1473 EAPI void evas_render_updates_free(Eina_List *updates);
1480 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
1482 * Functions that deal with the freezing of input event processing of
1485 * There might be scenarios during a graphical user interface
1486 * program's use when the developer wishes the users wouldn't be able
1487 * to deliver input events to this application. It may, for example,
1488 * be the time for it to populate a view or to change some
1489 * layout. Assuming proper behavior with user interaction during this
1490 * exact time would be hard, as things are in a changing state. The
1491 * programmer can then tell the canvas to ignore input events,
1492 * bringing it back to normal behavior when he/she wants.
1494 * Most of the time use of freezing events is done like this:
1496 * evas_event_freeze(my_evas_canvas);
1497 * function_that_does_work_which_cant_be_interrupted_by_events();
1498 * evas_event_thaw(my_evas_canvas);
1501 * Some of the functions in this group are exemplified @ref
1502 * Example_Evas_Events here.
1504 * @ingroup Evas_Canvas_Events
1509 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
1511 * Functions to tell Evas that input events happened and should be
1514 * @warning Most of the time these functions are @b not what you're looking for.
1515 * These functions should only be used if you're not working with ecore evas(or
1516 * another input handling system). If you're not using ecore evas please
1517 * consider using it, in most situation it will make life a lot easier.
1519 * As explained in @ref intro_not_evas, Evas does not know how to poll
1520 * for input events, so the developer should do it and then feed such
1521 * events to the canvas to be processed. This is only required if
1522 * operating Evas directly. Modules such as Ecore_Evas do that for
1525 * Some of the functions in this group are exemplified @ref
1526 * Example_Evas_Events here.
1528 * @ingroup Evas_Canvas_Events
1533 * @addtogroup Evas_Event_Feeding_Group
1538 * Add a new device type
1540 * @param e The canvas to create the device node for.
1542 * Adds a new device node to the given canvas @p e. All devices created as
1543 * part of the canvas @p e will automatically be deleted when the canvas
1546 * @return the device node created or NULL if an error occured.
1548 * @see evas_device_del
1551 EAPI Evas_Device *evas_device_add(Evas *e);
1554 * Delete a new device type
1556 * @param dev The device node you want to delete.
1558 * @see evas_device_add
1559 * @see evas_device_push
1560 * @see evas_device_pop
1563 EAPI void evas_device_del(Evas_Device *dev);
1566 * Push the current context device onto the device stack
1568 * @param e The canvas to push the device on to
1569 * @param dev The device to push.
1571 * This pushes the given device @p dev onto the stack for the canvas @p e
1572 * resulting in the dev pointer in all events that get fed to the canvas
1573 * being the device at the top of the device stack for that canvas.
1575 * If a device is pushed onto the device stack, it will not be deleted
1576 * until a canvas free OR until it has been popped from the stack even if
1577 * evas_device_del() is called.
1579 * The device @p dev must have been created as a device for the canvas it
1580 * is pushed onto (and not another canvas).
1584 * evas_device_push(canvas, dev);
1585 * evas_event_feed_mouse_move(canvas, 20, 30, 0, NULL);
1586 * evas_device_pop(canvas);
1589 * @see evas_device_pop
1592 EAPI void evas_device_push(Evas *e, Evas_Device *dev);
1595 * This pops the top of the device stack for the canvas
1597 * @param e The canvas to pop the device stack from
1599 * This pops the top of the device stack making the current device context
1600 * used for device events being what is now at the top of the stack after
1603 * @see evas_device_push
1606 EAPI void evas_device_pop(Evas *e);
1609 * List all current devices attached to the given canvas and/or device
1611 * @param e The canvas to query for a device list
1612 * @param dev A specific device inside the canvas to query for child devices or NULL if just querying the base canvas devices
1613 * @return An internal list of Evas_Device pointers, or NULL if no devices are found
1615 * This will list all devices belonging to a specific evas canvas @p e, at the
1616 * top-level in the device tree if @p dev passed in is NULL. If @p dev is
1617 * a valid device for the given canvas @p e, then a list of child devices
1618 * of @p dev will be returned, allowing you to walk the device tree.
1620 * The list returned is only valid so long as no changes are made to the
1621 * device tree in the given canvas @p e. If there are no devices or children
1622 * then NULL is returned.
1624 * @see evas_device_parent_get
1625 * @see evas_device_name_get
1626 * @see evas_device_description_get
1627 * @see evas_device_class_get
1628 * @see evas_device_subclass_get
1629 * @see evas_device_emulation_source_get
1632 EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev);
1635 * Set the name of a device as a string
1637 * @p dev The device to set the name of
1638 * @p name The name string as a readable C UTF8 string
1642 EAPI void evas_device_name_set(Evas_Device *dev, const char *name);
1645 * Get the name of a device
1647 * @p dev The device to query
1648 * @return The device name string or NULL if none is set
1650 * This gets the name set by evas_device_name_set(). This is a readable UTF8
1651 * C string, or NULL if no name is set.
1653 * The name should be a short name like Wireless Mouse, Joystick,
1654 * Finger, Keyboard or Numberpad etc.
1658 EAPI const char *evas_device_name_get(const Evas_Device *dev);
1661 * Set the description of a device as a string
1663 * @p dev The device to set the description of
1664 * @p name The description string as a readable C UTF8 string
1668 EAPI void evas_device_description_set(Evas_Device *dev, const char *desc);
1671 * Get the description of a device
1673 * @p dev The device to query
1674 * @return The device description string or NULL if none is set
1676 * This gets the description set by evas_device_description_set(). This is
1677 * a readable UTF8 C string, or NULL if no description is set.
1679 * A description is meant to be a longer string describing the device so a
1680 * human may make sense of it. For example Wireless 6 button mouse in Black
1681 * with red buttons would be a good description, so a user may identify
1682 * precisely which device is being talked about.
1686 EAPI const char *evas_device_description_get(const Evas_Device *dev);
1689 * Set the parent of a device
1691 * @p dev The device to set the parent of
1692 * @p parent The new parent device
1694 * This sets the parent of a device @p dev to the parent given by @p parent.
1695 * If the device already has a parent, it is removed from that parent's list.
1696 * If @p parent is NULL then the device is unparented and placed back as a
1697 * root device in the canvas.
1699 * When a device is deleted with evas_device_del(), all children are also
1700 * deleted along with it.
1702 * @see evas_device_del
1703 * @see evas_device_parent_get
1704 * @see evas_device_list
1708 EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent);
1711 * Get the parent of a device
1713 * @param dev The device to query
1714 * @return The parent device or NULL if it is a toplevel
1716 * This returns the parent device of any given device entry, or NULL if no
1717 * parent device exists (is a toplevel device).
1721 EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev);
1724 * Set the major class of device
1726 * @param dev The device whose class to set
1727 * @param clas The class to set it to
1729 * This sets the primary class of device (a broad thing like mouse, keyboard,
1734 EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas);
1737 * Get the major class of a device
1739 * @param dev The devise to query
1740 * @return The device class to set
1742 * This sets the device class set by evas_device_class_set().
1746 EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev);
1749 * Set the sub-class of a device
1751 * @param dev The device to modify
1752 * @param clas The sub-class to set
1754 * This sets the sub-class of a device whihc gives much more detailed usage
1755 * within a broader category.
1759 EAPI void evas_device_subclass_set(Evas_Device *dev, Evas_Device_Subclass clas);
1762 * Get the device sub-class
1764 * @param dev The device to query
1765 * @return The device sub-class set by evas_device_subclass_set().
1769 EAPI Evas_Device_Subclass evas_device_subclass_get(const Evas_Device *dev);
1772 * Set the emulation source device
1774 * @param dev The device being emulated
1775 * @param src The primary source device producing events in the emulated device
1777 * Devices may not be real, but may be emulated by listening to input on other
1778 * devices and modifying or interpeting it to generate output on an emulated
1779 * device (example a fingeron a touchscreen will often emulate a mouse when
1780 * it presses). This allows you to set which device primarily emulates @p dev
1781 * so the user can choose to ignore events from emulated devices if they also
1782 * pay attention to source device events for example.
1786 EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src);
1789 * Get the emulation source device
1791 * @param dev The device to query
1792 * @return The source emulation device set by evas_device_emulation_source_set().
1796 EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev);
1804 * @defgroup Evas_Image_Group Image Functions
1806 * Functions that deals with images at canvas level.
1808 * @ingroup Evas_Canvas
1813 * @defgroup Evas_Font_Group Font Functions
1815 * Functions that deals with fonts.
1817 * @ingroup Evas_Canvas
1821 * @defgroup Evas_Object_Group Generic Object Functions
1824 * Functions that manipulate generic Evas objects.
1826 * All Evas displaying units are Evas objects. One handles them all by
1827 * means of the handle ::Evas_Object. Besides Evas treats their
1828 * objects equally, they have @b types, which define their specific
1829 * behavior (and individual API).
1831 * Evas comes with a set of built-in object types:
1840 * These functions apply to @b any Evas object, whichever type that
1843 * @note The built-in types which are most used are rectangles, text
1844 * and images. In fact, with these ones one can create 2D interfaces
1845 * of arbitrary complexity and EFL makes it easy.
1849 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
1851 * Almost every evas object created will have some generic function used to
1852 * manipulate it. That's because there are a number of basic actions to be done
1853 * to objects that are irrespective of the object's type, things like:
1854 * @li Showing/Hiding
1855 * @li Setting(and getting) geometry
1856 * @li Bring up or down a layer
1857 * @li Color management
1858 * @li Handling focus
1860 * @li Reference counting
1862 * All of this issues are handled through the functions here grouped. Examples
1863 * of these function can be seen in @ref Example_Evas_Object_Manipulation(which
1864 * deals with the most common ones) and in @ref Example_Evas_Stacking(which
1865 * deals with stacking functions).
1867 * @ingroup Evas_Object_Group
1871 * @defgroup Evas_Object_Group_Events Object Events
1873 * Objects generate events when they are moved, resized, when their
1874 * visibility change, when they are deleted and so on. These methods
1875 * allow one to be notified about and to handle such events.
1877 * Objects also generate events on input (keyboard and mouse), if they
1878 * accept them (are visible, focused, etc).
1880 * For each of those events, Evas provides a way for one to register
1881 * callback functions to be issued just after they happen.
1883 * The following figure illustrates some Evas (event) callbacks:
1885 * @image html evas-callbacks.png
1886 * @image rtf evas-callbacks.png
1887 * @image latex evas-callbacks.eps
1889 * These events have their values in the #Evas_Callback_Type
1890 * enumeration, which has also ones happening on the canvas level (see
1891 * @ref Evas_Canvas_Events ).
1893 * Examples on this group of functions can be found @ref
1894 * Example_Evas_Stacking here and @ref Example_Evas_Events here.
1896 * @ingroup Evas_Object_Group
1900 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspective, 3D...)
1902 * Evas allows different transformations to be applied to all kinds of
1903 * objects. These are applied by means of UV mapping.
1905 * With UV mapping, one maps points in the source object to a 3D space
1906 * positioning at target. This allows rotation, perspective, scale and
1907 * lots of other effects, depending on the map that is used.
1909 * Each map point may carry a multiplier color. If properly
1910 * calculated, these can do shading effects on the object, producing
1913 * As usual, Evas provides both the raw and easy to use methods. The
1914 * raw methods allow developers to create their maps somewhere else,
1915 * possibly loading them from some file format. The easy to use methods
1916 * calculate the points given some high-level parameters such as
1917 * rotation angle, ambient light, and so on.
1919 * @note applying mapping will reduce performance, so use with
1920 * care. The impact on performance depends on engine in
1921 * use. Software is quite optimized, but not as fast as OpenGL.
1923 * @section sec-map-points Map points
1924 * @subsection subsec-rotation Rotation
1926 * A map consists of a set of points, currently only four are supported. Each
1927 * of these points contains a set of canvas coordinates @c x and @c y that
1928 * can be used to alter the geometry of the mapped object, and a @c z
1929 * coordinate that indicates the depth of that point. This last coordinate
1930 * does not normally affect the map, but it's used by several of the utility
1931 * functions to calculate the right position of the point given other
1934 * The coordinates for each point are set with evas_map_point_coord_set().
1935 * The following image shows a map set to match the geometry of an existing
1938 * @image html map-set-map-points-1.png
1939 * @image rtf map-set-map-points-1.png
1940 * @image latex map-set-map-points-1.eps
1942 * This is a common practice, so there are a few functions that help make it
1945 * evas_map_util_points_populate_from_geometry() sets the coordinates of each
1946 * point in the given map to match the rectangle defined by the function
1949 * evas_map_util_points_populate_from_object() and
1950 * evas_map_util_points_populate_from_object_full() both take an object and
1951 * set the map points to match its geometry. The difference between the two
1952 * is that the first function sets the @c z value of all points to 0, while
1953 * the latter receives the value to set in said coordinate as a parameter.
1955 * The following lines of code all produce the same result as in the image
1958 * evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
1959 * // Assuming o is our original object
1960 * evas_object_move(o, 100, 100);
1961 * evas_object_resize(o, 200, 200);
1962 * evas_map_util_points_populate_from_object(m, o);
1963 * evas_map_util_points_populate_from_object_full(m, o, 0);
1966 * Several effects can be applied to an object by simply setting each point
1967 * of the map to the right coordinates. For example, a simulated perspective
1968 * could be achieve as follows.
1970 * @image html map-set-map-points-2.png
1971 * @image rtf map-set-map-points-2.png
1972 * @image latex map-set-map-points-2.eps
1974 * As said before, the @c z coordinate is unused here so when setting points
1975 * by hand, its value is of no importance.
1977 * @image html map-set-map-points-3.png
1978 * @image rtf map-set-map-points-3.png
1979 * @image latex map-set-map-points-3.eps
1981 * In all three cases above, setting the map to be used by the object is the
1984 * evas_object_map_set(o, m);
1985 * evas_object_map_enable_set(o, EINA_TRUE);
1988 * Doing things this way, however, is a lot of work that can be avoided by
1989 * using the provided utility functions, as described in the next section.
1991 * @section map-utils Utility functions
1993 * Utility functions take an already set up map and alter it to produce a
1994 * specific effect. For example, to rotate an object around its own center
1995 * you would need to take the rotation angle, the coordinates of each corner
1996 * of the object and do all the math to get the new set of coordinates that
1997 * need to be set in the map.
1999 * Or you can use this code:
2001 * evas_object_geometry_get(o, &x, &y, &w, &h);
2002 * m = evas_map_new(4);
2003 * evas_map_util_points_populate_from_object(m, o);
2004 * evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
2005 * evas_object_map_set(o, m);
2006 * evas_object_map_enable_set(o, EINA_TRUE);
2010 * Which will rotate the object around its center point in a 45 degree angle
2011 * in the clockwise direction, taking it from this
2013 * @image html map-rotation-2d-1.png
2014 * @image rtf map-rotation-2d-1.png
2015 * @image latex map-rotation-2d-1.eps
2019 * @image html map-rotation-2d-2.png
2020 * @image rtf map-rotation-2d-2.png
2021 * @image latex map-rotation-2d-2.eps
2023 * Objects may be rotated around any other point just by setting the last two
2024 * paramaters of the evas_map_util_rotate() function to the right values. A
2025 * circle of roughly the diameter of the object overlaid on each image shows
2026 * where the center of rotation is set for each example.
2028 * For example, this code
2030 * evas_object_geometry_get(o, &x, &y, &w, &h);
2031 * m = evas_map_new(4);
2032 * evas_map_util_points_populate_from_object(m, o);
2033 * evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
2034 * evas_object_map_set(o, m);
2035 * evas_object_map_enable_set(o, EINA_TRUE);
2039 * produces something like
2041 * @image html map-rotation-2d-3.png
2042 * @image rtf map-rotation-2d-3.png
2043 * @image latex map-rotation-2d-3.eps
2047 * evas_output_size_get(evas, &w, &h);
2048 * m = evas_map_new(4);
2049 * evas_map_util_points_populate_from_object(m, o);
2050 * evas_map_util_rotate(m, 45, w, h);
2051 * evas_object_map_set(o, m);
2052 * evas_object_map_enable_set(o, EINA_TRUE);
2056 * rotates the object around the center of the window
2058 * @image html map-rotation-2d-4.png
2059 * @image rtf map-rotation-2d-4.png
2060 * @image latex map-rotation-2d-4.eps
2062 * @subsection subsec-3d 3D Maps
2064 * Maps can also be used to achieve the effect of 3-dimensionality. When doing
2065 * this, the @c z coordinate of each point counts, with higher values meaning
2066 * the point is further into the screen, and smaller values (negative, usually)
2067 * meaning the point is closer towards the user.
2069 * Thinking in 3D also introduces the concept of back-face of an object. An
2070 * object is said to be facing the user when all its points are placed in a
2071 * clockwise fashion. The next image shows this, with each point showing the
2072 * with which is identified within the map.
2074 * @image html map-point-order-face.png
2075 * @image rtf map-point-order-face.png
2076 * @image latex map-point-order-face.eps
2078 * Rotating this map around the @c Y axis would leave the order of the points
2079 * in a counter-clockwise fashion, as seen in the following image.
2081 * @image html map-point-order-back.png
2082 * @image rtf map-point-order-back.png
2083 * @image latex map-point-order-back.eps
2085 * This way we can say that we are looking at the back face of the object.
2086 * This will have stronger implications later when we talk about lighting.
2088 * To know if a map is facing towards the user or not it's enough to use
2089 * the evas_map_util_clockwise_get() function, but this is normally done
2090 * after all the other operations are applied on the map.
2092 * @subsection subsec-3d-rot 3D rotation and perspective
2094 * Much like evas_map_util_rotate(), there's the function
2095 * evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
2096 * to an object. As in its 2D counterpart, the rotation can be applied around
2097 * any point in the canvas, this time with a @c z coordinate too. The rotation
2098 * can also be around any of the 3 axis.
2100 * Starting from this simple setup
2102 * @image html map-3d-basic-1.png
2103 * @image rtf map-3d-basic-1.png
2104 * @image latex map-3d-basic-1.eps
2106 * and setting maps so that the blue square to rotate on all axis around a
2107 * sphere that uses the object as its center, and the red square to rotate
2108 * around the @c Y axis, we get the following. A simple overlay over the image
2109 * shows the original geometry of each object and the axis around which they
2110 * are being rotated, with the @c Z one not appearing due to being orthogonal
2113 * @image html map-3d-basic-2.png
2114 * @image rtf map-3d-basic-2.png
2115 * @image latex map-3d-basic-2.eps
2117 * which doesn't look very real. This can be helped by adding perspective
2118 * to the transformation, which can be simply done by calling
2119 * evas_map_util_3d_perspective() on the map after its position has been set.
2120 * The result in this case, making the vanishing point the center of each
2123 * @image html map-3d-basic-3.png
2124 * @image rtf map-3d-basic-3.png
2125 * @image latex map-3d-basic-3.eps
2127 * @section sec-color Color and lighting
2129 * Each point in a map can be set to a color, which will be multiplied with
2130 * the objects own color and linearly interpolated in between adjacent points.
2131 * This is done with evas_map_point_color_set() for each point of the map,
2132 * or evas_map_util_points_color_set() to set every point to the same color.
2134 * When using 3D effects, colors can be used to improve the looks of them by
2135 * simulating a light source. The evas_map_util_3d_lighting() function makes
2136 * this task easier by taking the coordinates of the light source and its
2137 * color, along with the color of the ambient light. Evas then sets the color
2138 * of each point based on the distance to the light source, the angle with
2139 * which the object is facing the light and the ambient light. Here, the
2140 * orientation of each point as explained before, becomes more important.
2141 * If the map is defined counter-clockwise, the object will be facing away
2142 * from the user and thus become obscured, since no light would be reflecting
2145 * @image html map-light.png
2146 * @image rtf map-light.png
2147 * @image latex map-light.eps
2148 * @note Object facing the light source
2150 * @image html map-light2.png
2151 * @image rtf map-light2.png
2152 * @image latex map-light2.eps
2153 * @note Same object facing away from the user
2155 * @section Image mapping
2157 * @image html map-uv-mapping-1.png
2158 * @image rtf map-uv-mapping-1.png
2159 * @image latex map-uv-mapping-1.eps
2161 * Images need some special handling when mapped. Evas can easily take care
2162 * of objects and do almost anything with them, but it's completely oblivious
2163 * to the content of images, so each point in the map needs to be told to what
2164 * pixel in the source image it belongs. Failing to do may sometimes result
2165 * in the expected behavior, or it may look like a partial work.
2167 * The next image illustrates one possibility of a map being set to an image
2168 * object, without setting the right UV mapping for each point. The objects
2169 * themselves are mapped properly to their new geometry, but the image content
2170 * may not be displayed correctly within the mapped object.
2172 * @image html map-uv-mapping-2.png
2173 * @image rtf map-uv-mapping-2.png
2174 * @image latex map-uv-mapping-2.eps
2176 * Once Evas knows how to handle the source image within the map, it will
2177 * transform it as needed. This is done with evas_map_point_image_uv_set(),
2178 * which tells the map to which pixel in image it maps.
2180 * To match our example images to the maps above all we need is the size of
2181 * each image, which can always be found with evas_object_image_size_get().
2184 * evas_map_point_image_uv_set(m, 0, 0, 0);
2185 * evas_map_point_image_uv_set(m, 1, 150, 0);
2186 * evas_map_point_image_uv_set(m, 2, 150, 200);
2187 * evas_map_point_image_uv_set(m, 3, 0, 200);
2188 * evas_object_map_set(o, m);
2189 * evas_object_map_enable_set(o, EINA_TRUE);
2191 * evas_map_point_image_uv_set(m, 0, 0, 0);
2192 * evas_map_point_image_uv_set(m, 1, 120, 0);
2193 * evas_map_point_image_uv_set(m, 2, 120, 160);
2194 * evas_map_point_image_uv_set(m, 3, 0, 160);
2195 * evas_object_map_set(o2, m);
2196 * evas_object_map_enable_set(o2, EINA_TRUE);
2201 * @image html map-uv-mapping-3.png
2202 * @image rtf map-uv-mapping-3.png
2203 * @image latex map-uv-mapping-3.eps
2205 * Maps can also be set to use part of an image only, or even map them inverted,
2206 * and combined with evas_object_image_source_set() it can be used to achieve
2207 * more interesting results.
2210 * evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
2211 * evas_map_point_image_uv_set(m, 0, 0, h);
2212 * evas_map_point_image_uv_set(m, 1, w, h);
2213 * evas_map_point_image_uv_set(m, 2, w, h / 3);
2214 * evas_map_point_image_uv_set(m, 3, 0, h / 3);
2215 * evas_object_map_set(o, m);
2216 * evas_object_map_enable_set(o, EINA_TRUE);
2219 * @image html map-uv-mapping-4.png
2220 * @image rtf map-uv-mapping-4.png
2221 * @image latex map-uv-mapping-4.eps
2224 * @li @ref Example_Evas_Map_Overview
2226 * @ingroup Evas_Object_Group
2232 * @brief Populate source and destination map points to match exactly object.
2234 * @if MOBILE @since_tizen 2.3
2235 * @elseif WEARABLE @since_tizen 2.3.1
2238 * @remark Usually one initialize map of an object to match it's original
2239 * position and size, then transform these with evas_map_util_*
2240 * functions, such as evas_map_util_rotate() or
2241 * evas_map_util_3d_rotate(). The original set is done by this
2242 * function, avoiding code duplication all around.
2244 * @param[in] m map to change all 4 points (must be of size 4).
2245 * @param[in] obj object to use unmapped geometry to populate map coordinates.
2246 * @param[in] z Point Z Coordinate hint (pre-perspective transform). This value
2247 * will be used for all four points.
2249 * @see evas_map_util_points_populate_from_object()
2250 * @see evas_map_point_coord_set()
2251 * @see evas_map_point_image_uv_set()
2253 EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
2256 * @brief Populate source and destination map points to match exactly object.
2258 * @if MOBILE @since_tizen 2.3
2259 * @elseif WEARABLE @since_tizen 2.3.1
2262 * @remark Usually one initialize map of an object to match it's original
2263 * position and size, then transform these with evas_map_util_*
2264 * functions, such as evas_map_util_rotate() or
2265 * evas_map_util_3d_rotate(). The original set is done by this
2266 * function, avoiding code duplication all around.
2268 * @remark Z Point coordinate is assumed as 0 (zero).
2270 * @param[in] m map to change all 4 points (must be of size 4).
2271 * @param[in] obj object to use unmapped geometry to populate map coordinates.
2273 * @see evas_map_util_points_populate_from_object_full()
2274 * @see evas_map_util_points_populate_from_geometry()
2275 * @see evas_map_point_coord_set()
2276 * @see evas_map_point_image_uv_set()
2278 EAPI void evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj);
2281 * @brief Populate source and destination map points to match given geometry.
2283 * @if MOBILE @since_tizen 2.3
2284 * @elseif WEARABLE @since_tizen 2.3.1
2287 * @remark Similar to evas_map_util_points_populate_from_object_full(), this
2288 * call takes raw values instead of querying object's unmapped
2289 * geometry. The given width will be used to calculate destination
2290 * points (evas_map_point_coord_set()) and set the image uv
2291 * (evas_map_point_image_uv_set()).
2293 * @param[in] m map to change all 4 points (must be of size 4).
2294 * @param[in] x Point X Coordinate
2295 * @param[in] y Point Y Coordinate
2296 * @param[in] w width to use to calculate second and third points.
2297 * @param[in] h height to use to calculate third and fourth points.
2298 * @param[in] z Point Z Coordinate hint (pre-perspective transform). This value
2299 * will be used for all four points.
2301 * @see evas_map_util_points_populate_from_object()
2302 * @see evas_map_point_coord_set()
2303 * @see evas_map_point_image_uv_set()
2305 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);
2308 * @brief Set color of all points to given color.
2310 * @if MOBILE @since_tizen 2.3
2311 * @elseif WEARABLE @since_tizen 2.3.1
2314 * @remark This call is useful to reuse maps after they had 3d lightning or
2315 * any other colorization applied before.
2317 * @param[in] m map to change the color of.
2318 * @param[in] r red (0 - 255)
2319 * @param[in] g green (0 - 255)
2320 * @param[in] b blue (0 - 255)
2321 * @param[in] a alpha (0 - 255)
2323 * @see evas_map_point_color_set()
2325 EAPI void evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a);
2328 * @brief Change the map to apply the given rotation.
2330 * @if MOBILE @since_tizen 2.3
2331 * @elseif WEARABLE @since_tizen 2.3.1
2334 * @remark This rotates the indicated map's coordinates around the center coordinate
2335 * given by @p cx and @p cy as the rotation center. The points will have their
2336 * X and Y coordinates rotated clockwise by @p degrees degrees (360.0 is a
2337 * full rotation). Negative values for degrees will rotate counter-clockwise
2338 * by that amount. All coordinates are canvas global coordinates.
2340 * @param[in] m map to change.
2341 * @param[in] degrees amount of degrees from 0.0 to 360.0 to rotate.
2342 * @param[in] cx rotation's center horizontal position.
2343 * @param[in] cy rotation's center vertical position.
2345 * @see evas_map_point_coord_set()
2346 * @see evas_map_util_zoom()
2348 EAPI void evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
2351 * @brief Change the map to apply the given zooming.
2353 * @if MOBILE @since_tizen 2.3
2354 * @elseif WEARABLE @since_tizen 2.3.1
2357 * @remark Like evas_map_util_rotate(), this zooms the points of the map from a center
2358 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
2359 * parameters specify how much to zoom in the X and Y direction respectively.
2360 * A value of 1.0 means don't zoom. 2.0 means double the size. 0.5 is
2361 * half the size etc. All coordinates are canvas global coordinates.
2363 * @param[in] m map to change.
2364 * @param[in] zoomx horizontal zoom to use.
2365 * @param[in] zoomy vertical zoom to use.
2366 * @param[in] cx zooming center horizontal position.
2367 * @param[in] cy zooming center vertical position.
2369 * @see evas_map_point_coord_set()
2370 * @see evas_map_util_rotate()
2372 EAPI void evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
2375 * @brief Rotate the map around 3 axes in 3D
2377 * @if MOBILE @since_tizen 2.3
2378 * @elseif WEARABLE @since_tizen 2.3.1
2381 * @remark This will rotate not just around the Z axis as in evas_map_util_rotate()
2382 * (which is a convenience call for those only wanting 2D). This will rotate
2383 * around the X, Y and Z axes. The Z axis points into the screen with low
2384 * values at the screen and higher values further away. The X axis runs from
2385 * left to right on the screen and the Y axis from top to bottom. Like with
2386 * evas_map_util_rotate() you provide a center point to rotate around (in 3D).
2388 * @param[in] m map to change.
2389 * @param[in] dx amount of degrees from 0.0 to 360.0 to rotate around X axis.
2390 * @param[in] dy amount of degrees from 0.0 to 360.0 to rotate around Y axis.
2391 * @param[in] dz amount of degrees from 0.0 to 360.0 to rotate around Z axis.
2392 * @param[in] cx rotation's center horizontal position.
2393 * @param[in] cy rotation's center vertical position.
2394 * @param[in] cz rotation's center vertical position.
2396 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);
2399 * @brief Rotate the map in 3D using a unit quaternion.
2401 * @if MOBILE @since_tizen 2.3
2402 * @elseif WEARABLE @since_tizen 2.3.1
2405 * @remark This will rotate in 3D using a unit quaternion. Like with
2406 * evas_map_util_3d_rotate() you provide a center point
2407 * to rotate around (in 3D).
2409 * @param[in] m map to change.
2410 * @param[in] qx the x component of the imaginary part of the quaternion.
2411 * @param[in] qy the y component of the imaginary part of the quaternion.
2412 * @param[in] qz the z component of the imaginary part of the quaternion.
2413 * @param[in] qw the w component of the real part of the quaternion.
2414 * @param[in] cx rotation's center x.
2415 * @param[in] cy rotation's center y.
2416 * @param[in] cz rotation's center z.
2418 * @warning Rotations can be done using a unit quaternion. Thus, this
2419 * function expects a unit quaternion (i.e. qx² + qy² + qz² + qw² == 1).
2420 * If this is not the case the behavior is undefined.
2424 EAPI void evas_map_util_quat_rotate(Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz);
2427 * @brief Perform lighting calculations on the given Map
2429 * @if MOBILE @since_tizen 2.3
2430 * @elseif WEARABLE @since_tizen 2.3.1
2433 * @remark This is used to apply lighting calculations (from a single light source)
2434 * to a given map. The R, G and B values of each vertex will be modified to
2435 * reflect the lighting based on the lixth point coordinates, the light
2436 * color and the ambient color, and at what angle the map is facing the
2437 * light source. A surface should have its points be declared in a
2438 * clockwise fashion if the face is facing towards you (as opposed to
2439 * away from you) as faces have a logical side for lighting.
2441 * @image html map-light3.png
2442 * @image rtf map-light3.png
2443 * @image latex map-light3.eps
2444 * @remark Grey object, no lighting used
2446 * @image html map-light4.png
2447 * @image rtf map-light4.png
2448 * @image latex map-light4.eps
2449 * @remark Lights out! Every color set to 0
2451 * @image html map-light5.png
2452 * @image rtf map-light5.png
2453 * @image latex map-light5.eps
2454 * @remark Ambient light to full black, red light coming from close at the
2455 * bottom-left vertex
2457 * @image html map-light6.png
2458 * @image rtf map-light6.png
2459 * @image latex map-light6.eps
2460 * @remark Same light as before, but not the light is set to 0 and ambient light
2463 * @image html map-light7.png
2464 * @image rtf map-light7.png
2465 * @image latex map-light7.eps
2466 * @remark Both lights are on
2468 * @image html map-light8.png
2469 * @image rtf map-light8.png
2470 * @image latex map-light8.eps
2471 * @remark Both lights again, but this time both are the same color.
2473 * @param[in] m map to change.
2474 * @param[in] lx X coordinate in space of light point
2475 * @param[in] ly Y coordinate in space of light point
2476 * @param[in] lz Z coordinate in space of light point
2477 * @param[in] lr light red value (0 - 255)
2478 * @param[in] lg light green value (0 - 255)
2479 * @param[in] lb light blue value (0 - 255)
2480 * @param[in] ar ambient color red value (0 - 255)
2481 * @param[in] ag ambient color green value (0 - 255)
2482 * @param[in] ab ambient color blue value (0 - 255)
2484 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);
2487 * @brief Apply a perspective transform to the map
2489 * @if MOBILE @since_tizen 2.3
2490 * @elseif WEARABLE @since_tizen 2.3.1
2493 * @remark This applies a given perspective (3D) to the map coordinates. X, Y and Z
2494 * values are used. The px and py points specify the infinite distance point
2495 * in the 3D conversion (where all lines converge to like when artists draw
2496 * 3D by hand). The @p z0 value specifies the z value at which there is a 1:1
2497 * mapping between spatial coordinates and screen coordinates. Any points
2498 * on this z value will not have their X and Y values modified in the transform.
2499 * Those further away (Z value higher) will shrink into the distance, and
2500 * those less than this value will expand and become bigger. The @p foc value
2501 * determines the focal length of the camera. This is in reality the distance
2502 * between the camera lens plane itself (at or closer than this rendering
2503 * results are undefined) and the z0 z value. This allows for some depth
2504 * control and @p foc must be greater than 0.
2506 * @param[in] m map to change.
2507 * @param[in] px The perspective distance X coordinate
2508 * @param[in] py The perspective distance Y coordinate
2509 * @param[in] z0 The 0 z plane value
2510 * @param[in] foc The focal distance
2512 EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
2515 * @brief Get the clockwise state of a map
2517 * @if MOBILE @since_tizen 2.3
2518 * @elseif WEARABLE @since_tizen 2.3.1
2521 * @remark This determines if the output points (X and Y. Z is not used) are
2522 * clockwise or counter-clockwise. This can be used for back-face culling. This
2523 * is where you hide objects that face away from you. In this case objects
2524 * that are not clockwise.
2526 * @param[in] m map to query.
2527 * @return 1 if clockwise, 0 otherwise
2529 EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m);
2532 * @brief Create map of transformation points to be later used with an Evas object.
2534 * @if MOBILE @since_tizen 2.3
2535 * @elseif WEARABLE @since_tizen 2.3.1
2538 * @remark This creates a set of points (currently only 4 is supported. no other
2539 * number for @p count will work). That is empty and ready to be modified
2540 * with evas_map calls.
2542 * @param[in] count number of points in the map.
2543 * @return a newly allocated map or @c NULL on errors.
2545 * @see evas_map_free()
2546 * @see evas_map_dup()
2547 * @see evas_map_point_coord_set()
2548 * @see evas_map_point_image_uv_set()
2549 * @see evas_map_util_points_populate_from_object_full()
2550 * @see evas_map_util_points_populate_from_object()
2552 * @see evas_object_map_set()
2554 EAPI Evas_Map *evas_map_new(int count);
2557 * @brief Set the smoothing for map rendering
2559 * @if MOBILE @since_tizen 2.3
2560 * @elseif WEARABLE @since_tizen 2.3.1
2563 * @remark This sets smoothing for map rendering. If the object is a type that has
2564 * its own smoothing settings, then both the smooth settings for this object
2565 * and the map must be turned off. By default smooth maps are enabled.
2567 * @param[in] m map to modify. Must not be NULL.
2568 * @param[in] enabled enable or disable smooth map rendering
2570 EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled);
2573 * @brief Get the smoothing for map rendering
2575 * @if MOBILE @since_tizen 2.3
2576 * @elseif WEARABLE @since_tizen 2.3.1
2579 * @remark This gets smoothing for map rendering.
2581 * @param[in] m map to get the smooth from. Must not be NULL.
2582 * @return @c EINA_TRUE if the smooth is enabled, @c EINA_FALSE otherwise.
2584 EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m);
2587 * @brief Set the alpha flag for map rendering
2589 * @if MOBILE @since_tizen 2.3
2590 * @elseif WEARABLE @since_tizen 2.3.1
2593 * @remark This sets alpha flag for map rendering. If the object is a type that has
2594 * its own alpha settings, then this will take precedence. Only image objects
2595 * have this currently.
2596 * Setting this off stops alpha blending of the map area, and is
2597 * useful if you know the object and/or all sub-objects is 100% solid.
2599 * @param[in] m map to modify. Must not be NULL.
2600 * @param[in] enabled enable or disable alpha map rendering
2602 EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled);
2605 * @brief Get the alpha flag for map rendering
2607 * @if MOBILE @since_tizen 2.3
2608 * @elseif WEARABLE @since_tizen 2.3.1
2611 * @remark This gets the alpha flag for map rendering.
2613 * @param[in] m map to get the alpha from. Must not be NULL.
2614 * @return EINA_FALSE if map is NULL EINA_TRUE otherwise.
2616 EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m);
2621 * Set the flag of the object move synchronization for map rendering
2623 * This sets the flag of the object move synchronization for map rendering.
2624 * If the flag is set as enabled, the map will be moved as the object of the map
2625 * is moved. By default, the flag of the object move synchronization is not
2628 * @param m map to modify. Must not be NULL.
2629 * @param enabled enable or disable the object move synchronization for map
2633 EAPI void evas_map_util_object_move_sync_set(Evas_Map *m, Eina_Bool enabled);
2638 * Get the flag of the object move synchronization for map rendering
2640 * This gets the flag of the object move synchronization for map rendering.
2642 * @param m map to get the flag of the object move synchronization from. Must
2644 * @return EINA_FALSE if map is NULL EINA_TRUE otherwise.
2647 EAPI Eina_Bool evas_map_util_object_move_sync_get(const Evas_Map *m);
2650 * @brief Copy a previously allocated map.
2652 * @if MOBILE @since_tizen 2.3
2653 * @elseif WEARABLE @since_tizen 2.3.1
2656 * @remark This makes a duplicate of the @p m object and returns it.
2658 * @param[in] m map to copy. Must not be NULL.
2659 * @return newly allocated map with the same count and contents as @p m.
2661 EAPI Evas_Map *evas_map_dup(const Evas_Map *m);
2664 * @brief Free a previously allocated map.
2666 * @if MOBILE @since_tizen 2.3
2667 * @elseif WEARABLE @since_tizen 2.3.1
2670 * @remark This frees a given map @p m and all memory associated with it. You must NOT
2671 * free a map returned by evas_object_map_get() as this is internal.
2673 * @param[in] m map to free.
2675 EAPI void evas_map_free(Evas_Map *m);
2678 * @brief Get a maps size.
2680 * @if MOBILE @since_tizen 2.3
2681 * @elseif WEARABLE @since_tizen 2.3.1
2684 * @remark Returns the number of points in a map. Should be at least 4.
2686 * @param[in] m map to get size.
2687 * @return -1 on error, points otherwise.
2689 EAPI int evas_map_count_get(const Evas_Map *m) EINA_CONST;
2692 * @brief Change the map point's coordinate.
2694 * @if MOBILE @since_tizen 2.3
2695 * @elseif WEARABLE @since_tizen 2.3.1
2698 * @remark This sets the fixed point's coordinate in the map. Note that points
2699 * describe the outline of a quadrangle and are ordered either clockwise
2700 * or counter-clockwise. It is suggested to keep your quadrangles concave and
2701 * non-complex, though these polygon modes may work, they may not render
2702 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
2703 * 2 and 3, and 3 and 0 to describe the edges of the quadrangle.
2705 * @remark The X and Y and Z coordinates are in canvas units. Z is optional and may
2706 * or may not be honored in drawing. Z is a hint and does not affect the
2707 * X and Y rendered coordinates. It may be used for calculating fills with
2708 * perspective correct rendering.
2710 * @remark Remember all coordinates are canvas global ones like with move and resize
2713 * @param[in] m map to change point. Must not be @c NULL.
2714 * @param[in] idx index of point to change. Must be smaller than map size.
2715 * @param[in] x Point X Coordinate
2716 * @param[in] y Point Y Coordinate
2717 * @param[in] z Point Z Coordinate hint (pre-perspective transform)
2719 * @see evas_map_util_rotate()
2720 * @see evas_map_util_zoom()
2721 * @see evas_map_util_points_populate_from_object_full()
2722 * @see evas_map_util_points_populate_from_object()
2724 EAPI void evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
2727 * @brief Get the map point's coordinate.
2729 * @if MOBILE @since_tizen 2.3
2730 * @elseif WEARABLE @since_tizen 2.3.1
2733 * @remark This returns the coordinates of the given point in the map.
2735 * @param[in] m map to query point.
2736 * @param[in] idx index of point to query. Must be smaller than map size.
2737 * @param[out] x where to return the X coordinate.
2738 * @param[out] y where to return the Y coordinate.
2739 * @param[out] z where to return the Z coordinate.
2741 EAPI void evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
2744 * @brief Change the map point's U and V texture source point
2746 * @if MOBILE @since_tizen 2.3
2747 * @elseif WEARABLE @since_tizen 2.3.1
2750 * @remark This sets the U and V coordinates for the point. This determines which
2751 * coordinate in the source image is mapped to the given point, much like
2752 * OpenGL and textures. Notes that these points do select the pixel, but
2753 * are double floating point values to allow for accuracy and sub-pixel
2756 * @param[in] m map to change the point of.
2757 * @param[in] idx index of point to change. Must be smaller than map size.
2758 * @param[in] u the X coordinate within the image/texture source
2759 * @param[in] v the Y coordinate within the image/texture source
2761 * @see evas_map_point_coord_set()
2762 * @see evas_object_map_set()
2763 * @see evas_map_util_points_populate_from_object_full()
2764 * @see evas_map_util_points_populate_from_object()
2766 EAPI void evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v);
2769 * @brief Get the map point's U and V texture source points
2771 * @if MOBILE @since_tizen 2.3
2772 * @elseif WEARABLE @since_tizen 2.3.1
2775 * @remark This returns the texture points set by evas_map_point_image_uv_set().
2777 * @param[in] m map to query point.
2778 * @param[in] idx index of point to query. Must be smaller than map size.
2779 * @param[out] u where to write the X coordinate within the image/texture source
2780 * @param[out] v where to write the Y coordinate within the image/texture source
2782 EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v);
2785 * @brief Set the color of a vertex in the map
2787 * @if MOBILE @since_tizen 2.3
2788 * @elseif WEARABLE @since_tizen 2.3.1
2791 * @remark This sets the color of the vertex in the map. Colors will be linearly
2792 * interpolated between vertex points through the map. Color will multiply
2793 * the texture pixels (like GL_MODULATE in OpenGL). The default color of
2794 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
2795 * have no affect on modifying the texture pixels.
2797 * @param[in] m map to change the color of.
2798 * @param[in] idx index of point to change. Must be smaller than map size.
2799 * @param[in] r red (0 - 255)
2800 * @param[in] g green (0 - 255)
2801 * @param[in] b blue (0 - 255)
2802 * @param[in] a alpha (0 - 255)
2804 * @see evas_map_util_points_color_set()
2805 * @see evas_map_point_coord_set()
2806 * @see evas_object_map_set()
2808 EAPI void evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a);
2811 * @brief Get the color set on a vertex in the map
2813 * @if MOBILE @since_tizen 2.3
2814 * @elseif WEARABLE @since_tizen 2.3.1
2817 * @remark This gets the color set by evas_map_point_color_set() on the given vertex
2820 * @param[in] m map to get the color of the vertex from.
2821 * @param[in] idx index of point get. Must be smaller than map size.
2822 * @param[out] r pointer to red return
2823 * @param[out] g pointer to green return
2824 * @param[out] b pointer to blue return
2825 * @param[out] a pointer to alpha return
2827 * @see evas_map_point_coord_set()
2828 * @see evas_object_map_set()
2830 EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
2836 * @defgroup Evas_Object_Group_Size_Hints Size Hints
2838 * Objects may carry hints, so that another object that acts as a
2839 * manager (see @ref Evas_Smart_Object_Group) may know how to properly
2840 * position and resize its subordinate objects. The Size Hints provide
2841 * a common interface that is recommended as the protocol for such
2844 * For example, box objects use alignment hints to align its
2845 * lines/columns inside its container, padding hints to set the
2846 * padding between each individual child, etc.
2848 * Examples on their usage:
2849 * - @ref Example_Evas_Size_Hints evas-hints.c
2850 * - @ref Example_Evas_Aspect_Hints evas-aspect-hints.c
2852 * @ingroup Evas_Object_Group
2856 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
2858 * Miscellaneous functions that also apply to any object, but are less
2859 * used or not implemented by all objects.
2861 * Examples on this group of functions can be found @ref
2862 * Example_Evas_Stacking here and @ref Example_Evas_Events here.
2864 * @ingroup Evas_Object_Group
2869 * @defgroup Evas_Object_Group_Find Finding Objects
2871 * Functions that allows finding objects by their position, name or
2874 * @ingroup Evas_Object_Group
2879 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
2881 * Evas provides a way to intercept method calls. The interceptor
2882 * callback may opt to completely deny the call, or may check and
2883 * change the parameters before continuing. The continuation of an
2884 * intercepted call is done by calling the intercepted call again,
2885 * from inside the interceptor callback.
2887 * @ingroup Evas_Object_Group
2892 * @addtogroup Evas_Object_Group_Interceptors
2897 * Function signature for the resize event of an evas object
2899 * @param data is the pointer passed through the callback.
2900 * @param obj the object being shown.
2902 * @see evas_object_intercept_show_callback_add()
2903 * @see evas_object_intercept_show_callback_del()
2906 typedef void (*Evas_Object_Intercept_Show_Cb)(void *data, Evas_Object *obj);
2909 * Function signature for the hide event of an evas object
2911 * @param data is the pointer passed through the callback.
2912 * @param obj the object being hidden.
2914 * @see evas_object_intercept_hide_callback_add()
2915 * @see evas_object_intercept_hide_callback_del()
2918 typedef void (*Evas_Object_Intercept_Hide_Cb)(void *data, Evas_Object *obj);
2921 * Function signature for the move event of an evas object
2923 * @param data the pointer passed through the callback.
2924 * @param obj the object being moved.
2925 * @param x move x position
2926 * @param y move y position
2928 * @see evas_object_intercept_move_callback_add()
2929 * @see evas_object_intercept_move_callback_del()
2932 typedef void (*Evas_Object_Intercept_Move_Cb)(void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
2935 * Function signature for the resize event of an evas object
2937 * @param data the pointer passed through the callback.
2938 * @param obj the object being resized.
2939 * @param width of the object
2940 * @param height of the object
2942 * @see evas_object_intercept_resize_callback_add()
2943 * @see evas_object_intercept_resize_callback_del()
2946 typedef void (*Evas_Object_Intercept_Resize_Cb)(void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
2949 * Function signature for the raise event of an evas object
2951 * @param data the pointer passed through the callback.
2952 * @param obj the object being raised.
2954 * @see evas_object_intercept_raise_callback_add()
2955 * @see evas_object_intercept_raise_callback_del()
2958 typedef void (*Evas_Object_Intercept_Raise_Cb)(void *data, Evas_Object *obj);
2961 * Function signature for the lower event of an evas object
2963 * @param data the pointer passed through the callback.
2964 * @param obj the object being lowered.
2966 * @see evas_object_intercept_lower_callback_add()
2967 * @see evas_object_intercept_lower_callback_del()
2970 typedef void (*Evas_Object_Intercept_Lower_Cb)(void *data, Evas_Object *obj);
2973 * Function signature for the stack above event of an evas object
2975 * @param data the pointer passed through the callback.
2976 * @param obj the object being stacked above.
2977 * @param above the object above which the object is stacked
2979 * @see evas_object_intercept_stack_above_callback_add()
2980 * @see evas_object_intercept_stack_above_callback_del()
2983 typedef void (*Evas_Object_Intercept_Stack_Above_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
2986 * Function signature for the stack below event of an evas object
2988 * @param data the pointer passed through the callback.
2989 * @param obj the object being stacked below.
2990 * @param above the object below which the object is stacked
2992 * @see evas_object_intercept_stack_below_callback_add()
2993 * @see evas_object_intercept_stack_below_callback_del()
2996 typedef void (*Evas_Object_Intercept_Stack_Below_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
2999 * Function signature for the layer event of an evas object
3001 * @param data the pointer passed through the callback.
3002 * @param obj the object being layered
3003 * @param l the layer value
3005 * @see evas_object_intercept_layer_callback_add()
3006 * @see evas_object_intercept_layer_callback_del()
3009 typedef void (*Evas_Object_Intercept_Layer_Set_Cb)(void *data, Evas_Object *obj, int l);
3012 * Function signature for the focus set event of an evas object
3014 * @param data the pointer passed through the callback.
3015 * @param obj the object being focused
3016 * @param focus the focus value, EINA_TRUE if the object is focused, EINA_FALSE otherwise
3018 * @see evas_object_intercept_focus_set_callback_add()
3019 * @see evas_object_intercept_focus_set_callback_del()
3022 typedef void (*Evas_Object_Intercept_Focus_Set_Cb)(void *data, Evas_Object *obj, Eina_Bool focus);
3025 * Function signature for the color set event of an evas object
3027 * @param data the pointer passed through the callback.
3028 * @param obj the object changing color
3029 * @param r the red component of the color
3030 * @param g the green component of the color
3031 * @param b the blue component of the color
3032 * @param a the alpha component of the color
3034 * @see evas_object_intercept_color_set_callback_add()
3035 * @see evas_object_intercept_color_set_callback_del()
3038 typedef void (*Evas_Object_Intercept_Color_Set_Cb)(void *data, Evas_Object *obj, int r, int g, int b, int a);
3041 * Function signature for the clip set event of an evas object
3043 * @param data the pointer passed through the callback.
3044 * @param obj the object being clipped
3045 * @param clip the evas object on which the object is clipped
3047 * @see evas_object_intercept_clip_set_callback_add()
3048 * @see evas_object_intercept_clip_set_callback_del()
3051 typedef void (*Evas_Object_Intercept_Clip_Set_Cb)(void *data, Evas_Object *obj, Evas_Object *clip);
3054 * Function signature for the clip unset event of an evas object
3056 * @param data the pointer passed through the callback.
3057 * @param obj the object being unclipped
3059 * @see evas_object_intercept_clip_unset_callback_add()
3060 * @see evas_object_intercept_clip_unset_callback_del()
3063 typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj);
3070 * @defgroup Evas_Object_Specific Specific Object Functions
3073 * Functions that work on specific objects.
3078 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
3080 * @brief Function to create evas rectangle objects.
3082 * There is only one function to deal with rectangle objects, this may make this
3083 * function seem useless given there are no functions to manipulate the created
3084 * rectangle, however the rectangle is actually very useful and should be
3085 * manipulated using the generic @ref Evas_Object_Group evas object functions.
3087 * The evas rectangle serves a number of key functions when working on evas
3093 * @section Background
3095 * One extremely common requirement of evas programs is to have a solid color
3096 * background, this can be accomplished with the following very simple code:
3098 * Evas_Object *bg = evas_object_rectangle_add(evas_canvas);
3099 * //Here we set the rectangles red, green, blue and opacity levels
3100 * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
3101 * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
3102 * evas_object_show(bg);
3105 * This however will have issues if the @c evas_canvas is resized, however most
3106 * windows are created using ecore evas and that has a solution to using the
3107 * rectangle as a background
3108 * So this gives us a white background to our window that will be resized
3111 * @section Debugging
3113 * Debugging is a major part of any programmers task and when debugging visual
3114 * issues with evas programs the rectangle is an extremely useful tool. The
3115 * rectangle's simplicity means that it's easier to pinpoint issues with it than
3116 * with more complex objects. Therefore a common technique to use when writing
3117 * an evas program and not getting the desired visual result is to replace the
3118 * misbehaving object for a solid color rectangle and seeing how it interacts
3119 * with the other elements, this often allows us to notice clipping, parenting
3120 * or positioning issues. Once the issues have been identified and corrected the
3121 * rectangle can be replaced for the original part and in all likelihood any
3122 * remaining issues will be specific to that object's type.
3124 * @section clipping Clipping
3126 * Clipping serves two main functions:
3127 * @li Limiting visibility(i.e. hiding portions of an object).
3128 * @li Applying a layer of color to an object.
3130 * @subsection hiding Limiting visibility
3132 * It is often necessary to show only parts of an object, while it may be
3133 * possible to create an object that corresponds only to the part that must be
3134 * shown(and it isn't always possible) it's usually easier to use a a clipper. A
3135 * clipper is a rectangle that defines what's visible and what is not. The way
3136 * to do this is to create a solid white rectangle(which is the default, no need
3137 * to call evas_object_color_set()) and give it a position and size of what
3138 * should be visible. The following code exemplifies showing the center half of
3139 * @c my_evas_object:
3141 * Evas_Object *clipper = evas_object_rectangle_add(evas_canvas);
3142 * evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4);
3143 * evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2);
3144 * evas_object_clip_set(my_evas_object, clipper);
3145 * evas_object_show(clipper);
3148 * @subsection color Layer of color
3150 * In the @ref clipping section we used a solid white clipper, which produced no
3151 * change in the color of the clipped object, it just hid what was outside the
3152 * clippers area. It is however sometimes desirable to change the of color an
3153 * object, this can be accomplished using a clipper that has a non-white color.
3154 * Clippers with color work by multiplying the colors of clipped object. The
3155 * following code will show how to remove all the red from an object:
3157 * Evas_Object *clipper = evas_object_rectangle_add(evas);
3158 * evas_object_move(clipper, my_evas_object_x, my_evas_object_y);
3159 * evas_object_resize(clipper, my_evas_object_width, my_evas_object_height);
3160 * evas_object_color_set(clipper, 0, 255, 255, 255);
3161 * evas_object_clip_set(obj, clipper);
3162 * evas_object_show(clipper);
3165 * @warning We don't guarantee any proper results if you create a Rectangle
3166 * object without setting the evas engine.
3168 * For an example that more fully exercise the use of an evas object rectangle
3169 * see @ref Example_Evas_Object_Manipulation.
3171 * @ingroup Evas_Object_Specific
3175 * @defgroup Evas_Object_Image Image Object Functions
3177 * Here are grouped together functions used to create and manipulate
3178 * image objects. They are available to whichever occasion one needs
3179 * complex imagery on a GUI that could not be achieved by the other
3180 * Evas' primitive object types, or to make image manipulations.
3182 * Evas will support whichever image file types it was compiled with
3183 * support to (its image loaders) -- check your software packager for
3184 * that information and see
3185 * evas_object_image_extension_can_load_get().
3187 * @section Evas_Object_Image_Basics Image object basics
3189 * The most common use of image objects -- to display an image on the
3190 * canvas -- is achieved by a common function triplet:
3192 * img = evas_object_image_add(canvas);
3193 * evas_object_image_file_set(img, "path/to/img", NULL);
3194 * evas_object_image_fill_set(img, 0, 0, w, h);
3196 * The first function, naturally, is creating the image object. Then,
3197 * one must set an source file on it, so that it knows where to fetch
3198 * image data from. Next, one must set <b>how to fill the image
3199 * object's area</b> with that given pixel data. One could use just a
3200 * sub-region of the original image or even have it tiled repeatedly
3201 * on the image object. For the common case of having the whole source
3202 * image to be displayed on the image object, stretched to the
3203 * destination's size, there's also a function helper, to be used
3204 * instead of evas_object_image_fill_set():
3206 * evas_object_image_filled_set(img, EINA_TRUE);
3208 * See those functions' documentation for more details.
3210 * @section Evas_Object_Image_Scale Scale and resizing
3212 * Resizing of image objects will scale their respective source images
3213 * to their areas, if they are set to fill the object's area
3214 * (evas_object_image_filled_set()). If the user wants any control on
3215 * the aspect ratio of an image for different sizes, he/she has to
3216 * take care of that themselves. There are functions to make images to
3217 * get loaded scaled (up or down) in memory, already, if the user is
3218 * going to use them at pre-determined sizes and wants to save
3221 * Evas has even a scale cache, which will take care of caching scaled
3222 * versions of images with more often usage/hits. Finally, one can
3223 * have images being rescaled @b smoothly by Evas (more
3224 * computationally expensive) or not.
3226 * @section Evas_Object_Image_Performance Performance hints
3228 * When dealing with image objects, there are some tricks to boost the
3229 * performance of your application, if it does intense image loading
3230 * and/or manipulations, as in animations on a UI.
3232 * @subsection Evas_Object_Image_Load Load hints
3234 * In image viewer applications, for example, the user will be looking
3235 * at a given image, at full size, and will desire that the navigation
3236 * to the adjacent images on his/her album be fluid and fast. Thus,
3237 * while displaying a given image, the program can be on the
3238 * background loading the next and previous images already, so that
3239 * displaying them on the sequence is just a matter of repainting the
3240 * screen (and not decoding image data).
3242 * Evas addresses this issue with <b>image pre-loading</b>. The code
3243 * for the situation above would be something like the following:
3245 * prev = evas_object_image_filled_add(canvas);
3246 * evas_object_image_file_set(prev, "/path/to/prev", NULL);
3247 * evas_object_image_preload(prev, EINA_TRUE);
3249 * next = evas_object_image_filled_add(canvas);
3250 * evas_object_image_file_set(next, "/path/to/next", NULL);
3251 * evas_object_image_preload(next, EINA_TRUE);
3254 * If you're loading images which are too big, consider setting
3255 * previously it's loading size to something smaller, in case you
3256 * won't expose them in real size. It may speed up the loading
3259 * //to load a scaled down version of the image in memory, if that's
3260 * //the size you'll be displaying it anyway
3261 * evas_object_image_load_scale_down_set(img, zoom);
3263 * //optional: if you know you'll be showing a sub-set of the image's
3264 * //pixels, you can avoid loading the complementary data
3265 * evas_object_image_load_region_set(img, x, y, w, h);
3267 * Refer to Elementary's Photocam widget for a high level (smart)
3268 * object which does lots of loading speed-ups for you.
3270 * @subsection Evas_Object_Image_Animation Animation hints
3272 * If you want to animate image objects on a UI (what you'd get by
3273 * concomitant usage of other libraries, like Ecore and Edje), there
3274 * are also some tips on how to boost the performance of your
3275 * application. If the animation involves resizing of an image (thus,
3276 * re-scaling), you'd better turn off smooth scaling on it @b during
3277 * the animation, turning it back on afterwards, for less
3278 * computations. Also, in this case you'd better flag the image object
3279 * in question not to cache scaled versions of it:
3281 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC);
3283 * // resizing takes place in between
3285 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC);
3288 * Finally, movement of opaque images through the canvas is less
3289 * expensive than of translucid ones, because of blending
3292 * @section Evas_Object_Image_Borders Borders
3294 * Evas provides facilities for one to specify an image's region to be
3295 * treated specially -- as borders. This will make those regions be
3296 * treated specially on resizing scales, by keeping their aspect. This
3297 * makes setting frames around other objects on UIs easy.
3298 * See the following figures for a visual explanation:
3300 * <img src="image-borders.png" style="max-width: 100%;" />
3301 * <a href="image-borders.png">Full-size</a>
3303 * @image rtf image-borders.png
3304 * @image latex image-borders.eps width=\textwidth
3306 * <img src="border-effect.png" style="max-width: 100%;" />
3307 * <a href="border-effect.png">Full-size</a>
3309 * @image rtf border-effect.png
3310 * @image latex border-effect.eps width=\textwidth
3312 * @section Evas_Object_Image_Manipulation Manipulating pixels
3314 * Evas image objects can be used to manipulate raw pixels in many
3315 * ways. The meaning of the data in the pixel arrays will depend on
3316 * the image's color space, be warned (see next section). You can set
3317 * your own data as an image's pixel data, fetch an image's pixel data
3318 * for saving/altering, convert images between different color spaces
3319 * and even advanced operations like setting a native surface as image
3322 * @section Evas_Object_Image_Color_Spaces Color spaces
3324 * Image objects may return or accept image data in multiple
3325 * formats. This is based on the color space of an object. Here is a
3326 * rundown on formats:
3328 * - #EVAS_COLORSPACE_ARGB8888:
3329 * This pixel format is a linear block of pixels, starting at the
3330 * top-left row by row until the bottom right of the image or pixel
3331 * region. All pixels are 32-bit unsigned int's with the high-byte
3332 * being alpha and the low byte being blue in the format ARGB. Alpha
3333 * may or may not be used by evas depending on the alpha flag of the
3334 * image, but if not used, should be set to 0xff anyway.
3335 * This colorspace uses premultiplied alpha. That means that R, G
3336 * and B cannot exceed A in value. The conversion from
3337 * non-premultiplied colorspace is:
3338 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
3339 * So 50% transparent blue will be: 0x80000080. This will not be
3340 * dark - just 50% transparent. Values are 0 == black, 255 ==
3341 * solid or full red, green or blue.
3343 * - #EVAS_COLORSPACE_YCBCR422P601_PL:
3344 * This is a pointer-list indirected set of YUV (YCbCr) pixel
3345 * data. This means that the data returned or set is not actual
3346 * pixel data, but pointers TO lines of pixel data. The list of
3347 * pointers will first be N rows of pointers to the Y plane -
3348 * pointing to the first pixel at the start of each row in the Y
3349 * plane. N is the height of the image data in pixels. Each pixel in
3350 * the Y, U and V planes is 1 byte exactly, packed. The next N / 2
3351 * pointers will point to rows in the U plane, and the next N / 2
3352 * pointers will point to the V plane rows. U and V planes are half
3353 * the horizontal and vertical resolution of the Y plane.
3354 * Row order is top to bottom and row pixels are stored left to
3356 * There is a limitation that these images MUST be a multiple of 2
3357 * pixels in size horizontally or vertically. This is due to the U
3358 * and V planes being half resolution. Also note that this assumes
3359 * the itu601 YUV colorspace specification. This is defined for
3360 * standard television and mpeg streams. HDTV may use the itu709
3362 * Values are 0 to 255, indicating full or no signal in that plane
3365 * - #EVAS_COLORSPACE_YCBCR422P709_PL:
3366 * Not implemented yet.
3368 * - #EVAS_COLORSPACE_RGB565_A5P:
3369 * In the process of being implemented in 1 engine only. This may
3371 * This is a pointer to image data for 16-bit half-word pixel data
3372 * in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue),
3373 * with the high-byte containing red and the low byte containing
3374 * blue, per pixel. This data is packed row by row from the top-left
3375 * to the bottom right.
3376 * If the image has an alpha channel enabled there will be an extra
3377 * alpha plane after the color pixel plane. If not, then this data
3378 * will not exist and should not be accessed in any way. This plane
3379 * is a set of pixels with 1 byte per pixel defining the alpha
3380 * values of all pixels in the image from the top-left to the bottom
3381 * right of the image, row by row. Even though the values of the
3382 * alpha pixels can be 0 to 255, only values 0 through to 32 are
3383 * used, 32 being solid and 0 being transparent.
3384 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
3385 * with 0 being black and 31 or 63 being full red, green or blue
3386 * respectively. This colorspace is also pre-multiplied like
3387 * EVAS_COLORSPACE_ARGB8888 so:
3388 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
3390 * - #EVAS_COLORSPACE_GRY8:
3391 * The image is just a alpha mask (8 bit's per pixel). This is used
3392 * for alpha masking.
3394 * @warning We don't guarantee any proper results if you create a Image object
3395 * without setting the evas engine.
3397 * Some examples on this group of functions can be found @ref
3398 * Example_Evas_Images here.
3400 * @ingroup Evas_Object_Specific
3405 * Function signature for the evas object pixels get callback function
3406 * @see evas_object_image_pixels_get()
3408 * By @a data it will be passed the private data. By @a o it will be passed the
3409 * Evas_Object image on which the pixels are requested.
3412 typedef void (*Evas_Object_Image_Pixels_Get_Cb)(void *data, Evas_Object *o);
3415 * Check if a file extension may be supported by @ref Evas_Object_Image.
3419 * @param file The file to check
3420 * @return @c EINA_TRUE if we may be able to open it, @c EINA_FALSE if it's
3424 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
3426 * This functions is threadsafe.
3428 EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
3431 * Check if a file extension may be supported by @ref Evas_Object_Image.
3435 * @param file The file to check, it should be an Eina_Stringshare.
3436 * @return @c EINA_TRUE if we may be able to open it, @c EINA_FALSE if it's
3440 * This functions is threadsafe.
3442 EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
3448 * @defgroup Evas_Object_Text Text Object Functions
3450 * Functions that operate on single line, single style text objects.
3452 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
3454 * See some @ref Example_Evas_Text examples on this group of functions.
3456 * @warning We don't guarantee any proper results if you create a Text object
3457 * without setting the evas engine.
3459 * @ingroup Evas_Object_Specific
3463 /* basic styles (4 bits allocated use 0->10 now, 5 left) */
3464 #define EVAS_TEXT_STYLE_MASK_BASIC 0xf
3467 * Text style type creation macro. Use style types on the 's'
3468 * arguments, being 'x' your style variable.
3470 #define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
3471 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
3473 #define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
3476 * Text style type creation macro. This one will impose shadow
3477 * directions on the style type variable -- use the @c
3478 * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* values on 's', incrementally.
3480 #define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
3481 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
3484 * @typedef Evas_Text_Style_Type
3486 * Types of styles to be applied on text objects. The @c
3487 * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* ones are to be ORed together with others
3488 * imposing shadow, to change shadow's direction
3490 typedef enum _Evas_Text_Style_Type
3492 EVAS_TEXT_STYLE_PLAIN, /**< plain, standard text */
3493 EVAS_TEXT_STYLE_SHADOW, /**< text with shadow underneath */
3494 EVAS_TEXT_STYLE_OUTLINE, /**< text with an outline */
3495 EVAS_TEXT_STYLE_SOFT_OUTLINE, /**< text with a soft outline */
3496 EVAS_TEXT_STYLE_GLOW, /**< text with a glow effect */
3497 EVAS_TEXT_STYLE_OUTLINE_SHADOW, /**< text with both outline and shadow effects */
3498 EVAS_TEXT_STYLE_FAR_SHADOW, /**< text with (far) shadow underneath */
3499 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW, /**< text with outline and soft shadow effects combined */
3500 EVAS_TEXT_STYLE_SOFT_SHADOW, /**< text with (soft) shadow underneath */
3501 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW, /**< text with (far soft) shadow underneath */
3503 /* OR these to modify shadow direction (3 bits needed) */
3504 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< shadow growing to bottom right */
3505 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< shadow growing to the bottom */
3506 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< shadow growing to bottom left */
3507 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< shadow growing to the left */
3508 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< shadow growing to top left */
3509 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< shadow growing to the top */
3510 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< shadow growing to top right */
3511 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< shadow growing to the right */
3512 } Evas_Text_Style_Type;
3518 * @defgroup Evas_Object_Textblock Textblock Object Functions
3520 * Functions used to create and manipulate textblock objects. Unlike
3521 * @ref Evas_Object_Text, these handle complex text, doing multiple
3522 * styles and multiline text based on HTML-like tags. Of these extra
3523 * features will be heavier on memory and processing cost.
3525 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
3527 * This part explains about the textblock object's API and proper usage.
3528 * The main user of the textblock object is the edje entry object in Edje, so
3529 * that's a good place to learn from, but I think this document is more than
3530 * enough, if it's not, please contact me and I'll update it.
3532 * @subsection textblock_intro Introduction
3533 * The textblock objects is, as implied, an object that can show big chunks of
3534 * text. Textblock supports many features including: Text formatting, automatic
3535 * and manual text alignment, embedding items (for example icons) and more.
3536 * Textblock has three important parts, the text paragraphs, the format nodes
3539 * You can use markup to format text, for example: "<font_size=50>Big!</font_size>".
3540 * You can also put more than one style directive in one tag:
3541 * "<font_size=50 color=#F00>Big and Red!</font_size>".
3542 * Please notice that we used </font_size> although the format also included
3543 * color, this is because the first format determines the matching closing tag's
3544 * name. You can also use anonymous tags, like: "<font_size=30>Big</>" which
3545 * just pop any type of format, but it's advised to use the named alternatives
3548 * @subsection textblock_cursors Textblock Object Cursors
3549 * A textblock Cursor is data type that represents
3550 * a position in a textblock. Each cursor contains information about the
3551 * paragraph it points to, the position in that paragraph and the object itself.
3552 * Cursors register to textblock objects upon creation, this means that once
3553 * you created a cursor, it belongs to a specific obj and you can't for example
3554 * copy a cursor into a cursor of a different object. Registered cursors
3555 * also have the added benefit of updating automatically upon textblock changes,
3556 * this means that if you have a cursor pointing to a specific character, it'll
3557 * still point to it even after you change the whole object completely (as long
3558 * as the char was not deleted), this is not possible without updating, because
3559 * as mentioned, each cursor holds a character position. There are many
3560 * functions that handle cursors, just check out the evas_textblock_cursor*
3561 * functions. For creation and deletion of cursors check out:
3562 * @see evas_object_textblock_cursor_new()
3563 * @see evas_textblock_cursor_free()
3564 * @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).
3566 * @subsection textblock_paragraphs Textblock Object Paragraphs
3567 * The textblock object is made out of text splitted to paragraphs (delimited
3568 * by the paragraph separation character). Each paragraph has many (or none)
3569 * format nodes associated with it which are responsible for the formatting
3570 * of that paragraph.
3572 * @subsection textblock_format_nodes Textblock Object Format Nodes
3573 * As explained in @ref textblock_paragraphs each one of the format nodes
3574 * is associated with a paragraph.
3575 * There are two types of format nodes, visible and invisible:
3576 * Visible: formats that a cursor can point to, i.e formats that
3577 * occupy space, for example: newlines, tabs, items and etc. Some visible items
3578 * are made of two parts, in this case, only the opening tag is visible.
3579 * A closing tag (i.e a \</tag\> tag) should NEVER be visible.
3580 * Invisible: formats that don't occupy space, for example: bold and underline.
3581 * Being able to access format nodes is very important for some uses. For
3582 * example, edje uses the <a> format to create links in the text (and pop
3583 * popups above them when clicked). For the textblock object a is just a
3584 * formatting instruction (how to color the text), but edje utilizes the access
3585 * to the format nodes to make it do more.
3586 * For more information, take a look at all the evas_textblock_node_format_*
3588 * The translation of <tag> tags to actual format is done according to the
3589 * tags defined in the style, see @ref evas_textblock_style_set
3591 * @subsection textblock_special_formats Special Formats
3592 * Textblock supports various format directives that can be used in markup. In
3593 * addition to the mentioned format directives, textblock allows creating
3594 * additional format directives using tags that can be set in the style see
3595 * @ref evas_textblock_style_set .
3597 * For more details see @ref evas_textblock_style_page
3599 * Textblock supports the following formats:
3600 * @li font - Font description in fontconfig like format, e.g: Sans:style=Italic:lang=hi. or Serif:style=Bold.
3601 * @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.
3602 * @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.
3603 * @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.
3604 * @li lang - Overrides the language defined in font. E.g: lang=he is the same as font=:lang=he.
3605 * @li font_fallbacks - A comma delimited list of fonts to try if finding the main font fails.
3606 * @li font_size - The font size in points.
3607 * @li font_source - The source of the font, e.g an eet file.
3608 * @li color - Text color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3609 * @li underline_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3610 * @li underline2_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3611 * @li outline_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3612 * @li shadow_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3613 * @li glow_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3614 * @li glow2_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3615 * @li strikethrough_color - color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3616 * @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%.
3617 * @li valign - Either top, bottom, middle, center, baseline, base, a value between 0.0 and 1.0, or a value between 0% to 100%.
3618 * @li wrap - word, char, mixed, or none.
3619 * @li left_margin - Either reset, or a pixel value indicating the margin.
3620 * @li right_margin - Either reset, or a pixel value indicating the margin.
3621 * @li underline - on, off, single, or double.
3622 * @li strikethrough - on or off
3623 * @li backing_color - Background color in one of the following formats: #RRGGBB, #RRGGBBAA, #RGB, and #RGBA.
3624 * @li backing - Enable/disable background color. ex) on or off
3625 * @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.
3626 * @li tabstops - Pixel value for tab width.
3627 * @li linesize - Force a line size in pixels.
3628 * @li linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
3629 * @li linegap - Force a line gap in pixels.
3630 * @li linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
3631 * @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.
3632 * @li linefill - Either a float value or percentage indicating how much to fill the line.
3633 * @li ellipsis - Value between 0.0-1.0 to indicate the type of ellipsis, or -1.0 to indicate ellipsis isn't wanted.
3634 * @li password - on or off. This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off.
3636 * @warning We don't guarantee any proper results if you create a Textblock
3638 * without setting the evas engine.
3640 * @todo put here some usage examples
3642 * @ingroup Evas_Object_Specific
3648 * @typedef Evas_Textblock_Style
3650 * A textblock style object.
3651 * @see evas_textblock_style_new()
3652 * @see evas_textblock_style_get()
3653 * @see evas_textblock_style_set()
3656 typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
3659 * @typedef Evas_Textblock_Cursor
3661 * A textblock cursor object, used to maipulate the cursor of an evas textblock
3662 * @see evas_object_textblock_cursor_new
3665 typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
3668 * @typedef Evas_Object_Textblock_Node_Format
3671 typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
3673 typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
3674 struct _Evas_Textblock_Rectangle
3676 Evas_Coord x, y, w, h;
3680 * Text type for evas textblock.
3682 typedef enum _Evas_Textblock_Text_Type
3684 EVAS_TEXTBLOCK_TEXT_RAW, /**< textblock text of type raw */
3685 EVAS_TEXTBLOCK_TEXT_PLAIN, /**< textblock text of type plain */
3686 EVAS_TEXTBLOCK_TEXT_MARKUP /**< textblock text of type markup */
3687 } Evas_Textblock_Text_Type;
3690 * Cursor type for evas textblock.
3692 typedef enum _Evas_Textblock_Cursor_Type
3694 EVAS_TEXTBLOCK_CURSOR_UNDER, /**< cursor type is under */
3695 EVAS_TEXTBLOCK_CURSOR_BEFORE /**< cursor type is before */
3696 } Evas_Textblock_Cursor_Type;
3699 * @brief Returns the unescaped version of escape.
3700 * @param[in] escape the string to be escaped
3702 * @if MOBILE @since_tizen 2.3
3703 * @elseif WEARABLE @since_tizen 2.3.1
3706 * @return the unescaped version of escape
3708 EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3711 * @brief Returns the escaped version of the string.
3712 * @param[in] string to escape
3713 * @param[out] len_ret the len of the part of the string that was used.
3715 * @if MOBILE @since_tizen 2.3
3716 * @elseif WEARABLE @since_tizen 2.3.1
3719 * @return the escaped string.
3721 EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3724 * @brief Return the unescaped version of the string between start and end.
3726 * @if MOBILE @since_tizen 2.3
3727 * @elseif WEARABLE @since_tizen 2.3.1
3730 * @param[in] escape_start the start of the string.
3731 * @param[in] escape_end the end of the string.
3732 * @return the unescaped version of the range
3734 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);
3737 * @brief Creates a new textblock style.
3739 * @if MOBILE @since_tizen 2.3
3740 * @elseif WEARABLE @since_tizen 2.3.1
3743 * @return The new textblock style.
3745 EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
3748 * @brief Destroys a textblock style.
3749 * @param[in] ts The textblock style to free.
3751 * @if MOBILE @since_tizen 2.3
3752 * @elseif WEARABLE @since_tizen 2.3.1
3756 EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
3759 * @brief Sets the style ts to the style passed as text by text.
3760 * Expected a string consisting of many (or none) tag='format' pairs.
3762 * @if MOBILE @since_tizen 2.3
3763 * @elseif WEARABLE @since_tizen 2.3.1
3766 * @param[in] ts the style to set.
3767 * @param[in] text the text to parse - NOT NULL.
3768 * @return Returns no value.
3770 EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
3773 * @brief Return the text of the style ts.
3774 * @param[in] ts the style to get it's text.
3776 * @if MOBILE @since_tizen 2.3
3777 * @elseif WEARABLE @since_tizen 2.3.1
3780 * @return the text of the style or null on error.
3782 EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3785 * @brief Prepends markup to the cursor cur.
3787 * @if MOBILE @since_tizen 2.3
3788 * @elseif WEARABLE @since_tizen 2.3.1
3791 * @remark assumes text does not include the unicode object replacement char (0xFFFC)
3793 * @param[in] cur the cursor to prepend to.
3794 * @param[in] text the markup text to prepend.
3795 * @return Return no value.
3797 EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
3800 * @brief Free the cursor and unassociate it from the object.
3801 * @note do not use it to free unassociated cursors.
3803 * @if MOBILE @since_tizen 2.3
3804 * @elseif WEARABLE @since_tizen 2.3.1
3807 * @param[in] cur the cursor to free.
3808 * @return Returns no value.
3810 EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3813 * @brief Sets the cursor to the start of the first text node.
3815 * @if MOBILE @since_tizen 2.3
3816 * @elseif WEARABLE @since_tizen 2.3.1
3819 * @param[in] cur the cursor to update.
3820 * @return Returns no value.
3822 EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3825 * @brief sets the cursor to the end of the last text node.
3827 * @if MOBILE @since_tizen 2.3
3828 * @elseif WEARABLE @since_tizen 2.3.1
3831 * @param[in] cur the cursor to set.
3832 * @return Returns no value.
3834 EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3837 * @brief Advances to the start of the next text node
3839 * @if MOBILE @since_tizen 2.3
3840 * @elseif WEARABLE @since_tizen 2.3.1
3843 * @param[in] cur the cursor to update
3844 * @return @c EINA_TRUE if it managed to advance a paragraph, @c EINA_FALSE
3847 EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3850 * @brief Advances to the end of the previous text node
3852 * @if MOBILE @since_tizen 2.3
3853 * @elseif WEARABLE @since_tizen 2.3.1
3856 * @param[in] cur the cursor to update
3857 * @return @c EINA_TRUE if it managed to advance a paragraph, @c EINA_FALSE
3860 EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3863 * @brief Returns the next format node (after n)
3865 * @if MOBILE @since_tizen 2.3
3866 * @elseif WEARABLE @since_tizen 2.3.1
3869 * @param[in] n the current format node - not null.
3870 * @return Returns the next format node, may be null.
3872 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
3875 * @brief Returns the prev format node (after n)
3877 * @if MOBILE @since_tizen 2.3
3878 * @elseif WEARABLE @since_tizen 2.3.1
3881 * @param[in] n the current format node - not null.
3882 * @return Returns the prev format node, may be null.
3884 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
3887 * @brief Sets the cursor to point to the place where format points to.
3889 * @if MOBILE @since_tizen 2.3
3890 * @elseif WEARABLE @since_tizen 2.3.1
3893 * @param[in] cur the cursor to update.
3894 * @param[in] n the format node to update according.
3895 * @deprecated Use evas_textblock_cursor_at_format_set instead
3896 * Deprecated since Tizen 2.4
3898 EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
3901 * @brief Return the format node at the position pointed by cur.
3903 * @if MOBILE @since_tizen 2.3
3904 * @elseif WEARABLE @since_tizen 2.3.1
3907 * @param[in] cur the position to look at.
3908 * @return the format node if found, @c NULL otherwise.
3909 * @see evas_textblock_cursor_format_is_visible_get()
3911 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3914 * @brief Get the text format representation of the format node.
3916 * @if MOBILE @since_tizen 2.3
3917 * @elseif WEARABLE @since_tizen 2.3.1
3920 * @param[in] fnode the format node.
3921 * @return the textual format of the format node.
3923 EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fnode) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3926 * @brief Set the cursor to point to the position of fmt.
3928 * @if MOBILE @since_tizen 2.3
3929 * @elseif WEARABLE @since_tizen 2.3.1
3932 * @param[in] cur the cursor to update
3933 * @param[in] fmt the format to update according to.
3935 EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
3938 * @brief Check if the current cursor position is a visible format. This way is more
3939 * efficient than evas_textblock_cursor_format_get() to check for the existence
3940 * of a visible format.
3942 * @if MOBILE @since_tizen 2.3
3943 * @elseif WEARABLE @since_tizen 2.3.1
3946 * @param[in] cur the cursor to look at.
3947 * @return @c EINA_TRUE if the cursor points to a visible format, @c EINA_FALSE
3949 * @see evas_textblock_cursor_format_get()
3951 EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3954 * @brief Advances to the next format node
3956 * @if MOBILE @since_tizen 2.3
3957 * @elseif WEARABLE @since_tizen 2.3.1
3960 * @param[in] cur the cursor to be updated.
3961 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3963 EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3966 * @brief Advances to the previous format node.
3968 * @if MOBILE @since_tizen 2.3
3969 * @elseif WEARABLE @since_tizen 2.3.1
3972 * @param[in] cur the cursor to update.
3973 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3975 EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3978 * @brief Returns true if the cursor points to a format.
3980 * @if MOBILE @since_tizen 2.3
3981 * @elseif WEARABLE @since_tizen 2.3.1
3984 * @param[in] cur the cursor to check.
3985 * @return @c EINA_TRUE if a cursor points to a format @c EINA_FALSE
3988 EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3991 * @brief Advances 1 char forward.
3993 * @if MOBILE @since_tizen 2.3
3994 * @elseif WEARABLE @since_tizen 2.3.1
3997 * @param[in] cur the cursor to advance.
3998 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4000 EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4003 * @brief Advances 1 char backward.
4005 * @if MOBILE @since_tizen 2.3
4006 * @elseif WEARABLE @since_tizen 2.3.1
4009 * @param[in] cur the cursor to advance.
4010 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4012 EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4016 * TIZEN_ONLY(20150127): Add evas_textblock_cursor_cluster_* APIs.
4017 * Advances 1 cluster forward.
4018 * Cluster is an text ligature.
4020 * @param cur the cursor to advance.
4021 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4023 EAPI Eina_Bool evas_textblock_cursor_cluster_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4027 * TIZEN_ONLY(20150127): Add evas_textblock_cursor_cluster_* APIs.
4028 * Advances 1 cluster backward.
4029 * Cluster is an text ligature.
4031 * @param cur the cursor to advance.
4032 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4034 EAPI Eina_Bool evas_textblock_cursor_cluster_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4037 * @brief Moves the cursor to the start of the word under the cursor.
4039 * @if MOBILE @since_tizen 2.3
4040 * @elseif WEARABLE @since_tizen 2.3.1
4043 * @param[in] cur the cursor to move.
4044 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4047 EAPI Eina_Bool evas_textblock_cursor_word_start(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4050 * @brief Moves the cursor to the end of the word under the cursor.
4052 * @if MOBILE @since_tizen 2.3
4053 * @elseif WEARABLE @since_tizen 2.3.1
4056 * @param[in] cur the cursor to move.
4057 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
4060 EAPI Eina_Bool evas_textblock_cursor_word_end(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4063 * @brief Go to the first char in the node the cursor is pointing on.
4065 * @if MOBILE @since_tizen 2.3
4066 * @elseif WEARABLE @since_tizen 2.3.1
4069 * @param[in] cur the cursor to update.
4070 * @return Returns no value.
4072 EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4075 * @brief Go to the last char in a text node.
4077 * @if MOBILE @since_tizen 2.3
4078 * @elseif WEARABLE @since_tizen 2.3.1
4081 * @param[in] cur the cursor to update.
4082 * @return Returns no value.
4084 EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4087 * @brief Go to the start of the current line
4089 * @if MOBILE @since_tizen 2.3
4090 * @elseif WEARABLE @since_tizen 2.3.1
4093 * @param[in] cur the cursor to update.
4094 * @return Returns no value.
4096 EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4099 * @brief Go to the end of the current line.
4101 * @if MOBILE @since_tizen 2.3
4102 * @elseif WEARABLE @since_tizen 2.3.1
4105 * @param[in] cur the cursor to update.
4106 * @return Returns no value.
4108 EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4111 * @brief Return the current cursor pos.
4113 * @if MOBILE @since_tizen 2.3
4114 * @elseif WEARABLE @since_tizen 2.3.1
4117 * @param[in] cur the cursor to take the position from.
4118 * @return the position or -1 on error
4120 EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4123 * @brief Set the cursor pos.
4125 * @if MOBILE @since_tizen 2.3
4126 * @elseif WEARABLE @since_tizen 2.3.1
4129 * @param[in] cur the cursor to be set.
4130 * @param[in] pos the pos to set.
4132 EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
4135 * @brief Go to the start of the line passed
4137 * @if MOBILE @since_tizen 2.3
4138 * @elseif WEARABLE @since_tizen 2.3.1
4141 * @param[in] cur cursor to update.
4142 * @param[in] line numer to set.
4143 * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
4145 EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
4148 * @brief Compare two cursors.
4150 * @if MOBILE @since_tizen 2.3
4151 * @elseif WEARABLE @since_tizen 2.3.1
4154 * @param[in] cur1 the first cursor.
4155 * @param[in] cur2 the second cursor.
4156 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
4158 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);
4161 * @brief Make cur_dest point to the same place as cur. Does not work if they don't
4162 * point to the same object.
4164 * @if MOBILE @since_tizen 2.3
4165 * @elseif WEARABLE @since_tizen 2.3.1
4168 * @param[in] cur the source cursor.
4169 * @param[in] cur_dest destination cursor.
4170 * @return Returns no value.
4172 EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
4175 * @brief Adds text to the current cursor position and set the cursor to *before*
4176 * the start of the text just added.
4178 * @if MOBILE @since_tizen 2.3
4179 * @elseif WEARABLE @since_tizen 2.3.1
4182 * @param[in] cur the cursor to where to add text at.
4183 * @param[in] text the text to add.
4184 * @return Returns the len of the text added.
4185 * @see evas_textblock_cursor_text_prepend()
4187 EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
4190 * @brief Adds text to the current cursor position and set the cursor to *after*
4191 * the start of the text just added.
4193 * @if MOBILE @since_tizen 2.3
4194 * @elseif WEARABLE @since_tizen 2.3.1
4197 * @param[in] cur the cursor to where to add text at.
4198 * @param[in] text the text to add.
4199 * @return Returns the len of the text added.
4200 * @see evas_textblock_cursor_text_append()
4202 EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
4205 * Adds format to the current cursor position. If the format being added is a
4206 * visible format, add it *before* the cursor position, otherwise, add it after.
4207 * This behavior is because visible formats are like characters and invisible
4208 * should be stacked in a way that the last one is added last.
4210 * This function works with native formats, that means that style defined
4211 * tags like <br> won't work here. For those kind of things use markup prepend.
4213 * @param cur the cursor to where to add format at.
4214 * @param format the format to add.
4215 * @return Returns true if a visible format was added, false otherwise.
4216 * @see evas_textblock_cursor_format_prepend()
4220 * @brief Check if the current cursor position points to the terminating null of the
4221 * last paragraph. (shouldn't be allowed to point to the terminating null of
4222 * any previous paragraph anyway.
4224 * @if MOBILE @since_tizen 2.3
4225 * @elseif WEARABLE @since_tizen 2.3.1
4228 * @param[in] cur the cursor to look at.
4229 * @return @c EINA_TRUE if the cursor points to the terminating null, @c EINA_FALSE otherwise.
4231 EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
4234 * @brief Adds format to the current cursor position. If the format being added is a
4235 * visible format, add it *before* the cursor position, otherwise, add it after.
4236 * This behavior is because visible formats are like characters and invisible
4237 * should be stacked in a way that the last one is added last.
4238 * If the format is visible the cursor is advanced after it.
4240 * @if MOBILE @since_tizen 2.3
4241 * @elseif WEARABLE @since_tizen 2.3.1
4244 * @remark This function works with native formats, that means that style defined
4245 * tags like <br> won't work here. For those kind of things use markup prepend.
4247 * @param[in] cur the cursor to where to add format at.
4248 * @param[in] format the format to add.
4249 * @return Returns true if a visible format was added, false otherwise.
4250 * @see evas_textblock_cursor_format_prepend()
4252 EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
4255 * @brief Delete the character at the location of the cursor. If there's a format
4256 * pointing to this position, delete it as well.
4258 * @if MOBILE @since_tizen 2.3
4259 * @elseif WEARABLE @since_tizen 2.3.1
4262 * @param[in] cur the cursor pointing to the current location.
4263 * @return Returns no value.
4265 EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
4268 * @brief Delete the range between cur1 and cur2.
4270 * @if MOBILE @since_tizen 2.3
4271 * @elseif WEARABLE @since_tizen 2.3.1
4274 * @param[in] cur1 one side of the range.
4275 * @param[in] cur2 the second side of the range
4276 * @return Returns no value.
4278 EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
4281 * @brief Return the text of the paragraph cur points to - returns the text in markup.
4283 * @if MOBILE @since_tizen 2.3
4284 * @elseif WEARABLE @since_tizen 2.3.1
4287 * @param[in] cur the cursor pointing to the paragraph.
4288 * @return the text on success, @c NULL otherwise.
4290 EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4293 * @brief Return the length of the paragraph, cheaper the eina_unicode_strlen()
4295 * @if MOBILE @since_tizen 2.3
4296 * @elseif WEARABLE @since_tizen 2.3.1
4299 * @param[in] cur the position of the paragraph.
4300 * @return the length of the paragraph on success, -1 otehrwise.
4302 EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4305 * @brief Return the currently visible range.
4307 * @if MOBILE @since_tizen 2.3
4308 * @elseif WEARABLE @since_tizen 2.3.1
4311 * @param[in] start the start of the range.
4312 * @param[in] end the end of the range.
4313 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
4316 EAPI Eina_Bool evas_textblock_cursor_visible_range_get(Evas_Textblock_Cursor *start, Evas_Textblock_Cursor *end) EINA_ARG_NONNULL(1, 2);
4319 * @brief Return the format nodes in the range between cur1 and cur2.
4321 * @if MOBILE @since_tizen 2.3
4322 * @elseif WEARABLE @since_tizen 2.3.1
4325 * @param[in] cur1 one side of the range.
4326 * @param[in] cur2 the other side of the range
4327 * @return the foramt nodes in the range. You have to free it.
4330 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);
4333 * @brief Return the text in the range between cur1 and cur2
4335 * @if MOBILE @since_tizen 2.3
4336 * @elseif WEARABLE @since_tizen 2.3.1
4339 * @param[in] cur1 one side of the range.
4340 * @param[in] cur2 the other side of the range
4341 * @param[in] format The form on which to return the text. Markup - in textblock markup. Plain - UTF8.
4342 * @return the text in the range
4343 * @see elm_entry_markup_to_utf8()
4345 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);
4349 * // TIZEN_ONLY(20150128): Add evas_textblock_cursor_range_text_valid_markup_get API.
4350 * @brief Gets the text and markup tags in the range between @a cur1 and @a cur2.
4352 * @param cur1 The start of the range
4353 * @param cur2 The end of the range
4354 * @return The text in the range and the markup tags that affect the text
4355 * @see elm_entry_markup_to_utf8()
4357 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);
4360 * @brief Return the content of the cursor.
4362 * @if MOBILE @since_tizen 2.3
4363 * @elseif WEARABLE @since_tizen 2.3.1
4366 * @remark Free the returned string pointer when done (if it is not NULL).
4368 * @param[in] cur the cursor
4369 * @return the text in the range, terminated by a nul byte (may be utf8).
4371 EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
4374 * @brief Returns the geometry of two cursors (split cursor), if logical cursor is
4375 * between LTR/RTL text, also considering paragraph direction.
4376 * Upper cursor is shown for the text of the same direction as paragraph,
4377 * lower cursor - for opposite.
4379 * @if MOBILE @since_tizen 2.3
4380 * @elseif WEARABLE @since_tizen 2.3.1
4383 * @remark Split cursor geometry is valid only in '|' cursor mode.
4384 * In this case @c EINA_TRUE is returned and cx2, cy2, cw2, ch2 are set,
4385 * otherwise it behaves like cursor_geometry_get.
4387 * @param[in] cur the cursor.
4388 * @param[out] cx the x of the cursor (or upper cursor)
4389 * @param[out] cy the y of the cursor (or upper cursor)
4390 * @param[out] cw the width of the cursor (or upper cursor)
4391 * @param[out] ch the height of the cursor (or upper cursor)
4392 * @param[out] cx2 the x of the lower cursor
4393 * @param[out] cy2 the y of the lower cursor
4394 * @param[out] cw2 the width of the lower cursor
4395 * @param[out] ch2 the height of the lower cursor
4396 * @param[in] ctype the type of the cursor.
4397 * @return @c EINA_TRUE for split cursor, @c EINA_FALSE otherwise
4401 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);
4404 * @brief Returns the geometry of the cursor. Depends on the type of cursor requested.
4405 * This should be used instead of char_geometry_get because there are weird
4406 * special cases with BiDi text.
4407 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
4408 * get, except for the case of the last char of a line which depends on the
4409 * paragraph direction.
4411 * @if MOBILE @since_tizen 2.3
4412 * @elseif WEARABLE @since_tizen 2.3.1
4415 * @remark in '|' cursor mode (i.e a line between two chars) it is very variable.
4416 * For example consider the following visual string:
4417 * abcCBA (ABC are rtl chars), a cursor pointing on A should actually draw
4418 * a '|' between the c and the C.
4420 * @param[in] cur the cursor.
4421 * @param[out] cx the x of the cursor
4422 * @param[out] cy the y of the cursor
4423 * @param[out] cw the width of the cursor
4424 * @param[out] ch the height of the cursor
4425 * @param[out] dir the direction of the cursor, can be NULL.
4426 * @param[in] ctype the type of the cursor.
4427 * @return line number of the char on success, -1 on error.
4429 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);
4432 * @brief Returns the geometry of the char at cur.
4434 * @if MOBILE @since_tizen 2.3
4435 * @elseif WEARABLE @since_tizen 2.3.1
4438 * @param[in] cur the position of the char.
4439 * @param[out] cx the x of the char.
4440 * @param[out] cy the y of the char.
4441 * @param[out] cw the w of the char.
4442 * @param[out] ch the h of the char.
4443 * @return line number of the char on success, -1 on error.
4445 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);
4448 * @brief Returns the geometry of the pen at cur.
4450 * @if MOBILE @since_tizen 2.3
4451 * @elseif WEARABLE @since_tizen 2.3.1
4454 * @param[in] cur the position of the char.
4455 * @param[out] cpen_x the pen_x of the char.
4456 * @param[out] cy the y of the char.
4457 * @param[out] cadv the adv of the char.
4458 * @param[out] ch the h of the char.
4459 * @return line number of the char on success, -1 on error.
4461 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);
4464 * @brief Returns the geometry of the line at cur.
4466 * @if MOBILE @since_tizen 2.3
4467 * @elseif WEARABLE @since_tizen 2.3.1
4470 * @param[in] cur the position of the line.
4471 * @param[out] cx the x of the line.
4472 * @param[out] cy the y of the line.
4473 * @param[out] cw the width of the line.
4474 * @param[out] ch the height of the line.
4475 * @return line number of the line on success, -1 on error.
4477 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);
4480 * @brief Set the position of the cursor according to the X and Y coordinates.
4482 * @if MOBILE @since_tizen 2.3
4483 * @elseif WEARABLE @since_tizen 2.3.1
4486 * @param[in] cur the cursor to set.
4487 * @param[in] x coord to set by.
4488 * @param[in] y coord to set by.
4489 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
4491 EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
4495 * TIZEN_ONLY(20150127): Add evas_textblock_cursor_cluster_* APIs.
4496 * Set the position of the cursor according to the X and Y coordinates and text ligature.
4498 * @param cur the cursor to set.
4499 * @param x coord to set by.
4500 * @param y coord to set by.
4501 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
4503 EAPI Eina_Bool evas_textblock_cursor_cluster_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
4506 * @brief Set the cursor position according to the y coord.
4508 * @if MOBILE @since_tizen 2.3
4509 * @elseif WEARABLE @since_tizen 2.3.1
4512 * @param[in] cur the cur to be set.
4513 * @param[in] y the coord to set by.
4514 * @return the line number found, -1 on error.
4516 EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
4519 * @brief Get the geometry of a range.
4521 * @if MOBILE @since_tizen 2.3
4522 * @elseif WEARABLE @since_tizen 2.3.1
4525 * @param[in] cur1 one side of the range.
4526 * @param[in] cur2 other side of the range.
4527 * @return a list of Rectangles representing the geometry of the range.
4529 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);
4534 * Get the simple geometry of a range.
4535 * The simple geometry is the geomtry in which rectangles in middle
4536 * lines of range are merged into one big rectangle.
4539 * @param cur1 one side of the range.
4540 * @param cur2 other side of the range.
4541 * @return an iterator of rectangles representing the geometry of the range.
4543 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);
4548 * Get the geometry of ?
4550 * @param cur one side of the range.
4551 * @param cur2 other side of the range.
4553 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);
4556 * @brief Checks if the cursor points to the end of the line.
4558 * @if MOBILE @since_tizen 2.3
4559 * @elseif WEARABLE @since_tizen 2.3.1
4562 * @param[in] cur the cursor to check.
4563 * @return @c EINA_TRUE if true, @c EINA_FALSE otherwise.
4565 EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4573 * @defgroup Evas_Object_Textgrid Textgrid Object Functions
4575 * @todo put here some usage examples
4579 * @ingroup Evas_Object_Specific
4585 * @typedef Evas_Textgrid_Palette
4587 * The palette to use for the foreground and background colors.
4593 EVAS_TEXTGRID_PALETTE_NONE, /**< No palette is used */
4594 EVAS_TEXTGRID_PALETTE_STANDARD, /**< standard palette (around 16 colors) */
4595 EVAS_TEXTGRID_PALETTE_EXTENDED, /**< extended palette (at max 256 colors) */
4596 EVAS_TEXTGRID_PALETTE_LAST /**< ignore it */
4597 } Evas_Textgrid_Palette;
4600 * @typedef Evas_Textgrid_Font_Style
4602 * The style to give to each character of the grid.
4608 EVAS_TEXTGRID_FONT_STYLE_NORMAL = (1 << 0), /**< Normal style */
4609 EVAS_TEXTGRID_FONT_STYLE_BOLD = (1 << 1), /**< Bold style */
4610 EVAS_TEXTGRID_FONT_STYLE_ITALIC = (1 << 2) /**< Oblique style */
4611 } Evas_Textgrid_Font_Style;
4614 * @typedef Evas_Textgrid_Cell
4616 * The values that describes each cell.
4620 typedef struct _Evas_Textgrid_Cell Evas_Textgrid_Cell;
4623 * @struct _Evas_Textgrid_Cell
4625 * The values that describes each cell.
4629 struct _Evas_Textgrid_Cell
4631 Eina_Unicode codepoint; /**< the UNICODE value of the character */
4632 unsigned char fg; /**< the index of the palette for the foreground color */
4633 unsigned char bg; /**< the index of the palette for the background color */
4634 unsigned short bold : 1; /**< whether the character is bold */
4635 unsigned short italic : 1; /**< whether the character is oblique */
4636 unsigned short underline : 1; /**< whether the character is underlined */
4637 unsigned short strikethrough : 1; /**< whether the character is strikethrough'ed */
4638 unsigned short fg_extended : 1; /**< whether the extended palette is used for the foreground color */
4639 unsigned short bg_extended : 1; /**< whether the extended palette is used for the background color */
4640 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) */
4648 * @defgroup Evas_Line_Group Line Object Functions
4650 * Functions used to deal with evas line objects.
4652 * @warning We don't guarantee any proper results if you create a Line object
4653 * without setting the evas engine.
4655 * @ingroup Evas_Object_Specific
4660 * @defgroup Evas_Object_Polygon Polygon Object Functions
4662 * Functions that operate on evas polygon objects.
4664 * Hint: as evas does not provide ellipse, smooth paths or circle, one
4665 * can calculate points and convert these to a polygon.
4667 * @warning We don't guarantee any proper results if you create a Polygon
4668 * object without setting the evas engine.
4670 * @ingroup Evas_Object_Specific
4676 * @defgroup Evas_Smart_Group Smart Functions
4679 * Functions that deal with #Evas_Smart structs, creating definition
4680 * (classes) of objects that will have customized behavior for methods
4681 * like evas_object_move(), evas_object_resize(),
4682 * evas_object_clip_set() and others.
4684 * These objects will accept the generic methods defined in @ref
4685 * Evas_Object_Group and the extensions defined in @ref
4686 * Evas_Smart_Object_Group. There are a couple of existent smart
4687 * objects in Evas itself (see @ref Evas_Object_Box, @ref
4688 * Evas_Object_Table and @ref Evas_Smart_Object_Clipped).
4690 * See also some @ref Example_Evas_Smart_Objects examples of this
4691 * group of functions.
4698 * @def EVAS_SMART_CLASS_VERSION
4700 * The version you have to put into the version field in the
4701 * #Evas_Smart_Class struct. Used to safeguard from binaries with old
4702 * smart object intefaces running with newer ones.
4704 * @ingroup Evas_Smart_Group
4706 #define EVAS_SMART_CLASS_VERSION 4
4708 * @struct _Evas_Smart_Class
4710 * A smart object's @b base class definition
4712 * @ingroup Evas_Smart_Group
4714 struct _Evas_Smart_Class
4716 const char *name; /**< the name string of the class */
4718 void (*add)(Evas_Object *o); /**< code to be run when adding object to a canvas */
4719 void (*del)(Evas_Object *o); /**< code to be run when removing object from a canvas */
4720 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. */
4721 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. */
4722 void (*show)(Evas_Object *o); /**< code to be run when showing object on a canvas */
4723 void (*hide)(Evas_Object *o); /**< code to be run when hiding object on a canvas */
4724 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. */
4725 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. */
4726 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. */
4727 void (*calculate)(Evas_Object *o); /**< code to be run when object has rendering updates on a canvas */
4728 void (*member_add)(Evas_Object *o, Evas_Object *child); /**< code to be run when a child member is added to object */
4729 void (*member_del)(Evas_Object *o, Evas_Object *child); /**< code to be run when a child member is removed from object */
4731 const Evas_Smart_Class *parent; /**< this class inherits from this parent */
4732 const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, @c NULL terminated */
4733 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 */
4738 * @struct _Evas_Smart_Interface
4740 * A smart object's @b base interface definition
4742 * Every Evas interface must have a name field, pointing to a global,
4743 * constant string variable. This string pointer will be the only way
4744 * of retrieving back a given interface from a smart object. Two
4745 * function pointers must be defined, too, which will be called at
4746 * object creation and deletion times.
4748 * See also some @ref Example_Evas_Smart_Interfaces examples on
4753 * @ingroup Evas_Smart_Group
4755 struct _Evas_Smart_Interface
4757 const char *name; /**< Name of the given interface */
4758 unsigned private_size; /**< Size, in bytes, of the interface's private dada blob. This will be allocated and freed automatically for you. */
4759 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. */
4760 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. */
4764 * @struct _Evas_Smart_Cb_Description
4766 * Describes a callback issued by a smart object
4767 * (evas_object_smart_callback_call()), as defined in its smart object
4768 * class. This is particularly useful to explain to end users and
4769 * their code (i.e., introspection) what the parameter @c event_info
4772 * @ingroup Evas_Smart_Group
4774 struct _Evas_Smart_Cb_Description
4776 const char *name; /**< callback name ("changed", for example) */
4779 * @brief Hint on the type of @c event_info parameter's contents on
4780 * a #Evas_Smart_Cb callback.
4782 * The type string uses the pattern similar to
4783 * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures,
4784 * but extended to optionally include variable names within
4785 * brackets preceding types. Example:
4787 * @li Structure with two integers:
4790 * @li Structure called 'x' with two integers named 'a' and 'b':
4793 * @li Array of integers:
4796 * @li Array called 'x' of struct with two integers:
4799 * @note This type string is used as a hint and is @b not validated
4800 * or enforced in any way. Implementors should make the best
4801 * use of it to help bindings, documentation and other users
4802 * of introspection features.
4808 * @def EVAS_SMART_CLASS_INIT_NULL
4809 * Initializer to zero a whole Evas_Smart_Class structure.
4811 * @see EVAS_SMART_CLASS_INIT_VERSION
4812 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4813 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4814 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4815 * @ingroup Evas_Smart_Group
4817 #define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
4820 * @def EVAS_SMART_CLASS_INIT_VERSION
4821 * Initializer to zero a whole Evas_Smart_Class structure and set version.
4823 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4824 * latest EVAS_SMART_CLASS_VERSION.
4826 * @see EVAS_SMART_CLASS_INIT_NULL
4827 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4828 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4829 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4830 * @ingroup Evas_Smart_Group
4832 #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}
4835 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
4836 * Initializer to zero a whole Evas_Smart_Class structure and set name
4839 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4840 * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
4842 * It will keep a reference to name field as a const char *, that is,
4843 * name must be available while the structure is used (hint: static or global!)
4844 * and will not be modified.
4846 * @see EVAS_SMART_CLASS_INIT_NULL
4847 * @see EVAS_SMART_CLASS_INIT_VERSION
4848 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4849 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4850 * @ingroup Evas_Smart_Group
4852 #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}
4855 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4856 * Initializer to zero a whole Evas_Smart_Class structure and set name,
4857 * version and parent class.
4859 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4860 * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
4863 * It will keep a reference to name field as a const char *, that is,
4864 * name must be available while the structure is used (hint: static or global!)
4865 * and will not be modified. Similarly, parent reference will be kept.
4867 * @see EVAS_SMART_CLASS_INIT_NULL
4868 * @see EVAS_SMART_CLASS_INIT_VERSION
4869 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4870 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4871 * @ingroup Evas_Smart_Group
4873 #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}
4876 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4877 * Initializer to zero a whole Evas_Smart_Class structure and set name,
4878 * version, parent class and callbacks definition.
4880 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4881 * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
4882 * class and callbacks at this level.
4884 * It will keep a reference to name field as a const char *, that is,
4885 * name must be available while the structure is used (hint: static or global!)
4886 * and will not be modified. Similarly, parent and callbacks reference
4889 * @see EVAS_SMART_CLASS_INIT_NULL
4890 * @see EVAS_SMART_CLASS_INIT_VERSION
4891 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4892 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4893 * @ingroup Evas_Smart_Group
4895 #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}
4898 * @def EVAS_SMART_SUBCLASS_NEW
4900 * Convenience macro to subclass a given Evas smart class.
4902 * @param smart_name The name used for the smart class. e.g:
4903 * @c Evas_Object_Box.
4904 * @param prefix Prefix used for all variables and functions defined
4905 * and referenced by this macro.
4906 * @param api_type Type of the structure used as API for the smart
4907 * class. Either #Evas_Smart_Class or something derived from it.
4908 * @param parent_type Type of the parent class API.
4909 * @param parent_func Function that gets the parent class. e.g:
4910 * evas_object_box_smart_class_get().
4911 * @param cb_desc Array of callback descriptions for this smart class.
4913 * This macro saves some typing when writing a smart class derived
4914 * from another one. In order to work, the user @b must provide some
4915 * functions adhering to the following guidelines:
4916 * - @<prefix@>_smart_set_user(): the @b internal @c _smart_set
4917 * function (defined by this macro) will call this one, provided by
4918 * the user, after inheriting everything from the parent, which
4919 * should <b>take care of setting the right member functions for
4920 * the class</b>, both overrides and extensions, if any.
4921 * - If this new class should be subclassable as well, a @b public
4922 * @c _smart_set() function is desirable to fill in the class used as
4923 * parent by the children. It's up to the user to provide this
4924 * interface, which will most likely call @<prefix@>_smart_set() to
4927 * After the macro's usage, the following will be defined for use:
4928 * - @<prefix@>_parent_sc: A pointer to the @b parent smart
4929 * class. When calling parent functions from overloaded ones, use
4930 * this global variable.
4931 * - @<prefix@>_smart_class_new(): this function returns the
4932 * #Evas_Smart needed to create smart objects with this class,
4933 * which should be passed to evas_object_smart_add().
4935 * @warning @p smart_name has to be a pointer to a globally available
4936 * string! The smart class created here will just have a pointer set
4937 * to that, and all object instances will depend on it for smart class
4940 * @ingroup Evas_Smart_Group
4942 #define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
4943 static const parent_type * prefix##_parent_sc = NULL; \
4944 static void prefix##_smart_set_user(api_type * api); \
4945 static void prefix##_smart_set(api_type * api) \
4947 Evas_Smart_Class *sc; \
4948 if (!(sc = (Evas_Smart_Class *)api)) \
4950 if (!prefix##_parent_sc) \
4951 prefix##_parent_sc = parent_func(); \
4952 evas_smart_class_inherit(sc, prefix##_parent_sc); \
4953 prefix##_smart_set_user(api); \
4955 static Evas_Smart *prefix##_smart_class_new(void) \
4957 static Evas_Smart *smart = NULL; \
4958 static api_type api; \
4961 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
4962 memset(&api, 0, sizeof(api_type)); \
4963 sc->version = EVAS_SMART_CLASS_VERSION; \
4964 sc->name = smart_name; \
4965 sc->callbacks = cb_desc; \
4966 prefix##_smart_set(&api); \
4967 smart = evas_smart_class_new(sc); \
4973 * @def EVAS_SMART_SUBCLASS_IFACE_NEW
4977 * Convenience macro to subclass a given Evas smart class. This is the
4978 * same as #EVAS_SMART_SUBCLASS_NEW, but now <b>declaring smart
4979 * interfaces</b> besides the smart callbacks.
4981 * @param smart_name The name used for the smart class. e.g:
4982 * @c Evas_Object_Box.
4983 * @param prefix Prefix used for all variables and functions defined
4984 * and referenced by this macro.
4985 * @param api_type Type of the structure used as API for the smart
4986 * class. Either #Evas_Smart_Class or something
4988 * @param parent_type Type of the parent class API.
4989 * @param parent_func Function that gets the parent class. e.g:
4990 * evas_object_box_smart_class_get().
4991 * @param cb_desc Array of smart callback descriptions for this smart
4993 * @param ifaces Array of Evas smart interafaces for this smart
4996 * This macro saves some typing when writing a smart class derived
4997 * from another one. In order to work, the user @b must provide some
4998 * functions adhering to the following guidelines:
4999 * - @<prefix@>_smart_set_user(): the @b internal @c _smart_set
5000 * function (defined by this macro) will call this one, provided by
5001 * the user, after inheriting everything from the parent, which
5002 * should <b>take care of setting the right member functions for
5003 * the class</b>, both overrides and extensions, if any.
5004 * - If this new class should be subclassable as well, a @b public
5005 * @c _smart_set() function is desirable to fill in the class used as
5006 * parent by the children. It's up to the user to provide this
5007 * interface, which will most likely call @<prefix@>_smart_set() to
5010 * After the macro's usage, the following will be defined for use:
5011 * - @<prefix@>_parent_sc: A pointer to the @b parent smart
5012 * class. When calling parent functions from overloaded ones, use
5013 * this global variable.
5014 * - @<prefix@>_smart_class_new(): this function returns the
5015 * #Evas_Smart needed to create smart objects with this class,
5016 * which should be passed to evas_object_smart_add().
5018 * @warning @p smart_name has to be a pointer to a globally available
5019 * string! The smart class created here will just have a pointer set
5020 * to that, and all object instances will depend on it for smart class
5023 * @ingroup Evas_Smart_Group
5025 #define EVAS_SMART_SUBCLASS_IFACE_NEW(smart_name, \
5032 static const parent_type * prefix##_parent_sc = NULL; \
5033 static void prefix##_smart_set_user(api_type * api); \
5034 static void prefix##_smart_set(api_type * api) \
5036 Evas_Smart_Class *sc; \
5037 if (!(sc = (Evas_Smart_Class *)api)) \
5039 if (!prefix##_parent_sc) \
5040 prefix##_parent_sc = parent_func(); \
5041 evas_smart_class_inherit(sc, prefix##_parent_sc); \
5042 prefix##_smart_set_user(api); \
5044 static Evas_Smart *prefix##_smart_class_new(void) \
5046 static Evas_Smart *smart = NULL; \
5047 static api_type api; \
5050 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
5051 memset(&api, 0, sizeof(api_type)); \
5052 sc->version = EVAS_SMART_CLASS_VERSION; \
5053 sc->name = smart_name; \
5054 sc->callbacks = cb_desc; \
5055 sc->interfaces = ifaces; \
5056 prefix##_smart_set(&api); \
5057 smart = evas_smart_class_new(sc); \
5063 * @def EVAS_SMART_DATA_ALLOC
5065 * Convenience macro to allocate smart data only if needed.
5067 * When writing a subclassable smart object, the @c .add() function
5068 * will need to check if the smart private data was already allocated
5069 * by some child object or not. This macro makes it easier to do it.
5071 * @note This is an idiom used when one calls the parent's @c .add()
5072 * after the specialized code. Naturally, the parent's base smart data
5073 * has to be contemplated as the specialized one's first member, for
5076 * @param o Evas object passed to the @c .add() function
5077 * @param priv_type The type of the data to allocate
5079 * @ingroup Evas_Smart_Group
5081 #define EVAS_SMART_DATA_ALLOC(o, priv_type) \
5083 priv = evas_object_smart_data_get(o); \
5085 priv = (priv_type *)calloc(1, sizeof(priv_type)); \
5086 if (!priv) return; \
5087 evas_object_smart_data_set(o, priv); \
5091 * Free an #Evas_Smart struct
5093 * @param s the #Evas_Smart struct to free
5095 * @warning If this smart handle was created using
5096 * evas_smart_class_new(), the associated #Evas_Smart_Class will not
5099 * @note If you're using the #EVAS_SMART_SUBCLASS_NEW schema to create your
5100 * smart object, note that an #Evas_Smart handle will be shared amongst all
5101 * instances of the given smart class, through a static variable.
5102 * Evas will internally count references on #Evas_Smart handles and free them
5103 * when they are not referenced anymore. Thus, this function is of no use
5104 * for Evas users, most probably.
5106 EAPI void evas_smart_free(Evas_Smart *s) EINA_ARG_NONNULL(1);
5109 * Creates a new #Evas_Smart from a given #Evas_Smart_Class struct
5111 * @param sc the smart class definition
5112 * @return a new #Evas_Smart pointer
5114 * #Evas_Smart handles are necessary to create new @b instances of
5115 * smart objects belonging to the class described by @p sc. That
5116 * handle will contain, besides the smart class interface definition,
5117 * all its smart callbacks infrastructure set, too.
5119 * @note If you are willing to subclass a given smart class to
5120 * construct yours, consider using the #EVAS_SMART_SUBCLASS_NEW macro,
5121 * which will make use of this function automatically for you.
5123 EAPI Evas_Smart *evas_smart_class_new(const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
5126 * Get the #Evas_Smart_Class handle of an #Evas_Smart struct
5128 * @param s a valid #Evas_Smart pointer
5129 * @return the #Evas_Smart_Class in it
5131 EAPI const Evas_Smart_Class *evas_smart_class_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5134 * @brief Get the data pointer set on an #Evas_Smart struct
5136 * @param s a valid #Evas_Smart handle
5138 * This data pointer is set as the data field in the #Evas_Smart_Class
5139 * passed in to evas_smart_class_new().
5141 EAPI void *evas_smart_data_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5144 * Get the smart callbacks known by this #Evas_Smart handle's smart
5147 * @param s A valid #Evas_Smart handle.
5148 * @param[out] count Returns the number of elements in the returned
5150 * @return The array with callback descriptions known by this smart
5151 * class, with its size returned in @a count parameter. It
5152 * should not be modified in any way. If no callbacks are
5153 * known, @c NULL is returned. The array is sorted by event
5154 * names and elements refer to the original values given to
5155 * evas_smart_class_new()'s Evas_Smart_Class::callbacks
5156 * (pointer to them).
5158 * This is likely different from
5159 * evas_object_smart_callbacks_descriptions_get() as it will contain
5160 * the callbacks of @b all this class hierarchy sorted, while the
5161 * direct smart class member refers only to that specific class and
5162 * should not include parent's.
5164 * If no callbacks are known, this function returns @c NULL.
5166 * The array elements and thus their contents will be @b references to
5167 * original values given to evas_smart_class_new() as
5168 * Evas_Smart_Class::callbacks.
5170 * The array is sorted by Evas_Smart_Cb_Description::name. The last
5171 * array element is a @c NULL pointer and is not accounted for in @a
5172 * count. Loop iterations can check any of these size indicators.
5174 * @note objects may provide per-instance callbacks, use
5175 * evas_object_smart_callbacks_descriptions_get() to get those
5177 * @see evas_object_smart_callbacks_descriptions_get()
5179 EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
5182 * Find a callback description for the callback named @a name.
5184 * @param s The #Evas_Smart where to search for class registered smart
5186 * @param name Name of the desired callback, which must @b not be @c
5187 * NULL. The search has a special case for @a name being the
5188 * same pointer as registered with #Evas_Smart_Cb_Description.
5189 * One can use it to avoid excessive use of strcmp().
5190 * @return A reference to the description if found, or @c NULL, otherwise
5192 * @see evas_smart_callbacks_descriptions_get()
5194 EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2);
5197 * Sets one class to inherit from the other.
5199 * Copy all function pointers, set @c parent to @a parent_sc and copy
5200 * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
5201 * using @a parent_sc_size as reference.
5203 * This is recommended instead of a single memcpy() since it will take
5204 * care to not modify @a sc name, version, callbacks and possible
5207 * @param sc child class.
5208 * @param parent_sc parent class, will provide attributes.
5209 * @param parent_sc_size size of parent_sc structure, child should be at least
5210 * this size. Everything after @c Evas_Smart_Class size is copied
5211 * using regular memcpy().
5213 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);
5216 * Get the number of users of the smart instance
5218 * @param s The Evas_Smart to get the usage count of
5219 * @return The number of uses of the smart instance
5221 * This function tells you how many more uses of the smart instance are in
5222 * existence. This should be used before freeing/clearing any of the
5223 * Evas_Smart_Class that was used to create the smart instance. The smart
5224 * instance will refer to data in the Evas_Smart_Class used to create it and
5225 * thus you cannot remove the original data until all users of it are gone.
5226 * When the usage count goes to 0, you can evas_smart_free() the smart
5227 * instance @p s and remove from memory any of the Evas_Smart_Class that
5228 * was used to create the smart instance, if you desire. Removing it from
5229 * memory without doing this will cause problems (crashes, undefined
5230 * behavior etc. etc.), so either never remove the original
5231 * Evas_Smart_Class data from memory (have it be a constant structure and
5232 * data), or use this API call and be very careful.
5234 EAPI int evas_smart_usage_get(const Evas_Smart *s);
5237 * @def evas_smart_class_inherit
5238 * Easy to use version of evas_smart_class_inherit_full().
5240 * This version will use sizeof(parent_sc), copying everything.
5242 * @param sc child class, will have methods copied from @a parent_sc
5243 * @param parent_sc parent class, will provide contents to be copied.
5244 * @return 1 on success, 0 on failure.
5245 * @ingroup Evas_Smart_Group
5247 #define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, (Evas_Smart_Class *)parent_sc, sizeof(*parent_sc))
5253 * @defgroup Evas_Smart_Object_Group Smart Object Functions
5256 * Functions dealing with Evas smart objects (instances).
5258 * Smart objects are groupings of primitive Evas objects that behave
5259 * as a cohesive group. For instance, a file manager icon may be a
5260 * smart object composed of an image object, a text label and two
5261 * rectangles that appear behind the image and text when the icon is
5262 * selected. As a smart object, the normal Evas object API could be
5263 * used on the icon object.
5265 * Besides that, generally smart objects implement a <b>specific
5266 * API</b>, so that users interact with its own custom features. The
5267 * API takes form of explicit exported functions one may call and
5268 * <b>smart callbacks</b>.
5270 * @section Evas_Smart_Object_Group_Callbacks Smart events and callbacks
5272 * Smart objects can elect events (smart events, from now on) occurring
5273 * inside of them to be reported back to their users via callback
5274 * functions (smart callbacks). This way, you can extend Evas' own
5275 * object events. They are defined by an <b>event string</b>, which
5276 * identifies them uniquely. There's also a function prototype
5277 * definition for the callback functions: #Evas_Smart_Cb.
5279 * When defining an #Evas_Smart_Class, smart object implementors are
5280 * strongly encouraged to properly set the Evas_Smart_Class::callbacks
5281 * callbacks description array, so that the users of the smart object
5282 * can have introspection on its events API <b>at run time</b>.
5284 * See some @ref Example_Evas_Smart_Objects examples of this group
5287 * @see @ref Evas_Smart_Group for class definitions.
5291 * @addtogroup Evas_Smart_Object_Group
5297 * Registers an object type and its associated class. LEGACY MECHANISM SUPPORT.
5299 * This function is invoked in the class constructor of smart classes. It will
5300 * add the type and the class into a hash table that will then be used to check
5301 * the type of an object.
5302 * This function has been implemented to support legacy mechanism that checks
5303 * objects types by name.
5304 * USE IT ONLY FOR LEGACY SUPPORT.
5305 * Otherwise, it is HIGHLY recommended to use eo_isa.
5307 * @param type The type (name string) to add.
5308 * @param klass The class to associate to the type.
5312 * @ingroup Evas_Smart_Object_Group
5314 EAPI void evas_smart_legacy_type_register(const char *type, const Eo_Class *klass) EINA_ARG_NONNULL(1, 2);
5322 * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
5324 * Clipped smart object is a base to construct other smart objects
5325 * based on the concept of having an internal clipper that is applied
5326 * to all children objects. This clipper will control the visibility,
5327 * clipping and color of sibling objects (remember that the clipping
5328 * is recursive, and clipper color modulates the color of its
5329 * clippees). By default, this base will also move children relatively
5330 * to the parent, and delete them when parent is deleted. In other
5331 * words, it is the base for simple object grouping.
5333 * See some @ref Example_Evas_Smart_Objects examples of this group
5336 * @see evas_object_smart_clipped_smart_set()
5338 * @ingroup Evas_Smart_Object_Group
5344 * Every subclass should provide this at the beginning of their own
5345 * data set with evas_object_smart_data_set().
5347 typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
5348 struct _Evas_Object_Smart_Clipped_Data
5350 Evas_Object *clipper;
5355 * Set a given smart class' callbacks so it implements the <b>clipped smart
5356 * object </b>'s interface.
5358 * @param sc The smart class handle to operate on
5360 * This call will assign all the required methods of the @p sc
5361 * #Evas_Smart_Class instance to the implementations set for clipped
5362 * smart objects. If one wants to subclass it, call this function
5363 * and then override desired values. If one wants to call any original
5364 * method, save it somewhere. Example:
5367 * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
5369 * static void my_class_smart_add(Evas_Object *o)
5372 * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
5376 * Evas_Smart_Class *my_class_new(void)
5378 * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
5379 * if (!parent_sc.name)
5381 * evas_object_smart_clipped_smart_set(&sc);
5383 * sc.add = my_class_smart_add;
5389 * Default behavior for each of #Evas_Smart_Class functions on a
5390 * clipped smart object are:
5391 * - @c add: creates a hidden clipper with infinite size, to clip
5392 * any incoming members;
5393 * - @c del: delete all children objects;
5394 * - @c move: move all objects relative relatively;
5395 * - @c resize: <b>not defined</b>;
5396 * - @c show: if there are children objects, show clipper;
5397 * - @c hide: hides clipper;
5398 * - @c color_set: set the color of clipper;
5399 * - @c clip_set: set clipper of clipper;
5400 * - @c clip_unset: unset the clipper of clipper;
5402 * @note There are other means of assigning parent smart classes to
5403 * child ones, like the #EVAS_SMART_SUBCLASS_NEW macro or the
5404 * evas_smart_class_inherit_full() function.
5406 EAPI void evas_object_smart_clipped_smart_set(Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
5409 * Get a pointer to the <b>clipped smart object's</b> class, to use
5410 * for proper inheritance
5412 * @see #Evas_Smart_Object_Clipped for more information on this smart
5415 EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get(void) EINA_CONST;
5421 * @defgroup Evas_Object_Box Box Smart Object
5423 * A box is a convenience smart object that packs children inside it
5424 * in @b sequence, using a layouting function specified by the
5425 * user. There are a couple of pre-made layouting functions <b>built-in
5426 * in Evas</b>, all of them using children size hints to define their
5427 * size and alignment inside their cell space.
5429 * Examples on this smart object's usage:
5430 * - @ref Example_Evas_Box
5431 * - @ref Example_Evas_Size_Hints
5433 * @see @ref Evas_Object_Group_Size_Hints
5435 * @ingroup Evas_Smart_Object_Group
5441 * @typedef Evas_Object_Box_Api
5443 * Smart class extension, providing extra box object requirements.
5445 * @ingroup Evas_Object_Box
5447 typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
5450 * @typedef Evas_Object_Box_Data
5452 * Smart object instance data, providing box object requirements.
5454 * @ingroup Evas_Object_Box
5456 typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
5459 * @typedef Evas_Object_Box_Option
5461 * The base structure for a box option. Box options are a way of
5462 * extending box items properties, which will be taken into account
5463 * for layouting decisions. The box layouting functions provided by
5464 * Evas will only rely on objects' canonical size hints to layout
5465 * them, so the basic box option has @b no (custom) property set.
5467 * Users creating their own layouts, but not depending on extra child
5468 * items' properties, would be fine just using
5469 * evas_object_box_layout_set(). But if one desires a layout depending
5470 * on extra child properties, he/she has to @b subclass the box smart
5471 * object. Thus, by using evas_object_box_smart_class_get() and
5472 * evas_object_box_smart_set(), the @c option_new() and @c
5473 * option_free() smart class functions should be properly
5474 * redefined/extended.
5476 * Object properties are bound to an integer identifier and must have
5477 * a name string. Their values are open to any data. See the API on
5478 * option properties for more details.
5480 * @ingroup Evas_Object_Box
5482 typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
5485 * @typedef Evas_Object_Box_Layout
5487 * Function signature for an Evas box object layouting routine. By
5488 * @a o it will be passed the box object in question, by @a priv it will
5489 * be passed the box's internal data and, by @a user_data, it will be
5490 * passed any custom data one could have set to a given box layouting
5491 * function, with evas_object_box_layout_set().
5493 * @ingroup Evas_Object_Box
5495 typedef void (*Evas_Object_Box_Layout)(Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
5498 * @def EVAS_OBJECT_BOX_API_VERSION
5500 * Current version for Evas box object smart class, a value which goes
5501 * to _Evas_Object_Box_Api::version.
5503 * @ingroup Evas_Object_Box
5505 #define EVAS_OBJECT_BOX_API_VERSION 1
5508 * @struct _Evas_Object_Box_Api
5510 * This structure should be used by any smart class inheriting from
5511 * the box's one, to provide custom box behavior which could not be
5512 * achieved only by providing a layout function, with
5513 * evas_object_box_layout_set().
5515 * @extends Evas_Smart_Class
5516 * @ingroup Evas_Object_Box
5518 struct _Evas_Object_Box_Api
5520 Evas_Smart_Class base; /**< Base smart class struct, need for all smart objects */
5521 int version; /**< Version of this smart class definition */
5522 Evas_Object_Box_Option *(*append)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to append child elements in boxes */
5523 Evas_Object_Box_Option *(*prepend)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to prepend child elements in boxes */
5524 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 */
5525 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 */
5526 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 */
5527 Evas_Object *(*remove)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to remove a child element from boxes */
5528 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 */
5529 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 */
5530 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 */
5531 const char *(*property_name_get)(const Evas_Object * o, int property); /**< Smart function to get the name of a custom property of box children */
5532 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 */
5533 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 */
5534 void (*option_free)(Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt); /**< Smart function to delete a box option struct */
5538 * @def EVAS_OBJECT_BOX_API_INIT
5540 * Initializer for a whole #Evas_Object_Box_Api structure, with
5541 * @c NULL values on its specific fields.
5543 * @param smart_class_init initializer to use for the base field
5544 * (#Evas_Smart_Class).
5546 * @see EVAS_SMART_CLASS_INIT_NULL
5547 * @see EVAS_SMART_CLASS_INIT_VERSION
5548 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
5549 * @see EVAS_OBJECT_BOX_API_INIT_NULL
5550 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
5551 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
5552 * @ingroup Evas_Object_Box
5554 #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}
5557 * @def EVAS_OBJECT_BOX_API_INIT_NULL
5559 * Initializer to zero out a whole #Evas_Object_Box_Api structure.
5561 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
5562 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
5563 * @see EVAS_OBJECT_BOX_API_INIT
5564 * @ingroup Evas_Object_Box
5566 #define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
5569 * @def EVAS_OBJECT_BOX_API_INIT_VERSION
5571 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
5572 * set a specific version on it.
5574 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will set
5575 * the version field of #Evas_Smart_Class (base field) to the latest
5576 * #EVAS_SMART_CLASS_VERSION.
5578 * @see EVAS_OBJECT_BOX_API_INIT_NULL
5579 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
5580 * @see EVAS_OBJECT_BOX_API_INIT
5581 * @ingroup Evas_Object_Box
5583 #define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
5586 * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
5588 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
5589 * set its name and version.
5591 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will also
5592 * set the version field of #Evas_Smart_Class (base field) to the
5593 * latest #EVAS_SMART_CLASS_VERSION and name it to the specific value.
5595 * It will keep a reference to the name field as a <c>const char *</c>,
5596 * i.e., the name must be available while the structure is
5597 * used (hint: static or global variable!) and must not be modified.
5599 * @see EVAS_OBJECT_BOX_API_INIT_NULL
5600 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
5601 * @see EVAS_OBJECT_BOX_API_INIT
5602 * @ingroup Evas_Object_Box
5604 #define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
5607 * @struct _Evas_Object_Box_Data
5609 * This structure augments clipped smart object's instance data,
5610 * providing extra members required by generic box implementation. If
5611 * a subclass inherits from #Evas_Object_Box_Api, then it may augment
5612 * #Evas_Object_Box_Data to fit its own needs.
5614 * @extends Evas_Object_Smart_Clipped_Data
5615 * @ingroup Evas_Object_Box
5617 struct _Evas_Object_Box_Data
5619 Evas_Object_Smart_Clipped_Data base;
5620 const Evas_Object_Box_Api *api;
5629 Eina_List *children;
5632 Evas_Object_Box_Layout cb;
5634 void (*free_data)(void *data);
5636 Eina_Bool layouting : 1;
5637 Eina_Bool children_changed : 1;
5640 struct _Evas_Object_Box_Option
5642 Evas_Object *obj; /**< Pointer to the box child object, itself */
5643 Eina_Bool max_reached : 1;
5644 Eina_Bool min_reached : 1;
5645 Evas_Coord alloc_size;
5646 }; /**< #Evas_Object_Box_Option struct fields */
5649 * @brief Set the default box @a api struct (Evas_Object_Box_Api)
5650 * with the default values. May be used to extend that API.
5652 * @if MOBILE @since_tizen 2.3
5653 * @elseif WEARABLE @since_tizen 2.3.1
5656 * @param[in] api The box API struct to set back, most probably with
5657 * overridden fields (on class extensions scenarios)
5659 EAPI void evas_object_box_smart_set(Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
5662 * @brief Get the Evas box smart class, for inheritance purposes.
5664 * @if MOBILE @since_tizen 2.3
5665 * @elseif WEARABLE @since_tizen 2.3.1
5668 * @return the (canonical) Evas box smart class.
5670 * @remark The returned value is @b not to be modified, just use it as your
5673 EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get(void) EINA_CONST;
5680 * @defgroup Evas_Object_Table Table Smart Object.
5682 * Convenience smart object that packs children using a tabular
5683 * layout using children size hints to define their size and
5684 * alignment inside their cell space.
5686 * @ref tutorial_table shows how to use this Evas_Object.
5688 * @see @ref Evas_Object_Group_Size_Hints
5690 * @ingroup Evas_Smart_Object_Group
5695 * @defgroup Evas_Object_Grid Grid Smart Object.
5697 * Convenience smart object that packs children under a regular grid
5698 * layout, using their virtual grid location and size to determine
5699 * children's positions inside the grid object's area.
5701 * @ingroup Evas_Smart_Object_Group
5707 * @defgroup Evas_Cserve Shared Image Cache Server
5710 * Evas has an (optional) module which provides client-server
5711 * infrastructure to <b>share bitmaps across multiple processes</b>,
5712 * saving data and processing power.
5714 * Be warned that it @b doesn't work when <b>threaded image
5715 * preloading</b> is enabled for Evas, though.
5719 typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
5720 typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
5721 typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
5722 typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
5725 * Statistics about the server that shares cached bitmaps.
5726 * @ingroup Evas_Cserve
5728 struct _Evas_Cserve_Stats
5730 int saved_memory; /**< current amount of saved memory, in bytes */
5731 int wasted_memory; /**< current amount of wasted memory, in bytes */
5732 int saved_memory_peak; /**< peak amount of saved memory, in bytes */
5733 int wasted_memory_peak; /**< peak amount of wasted memory, in bytes */
5734 double saved_time_image_header_load; /**< time, in seconds, saved in header loads by sharing cached loads instead */
5735 double saved_time_image_data_load; /**< time, in seconds, saved in data loads by sharing cached loads instead */
5739 * A handle of a cache of images shared by a server.
5740 * @ingroup Evas_Cserve
5742 struct _Evas_Cserve_Image_Cache
5753 * A handle to an image shared by a server.
5754 * @ingroup Evas_Cserve
5756 struct _Evas_Cserve_Image
5758 const char *file, *key;
5760 time_t file_mod_time;
5761 time_t file_checked_time;
5765 int memory_footprint;
5766 double head_load_time;
5767 double data_load_time;
5768 Eina_Bool alpha : 1;
5769 Eina_Bool data_loaded : 1;
5770 Eina_Bool active : 1;
5772 Eina_Bool useless : 1;
5776 * Configuration that controls the server that shares cached bitmaps.
5777 * @ingroup Evas_Cserve
5779 struct _Evas_Cserve_Config
5781 int cache_max_usage;
5782 int cache_item_timeout;
5783 int cache_item_timeout_check;
5787 * Retrieves if the system wants to share bitmaps using the server.
5788 * @return @c EINA_TRUE if it wants, @c EINA_FALSE otherwise.
5789 * @ingroup Evas_Cserve
5791 EAPI Eina_Bool evas_cserve_want_get(void) EINA_WARN_UNUSED_RESULT;
5794 * Retrieves if the system is connected to the server used to share
5797 * @return @c EINA_TRUE if it's connected, @c EINA_FALSE otherwise.
5798 * @ingroup Evas_Cserve
5800 EAPI Eina_Bool evas_cserve_connected_get(void) EINA_WARN_UNUSED_RESULT;
5803 * Retrieves statistics from a running bitmap sharing server.
5804 * @param stats pointer to structure to fill with statistics about the
5805 * bitmap cache server.
5807 * @return @c EINA_TRUE if @p stats were filled with data,
5808 * @c EINA_FALSE otherwise (when @p stats is untouched)
5809 * @ingroup Evas_Cserve
5811 EAPI Eina_Bool evas_cserve_stats_get(Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
5814 * Completely discard/clean a given images cache, thus re-setting it.
5816 * @param cache A handle to the given images cache.
5818 EAPI void evas_cserve_image_cache_contents_clean(Evas_Cserve_Image_Cache *cache);
5821 * Retrieves the current configuration of the Evas image caching
5824 * @param config where to store current image caching server's
5827 * @return @c EINA_TRUE if @p config was filled with data,
5828 * @c EINA_FALSE otherwise (when @p config is untouched)
5830 * The fields of @p config will be altered to reflect the current
5831 * configuration's values.
5833 * @see evas_cserve_config_set()
5835 * @ingroup Evas_Cserve
5837 EAPI Eina_Bool evas_cserve_config_get(Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
5840 * Changes the configurations of the Evas image caching server.
5842 * @param config A bitmap cache configuration handle with fields set
5843 * to desired configuration values.
5844 * @return @c EINA_TRUE if @p config was successfully applied,
5845 * @c EINA_FALSE otherwise.
5847 * @see evas_cserve_config_get()
5849 * @ingroup Evas_Cserve
5851 EAPI Eina_Bool evas_cserve_config_set(const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
5854 * Force the system to disconnect from the bitmap caching server.
5856 * @ingroup Evas_Cserve
5858 EAPI void evas_cserve_disconnect(void);
5865 * @defgroup Evas_Utils General Utilities
5868 * Some functions that are handy but are not specific of canvas or
5875 * @brief Converts the given Evas image load error code into a string
5876 * describing it in english.
5878 * @if MOBILE @since_tizen 2.3
5879 * @elseif WEARABLE @since_tizen 2.3.1
5882 * @param[in] error the error code, a value in ::Evas_Load_Error.
5883 * @return Always returns a valid string. If the given @p error is not
5884 * supported, <code>Unknown error</code> is returned.
5886 * @remark Mostly evas_object_image_file_set() would be the function setting
5887 * that error value afterwards, but also evas_object_image_load(),
5888 * evas_object_image_save(), evas_object_image_data_get(),
5889 * evas_object_image_data_convert(), evas_object_image_pixels_import()
5890 * and evas_object_image_is_inside(). This function is meant to be
5891 * used in conjunction with evas_object_image_load_error_get(), as in:
5893 * @remark Example code:
5894 * @dontinclude evas-images.c
5896 * @until ecore_main_loop_begin(
5898 * @remark Here, being @c valid_path the path to a valid image and @c
5899 * bogus_path a path to a file which does not exist, the two outputs
5900 * of evas_load_error_str() would be (if no other errors occur):
5901 * <code>No error on load</code> and <code>File (or file path) does
5902 * not exist</code>, respectively. See the full @ref
5903 * Example_Evas_Images example.
5905 * @ingroup Evas_Utils
5907 EAPI const char *evas_load_error_str(Evas_Load_Error error);
5909 /* Evas utility routines for color space conversions */
5910 /* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
5911 /* rgb color space has r,g,b in the range 0 to 255 */
5914 * @brief Convert a given color from HSV to RGB format.
5916 * @if MOBILE @since_tizen 2.3
5917 * @elseif WEARABLE @since_tizen 2.3.1
5920 * @param[in] h The Hue component of the color.
5921 * @param[in] s The Saturation component of the color.
5922 * @param[in] v The Value component of the color.
5923 * @param[out] r The Red component of the color.
5924 * @param[out] g The Green component of the color.
5925 * @param[out] b The Blue component of the color.
5927 * @remark This function converts a given color in HSV color format to RGB
5930 * @ingroup Evas_Utils
5932 EAPI void evas_color_hsv_to_rgb(float h, float s, float v, int *r, int *g, int *b);
5935 * @brief Convert a given color from RGB to HSV format.
5937 * @if MOBILE @since_tizen 2.3
5938 * @elseif WEARABLE @since_tizen 2.3.1
5941 * @param[in] r The Red component of the color.
5942 * @param[in] g The Green component of the color.
5943 * @param[in] b The Blue component of the color.
5944 * @param[out] h The Hue component of the color.
5945 * @param[out] s The Saturation component of the color.
5946 * @param[out] v The Value component of the color.
5948 * @remark This function converts a given color in RGB color format to HSV
5951 * @ingroup Evas_Utils
5953 EAPI void evas_color_rgb_to_hsv(int r, int g, int b, float *h, float *s, float *v);
5955 /* argb color space has a,r,g,b in the range 0 to 255 */
5958 * @brief Pre-multiplies a rgb triplet by an alpha factor.
5960 * @if MOBILE @since_tizen 2.3
5961 * @elseif WEARABLE @since_tizen 2.3.1
5964 * @param[in] a The alpha factor.
5965 * @param[out] r The Red component of the color.
5966 * @param[out] g The Green component of the color.
5967 * @param[out] b The Blue component of the color.
5969 * @remark This function pre-multiplies a given rgb triplet by an alpha
5970 * factor. Alpha factor is used to define transparency.
5972 * @ingroup Evas_Utils
5974 EAPI void evas_color_argb_premul(int a, int *r, int *g, int *b);
5977 * @brief Undo pre-multiplication of a rgb triplet by an alpha factor.
5979 * @if MOBILE @since_tizen 2.3
5980 * @elseif WEARABLE @since_tizen 2.3.1
5983 * @param[in] a The alpha factor.
5984 * @param[out] r The Red component of the color.
5985 * @param[out] g The Green component of the color.
5986 * @param[out] b The Blue component of the color.
5988 * @remark This function undoes pre-multiplication a given rbg triplet by an
5989 * alpha factor. Alpha factor is used to define transparency.
5991 * @see evas_color_argb_premul().
5993 * @ingroup Evas_Utils
5995 EAPI void evas_color_argb_unpremul(int a, int *r, int *g, int *b);
5998 * @brief Pre-multiplies data by an alpha factor.
6000 * @if MOBILE @since_tizen 2.3
6001 * @elseif WEARABLE @since_tizen 2.3.1
6004 * @param[in] data The data value.
6005 * @param[in] len The length value.
6007 * @remark This function pre-multiplies a given data by an alpha
6008 * factor. Alpha factor is used to define transparency.
6010 * @ingroup Evas_Utils
6012 EAPI void evas_data_argb_premul(unsigned int *data, unsigned int len);
6015 * @brief Undo pre-multiplication data by an alpha factor.
6017 * @if MOBILE @since_tizen 2.3
6018 * @elseif WEARABLE @since_tizen 2.3.1
6021 * @param[in] data The data value.
6022 * @param[in] len The length value.
6024 * @remark This function undoes pre-multiplication of a given data by an alpha
6025 * factor. Alpha factor is used to define transparency.
6027 * @ingroup Evas_Utils
6029 EAPI void evas_data_argb_unpremul(unsigned int *data, unsigned int len);
6031 /* string and font handling */
6034 * @brief Gets the next character in the string
6036 * @if MOBILE @since_tizen 2.3
6037 * @elseif WEARABLE @since_tizen 2.3.1
6040 * @remark Given the UTF-8 string in @p str, and starting byte position in @p pos,
6041 * this function will place in @p decoded the decoded code point at @p pos
6042 * and return the byte index for the next character in the string.
6044 * @remark The only boundary check done is that @p pos must be >= 0. Other than that,
6045 * no checks are performed, so passing an index value that's not within the
6046 * length of the string will result in undefined behavior.
6048 * @param[in] str The UTF-8 string
6049 * @param[in] pos The byte index where to start
6050 * @param[out] decoded Address where to store the decoded code point. Optional.
6052 * @return The byte index of the next character
6054 * @ingroup Evas_Utils
6056 EAPI int evas_string_char_next_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
6059 * @brief Gets the previous character in the string
6061 * @if MOBILE @since_tizen 2.3
6062 * @elseif WEARABLE @since_tizen 2.3.1
6065 * @remark Given the UTF-8 string in @p str, and starting byte position in @p pos,
6066 * this function will place in @p decoded the decoded code point at @p pos
6067 * and return the byte index for the previous character in the string.
6069 * @remark The only boundary check done is that @p pos must be >= 1. Other than that,
6070 * no checks are performed, so passing an index value that's not within the
6071 * length of the string will result in undefined behavior.
6073 * @param[in] str The UTF-8 string
6074 * @param[in] pos The byte index where to start
6075 * @param[out] decoded Address where to store the decoded code point. Optional.
6077 * @return The byte index of the previous character
6079 * @ingroup Evas_Utils
6081 EAPI int evas_string_char_prev_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
6084 * @brief Get the length in characters of the string.
6085 * @param[in] str The string to get the length of.
6087 * @if MOBILE @since_tizen 2.3
6088 * @elseif WEARABLE @since_tizen 2.3.1
6091 * @return The length in characters (not bytes)
6092 * @ingroup Evas_Utils
6094 EAPI int evas_string_char_len_get(const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6101 * @defgroup Evas_Keys Key Input Functions
6103 * Functions which feed key events to the canvas.
6105 * As explained in @ref intro_not_evas, Evas is @b not aware of input
6106 * systems at all. Then, the user, if using it crudely (evas_new()),
6107 * will have to feed it with input events, so that it can react
6108 * somehow. If, however, the user creates a canvas by means of the
6109 * Ecore_Evas wrapper, it will automatically bind the chosen display
6110 * engine's input events to the canvas, for you.
6112 * This group presents the functions dealing with the feeding of key
6113 * events to the canvas. On most of them, one has to reference a given
6114 * key by a name (<code>keyname</code> argument). Those are
6115 * <b>platform dependent</b> symbolic names for the keys. Sometimes
6116 * you'll get the right <code>keyname</code> by simply using an ASCII
6117 * value of the key name, but it won't be like that always.
6119 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
6120 * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
6121 * to your display engine's documentation when using evas through an
6122 * Ecore helper wrapper when you need the <code>keyname</code>s.
6125 * @dontinclude evas-events.c
6126 * @skip mods = evas_key_modifier_get(evas);
6129 * All the other @c evas_key functions behave on the same manner. See
6130 * the full @ref Example_Evas_Events example.
6132 * @ingroup Evas_Canvas
6136 * @addtogroup Evas_Keys
6140 * @brief Checks the state of a given modifier key, at the time of the
6141 * call. If the modifier is set, such as shift being pressed, this
6142 * function returns @c Eina_True.
6144 * @if MOBILE @since_tizen 2.3
6145 * @elseif WEARABLE @since_tizen 2.3.1
6148 * @param[in] m The current modifiers set, as returned by
6149 * evas_key_modifier_get().
6150 * @param[in] keyname The name of the modifier key to check status for.
6152 * @return @c Eina_True if the modifier key named @p keyname is on, @c
6153 * Eina_False otherwise.
6155 * @see evas_key_modifier_add
6156 * @see evas_key_modifier_del
6157 * @see evas_key_modifier_get
6158 * @see evas_key_modifier_on
6159 * @see evas_key_modifier_off
6161 EAPI Eina_Bool evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
6164 * @brief Checks the state of a given lock key, at the time of the call. If
6165 * the lock is set, such as caps lock, this function returns @c
6168 * @if MOBILE @since_tizen 2.3
6169 * @elseif WEARABLE @since_tizen 2.3.1
6172 * @param[in] l The current locks set, as returned by evas_key_lock_get().
6173 * @param[in] keyname The name of the lock key to check status for.
6175 * @return @c Eina_True if the @p keyname lock key is set, @c
6176 * Eina_False otherwise.
6178 * @see evas_key_lock_get
6179 * @see evas_key_lock_add
6180 * @see evas_key_lock_del
6181 * @see evas_key_lock_on
6182 * @see evas_key_lock_off
6184 EAPI Eina_Bool evas_key_lock_is_set(const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
6192 * @defgroup Evas_Touch_Point_List Touch Point List Functions
6194 * Functions to get information of touched points in the Evas.
6196 * Evas maintains list of touched points on the canvas. Each point has
6197 * its co-ordinates, id and state. You can get the number of touched
6198 * points and information of each point using evas_touch_point_list
6201 * @ingroup Evas_Canvas
6205 * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
6206 * @ingroup Evas_Canvas
6208 * @brief This group provides functions that deal with the status of the pointer (mouse cursor).
6213 typedef Eo Evas_Out;
6215 #define _EVAS_OUT_EO_CLASS_TYPE
6218 * @ingroup Evas_Font_Group
6225 * @defgroup Evas_Font_Path_Group Font Path Functions
6227 * Functions that edit the paths being used to load fonts.
6229 * @ingroup Evas_Font_Group
6233 * Removes all font paths loaded into memory by evas_font_path_app_* APIs
6234 * for the application.
6235 * @ingroup Evas_Font_Path_Group
6238 EAPI void evas_font_path_global_clear(void);
6241 * Appends a font path to the list of font paths used by the application.
6242 * @param path The new font path.
6243 * @ingroup Evas_Font_Path_Group
6246 EAPI void evas_font_path_global_append(const char *path) EINA_ARG_NONNULL(1);
6249 * Prepends a font path to the list of font paths used by the application.
6250 * @param path The new font path.
6251 * @ingroup Evas_Font_Path_Group
6254 EAPI void evas_font_path_global_prepend(const char *path) EINA_ARG_NONNULL(1);
6257 * Retrieves the list of font paths used by the application.
6258 * @return The list of font paths used.
6259 * @ingroup Evas_Font_Path_Group
6262 EAPI const Eina_List *evas_font_path_global_list(void) EINA_WARN_UNUSED_RESULT;