2 # error You shall not include this header directly
5 #define EVAS_VERSION_MAJOR EFL_VERSION_MAJOR
6 #define EVAS_VERSION_MINOR EFL_VERSION_MINOR
8 typedef struct _Evas_Version
16 EAPI extern Evas_Version * evas_version;
20 * @brief These routines are used for Evas library interaction.
22 * @todo check boolean return values and convert to Eina_Bool
23 * @todo change all api to use EINA_SAFETY_*
24 * @todo finish api documentation
27 /* BiDi exposed stuff */
29 typedef enum _Evas_BiDi_Direction
31 EVAS_BIDI_DIRECTION_NATURAL,
32 EVAS_BIDI_DIRECTION_NEUTRAL = EVAS_BIDI_DIRECTION_NATURAL,
33 EVAS_BIDI_DIRECTION_LTR,
34 EVAS_BIDI_DIRECTION_RTL
35 } Evas_BiDi_Direction;
38 * Identifier of callbacks to be set for Evas canvases or Evas
41 * The following figure illustrates some Evas callbacks:
43 * @image html evas-callbacks.png
44 * @image rtf evas-callbacks.png
45 * @image latex evas-callbacks.eps
47 * @see evas_object_event_callback_add()
48 * @see evas_event_callback_add()
50 typedef enum _Evas_Callback_Type
53 * The following events are only for use with Evas objects, with
54 * evas_object_event_callback_add():
56 EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */
57 EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
58 EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
59 EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
60 EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
61 EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
62 EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
63 EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
64 EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
65 EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
66 EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
67 EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
68 EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
69 EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
70 EVAS_CALLBACK_SHOW, /**< Show Event */
71 EVAS_CALLBACK_HIDE, /**< Hide Event */
72 EVAS_CALLBACK_MOVE, /**< Move Event */
73 EVAS_CALLBACK_RESIZE, /**< Resize Event */
74 EVAS_CALLBACK_RESTACK, /**< Restack Event */
75 EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
76 EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
77 EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
78 EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */
81 * The following events are only for use with Evas canvases, with
82 * evas_event_callback_add():
84 EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
85 EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
86 EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */
87 EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
88 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
89 EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
92 * More Evas object event types - see evas_object_event_callback_add():
94 EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanism in Evas that throw out original image data) */
96 EVAS_CALLBACK_RENDER_PRE, /**< Called just before rendering starts on the canvas target @since 1.2 */
97 EVAS_CALLBACK_RENDER_POST, /**< Called just after rendering stops on the canvas target @since 1.2 */
99 EVAS_CALLBACK_IMAGE_RESIZE, /**< Image size is changed @since 1.8 */
100 EVAS_CALLBACK_DEVICE_CHANGED, /**< Devices added, removed or changed on canvas @since 1.8 */
101 EVAS_CALLBACK_LAST /**< kept as last element/sentinel -- not really an event */
102 } Evas_Callback_Type; /**< The types of events triggering a callback */
105 * @def EVAS_CALLBACK_PRIORITY_BEFORE
106 * Slightly more prioritized than default.
109 #define EVAS_CALLBACK_PRIORITY_BEFORE -100
111 * @def EVAS_CALLBACK_PRIORITY_DEFAULT
112 * Default callback priority level
115 #define EVAS_CALLBACK_PRIORITY_DEFAULT 0
117 * @def EVAS_CALLBACK_PRIORITY_AFTER
118 * Slightly less prioritized than default.
121 #define EVAS_CALLBACK_PRIORITY_AFTER 100
124 * @typedef Evas_Callback_Priority
126 * Callback priority value. Range is -32k - 32k. The lower the number, the
127 * bigger the priority.
129 * @see EVAS_CALLBACK_PRIORITY_AFTER
130 * @see EVAS_CALLBACK_PRIORITY_BEFORE
131 * @see EVAS_CALLBACK_PRIORITY_DEFAULT
135 typedef Eo_Callback_Priority Evas_Callback_Priority;
138 * Flags for Mouse Button events
140 typedef enum _Evas_Button_Flags
142 EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
143 EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< This mouse button press was the 2nd press of a double click */
144 EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< This mouse button press was the 3rd press of a triple click */
145 } Evas_Button_Flags; /**< Flags for Mouse Button events */
150 typedef enum _Evas_Event_Flags
152 EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
153 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 */
154 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 */
155 } Evas_Event_Flags; /**< Flags for Events */
158 * State of Evas_Coord_Touch_Point
160 typedef enum _Evas_Touch_Point_State
162 EVAS_TOUCH_POINT_DOWN, /**< Touch point is pressed down */
163 EVAS_TOUCH_POINT_UP, /**< Touch point is released */
164 EVAS_TOUCH_POINT_MOVE, /**< Touch point is moved */
165 EVAS_TOUCH_POINT_STILL, /**< Touch point is not moved after pressed */
166 EVAS_TOUCH_POINT_CANCEL /**< Touch point is cancelled */
167 } Evas_Touch_Point_State;
170 * Flags for Font Hinting
171 * @ingroup Evas_Font_Group
173 typedef enum _Evas_Font_Hinting_Flags
175 EVAS_FONT_HINTING_NONE, /**< No font hinting */
176 EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
177 EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
178 } Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */
181 * Colorspaces for pixel data supported by Evas
182 * @ingroup Evas_Object_Image
184 typedef enum _Evas_Colorspace
186 EVAS_COLORSPACE_ARGB8888, /**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */
187 /* these are not currently supported - but planned for the future */
188 EVAS_COLORSPACE_YCBCR422P601_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */
189 EVAS_COLORSPACE_YCBCR422P709_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-709 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */
190 EVAS_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */
191 EVAS_COLORSPACE_GRY8, /**< 8bit grayscale */
192 EVAS_COLORSPACE_YCBCR422601_PL, /**< YCbCr 4:2:2, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to line of Y,Cb,Y,Cr bytes */
193 EVAS_COLORSPACE_YCBCR420NV12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb,Cr rows. */
194 EVAS_COLORSPACE_YCBCR420TM12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of tiled row pointer, pointing to the Y rows, then the Cb,Cr rows. */
195 } Evas_Colorspace; /**< Colorspaces for pixel data supported by Evas */
198 * How to pack items into cells in a table.
199 * @ingroup Evas_Object_Table
201 * @see evas_object_table_homogeneous_set() for an explanation of the function of
204 typedef enum _Evas_Object_Table_Homogeneous_Mode
206 EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0,
207 EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1,
208 EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2
209 } Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode. */
211 typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< A generic rectangle handle */
212 typedef struct _Evas_Point Evas_Point; /**< integer point */
214 typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */
215 typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */
217 typedef struct _Evas_Coord_Size Evas_Coord_Size; /** <Evas_Coord size @since 1.8 */
218 typedef struct _Evas_Coord_Precision_Size Evas_Coord_Precision_Size; /** <Evas_Coord size with sub-pixel precision @since 1.8 */
220 typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */
221 typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */
224 * @typedef Evas_Smart_Class
226 * A smart object's @b base class definition
228 * @ingroup Evas_Smart_Group
230 typedef struct _Evas_Smart_Class Evas_Smart_Class;
233 * @typedef Evas_Smart_Interface
235 * A smart object's @b base interface definition
237 * An Evas interface is exactly like the OO-concept: an 'contract' or
238 * API a given object is declared to support. A smart object may have
239 * more than one interface, thus extending the behavior it gets from
244 * @ingroup Evas_Smart_Group
246 typedef struct _Evas_Smart_Interface Evas_Smart_Interface;
249 * @typedef Evas_Smart_Cb_Description
251 * A smart object callback description, used to provide introspection
253 * @ingroup Evas_Smart_Group
255 typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
260 * An opaque handle to map points
262 * @see evas_map_new()
263 * @see evas_map_free()
264 * @see evas_map_dup()
266 * @ingroup Evas_Object_Group_Map
268 typedef struct _Evas_Map Evas_Map;
273 * An opaque handle to an Evas canvas.
278 * @ingroup Evas_Canvas
283 * @typedef Evas_Public_Data
284 * Public data for an Evas.
285 * @ingroup Evas_Canvas
287 typedef struct _Evas_Public_Data Evas_Public_Data;
290 * @typedef Evas_Object
291 * An Evas Object handle.
292 * @ingroup Evas_Object_Group
294 typedef Eo Evas_Object;
296 typedef void Evas_Performance; /**< An Evas Performance handle */
297 typedef struct _Evas_Modifier Evas_Modifier; /**< An opaque type containing information on which modifier keys are registered in an Evas canvas */
298 typedef struct _Evas_Lock Evas_Lock; /**< An opaque type containing information on which lock keys are registered in an Evas canvas */
299 typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
300 typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< A generic datatype for engine specific native surface information */
303 * @typedef Evas_Video_Surface
305 * A generic datatype for video specific surface information
306 * @see evas_object_image_video_surface_set
307 * @see evas_object_image_video_surface_get
310 typedef struct _Evas_Video_Surface Evas_Video_Surface;
312 typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */
314 typedef int Evas_Coord;
315 typedef int Evas_Font_Size;
316 typedef int Evas_Angle;
318 struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */
320 Evas_Coord x; /**< top-left x co-ordinate of rectangle */
321 Evas_Coord y; /**< top-left y co-ordinate of rectangle */
322 Evas_Coord w; /**< width of rectangle */
323 Evas_Coord h; /**< height of rectangle */
326 struct _Evas_Coord_Point
328 Evas_Coord x; /**< x co-ordinate */
329 Evas_Coord y; /**< y co-ordinate */
332 struct _Evas_Coord_Size
334 Evas_Coord w; /**< width */
335 Evas_Coord h; /**< height */
338 struct _Evas_Coord_Precision_Size
340 Evas_Coord w; /** < width */
341 Evas_Coord h; /** < height */
342 double wsub; /** < subpixel precision for width */
343 double ysub; /** < subpixel precision for height */
346 struct _Evas_Coord_Precision_Point
357 struct _Evas_Position
360 Evas_Coord_Point canvas; /**< position on the canvas */
363 struct _Evas_Precision_Position
366 Evas_Coord_Precision_Point canvas;
369 typedef enum _Evas_Aspect_Control
371 EVAS_ASPECT_CONTROL_NONE = 0, /**< Preference on scaling unset */
372 EVAS_ASPECT_CONTROL_NEITHER = 1, /**< Same effect as unset preference on scaling */
373 EVAS_ASPECT_CONTROL_HORIZONTAL = 2, /**< Use all horizontal container space to place an object, using the given aspect */
374 EVAS_ASPECT_CONTROL_VERTICAL = 3, /**< Use all vertical container space to place an object, using the given aspect */
375 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 */
376 } Evas_Aspect_Control; /**< Aspect types/policies for scaling size hints, used for evas_object_size_hint_aspect_set() */
378 typedef enum _Evas_Display_Mode
380 EVAS_DISPLAY_MODE_NONE = 0, /**<Default mode */
381 EVAS_DISPLAY_MODE_COMPRESS = 1, /**< Use this mode when you want to give compress display mode hint to an object */
382 EVAS_DISPLAY_MODE_EXPAND = 2, /**< Use this mode when you want to give expand display mode hint to an object */
383 EVAS_DISPLAY_MODE_DONT_CHANGE = 3 /**< Use this mode when an object should not change its display mode */
384 } Evas_Display_Mode; /**< object's display mode type related with compress/expand or etc mode */
386 typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< A source description of pixels for importing pixels */
387 typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< A generic Evas Engine information structure */
388 typedef struct _Evas_Device Evas_Device; /**< A source device handle - where the event came from */
389 typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
390 typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
391 typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
392 typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
393 typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
394 typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
395 typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
396 typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
397 typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
398 typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
399 typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
400 typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< Event structure for #EVAS_CALLBACK_HOLD event callbacks */
401 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 */
403 typedef enum _Evas_Alloc_Error
405 EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */
406 EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */
407 EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded, but extra memory had to be found by freeing up speculative resources */
408 } Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */
410 typedef enum _Evas_Fill_Spread
412 EVAS_TEXTURE_REFLECT = 0, /**< image fill tiling mode - tiling reflects */
413 EVAS_TEXTURE_REPEAT = 1, /**< tiling repeats */
414 EVAS_TEXTURE_RESTRICT = 2, /**< tiling clamps - range offset ignored */
415 EVAS_TEXTURE_RESTRICT_REFLECT = 3, /**< tiling clamps and any range offset reflects */
416 EVAS_TEXTURE_RESTRICT_REPEAT = 4, /**< tiling clamps and any range offset repeats */
417 EVAS_TEXTURE_PAD = 5 /**< tiling extends with end values */
418 } Evas_Fill_Spread; /**< Fill types used for evas_object_image_fill_spread_set() */
420 typedef enum _Evas_Pixel_Import_Pixel_Format
422 EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
423 EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
424 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 */
425 } Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
427 struct _Evas_Pixel_Import_Source
429 Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
430 int w, h; /**< width and height of source in pixels */
431 void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
434 /* magic version number to know what the native surf struct looks like */
435 #define EVAS_NATIVE_SURFACE_VERSION 2
437 typedef enum _Evas_Native_Surface_Type
439 EVAS_NATIVE_SURFACE_NONE,
440 EVAS_NATIVE_SURFACE_X11,
441 EVAS_NATIVE_SURFACE_OPENGL
442 } Evas_Native_Surface_Type;
444 struct _Evas_Native_Surface
447 Evas_Native_Surface_Type type;
451 void *visual; /**< visual of the pixmap to use (Visual) */
452 unsigned long pixmap; /**< pixmap id to use (Pixmap) */
456 unsigned int texture_id; /**< opengl texture id to use from glGenTextures() */
457 unsigned int framebuffer_id; /**< 0 if not a FBO, FBO id otherwise from glGenFramebuffers() */
458 unsigned int internal_format; /**< same as 'internalFormat' for glTexImage2D() */
459 unsigned int format; /**< same as 'format' for glTexImage2D() */
460 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) */
466 * @def EVAS_VIDEO_SURFACE_VERSION
467 * Magic version number to know what the video surf struct looks like
470 #define EVAS_VIDEO_SURFACE_VERSION 1
472 typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface);
473 typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b);
475 struct _Evas_Video_Surface
479 Evas_Video_Coord_Cb move; /**< Move the video surface to this position */
480 Evas_Video_Coord_Cb resize; /**< Resize the video surface to that size */
481 Evas_Video_Cb show; /**< Show the video overlay surface */
482 Evas_Video_Cb hide; /**< Hide the video overlay surface */
483 Evas_Video_Cb update_pixels; /**< Please update the Evas_Object_Image pixels when called */
489 typedef enum _Evas_Video_Surface_Caps
491 EVAS_VIDEO_SURFACE_MOVE = 1,
492 EVAS_VIDEO_SURFACE_RESIZE = 2,
493 EVAS_VIDEO_SURFACE_CLIP = 4,
494 EVAS_VIDEO_SURFACE_BELOW = 8,
495 EVAS_VIDEO_SURFACE_STACKING_CHECK = 16,
496 EVAS_VIDEO_SURFACE_IGNORE_WINDOW = 32,
497 } Evas_Video_Surface_Caps;
499 #define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
500 #define EVAS_LAYER_MAX 32767 /**< top-most layer number */
502 #define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
503 #define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
504 #define EVAS_TEXT_INVALID -1 /**< Not used for anything */
505 #define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
507 #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() */
508 #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() */
509 #define evas_object_size_hint_fill_set evas_object_size_hint_align_set /**< Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align) */
510 #define evas_object_size_hint_fill_get evas_object_size_hint_align_get /**< Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align) */
511 #define evas_object_size_hint_expand_set evas_object_size_hint_weight_set /**< Convenience macro to make it easier to understand that weight is also used for expand properties */
512 #define evas_object_size_hint_expand_get evas_object_size_hint_weight_get /**< Convenience macro to make it easier to understand that weight is also used for expand properties */
515 * How the object should be rendered to output.
516 * @ingroup Evas_Object_Group_Extras
518 typedef enum _Evas_Render_Op
520 EVAS_RENDER_BLEND = 0, /**< default op: d = d*(1-sa) + s */
521 EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
522 EVAS_RENDER_COPY = 2, /**< d = s */
523 EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
524 EVAS_RENDER_ADD = 4, /* d = d + s */
525 EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
526 EVAS_RENDER_SUB = 6, /**< d = d - s */
527 EVAS_RENDER_SUB_REL = 7, /* d = d - s*da */
528 EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
529 EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
530 EVAS_RENDER_MASK = 10, /**< d = d*sa */
531 EVAS_RENDER_MUL = 11 /**< d = d*s */
532 } Evas_Render_Op; /**< How the object should be rendered to output. */
534 typedef enum _Evas_Border_Fill_Mode
536 EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */
537 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 */
538 EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */
539 } Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */
541 typedef enum _Evas_Engine_Render_Mode
543 EVAS_RENDER_MODE_BLOCKING = 0,
544 EVAS_RENDER_MODE_NONBLOCKING = 1,
545 } Evas_Engine_Render_Mode;
547 typedef enum _Evas_Image_Content_Hint
549 EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
550 EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents will change over time */
551 EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents won't change over time */
552 } Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
554 typedef enum _Evas_Device_Class
556 EVAS_DEVICE_CLASS_NONE, /**< Not a device @since 1.8 */
557 EVAS_DEVICE_CLASS_SEAT, /**< The user/seat (the user themselves) @since 1.8 */
558 EVAS_DEVICE_CLASS_KEYBOARD, /**< A regular keyboard, numberpad or attached buttons @since 1.8 */
559 EVAS_DEVICE_CLASS_MOUSE, /**< A mouse, trackball or touchpad relative motion device @since 1.8 */
560 EVAS_DEVICE_CLASS_TOUCH, /**< A touchscreen with fingers or stylus @since 1.8 */
561 EVAS_DEVICE_CLASS_PEN, /**< A special pen device @since 1.8 */
562 EVAS_DEVICE_CLASS_POINTER, /**< A laser pointer, wii-style or "minority report" pointing device @since 1.8 */
563 EVAS_DEVICE_CLASS_GAMEPAD /**< A gamepad controller or joystick @since 1.8 */
564 } Evas_Device_Class; /**< A general class of device @since 1.8 */
566 typedef enum _Evas_Device_Subclass
568 EVAS_DEVICE_SUBCLASS_NONE, /**< Not a device @since 1.8 */
569 EVAS_DEVICE_SUBCLASS_FINGER, /**< The normal flat of your finger @since 1.8 */
570 EVAS_DEVICE_SUBCLASS_FINGERNAIL, /**< A fingernail @since 1.8 */
571 EVAS_DEVICE_SUBCLASS_KNUCKLE, /**< A Knuckle @since 1.8 */
572 EVAS_DEVICE_SUBCLASS_PALM, /**< The palm of a users hand @since 1.8 */
573 EVAS_DEVICE_SUBCLASS_HAND_SIZE, /**< The side of your hand @since 1.8 */
574 EVAS_DEVICE_SUBCLASS_HAND_FLAT, /**< The flat of your hand @since 1.8 */
575 EVAS_DEVICE_SUBCLASS_PEN_TIP, /**< The tip of a pen @since 1.8 */
576 EVAS_DEVICE_SUBCLASS_TRACKPAD, /**< A trackpad style mouse @since 1.8 */
577 EVAS_DEVICE_SUBCLASS_TRACKPOINT, /**< A trackpoint style mouse @since 1.8 */
578 EVAS_DEVICE_SUBCLASS_TRACKBALL, /**< A trackball style mouse @since 1.8 */
579 } Evas_Device_Subclass; /**< A general class of device @since 1.8 */
581 struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
583 int magic; /**< Magic number */
586 struct _Evas_Event_Mouse_Down /** Mouse button press event */
588 int button; /**< Mouse button number that went down (1 - 32) */
590 Evas_Point output; /**< The X/Y location of the cursor */
591 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
594 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
597 Evas_Button_Flags flags; /**< button flags set during the event */
598 unsigned int timestamp;
599 Evas_Event_Flags event_flags;
601 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
604 struct _Evas_Event_Mouse_Up /** Mouse button release event */
606 int button; /**< Mouse button number that was raised (1 - 32) */
608 Evas_Point output; /**< The X/Y location of the cursor */
609 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
612 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
615 Evas_Button_Flags flags; /**< button flags set during the event */
616 unsigned int timestamp;
617 Evas_Event_Flags event_flags;
619 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
622 struct _Evas_Event_Mouse_In /** Mouse enter event */
624 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
626 Evas_Point output; /**< The X/Y location of the cursor */
627 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
630 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
632 unsigned int timestamp;
633 Evas_Event_Flags event_flags;
635 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
638 struct _Evas_Event_Mouse_Out /** Mouse leave event */
640 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
642 Evas_Point output; /**< The X/Y location of the cursor */
643 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
646 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
648 unsigned int timestamp;
649 Evas_Event_Flags event_flags;
651 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
654 struct _Evas_Event_Mouse_Move /** Mouse move event */
656 int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
658 Evas_Position cur; /**< Current mouse position */
659 Evas_Position prev; /**< Previous mouse position */
662 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
664 unsigned int timestamp;
665 Evas_Event_Flags event_flags;
667 Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */
670 struct _Evas_Event_Mouse_Wheel /** Wheel event */
672 int direction; /* 0 = default up/down wheel FIXME: more wheel types */
673 int z; /* ...,-2,-1 = down, 1,2,... = up */
675 Evas_Point output; /**< The X/Y location of the cursor */
676 Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
679 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
681 unsigned int timestamp;
682 Evas_Event_Flags event_flags;
686 struct _Evas_Event_Multi_Down /** Multi button press event */
688 int device; /**< Multi device number that went down (1 or more for extra touches) */
689 double radius, radius_x, radius_y;
690 double pressure, angle;
693 Evas_Coord_Precision_Point canvas;
696 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
699 Evas_Button_Flags flags; /**< button flags set during the event */
700 unsigned int timestamp;
701 Evas_Event_Flags event_flags;
705 struct _Evas_Event_Multi_Up /** Multi button release event */
707 int device; /**< Multi device number that went up (1 or more for extra touches) */
708 double radius, radius_x, radius_y;
709 double pressure, angle;
712 Evas_Coord_Precision_Point canvas;
715 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
718 Evas_Button_Flags flags; /**< button flags set during the event */
719 unsigned int timestamp;
720 Evas_Event_Flags event_flags;
724 struct _Evas_Event_Multi_Move /** Multi button down event */
726 int device; /**< Multi device number that moved (1 or more for extra touches) */
727 double radius, radius_x, radius_y;
728 double pressure, angle;
730 Evas_Precision_Position cur;
733 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
735 unsigned int timestamp;
736 Evas_Event_Flags event_flags;
740 struct _Evas_Event_Key_Down /** Key press event */
742 char *keyname; /**< the name string of the key pressed */
744 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
747 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
748 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
749 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 */
750 unsigned int timestamp;
751 Evas_Event_Flags event_flags;
755 struct _Evas_Event_Key_Up /** Key release event */
757 char *keyname; /**< the name string of the key released */
759 Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
762 const char *key; /**< The logical key : (eg shift+1 == exclamation) */
763 const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
764 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 */
765 unsigned int timestamp;
766 Evas_Event_Flags event_flags;
770 struct _Evas_Event_Render_Post /** Send when the frame rendering is done @since 1.8 */
772 Eina_List *updated_area; /**< A list of rectangle that were updated in the canvas */
775 struct _Evas_Event_Hold /** Hold change event */
777 int hold; /**< The hold flag */
780 unsigned int timestamp;
781 Evas_Event_Flags event_flags;
786 * How the mouse pointer should be handled by Evas.
788 * In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button
789 * is pressed down over an object and held, with the mouse pointer
790 * being moved outside of it, the pointer still behaves as being bound
791 * to that object, albeit out of its drawing region. When the button
792 * is released, the event will be fed to the object, that may check if
793 * the final position is over it or not and do something about it.
795 * In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will
796 * always be bound to the object right below it.
798 * @ingroup Evas_Object_Group_Extras
800 typedef enum _Evas_Object_Pointer_Mode
802 EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
803 EVAS_OBJECT_POINTER_MODE_NOGRAB, /**< pointer always bound to the object right below it */
804 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 */
805 } Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
807 typedef void (*Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info); /**< Evas smart objects' "smart callback" function signature */
808 typedef void (*Evas_Event_Cb)(void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
809 typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e);
810 typedef void (*Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info); /**< Evas object event callback function signature */
811 typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
814 * @defgroup Evas_Main_Group Top Level Functions
817 * Functions that affect Evas as a whole.
821 * Get the path for the cserve binary to execute
823 * There is little need for anyone except a desktop environment to call this.
824 * This can be called before evas_init() has been called. It will try and find
825 * the full path to the to the cserve binary to run to provide cserve image
826 * and font caching services for evas.
828 * @return NULL if error, or a string with the full path to the cserve binary.
832 EAPI const char *evas_cserve_path_get(void);
837 * @return The init counter value.
839 * This function initializes Evas and increments a counter of the
840 * number of calls to it. It returns the new counter's value.
842 * @see evas_shutdown().
844 * Most EFL users wouldn't be using this function directly, because
845 * they wouldn't access Evas directly by themselves. Instead, they
846 * would be using higher level helpers, like @c ecore_evas_init().
849 * You should be using this if your use is something like the
850 * following. The buffer engine is just one of the many ones Evas
853 * @dontinclude evas-buffer-simple.c
856 * And being the canvas creation something like:
857 * @skip static Evas *create_canvas
858 * @until evas_output_viewport_set(canvas,
860 * Note that this is code creating an Evas canvas with no usage of
861 * Ecore helpers at all -- no linkage with Ecore on this scenario,
862 * thus. Again, this wouldn't be on Evas common usage for most
863 * developers. See the full @ref Example_Evas_Buffer_Simple "example".
865 * @ingroup Evas_Main_Group
867 EAPI int evas_init(void);
872 * @return Evas' init counter value.
874 * This function finalizes Evas, decrementing the counter of the
875 * number of calls to the function evas_init(). This new value for the
876 * counter is returned.
880 * If you were the sole user of Evas, by means of evas_init(), you can
881 * check if it's being properly shut down by expecting a return value
884 * Example code follows.
885 * @dontinclude evas-buffer-simple.c
886 * @skip // NOTE: use ecore_evas_buffer_new
887 * @until evas_shutdown
888 * Where that function would contain:
889 * @skip evas_free(canvas)
890 * @until evas_free(canvas)
892 * Most users would be using ecore_evas_shutdown() instead, like told
893 * in evas_init(). See the full @ref Example_Evas_Buffer_Simple
896 * @ingroup Evas_Main_Group
898 EAPI int evas_shutdown(void);
901 * Return if any allocation errors have occurred during the prior function
902 * @return The allocation error flag
904 * This function will return if any memory allocation errors occurred during,
905 * and what kind they were. The return value will be one of
906 * EVAS_ALLOC_ERROR_NONE, EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED
907 * with each meaning something different.
909 * EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
910 * worked as expected.
912 * EVAS_ALLOC_ERROR_FATAL means the function was completely unable to perform
913 * its job and will have exited as cleanly as possible. The programmer
914 * should consider this as a sign of very low memory and should try and safely
915 * recover from the prior functions failure (or try free up memory elsewhere
916 * and try again after more memory is freed).
918 * EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but was
919 * recovered from by evas finding memory of its own it has allocated and
920 * freeing what it sees as not really usefully allocated memory. What is freed
921 * may vary. Evas may reduce the resolution of images, free cached images or
922 * fonts, throw out pre-rendered data, reduce the complexity of change lists
923 * etc. Evas and the program will function as per normal after this, but this
924 * is a sign of low memory, and it is suggested that the program try and
925 * identify memory it doesn't need, and free it.
929 * extern Evas_Object *object;
930 * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
932 * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
933 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
935 * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n");
936 * fprintf(stderr, " destroy object now as it cannot be used.\n");
937 * evas_object_del(object);
939 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
940 * my_memory_cleanup();
942 * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
944 * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
945 * my_memory_cleanup();
949 * @ingroup Evas_Main_Group
951 EAPI Evas_Alloc_Error evas_alloc_error(void);
954 * @brief Get evas' internal asynchronous events read file descriptor.
956 * @return The canvas' asynchronous events read file descriptor.
958 * Evas' asynchronous events are meant to be dealt with internally,
959 * i. e., when building stuff to be glued together into the EFL
960 * infrastructure -- a module, for example. The context which demands
961 * its use is when calculations need to be done out of the main
962 * thread, asynchronously, and some action must be performed after
965 * An example of actual use of this API is for image asynchronous
966 * preload inside evas. If the canvas was instantiated through
967 * ecore-evas usage, ecore itself will take care of calling those
968 * events' processing.
970 * This function returns the read file descriptor where to get the
971 * asynchronous events of the canvas. Naturally, other mainloops,
972 * apart from ecore, may make use of it.
974 * @ingroup Evas_Main_Group
976 EAPI int evas_async_events_fd_get(void) EINA_WARN_UNUSED_RESULT;
979 * @brief Trigger the processing of all events waiting on the file
980 * descriptor returned by evas_async_events_fd_get().
982 * @return The number of events processed.
984 * All asynchronous events queued up by evas_async_events_put() are
985 * processed here. More precisely, the callback functions, informed
986 * together with other event parameters, when queued, get called (with
987 * those parameters), in that order.
989 * @ingroup Evas_Main_Group
991 EAPI int evas_async_events_process(void);
994 * Insert asynchronous events on the canvas.
996 * @param target The target to be affected by the events.
997 * @param type The type of callback function.
998 * @param event_info Information about the event.
999 * @param func The callback function pointer.
1001 * This is the way, for a routine running outside evas' main thread,
1002 * to report an asynchronous event. A callback function is informed,
1003 * whose call is to happen after evas_async_events_process() is
1006 * @ingroup Evas_Main_Group
1008 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);
1011 * @defgroup Evas_Canvas Canvas Functions
1014 * Low level Evas canvas functions. Sub groups will present more high
1015 * level ones, though.
1017 * Most of these functions deal with low level Evas actions, like:
1018 * @li create/destroy raw canvases, not bound to any displaying engine
1019 * @li tell a canvas i got focused (in a windowing context, for example)
1020 * @li tell a canvas a region should not be calculated anymore in rendering
1021 * @li tell a canvas to render its contents, immediately
1023 * Most users will be using Evas by means of the @c Ecore_Evas
1024 * wrapper, which deals with all the above mentioned issues
1025 * automatically for them. Thus, you'll be looking at this section
1026 * only if you're building low level stuff.
1028 * The groups within present you functions that deal with the canvas
1029 * directly, too, and not yet with its @b objects. They are the
1030 * functions you need to use at a minimum to get a working canvas.
1032 * Some of the functions in this group are exemplified @ref
1033 * Example_Evas_Events "here".
1040 * @defgroup Evas_Output_Method Render Engine Functions
1042 * Functions that are used to set the render engine for a given
1043 * function, and then get that engine working.
1045 * The following code snippet shows how they can be used to
1046 * initialise an evas that uses the X11 software engine:
1049 * Evas_Engine_Info_Software_X11 *einfo;
1050 * extern Display *display;
1051 * extern Window win;
1055 * evas = evas_new();
1056 * evas_output_method_set(evas, evas_render_method_lookup("software_x11"));
1057 * evas_output_size_set(evas, 640, 480);
1058 * evas_output_viewport_set(evas, 0, 0, 640, 480);
1059 * einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas);
1060 * einfo->info.display = display;
1061 * einfo->info.visual = DefaultVisual(display, DefaultScreen(display));
1062 * einfo->info.colormap = DefaultColormap(display, DefaultScreen(display));
1063 * einfo->info.drawable = win;
1064 * einfo->info.depth = DefaultDepth(display, DefaultScreen(display));
1065 * evas_engine_info_set(evas, (Evas_Engine_Info *)einfo);
1068 * @ingroup Evas_Canvas
1072 * Look up a numeric ID from a string name of a rendering engine.
1074 * @param name the name string of an engine
1075 * @return A numeric (opaque) ID for the rendering engine
1076 * @ingroup Evas_Output_Method
1078 * This function looks up a numeric return value for the named engine
1079 * in the string @p name. This is a normal C string, NUL byte
1080 * terminated. The name is case sensitive. If the rendering engine is
1081 * available, a numeric ID for that engine is returned that is not
1082 * 0. If the engine is not available, 0 is returned, indicating an
1085 * The programmer should NEVER rely on the numeric ID of an engine
1086 * unless it is returned by this function. Programs should NOT be
1087 * written accessing render method ID's directly, without first
1088 * obtaining it from this function.
1090 * @attention it is mandatory that one calls evas_init() before
1091 * looking up the render method.
1100 * evas = evas_new();
1103 * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
1106 * engine_id = evas_render_method_lookup("software_x11");
1109 * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
1112 * evas_output_method_set(evas, engine_id);
1115 EAPI int evas_render_method_lookup(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
1118 * List all the rendering engines compiled into the copy of the Evas library
1120 * @return A linked list whose data members are C strings of engine names
1121 * @ingroup Evas_Output_Method
1123 * Calling this will return a handle (pointer) to an Evas linked
1124 * list. Each node in the linked list will have the data pointer be a
1125 * (char *) pointer to the name string of the rendering engine
1126 * available. The strings should never be modified, neither should the
1127 * list be modified. This list should be cleaned up as soon as the
1128 * program no longer needs it using evas_render_method_list_free(). If
1129 * no engines are available from Evas, @c NULL will be returned.
1133 * Eina_List *engine_list, *l;
1134 * char *engine_name;
1136 * engine_list = evas_render_method_list();
1139 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1142 * printf("Available Evas Engines:\n");
1143 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1144 * printf("%s\n", engine_name);
1145 * evas_render_method_list_free(engine_list);
1148 EAPI Eina_List *evas_render_method_list(void) EINA_WARN_UNUSED_RESULT;
1151 * This function should be called to free a list of engine names
1153 * @param list The Eina_List base pointer for the engine list to be freed
1154 * @ingroup Evas_Output_Method
1156 * When this function is called it will free the engine list passed in
1157 * as @p list. The list should only be a list of engines generated by
1158 * calling evas_render_method_list(). If @p list is NULL, nothing will
1163 * Eina_List *engine_list, *l;
1164 * char *engine_name;
1166 * engine_list = evas_render_method_list();
1169 * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
1172 * printf("Available Evas Engines:\n");
1173 * EINA_LIST_FOREACH(engine_list, l, engine_name)
1174 * printf("%s\n", engine_name);
1175 * evas_render_method_list_free(engine_list);
1178 EAPI void evas_render_method_list_free(Eina_List *list);
1185 * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
1187 * Functions that are used to map coordinates from the canvas to the
1188 * screen or the screen to the canvas.
1190 * @ingroup Evas_Canvas
1194 * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
1196 * Functions that set and retrieve the output and viewport size of an
1199 * @ingroup Evas_Canvas
1203 * @defgroup Evas_Canvas_Events Canvas Events
1205 * Functions relating to canvas events, which are mainly reports on
1206 * its internal states changing (an object got focused, the rendering
1209 * Some of the functions in this group are exemplified @ref
1210 * Example_Evas_Events "here".
1212 * @ingroup Evas_Canvas
1216 * Free the rectangles returned by evas_render_updates().
1218 * @param updates The list of updated rectangles of the canvas.
1220 * This function removes the region from the render updates list. It
1221 * makes the region doesn't be render updated anymore.
1223 * @see evas_render_updates() for an example
1225 * @ingroup Evas_Canvas
1227 EAPI void evas_render_updates_free(Eina_List *updates);
1231 * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
1233 * Functions that deal with the freezing of input event processing of
1236 * There might be scenarios during a graphical user interface
1237 * program's use when the developer wishes the users wouldn't be able
1238 * to deliver input events to this application. It may, for example,
1239 * be the time for it to populate a view or to change some
1240 * layout. Assuming proper behavior with user interaction during this
1241 * exact time would be hard, as things are in a changing state. The
1242 * programmer can then tell the canvas to ignore input events,
1243 * bringing it back to normal behavior when he/she wants.
1245 * Most of the time use of freezing events is done like this:
1247 * evas_event_freeze(my_evas_canvas);
1248 * function_that_does_work_which_cant_be_interrupted_by_events();
1249 * evas_event_thaw(my_evas_canvas);
1252 * Some of the functions in this group are exemplified @ref
1253 * Example_Evas_Events "here".
1255 * @ingroup Evas_Canvas_Events
1259 * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
1261 * Functions to tell Evas that input events happened and should be
1264 * @warning Most of the time these functions are @b not what you're looking for.
1265 * These functions should only be used if you're not working with ecore evas(or
1266 * another input handling system). If you're not using ecore evas please
1267 * consider using it, in most situation it will make life a lot easier.
1269 * As explained in @ref intro_not_evas, Evas does not know how to poll
1270 * for input events, so the developer should do it and then feed such
1271 * events to the canvas to be processed. This is only required if
1272 * operating Evas directly. Modules such as Ecore_Evas do that for
1275 * Some of the functions in this group are exemplified @ref
1276 * Example_Evas_Events "here".
1278 * @ingroup Evas_Canvas_Events
1282 * @addtogroup Evas_Event_Feeding_Group
1287 * Add a new device type
1289 * @param e The canvas to create the device node for.
1291 * Adds a new device nod to the given canvas @p e. All devices created as
1292 * part of the canvas @p e will automatically be deleted when the canvas
1295 * @see evas_device_del
1298 EAPI Evas_Device *evas_device_add(Evas *e);
1301 * Delete a new device type
1303 * @see evas_device_add
1304 * @see evas_device_push
1305 * @see evas_device_pop
1308 EAPI void evas_device_del(Evas_Device *dev);
1311 * Push the current context device onto the device stack
1313 * @param e The canvas to push the device on to
1314 * @param dev The device to push.
1316 * This pushes the given device @p dev onto the stack for the canvas @p e
1317 * resulting in the dev pointer in all events that get fed to the canvas
1318 * being the device at the top of the device stack for that canvas.
1320 * If a device is pushed onto the device stack, it will not be deleted
1321 * until a canvas free OR until it has been popped from the stack even if
1322 * evas_device_del() is called.
1324 * The device @p dev must have been created as a device for the canvas it
1325 * is pushed onto (and not another canvas).
1329 * evas_device_push(canvas, dev);
1330 * evas_event_feed_mouse_move(canvas, 20, 30, 0, NULL);
1331 * evas_device_pop(canvas);
1334 * @see evas_device_pop
1337 EAPI void evas_device_push(Evas *e, Evas_Device *dev);
1340 * This pops the top of the device stack for the canvas
1342 * @param e The canvas to pop the device stack from
1344 * This pops the top of the device stack making the current device context
1345 * used for device events being what is now at the top of the stack after
1348 * @see evas_device_push
1351 EAPI void evas_device_pop(Evas *e);
1354 * List all current devices attached to the given canvas and/or device
1356 * @param e The canvas to query for a device list
1357 * @param dev A specific device inside the canvas to query for child devices or NULL if just querying the base canvas devices
1358 * @return An internal list of Evas_Device pointers, or NULL if no devices are found
1360 * This will list all devices belonging to a specific evas canvas @p e, at the
1361 * top-level in the device tree if @p dev passed in is NULL. If @p dev is
1362 * a valid device for the given canvas @p e, then a list of child devices
1363 * of @p dev will be returned, allowing you to walk the device tree.
1365 * The list returned is only valid so long as no changes are made to the
1366 * device tree in the given canvas @p e. If there are no devices or children
1367 * then NULL is returned.
1369 * @see evas_device_parent_get
1370 * @see evas_device_name_get
1371 * @see evas_device_description_get
1372 * @see evas_device_class_get
1373 * @see evas_device_subclass_get
1374 * @see evas_device_emulation_source_get
1377 EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev);
1380 * Set the name of a device as a string
1382 * @p dev The device to set the name of
1383 * @p name The name string as a readable C UTF8 string
1387 EAPI void evas_device_name_set(Evas_Device *dev, const char *name);
1390 * Get the name of a device
1392 * @p dev The device to query
1393 * @return The device name string or NULL if none is set
1395 * This gets the name set by evas_device_name_set(). This is a readable UTF8
1396 * C string, or NULL if no name is set.
1398 * The name should be a short name like "Wireless Mouse", "Joystick",
1399 * "Finger", "Keyboard" or "Numberpad" etc.
1403 EAPI const char *evas_device_name_get(const Evas_Device *dev);
1406 * Set the description of a device as a string
1408 * @p dev The device to set the description of
1409 * @p name The description string as a readable C UTF8 string
1413 EAPI void evas_device_description_set(Evas_Device *dev, const char *desc);
1416 * Get the description of a device
1418 * @p dev The device to query
1419 * @return The device description string or NULL if none is set
1421 * This gets the description set by evas_device_description_set(). This is
1422 * a readable UTF8 C string, or NULL if no description is set.
1424 * A description is meant to be a longer string describing the device so a
1425 * human may make sense of it. For example "Wireless 6 button mouse in Black
1426 * with red buttons" would be a good description, so a user may identify
1427 * precisely which device is being talked about.
1431 EAPI const char *evas_device_description_get(const Evas_Device *dev);
1434 * Set the parent of a device
1436 * @p dev The device to set the parent of
1437 * @p parent The new parent device
1439 * This sets the parent of a device @p dev to the parent given by @p parent.
1440 * If the device already has a parent, it is removed from that parent's list.
1441 * If @p parent is NULL then the device is unparented and placed back as a
1442 * root device in the canvas.
1444 * When a device is deleted with evas_device_del(), all children are also
1445 * deleted along with it.
1447 * @see evas_device_del
1448 * @see evas_device_parent_get
1449 * @see evas_device_list
1453 EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent);
1456 * Get the parent of a device
1458 * @param dev The device to query
1459 * @return The parent device or NULL if it is a toplevel
1461 * This returns the parent device of any given device entry, or NULL if no
1462 * parent device exists (is a toplevel device).
1466 EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev);
1469 * Set the major class of device
1471 * @param dev The device whose class to set
1472 * @param clas The class to set it to
1474 * This sets the "primary" class of device (a broad thing like mouse, keyboard,
1479 EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas);
1482 * Get the major class of a device
1484 * @param dev The devise to query
1485 * @return The device class to set
1487 * This sets the device class set by evas_device_class_set().
1491 EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev);
1494 * Set the sub-class of a device
1496 * @param dev The device to modify
1497 * @param clas The sub-class to set
1499 * This sets the sub-class of a device whihc gives much more detailed usage
1500 * within a broader category.
1504 EAPI void evas_device_subclass_set(Evas_Device *dev, Evas_Device_Subclass clas);
1507 * Get the device sub-class
1509 * @param dev The device to query
1510 * @return The device sub-class set by evas_device_subclass_set().
1514 EAPI Evas_Device_Subclass evas_device_subclass_get(const Evas_Device *dev);
1517 * Set the emulation source device
1519 * @param dev The device being emulated
1520 * @param src The primary source device producing events in the emulated device
1522 * Devices may not be real, but may be emulated by listening to input on other
1523 * devices and modifying or interpeting it to generate output on an emulated
1524 * device (example a fingeron a touchscreen will often emulate a mouse when
1525 * it presses). This allows you to set which device primarily emulates @p dev
1526 * so the user can choose to ignore events from emulated devices if they also
1527 * pay attention to source device events for example.
1531 EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src);
1534 * Get the emulation source device
1536 * @param dev The device to query
1537 * @return The source emulation device set by evas_device_emulation_source_set().
1541 EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev);
1548 * @defgroup Evas_Image_Group Image Functions
1550 * Functions that deals with images at canvas level.
1552 * @ingroup Evas_Canvas
1556 * @defgroup Evas_Font_Group Font Functions
1558 * Functions that deals with fonts.
1560 * @ingroup Evas_Canvas
1564 * @defgroup Evas_Object_Group Generic Object Functions
1567 * Functions that manipulate generic Evas objects.
1569 * All Evas displaying units are Evas objects. One handles them all by
1570 * means of the handle ::Evas_Object. Besides Evas treats their
1571 * objects equally, they have @b types, which define their specific
1572 * behavior (and individual API).
1574 * Evas comes with a set of built-in object types:
1583 * These functions apply to @b any Evas object, whichever type that
1586 * @note The built-in types which are most used are rectangles, text
1587 * and images. In fact, with these ones one can create 2D interfaces
1588 * of arbitrary complexity and EFL makes it easy.
1592 * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
1594 * Almost every evas object created will have some generic function used to
1595 * manipulate it. That's because there are a number of basic actions to be done
1596 * to objects that are irrespective of the object's type, things like:
1597 * @li Showing/Hiding
1598 * @li Setting(and getting) geometry
1599 * @li Bring up or down a layer
1600 * @li Color management
1601 * @li Handling focus
1603 * @li Reference counting
1605 * All of this issues are handled through the functions here grouped. Examples
1606 * of these function can be seen in @ref Example_Evas_Object_Manipulation(which
1607 * deals with the most common ones) and in @ref Example_Evas_Stacking(which
1608 * deals with stacking functions).
1610 * @ingroup Evas_Object_Group
1614 * @defgroup Evas_Object_Group_Events Object Events
1616 * Objects generate events when they are moved, resized, when their
1617 * visibility change, when they are deleted and so on. These methods
1618 * allow one to be notified about and to handle such events.
1620 * Objects also generate events on input (keyboard and mouse), if they
1621 * accept them (are visible, focused, etc).
1623 * For each of those events, Evas provides a way for one to register
1624 * callback functions to be issued just after they happen.
1626 * The following figure illustrates some Evas (event) callbacks:
1628 * @image html evas-callbacks.png
1629 * @image rtf evas-callbacks.png
1630 * @image latex evas-callbacks.eps
1632 * These events have their values in the #Evas_Callback_Type
1633 * enumeration, which has also ones happening on the canvas level (see
1634 * @ref Evas_Canvas_Events ).
1636 * Examples on this group of functions can be found @ref
1637 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
1639 * @ingroup Evas_Object_Group
1643 * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspective, 3D...)
1645 * Evas allows different transformations to be applied to all kinds of
1646 * objects. These are applied by means of UV mapping.
1648 * With UV mapping, one maps points in the source object to a 3D space
1649 * positioning at target. This allows rotation, perspective, scale and
1650 * lots of other effects, depending on the map that is used.
1652 * Each map point may carry a multiplier color. If properly
1653 * calculated, these can do shading effects on the object, producing
1656 * As usual, Evas provides both the raw and easy to use methods. The
1657 * raw methods allow developers to create their maps somewhere else,
1658 * possibly loading them from some file format. The easy to use methods
1659 * calculate the points given some high-level parameters such as
1660 * rotation angle, ambient light, and so on.
1662 * @note applying mapping will reduce performance, so use with
1663 * care. The impact on performance depends on engine in
1664 * use. Software is quite optimized, but not as fast as OpenGL.
1666 * @section sec-map-points Map points
1667 * @subsection subsec-rotation Rotation
1669 * A map consists of a set of points, currently only four are supported. Each
1670 * of these points contains a set of canvas coordinates @c x and @c y that
1671 * can be used to alter the geometry of the mapped object, and a @c z
1672 * coordinate that indicates the depth of that point. This last coordinate
1673 * does not normally affect the map, but it's used by several of the utility
1674 * functions to calculate the right position of the point given other
1677 * The coordinates for each point are set with evas_map_point_coord_set().
1678 * The following image shows a map set to match the geometry of an existing
1681 * @image html map-set-map-points-1.png
1682 * @image rtf map-set-map-points-1.png
1683 * @image latex map-set-map-points-1.eps
1685 * This is a common practice, so there are a few functions that help make it
1688 * evas_map_util_points_populate_from_geometry() sets the coordinates of each
1689 * point in the given map to match the rectangle defined by the function
1692 * evas_map_util_points_populate_from_object() and
1693 * evas_map_util_points_populate_from_object_full() both take an object and
1694 * set the map points to match its geometry. The difference between the two
1695 * is that the first function sets the @c z value of all points to 0, while
1696 * the latter receives the value to set in said coordinate as a parameter.
1698 * The following lines of code all produce the same result as in the image
1701 * evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
1702 * // Assuming o is our original object
1703 * evas_object_move(o, 100, 100);
1704 * evas_object_resize(o, 200, 200);
1705 * evas_map_util_points_populate_from_object(m, o);
1706 * evas_map_util_points_populate_from_object_full(m, o, 0);
1709 * Several effects can be applied to an object by simply setting each point
1710 * of the map to the right coordinates. For example, a simulated perspective
1711 * could be achieve as follows.
1713 * @image html map-set-map-points-2.png
1714 * @image rtf map-set-map-points-2.png
1715 * @image latex map-set-map-points-2.eps
1717 * As said before, the @c z coordinate is unused here so when setting points
1718 * by hand, its value is of no importance.
1720 * @image html map-set-map-points-3.png
1721 * @image rtf map-set-map-points-3.png
1722 * @image latex map-set-map-points-3.eps
1724 * In all three cases above, setting the map to be used by the object is the
1727 * evas_object_map_set(o, m);
1728 * evas_object_map_enable_set(o, EINA_TRUE);
1731 * Doing things this way, however, is a lot of work that can be avoided by
1732 * using the provided utility functions, as described in the next section.
1734 * @section map-utils Utility functions
1736 * Utility functions take an already set up map and alter it to produce a
1737 * specific effect. For example, to rotate an object around its own center
1738 * you would need to take the rotation angle, the coordinates of each corner
1739 * of the object and do all the math to get the new set of coordinates that
1740 * need to be set in the map.
1742 * Or you can use this code:
1744 * evas_object_geometry_get(o, &x, &y, &w, &h);
1745 * m = evas_map_new(4);
1746 * evas_map_util_points_populate_from_object(m, o);
1747 * evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
1748 * evas_object_map_set(o, m);
1749 * evas_object_map_enable_set(o, EINA_TRUE);
1753 * Which will rotate the object around its center point in a 45 degree angle
1754 * in the clockwise direction, taking it from this
1756 * @image html map-rotation-2d-1.png
1757 * @image rtf map-rotation-2d-1.png
1758 * @image latex map-rotation-2d-1.eps
1762 * @image html map-rotation-2d-2.png
1763 * @image rtf map-rotation-2d-2.png
1764 * @image latex map-rotation-2d-2.eps
1766 * Objects may be rotated around any other point just by setting the last two
1767 * paramaters of the evas_map_util_rotate() function to the right values. A
1768 * circle of roughly the diameter of the object overlaid on each image shows
1769 * where the center of rotation is set for each example.
1771 * For example, this code
1773 * evas_object_geometry_get(o, &x, &y, &w, &h);
1774 * m = evas_map_new(4);
1775 * evas_map_util_points_populate_from_object(m, o);
1776 * evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
1777 * evas_object_map_set(o, m);
1778 * evas_object_map_enable_set(o, EINA_TRUE);
1782 * produces something like
1784 * @image html map-rotation-2d-3.png
1785 * @image rtf map-rotation-2d-3.png
1786 * @image latex map-rotation-2d-3.eps
1790 * evas_output_size_get(evas, &w, &h);
1791 * m = evas_map_new(4);
1792 * evas_map_util_points_populate_from_object(m, o);
1793 * evas_map_util_rotate(m, 45, w, h);
1794 * evas_object_map_set(o, m);
1795 * evas_object_map_enable_set(o, EINA_TRUE);
1799 * rotates the object around the center of the window
1801 * @image html map-rotation-2d-4.png
1802 * @image rtf map-rotation-2d-4.png
1803 * @image latex map-rotation-2d-4.eps
1805 * @subsection subsec-3d 3D Maps
1807 * Maps can also be used to achieve the effect of 3-dimensionality. When doing
1808 * this, the @c z coordinate of each point counts, with higher values meaning
1809 * the point is further into the screen, and smaller values (negative, usually)
1810 * meaning the point is closer towards the user.
1812 * Thinking in 3D also introduces the concept of back-face of an object. An
1813 * object is said to be facing the user when all its points are placed in a
1814 * clockwise fashion. The next image shows this, with each point showing the
1815 * with which is identified within the map.
1817 * @image html map-point-order-face.png
1818 * @image rtf map-point-order-face.png
1819 * @image latex map-point-order-face.eps
1821 * Rotating this map around the @c Y axis would leave the order of the points
1822 * in a counter-clockwise fashion, as seen in the following image.
1824 * @image html map-point-order-back.png
1825 * @image rtf map-point-order-back.png
1826 * @image latex map-point-order-back.eps
1828 * This way we can say that we are looking at the back face of the object.
1829 * This will have stronger implications later when we talk about lighting.
1831 * To know if a map is facing towards the user or not it's enough to use
1832 * the evas_map_util_clockwise_get() function, but this is normally done
1833 * after all the other operations are applied on the map.
1835 * @subsection subsec-3d-rot 3D rotation and perspective
1837 * Much like evas_map_util_rotate(), there's the function
1838 * evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
1839 * to an object. As in its 2D counterpart, the rotation can be applied around
1840 * any point in the canvas, this time with a @c z coordinate too. The rotation
1841 * can also be around any of the 3 axis.
1843 * Starting from this simple setup
1845 * @image html map-3d-basic-1.png
1846 * @image rtf map-3d-basic-1.png
1847 * @image latex map-3d-basic-1.eps
1849 * and setting maps so that the blue square to rotate on all axis around a
1850 * sphere that uses the object as its center, and the red square to rotate
1851 * around the @c Y axis, we get the following. A simple overlay over the image
1852 * shows the original geometry of each object and the axis around which they
1853 * are being rotated, with the @c Z one not appearing due to being orthogonal
1856 * @image html map-3d-basic-2.png
1857 * @image rtf map-3d-basic-2.png
1858 * @image latex map-3d-basic-2.eps
1860 * which doesn't look very real. This can be helped by adding perspective
1861 * to the transformation, which can be simply done by calling
1862 * evas_map_util_3d_perspective() on the map after its position has been set.
1863 * The result in this case, making the vanishing point the center of each
1866 * @image html map-3d-basic-3.png
1867 * @image rtf map-3d-basic-3.png
1868 * @image latex map-3d-basic-3.eps
1870 * @section sec-color Color and lighting
1872 * Each point in a map can be set to a color, which will be multiplied with
1873 * the objects own color and linearly interpolated in between adjacent points.
1874 * This is done with evas_map_point_color_set() for each point of the map,
1875 * or evas_map_util_points_color_set() to set every point to the same color.
1877 * When using 3D effects, colors can be used to improve the looks of them by
1878 * simulating a light source. The evas_map_util_3d_lighting() function makes
1879 * this task easier by taking the coordinates of the light source and its
1880 * color, along with the color of the ambient light. Evas then sets the color
1881 * of each point based on the distance to the light source, the angle with
1882 * which the object is facing the light and the ambient light. Here, the
1883 * orientation of each point as explained before, becomes more important.
1884 * If the map is defined counter-clockwise, the object will be facing away
1885 * from the user and thus become obscured, since no light would be reflecting
1888 * @image html map-light.png
1889 * @image rtf map-light.png
1890 * @image latex map-light.eps
1891 * @note Object facing the light source
1893 * @image html map-light2.png
1894 * @image rtf map-light2.png
1895 * @image latex map-light2.eps
1896 * @note Same object facing away from the user
1898 * @section Image mapping
1900 * @image html map-uv-mapping-1.png
1901 * @image rtf map-uv-mapping-1.png
1902 * @image latex map-uv-mapping-1.eps
1904 * Images need some special handling when mapped. Evas can easily take care
1905 * of objects and do almost anything with them, but it's completely oblivious
1906 * to the content of images, so each point in the map needs to be told to what
1907 * pixel in the source image it belongs. Failing to do may sometimes result
1908 * in the expected behavior, or it may look like a partial work.
1910 * The next image illustrates one possibility of a map being set to an image
1911 * object, without setting the right UV mapping for each point. The objects
1912 * themselves are mapped properly to their new geometry, but the image content
1913 * may not be displayed correctly within the mapped object.
1915 * @image html map-uv-mapping-2.png
1916 * @image rtf map-uv-mapping-2.png
1917 * @image latex map-uv-mapping-2.eps
1919 * Once Evas knows how to handle the source image within the map, it will
1920 * transform it as needed. This is done with evas_map_point_image_uv_set(),
1921 * which tells the map to which pixel in image it maps.
1923 * To match our example images to the maps above all we need is the size of
1924 * each image, which can always be found with evas_object_image_size_get().
1927 * evas_map_point_image_uv_set(m, 0, 0, 0);
1928 * evas_map_point_image_uv_set(m, 1, 150, 0);
1929 * evas_map_point_image_uv_set(m, 2, 150, 200);
1930 * evas_map_point_image_uv_set(m, 3, 0, 200);
1931 * evas_object_map_set(o, m);
1932 * evas_object_map_enable_set(o, EINA_TRUE);
1934 * evas_map_point_image_uv_set(m, 0, 0, 0);
1935 * evas_map_point_image_uv_set(m, 1, 120, 0);
1936 * evas_map_point_image_uv_set(m, 2, 120, 160);
1937 * evas_map_point_image_uv_set(m, 3, 0, 160);
1938 * evas_object_map_set(o2, m);
1939 * evas_object_map_enable_set(o2, EINA_TRUE);
1944 * @image html map-uv-mapping-3.png
1945 * @image rtf map-uv-mapping-3.png
1946 * @image latex map-uv-mapping-3.eps
1948 * Maps can also be set to use part of an image only, or even map them inverted,
1949 * and combined with evas_object_image_source_set() it can be used to achieve
1950 * more interesting results.
1953 * evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
1954 * evas_map_point_image_uv_set(m, 0, 0, h);
1955 * evas_map_point_image_uv_set(m, 1, w, h);
1956 * evas_map_point_image_uv_set(m, 2, w, h / 3);
1957 * evas_map_point_image_uv_set(m, 3, 0, h / 3);
1958 * evas_object_map_set(o, m);
1959 * evas_object_map_enable_set(o, EINA_TRUE);
1962 * @image html map-uv-mapping-4.png
1963 * @image rtf map-uv-mapping-4.png
1964 * @image latex map-uv-mapping-4.eps
1967 * @li @ref Example_Evas_Map_Overview
1969 * @ingroup Evas_Object_Group
1975 * Populate source and destination map points to match exactly object.
1977 * Usually one initialize map of an object to match it's original
1978 * position and size, then transform these with evas_map_util_*
1979 * functions, such as evas_map_util_rotate() or
1980 * evas_map_util_3d_rotate(). The original set is done by this
1981 * function, avoiding code duplication all around.
1983 * @param m map to change all 4 points (must be of size 4).
1984 * @param obj object to use unmapped geometry to populate map coordinates.
1985 * @param z Point Z Coordinate hint (pre-perspective transform). This value
1986 * will be used for all four points.
1988 * @see evas_map_util_points_populate_from_object()
1989 * @see evas_map_point_coord_set()
1990 * @see evas_map_point_image_uv_set()
1992 EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
1995 * Populate source and destination map points to match exactly object.
1997 * Usually one initialize map of an object to match it's original
1998 * position and size, then transform these with evas_map_util_*
1999 * functions, such as evas_map_util_rotate() or
2000 * evas_map_util_3d_rotate(). The original set is done by this
2001 * function, avoiding code duplication all around.
2003 * Z Point coordinate is assumed as 0 (zero).
2005 * @param m map to change all 4 points (must be of size 4).
2006 * @param obj object to use unmapped geometry to populate map coordinates.
2008 * @see evas_map_util_points_populate_from_object_full()
2009 * @see evas_map_util_points_populate_from_geometry()
2010 * @see evas_map_point_coord_set()
2011 * @see evas_map_point_image_uv_set()
2013 EAPI void evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj);
2016 * Populate source and destination map points to match given geometry.
2018 * Similar to evas_map_util_points_populate_from_object_full(), this
2019 * call takes raw values instead of querying object's unmapped
2020 * geometry. The given width will be used to calculate destination
2021 * points (evas_map_point_coord_set()) and set the image uv
2022 * (evas_map_point_image_uv_set()).
2024 * @param m map to change all 4 points (must be of size 4).
2025 * @param x Point X Coordinate
2026 * @param y Point Y Coordinate
2027 * @param w width to use to calculate second and third points.
2028 * @param h height to use to calculate third and fourth points.
2029 * @param z Point Z Coordinate hint (pre-perspective transform). This value
2030 * will be used for all four points.
2032 * @see evas_map_util_points_populate_from_object()
2033 * @see evas_map_point_coord_set()
2034 * @see evas_map_point_image_uv_set()
2036 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);
2039 * Set color of all points to given color.
2041 * This call is useful to reuse maps after they had 3d lightning or
2042 * any other colorization applied before.
2044 * @param m map to change the color of.
2045 * @param r red (0 - 255)
2046 * @param g green (0 - 255)
2047 * @param b blue (0 - 255)
2048 * @param a alpha (0 - 255)
2050 * @see evas_map_point_color_set()
2052 EAPI void evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a);
2055 * Change the map to apply the given rotation.
2057 * This rotates the indicated map's coordinates around the center coordinate
2058 * given by @p cx and @p cy as the rotation center. The points will have their
2059 * X and Y coordinates rotated clockwise by @p degrees degrees (360.0 is a
2060 * full rotation). Negative values for degrees will rotate counter-clockwise
2061 * by that amount. All coordinates are canvas global coordinates.
2063 * @param m map to change.
2064 * @param degrees amount of degrees from 0.0 to 360.0 to rotate.
2065 * @param cx rotation's center horizontal position.
2066 * @param cy rotation's center vertical position.
2068 * @see evas_map_point_coord_set()
2069 * @see evas_map_util_zoom()
2071 EAPI void evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
2074 * Change the map to apply the given zooming.
2076 * Like evas_map_util_rotate(), this zooms the points of the map from a center
2077 * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
2078 * parameters specify how much to zoom in the X and Y direction respectively.
2079 * A value of 1.0 means "don't zoom". 2.0 means "double the size". 0.5 is
2080 * "half the size" etc. All coordinates are canvas global coordinates.
2082 * @param m map to change.
2083 * @param zoomx horizontal zoom to use.
2084 * @param zoomy vertical zoom to use.
2085 * @param cx zooming center horizontal position.
2086 * @param cy zooming center vertical position.
2088 * @see evas_map_point_coord_set()
2089 * @see evas_map_util_rotate()
2091 EAPI void evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
2094 * Rotate the map around 3 axes in 3D
2096 * This will rotate not just around the "Z" axis as in evas_map_util_rotate()
2097 * (which is a convenience call for those only wanting 2D). This will rotate
2098 * around the X, Y and Z axes. The Z axis points "into" the screen with low
2099 * values at the screen and higher values further away. The X axis runs from
2100 * left to right on the screen and the Y axis from top to bottom. Like with
2101 * evas_map_util_rotate() you provide a center point to rotate around (in 3D).
2103 * @param m map to change.
2104 * @param dx amount of degrees from 0.0 to 360.0 to rotate around X axis.
2105 * @param dy amount of degrees from 0.0 to 360.0 to rotate around Y axis.
2106 * @param dz amount of degrees from 0.0 to 360.0 to rotate around Z axis.
2107 * @param cx rotation's center horizontal position.
2108 * @param cy rotation's center vertical position.
2109 * @param cz rotation's center vertical position.
2111 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);
2114 * Rotate the map in 3D using a unit quaternion.
2116 * This will rotate in 3D using a unit quaternion. Like with
2117 * evas_map_util_3d_rotate() you provide a center point
2118 * to rotate around (in 3D).
2120 * @param m map to change.
2121 * @param qx the x component of the imaginary part of the quaternion.
2122 * @param qy the y component of the imaginary part of the quaternion.
2123 * @param qz the z component of the imaginary part of the quaternion.
2124 * @param qw the w component of the real part of the quaternion.
2125 * @param cx rotation's center x.
2126 * @param cy rotation's center y.
2127 * @param cz rotation's center z.
2129 * @warning Rotations can be done using a unit quaternion. Thus, this
2130 * function expects a unit quaternion (i.e. qx² + qy² + qz² + qw² == 1).
2131 * If this is not the case the behavior is undefined.
2135 EAPI void evas_map_util_quat_rotate(Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz);
2138 * Perform lighting calculations on the given Map
2140 * This is used to apply lighting calculations (from a single light source)
2141 * to a given map. The R, G and B values of each vertex will be modified to
2142 * reflect the lighting based on the lixth point coordinates, the light
2143 * color and the ambient color, and at what angle the map is facing the
2144 * light source. A surface should have its points be declared in a
2145 * clockwise fashion if the face is "facing" towards you (as opposed to
2146 * away from you) as faces have a "logical" side for lighting.
2148 * @image html map-light3.png
2149 * @image rtf map-light3.png
2150 * @image latex map-light3.eps
2151 * @note Grey object, no lighting used
2153 * @image html map-light4.png
2154 * @image rtf map-light4.png
2155 * @image latex map-light4.eps
2156 * @note Lights out! Every color set to 0
2158 * @image html map-light5.png
2159 * @image rtf map-light5.png
2160 * @image latex map-light5.eps
2161 * @note Ambient light to full black, red light coming from close at the
2162 * bottom-left vertex
2164 * @image html map-light6.png
2165 * @image rtf map-light6.png
2166 * @image latex map-light6.eps
2167 * @note Same light as before, but not the light is set to 0 and ambient light
2170 * @image html map-light7.png
2171 * @image rtf map-light7.png
2172 * @image latex map-light7.eps
2173 * @note Both lights are on
2175 * @image html map-light8.png
2176 * @image rtf map-light8.png
2177 * @image latex map-light8.eps
2178 * @note Both lights again, but this time both are the same color.
2180 * @param m map to change.
2181 * @param lx X coordinate in space of light point
2182 * @param ly Y coordinate in space of light point
2183 * @param lz Z coordinate in space of light point
2184 * @param lr light red value (0 - 255)
2185 * @param lg light green value (0 - 255)
2186 * @param lb light blue value (0 - 255)
2187 * @param ar ambient color red value (0 - 255)
2188 * @param ag ambient color green value (0 - 255)
2189 * @param ab ambient color blue value (0 - 255)
2191 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);
2194 * Apply a perspective transform to the map
2196 * This applies a given perspective (3D) to the map coordinates. X, Y and Z
2197 * values are used. The px and py points specify the "infinite distance" point
2198 * in the 3D conversion (where all lines converge to like when artists draw
2199 * 3D by hand). The @p z0 value specifies the z value at which there is a 1:1
2200 * mapping between spatial coordinates and screen coordinates. Any points
2201 * on this z value will not have their X and Y values modified in the transform.
2202 * Those further away (Z value higher) will shrink into the distance, and
2203 * those less than this value will expand and become bigger. The @p foc value
2204 * determines the "focal length" of the camera. This is in reality the distance
2205 * between the camera lens plane itself (at or closer than this rendering
2206 * results are undefined) and the "z0" z value. This allows for some "depth"
2207 * control and @p foc must be greater than 0.
2209 * @param m map to change.
2210 * @param px The perspective distance X coordinate
2211 * @param py The perspective distance Y coordinate
2212 * @param z0 The "0" z plane value
2213 * @param foc The focal distance
2215 EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
2218 * Get the clockwise state of a map
2220 * This determines if the output points (X and Y. Z is not used) are
2221 * clockwise or counter-clockwise. This can be used for "back-face culling". This
2222 * is where you hide objects that "face away" from you. In this case objects
2223 * that are not clockwise.
2225 * @param m map to query.
2226 * @return 1 if clockwise, 0 otherwise
2228 EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m);
2231 * Create map of transformation points to be later used with an Evas object.
2233 * This creates a set of points (currently only 4 is supported. no other
2234 * number for @p count will work). That is empty and ready to be modified
2235 * with evas_map calls.
2237 * @param count number of points in the map.
2238 * @return a newly allocated map or @c NULL on errors.
2240 * @see evas_map_free()
2241 * @see evas_map_dup()
2242 * @see evas_map_point_coord_set()
2243 * @see evas_map_point_image_uv_set()
2244 * @see evas_map_util_points_populate_from_object_full()
2245 * @see evas_map_util_points_populate_from_object()
2247 * @see evas_object_map_set()
2249 EAPI Evas_Map *evas_map_new(int count);
2252 * Set the smoothing for map rendering
2254 * This sets smoothing for map rendering. If the object is a type that has
2255 * its own smoothing settings, then both the smooth settings for this object
2256 * and the map must be turned off. By default smooth maps are enabled.
2258 * @param m map to modify. Must not be NULL.
2259 * @param enabled enable or disable smooth map rendering
2261 EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled);
2264 * Get the smoothing for map rendering
2266 * This gets smoothing for map rendering.
2268 * @param m map to get the smooth from. Must not be NULL.
2269 * @return @c EINA_TRUE if the smooth is enabled, @c EINA_FALSE otherwise.
2271 EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m);
2274 * Set the alpha flag for map rendering
2276 * This sets alpha flag for map rendering. If the object is a type that has
2277 * its own alpha settings, then this will take precedence. Only image objects
2278 * have this currently.
2279 * Setting this off stops alpha blending of the map area, and is
2280 * useful if you know the object and/or all sub-objects is 100% solid.
2282 * @param m map to modify. Must not be NULL.
2283 * @param enabled enable or disable alpha map rendering
2285 EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled);
2288 * Get the alpha flag for map rendering
2290 * This gets the alpha flag for map rendering.
2292 * @param m map to get the alpha from. Must not be NULL.
2294 EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m);
2297 * Copy a previously allocated map.
2299 * This makes a duplicate of the @p m object and returns it.
2301 * @param m map to copy. Must not be NULL.
2302 * @return newly allocated map with the same count and contents as @p m.
2304 EAPI Evas_Map *evas_map_dup(const Evas_Map *m);
2307 * Free a previously allocated map.
2309 * This frees a given map @p m and all memory associated with it. You must NOT
2310 * free a map returned by evas_object_map_get() as this is internal.
2312 * @param m map to free.
2314 EAPI void evas_map_free(Evas_Map *m);
2319 * Returns the number of points in a map. Should be at least 4.
2321 * @param m map to get size.
2322 * @return -1 on error, points otherwise.
2324 EAPI int evas_map_count_get(const Evas_Map *m) EINA_CONST;
2327 * Change the map point's coordinate.
2329 * This sets the fixed point's coordinate in the map. Note that points
2330 * describe the outline of a quadrangle and are ordered either clockwise
2331 * or counter-clockwise. It is suggested to keep your quadrangles concave and
2332 * non-complex, though these polygon modes may work, they may not render
2333 * a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
2334 * 2 and 3, and 3 and 0 to describe the edges of the quadrangle.
2336 * The X and Y and Z coordinates are in canvas units. Z is optional and may
2337 * or may not be honored in drawing. Z is a hint and does not affect the
2338 * X and Y rendered coordinates. It may be used for calculating fills with
2339 * perspective correct rendering.
2341 * Remember all coordinates are canvas global ones like with move and resize
2344 * @param m map to change point. Must not be @c NULL.
2345 * @param idx index of point to change. Must be smaller than map size.
2346 * @param x Point X Coordinate
2347 * @param y Point Y Coordinate
2348 * @param z Point Z Coordinate hint (pre-perspective transform)
2350 * @see evas_map_util_rotate()
2351 * @see evas_map_util_zoom()
2352 * @see evas_map_util_points_populate_from_object_full()
2353 * @see evas_map_util_points_populate_from_object()
2355 EAPI void evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
2358 * Get the map point's coordinate.
2360 * This returns the coordinates of the given point in the map.
2362 * @param m map to query point.
2363 * @param idx index of point to query. Must be smaller than map size.
2364 * @param x where to return the X coordinate.
2365 * @param y where to return the Y coordinate.
2366 * @param z where to return the Z coordinate.
2368 EAPI void evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
2371 * Change the map point's U and V texture source point
2373 * This sets the U and V coordinates for the point. This determines which
2374 * coordinate in the source image is mapped to the given point, much like
2375 * OpenGL and textures. Notes that these points do select the pixel, but
2376 * are double floating point values to allow for accuracy and sub-pixel
2379 * @param m map to change the point of.
2380 * @param idx index of point to change. Must be smaller than map size.
2381 * @param u the X coordinate within the image/texture source
2382 * @param v the Y coordinate within the image/texture source
2384 * @see evas_map_point_coord_set()
2385 * @see evas_object_map_set()
2386 * @see evas_map_util_points_populate_from_object_full()
2387 * @see evas_map_util_points_populate_from_object()
2389 EAPI void evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v);
2392 * Get the map point's U and V texture source points
2394 * This returns the texture points set by evas_map_point_image_uv_set().
2396 * @param m map to query point.
2397 * @param idx index of point to query. Must be smaller than map size.
2398 * @param u where to write the X coordinate within the image/texture source
2399 * @param v where to write the Y coordinate within the image/texture source
2401 EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v);
2404 * Set the color of a vertex in the map
2406 * This sets the color of the vertex in the map. Colors will be linearly
2407 * interpolated between vertex points through the map. Color will multiply
2408 * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
2409 * a vertex in a map is white solid (255, 255, 255, 255) which means it will
2410 * have no affect on modifying the texture pixels.
2412 * @param m map to change the color of.
2413 * @param idx index of point to change. Must be smaller than map size.
2414 * @param r red (0 - 255)
2415 * @param g green (0 - 255)
2416 * @param b blue (0 - 255)
2417 * @param a alpha (0 - 255)
2419 * @see evas_map_util_points_color_set()
2420 * @see evas_map_point_coord_set()
2421 * @see evas_object_map_set()
2423 EAPI void evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a);
2426 * Get the color set on a vertex in the map
2428 * This gets the color set by evas_map_point_color_set() on the given vertex
2431 * @param m map to get the color of the vertex from.
2432 * @param idx index of point get. Must be smaller than map size.
2433 * @param r pointer to red return
2434 * @param g pointer to green return
2435 * @param b pointer to blue return
2436 * @param a pointer to alpha return
2438 * @see evas_map_point_coord_set()
2439 * @see evas_object_map_set()
2441 EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
2447 * @defgroup Evas_Object_Group_Size_Hints Size Hints
2449 * Objects may carry hints, so that another object that acts as a
2450 * manager (see @ref Evas_Smart_Object_Group) may know how to properly
2451 * position and resize its subordinate objects. The Size Hints provide
2452 * a common interface that is recommended as the protocol for such
2455 * For example, box objects use alignment hints to align its
2456 * lines/columns inside its container, padding hints to set the
2457 * padding between each individual child, etc.
2459 * Examples on their usage:
2460 * - @ref Example_Evas_Size_Hints "evas-hints.c"
2461 * - @ref Example_Evas_Aspect_Hints "evas-aspect-hints.c"
2463 * @ingroup Evas_Object_Group
2467 * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
2469 * Miscellaneous functions that also apply to any object, but are less
2470 * used or not implemented by all objects.
2472 * Examples on this group of functions can be found @ref
2473 * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
2475 * @ingroup Evas_Object_Group
2479 * @defgroup Evas_Object_Group_Find Finding Objects
2481 * Functions that allows finding objects by their position, name or
2484 * @ingroup Evas_Object_Group
2488 * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
2490 * Evas provides a way to intercept method calls. The interceptor
2491 * callback may opt to completely deny the call, or may check and
2492 * change the parameters before continuing. The continuation of an
2493 * intercepted call is done by calling the intercepted call again,
2494 * from inside the interceptor callback.
2496 * @ingroup Evas_Object_Group
2500 * @addtogroup Evas_Object_Group_Interceptors
2504 typedef void (*Evas_Object_Intercept_Show_Cb)(void *data, Evas_Object *obj);
2505 typedef void (*Evas_Object_Intercept_Hide_Cb)(void *data, Evas_Object *obj);
2506 typedef void (*Evas_Object_Intercept_Move_Cb)(void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
2507 typedef void (*Evas_Object_Intercept_Resize_Cb)(void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
2508 typedef void (*Evas_Object_Intercept_Raise_Cb)(void *data, Evas_Object *obj);
2509 typedef void (*Evas_Object_Intercept_Lower_Cb)(void *data, Evas_Object *obj);
2510 typedef void (*Evas_Object_Intercept_Stack_Above_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
2511 typedef void (*Evas_Object_Intercept_Stack_Below_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
2512 typedef void (*Evas_Object_Intercept_Layer_Set_Cb)(void *data, Evas_Object *obj, int l);
2513 typedef void (*Evas_Object_Intercept_Focus_Set_Cb)(void *data, Evas_Object *obj, Eina_Bool focus);
2514 typedef void (*Evas_Object_Intercept_Color_Set_Cb)(void *data, Evas_Object *obj, int r, int g, int b, int a);
2515 typedef void (*Evas_Object_Intercept_Clip_Set_Cb)(void *data, Evas_Object *obj, Evas_Object *clip);
2516 typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj);
2523 * @defgroup Evas_Object_Specific Specific Object Functions
2526 * Functions that work on specific objects.
2531 * @defgroup Evas_Object_Rectangle Rectangle Object Functions
2533 * @brief Function to create evas rectangle objects.
2535 * There is only one function to deal with rectangle objects, this may make this
2536 * function seem useless given there are no functions to manipulate the created
2537 * rectangle, however the rectangle is actually very useful and should be
2538 * manipulated using the generic @ref Evas_Object_Group "evas object functions".
2540 * The evas rectangle serves a number of key functions when working on evas
2546 * @section Background
2548 * One extremely common requirement of evas programs is to have a solid color
2549 * background, this can be accomplished with the following very simple code:
2551 * Evas_Object *bg = evas_object_rectangle_add(evas_canvas);
2552 * //Here we set the rectangles red, green, blue and opacity levels
2553 * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
2554 * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
2555 * evas_object_show(bg);
2558 * This however will have issues if the @c evas_canvas is resized, however most
2559 * windows are created using ecore evas and that has a solution to using the
2560 * rectangle as a background:
2562 * Evas_Object *bg = evas_object_rectangle_add(ecore_evas_get(ee));
2563 * //Here we set the rectangles red, green, blue and opacity levels
2564 * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
2565 * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
2566 * evas_object_show(bg);
2567 * ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE);
2569 * So this gives us a white background to our window that will be resized
2572 * @section Debugging
2574 * Debugging is a major part of any programmers task and when debugging visual
2575 * issues with evas programs the rectangle is an extremely useful tool. The
2576 * rectangle's simplicity means that it's easier to pinpoint issues with it than
2577 * with more complex objects. Therefore a common technique to use when writing
2578 * an evas program and not getting the desired visual result is to replace the
2579 * misbehaving object for a solid color rectangle and seeing how it interacts
2580 * with the other elements, this often allows us to notice clipping, parenting
2581 * or positioning issues. Once the issues have been identified and corrected the
2582 * rectangle can be replaced for the original part and in all likelihood any
2583 * remaining issues will be specific to that object's type.
2585 * @section clipping Clipping
2587 * Clipping serves two main functions:
2588 * @li Limiting visibility(i.e. hiding portions of an object).
2589 * @li Applying a layer of color to an object.
2591 * @subsection hiding Limiting visibility
2593 * It is often necessary to show only parts of an object, while it may be
2594 * possible to create an object that corresponds only to the part that must be
2595 * shown(and it isn't always possible) it's usually easier to use a a clipper. A
2596 * clipper is a rectangle that defines what's visible and what is not. The way
2597 * to do this is to create a solid white rectangle(which is the default, no need
2598 * to call evas_object_color_set()) and give it a position and size of what
2599 * should be visible. The following code exemplifies showing the center half of
2600 * @c my_evas_object:
2602 * Evas_Object *clipper = evas_object_rectangle_add(evas_canvas);
2603 * evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4);
2604 * evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2);
2605 * evas_object_clip_set(my_evas_object, clipper);
2606 * evas_object_show(clipper);
2609 * @subsection color Layer of color
2611 * In the @ref clipping section we used a solid white clipper, which produced no
2612 * change in the color of the clipped object, it just hid what was outside the
2613 * clippers area. It is however sometimes desirable to change the of color an
2614 * object, this can be accomplished using a clipper that has a non-white color.
2615 * Clippers with color work by multiplying the colors of clipped object. The
2616 * following code will show how to remove all the red from an object:
2618 * Evas_Object *clipper = evas_object_rectangle_add(evas);
2619 * evas_object_move(clipper, my_evas_object_x, my_evas_object_y);
2620 * evas_object_resize(clipper, my_evas_object_width, my_evas_object_height);
2621 * evas_object_color_set(clipper, 0, 255, 255, 255);
2622 * evas_object_clip_set(obj, clipper);
2623 * evas_object_show(clipper);
2626 * @warning We don't guarantee any proper results if you create a Rectangle
2627 * object without setting the evas engine.
2629 * For an example that more fully exercise the use of an evas object rectangle
2630 * see @ref Example_Evas_Object_Manipulation.
2632 * @ingroup Evas_Object_Specific
2636 * @defgroup Evas_Object_Image Image Object Functions
2638 * Here are grouped together functions used to create and manipulate
2639 * image objects. They are available to whichever occasion one needs
2640 * complex imagery on a GUI that could not be achieved by the other
2641 * Evas' primitive object types, or to make image manipulations.
2643 * Evas will support whichever image file types it was compiled with
2644 * support to (its image loaders) -- check your software packager for
2645 * that information and see
2646 * evas_object_image_extension_can_load_get().
2648 * @section Evas_Object_Image_Basics Image object basics
2650 * The most common use of image objects -- to display an image on the
2651 * canvas -- is achieved by a common function triplet:
2653 * img = evas_object_image_add(canvas);
2654 * evas_object_image_file_set(img, "path/to/img", NULL);
2655 * evas_object_image_fill_set(img, 0, 0, w, h);
2657 * The first function, naturally, is creating the image object. Then,
2658 * one must set an source file on it, so that it knows where to fetch
2659 * image data from. Next, one must set <b>how to fill the image
2660 * object's area</b> with that given pixel data. One could use just a
2661 * sub-region of the original image or even have it tiled repeatedly
2662 * on the image object. For the common case of having the whole source
2663 * image to be displayed on the image object, stretched to the
2664 * destination's size, there's also a function helper, to be used
2665 * instead of evas_object_image_fill_set():
2667 * evas_object_image_filled_set(img, EINA_TRUE);
2669 * See those functions' documentation for more details.
2671 * @section Evas_Object_Image_Scale Scale and resizing
2673 * Resizing of image objects will scale their respective source images
2674 * to their areas, if they are set to "fill" the object's area
2675 * (evas_object_image_filled_set()). If the user wants any control on
2676 * the aspect ratio of an image for different sizes, he/she has to
2677 * take care of that themselves. There are functions to make images to
2678 * get loaded scaled (up or down) in memory, already, if the user is
2679 * going to use them at pre-determined sizes and wants to save
2682 * Evas has even a scale cache, which will take care of caching scaled
2683 * versions of images with more often usage/hits. Finally, one can
2684 * have images being rescaled @b smoothly by Evas (more
2685 * computationally expensive) or not.
2687 * @section Evas_Object_Image_Performance Performance hints
2689 * When dealing with image objects, there are some tricks to boost the
2690 * performance of your application, if it does intense image loading
2691 * and/or manipulations, as in animations on a UI.
2693 * @subsection Evas_Object_Image_Load Load hints
2695 * In image viewer applications, for example, the user will be looking
2696 * at a given image, at full size, and will desire that the navigation
2697 * to the adjacent images on his/her album be fluid and fast. Thus,
2698 * while displaying a given image, the program can be on the
2699 * background loading the next and previous images already, so that
2700 * displaying them on the sequence is just a matter of repainting the
2701 * screen (and not decoding image data).
2703 * Evas addresses this issue with <b>image pre-loading</b>. The code
2704 * for the situation above would be something like the following:
2706 * prev = evas_object_image_filled_add(canvas);
2707 * evas_object_image_file_set(prev, "/path/to/prev", NULL);
2708 * evas_object_image_preload(prev, EINA_TRUE);
2710 * next = evas_object_image_filled_add(canvas);
2711 * evas_object_image_file_set(next, "/path/to/next", NULL);
2712 * evas_object_image_preload(next, EINA_TRUE);
2715 * If you're loading images which are too big, consider setting
2716 * previously it's loading size to something smaller, in case you
2717 * won't expose them in real size. It may speed up the loading
2720 * //to load a scaled down version of the image in memory, if that's
2721 * //the size you'll be displaying it anyway
2722 * evas_object_image_load_scale_down_set(img, zoom);
2724 * //optional: if you know you'll be showing a sub-set of the image's
2725 * //pixels, you can avoid loading the complementary data
2726 * evas_object_image_load_region_set(img, x, y, w, h);
2728 * Refer to Elementary's Photocam widget for a high level (smart)
2729 * object which does lots of loading speed-ups for you.
2731 * @subsection Evas_Object_Image_Animation Animation hints
2733 * If you want to animate image objects on a UI (what you'd get by
2734 * concomitant usage of other libraries, like Ecore and Edje), there
2735 * are also some tips on how to boost the performance of your
2736 * application. If the animation involves resizing of an image (thus,
2737 * re-scaling), you'd better turn off smooth scaling on it @b during
2738 * the animation, turning it back on afterwards, for less
2739 * computations. Also, in this case you'd better flag the image object
2740 * in question not to cache scaled versions of it:
2742 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC);
2744 * // resizing takes place in between
2746 * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC);
2749 * Finally, movement of opaque images through the canvas is less
2750 * expensive than of translucid ones, because of blending
2753 * @section Evas_Object_Image_Borders Borders
2755 * Evas provides facilities for one to specify an image's region to be
2756 * treated specially -- as "borders". This will make those regions be
2757 * treated specially on resizing scales, by keeping their aspect. This
2758 * makes setting frames around other objects on UIs easy.
2759 * See the following figures for a visual explanation:\n
2761 * <img src="image-borders.png" style="max-width: 100%;" />
2762 * <a href="image-borders.png">Full-size</a>
2764 * @image rtf image-borders.png
2765 * @image latex image-borders.eps width=\textwidth
2767 * <img src="border-effect.png" style="max-width: 100%;" />
2768 * <a href="border-effect.png">Full-size</a>
2770 * @image rtf border-effect.png
2771 * @image latex border-effect.eps width=\textwidth
2773 * @section Evas_Object_Image_Manipulation Manipulating pixels
2775 * Evas image objects can be used to manipulate raw pixels in many
2776 * ways. The meaning of the data in the pixel arrays will depend on
2777 * the image's color space, be warned (see next section). You can set
2778 * your own data as an image's pixel data, fetch an image's pixel data
2779 * for saving/altering, convert images between different color spaces
2780 * and even advanced operations like setting a native surface as image
2783 * @section Evas_Object_Image_Color_Spaces Color spaces
2785 * Image objects may return or accept "image data" in multiple
2786 * formats. This is based on the color space of an object. Here is a
2787 * rundown on formats:
2789 * - #EVAS_COLORSPACE_ARGB8888:
2790 * This pixel format is a linear block of pixels, starting at the
2791 * top-left row by row until the bottom right of the image or pixel
2792 * region. All pixels are 32-bit unsigned int's with the high-byte
2793 * being alpha and the low byte being blue in the format ARGB. Alpha
2794 * may or may not be used by evas depending on the alpha flag of the
2795 * image, but if not used, should be set to 0xff anyway.
2797 * This colorspace uses premultiplied alpha. That means that R, G
2798 * and B cannot exceed A in value. The conversion from
2799 * non-premultiplied colorspace is:
2801 * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
2803 * So 50% transparent blue will be: 0x80000080. This will not be
2804 * "dark" - just 50% transparent. Values are 0 == black, 255 ==
2805 * solid or full red, green or blue.
2807 * - #EVAS_COLORSPACE_YCBCR422P601_PL:
2808 * This is a pointer-list indirected set of YUV (YCbCr) pixel
2809 * data. This means that the data returned or set is not actual
2810 * pixel data, but pointers TO lines of pixel data. The list of
2811 * pointers will first be N rows of pointers to the Y plane -
2812 * pointing to the first pixel at the start of each row in the Y
2813 * plane. N is the height of the image data in pixels. Each pixel in
2814 * the Y, U and V planes is 1 byte exactly, packed. The next N / 2
2815 * pointers will point to rows in the U plane, and the next N / 2
2816 * pointers will point to the V plane rows. U and V planes are half
2817 * the horizontal and vertical resolution of the Y plane.
2819 * Row order is top to bottom and row pixels are stored left to
2822 * There is a limitation that these images MUST be a multiple of 2
2823 * pixels in size horizontally or vertically. This is due to the U
2824 * and V planes being half resolution. Also note that this assumes
2825 * the itu601 YUV colorspace specification. This is defined for
2826 * standard television and mpeg streams. HDTV may use the itu709
2829 * Values are 0 to 255, indicating full or no signal in that plane
2832 * - #EVAS_COLORSPACE_YCBCR422P709_PL:
2833 * Not implemented yet.
2835 * - #EVAS_COLORSPACE_RGB565_A5P:
2836 * In the process of being implemented in 1 engine only. This may
2839 * This is a pointer to image data for 16-bit half-word pixel data
2840 * in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue),
2841 * with the high-byte containing red and the low byte containing
2842 * blue, per pixel. This data is packed row by row from the top-left
2843 * to the bottom right.
2845 * If the image has an alpha channel enabled there will be an extra
2846 * alpha plane after the color pixel plane. If not, then this data
2847 * will not exist and should not be accessed in any way. This plane
2848 * is a set of pixels with 1 byte per pixel defining the alpha
2849 * values of all pixels in the image from the top-left to the bottom
2850 * right of the image, row by row. Even though the values of the
2851 * alpha pixels can be 0 to 255, only values 0 through to 32 are
2852 * used, 32 being solid and 0 being transparent.
2854 * RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
2855 * with 0 being black and 31 or 63 being full red, green or blue
2856 * respectively. This colorspace is also pre-multiplied like
2857 * EVAS_COLORSPACE_ARGB8888 so:
2859 * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
2861 * - #EVAS_COLORSPACE_GRY8:
2862 * The image is just a alpha mask (8 bit's per pixel). This is used
2863 * for alpha masking.
2865 * @warning We don't guarantee any proper results if you create a Image object
2866 * without setting the evas engine.
2868 * Some examples on this group of functions can be found @ref
2869 * Example_Evas_Images "here".
2871 * @ingroup Evas_Object_Specific
2876 typedef void (*Evas_Object_Image_Pixels_Get_Cb)(void *data, Evas_Object *o);
2879 * Check if a file extension may be supported by @ref Evas_Object_Image.
2881 * @param file The file to check
2882 * @return @c EINA_TRUE if we may be able to open it, @c EINA_FALSE if it's
2886 * If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
2888 * This functions is threadsafe.
2890 EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
2893 * Check if a file extension may be supported by @ref Evas_Object_Image.
2895 * @param file The file to check, it should be an Eina_Stringshare.
2896 * @return @c EINA_TRUE if we may be able to open it, @c EINA_FALSE if it's
2900 * This functions is threadsafe.
2902 EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
2908 * @defgroup Evas_Object_Text Text Object Functions
2910 * Functions that operate on single line, single style text objects.
2912 * For multiline and multiple style text, see @ref Evas_Object_Textblock.
2914 * See some @ref Example_Evas_Text "examples" on this group of functions.
2916 * @warning We don't guarantee any proper results if you create a Text object
2917 * without setting the evas engine.
2919 * @ingroup Evas_Object_Specific
2923 /* basic styles (4 bits allocated use 0->10 now, 5 left) */
2924 #define EVAS_TEXT_STYLE_MASK_BASIC 0xf
2927 * Text style type creation macro. Use style types on the 's'
2928 * arguments, being 'x' your style variable.
2930 #define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
2931 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
2933 #define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
2936 * Text style type creation macro. This one will impose shadow
2937 * directions on the style type variable -- use the @c
2938 * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* values on 's', incrementally.
2940 #define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
2941 do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
2943 typedef enum _Evas_Text_Style_Type
2945 EVAS_TEXT_STYLE_PLAIN, /**< plain, standard text */
2946 EVAS_TEXT_STYLE_SHADOW, /**< text with shadow underneath */
2947 EVAS_TEXT_STYLE_OUTLINE, /**< text with an outline */
2948 EVAS_TEXT_STYLE_SOFT_OUTLINE, /**< text with a soft outline */
2949 EVAS_TEXT_STYLE_GLOW, /**< text with a glow effect */
2950 EVAS_TEXT_STYLE_OUTLINE_SHADOW, /**< text with both outline and shadow effects */
2951 EVAS_TEXT_STYLE_FAR_SHADOW, /**< text with (far) shadow underneath */
2952 EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW, /**< text with outline and soft shadow effects combined */
2953 EVAS_TEXT_STYLE_SOFT_SHADOW, /**< text with (soft) shadow underneath */
2954 EVAS_TEXT_STYLE_FAR_SOFT_SHADOW, /**< text with (far soft) shadow underneath */
2956 /* OR these to modify shadow direction (3 bits needed) */
2957 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< shadow growing to bottom right */
2958 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< shadow growing to the bottom */
2959 EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< shadow growing to bottom left */
2960 EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< shadow growing to the left */
2961 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< shadow growing to top left */
2962 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< shadow growing to the top */
2963 EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< shadow growing to top right */
2964 EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< shadow growing to the right */
2965 } Evas_Text_Style_Type; /**< Types of styles to be applied on text objects. The @c EVAS_TEXT_STYLE_SHADOW_DIRECTION_* ones are to be ORed together with others imposing shadow, to change shadow's direction */
2972 * @defgroup Evas_Object_Textblock Textblock Object Functions
2974 * Functions used to create and manipulate textblock objects. Unlike
2975 * @ref Evas_Object_Text, these handle complex text, doing multiple
2976 * styles and multiline text based on HTML-like tags. Of these extra
2977 * features will be heavier on memory and processing cost.
2979 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
2981 * This part explains about the textblock object's API and proper usage.
2982 * The main user of the textblock object is the edje entry object in Edje, so
2983 * that's a good place to learn from, but I think this document is more than
2984 * enough, if it's not, please contact me and I'll update it.
2986 * @subsection textblock_intro Introduction
2987 * The textblock objects is, as implied, an object that can show big chunks of
2988 * text. Textblock supports many features including: Text formatting, automatic
2989 * and manual text alignment, embedding items (for example icons) and more.
2990 * Textblock has three important parts, the text paragraphs, the format nodes
2993 * You can use markup to format text, for example: "<font_size=50>Big!</font_size>".
2994 * You can also put more than one style directive in one tag:
2995 * "<font_size=50 color=#F00>Big and Red!</font_size>".
2996 * Please notice that we used "</font_size>" although the format also included
2997 * color, this is because the first format determines the matching closing tag's
2998 * name. You can also use anonymous tags, like: "<font_size=30>Big</>" which
2999 * just pop any type of format, but it's advised to use the named alternatives
3002 * @subsection textblock_cursors Textblock Object Cursors
3003 * A textblock Cursor is data type that represents
3004 * a position in a textblock. Each cursor contains information about the
3005 * paragraph it points to, the position in that paragraph and the object itself.
3006 * Cursors register to textblock objects upon creation, this means that once
3007 * you created a cursor, it belongs to a specific obj and you can't for example
3008 * copy a cursor "into" a cursor of a different object. Registered cursors
3009 * also have the added benefit of updating automatically upon textblock changes,
3010 * this means that if you have a cursor pointing to a specific character, it'll
3011 * still point to it even after you change the whole object completely (as long
3012 * as the char was not deleted), this is not possible without updating, because
3013 * as mentioned, each cursor holds a character position. There are many
3014 * functions that handle cursors, just check out the evas_textblock_cursor*
3015 * functions. For creation and deletion of cursors check out:
3016 * @see evas_object_textblock_cursor_new()
3017 * @see evas_textblock_cursor_free()
3018 * @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).
3020 * @subsection textblock_paragraphs Textblock Object Paragraphs
3021 * The textblock object is made out of text splitted to paragraphs (delimited
3022 * by the paragraph separation character). Each paragraph has many (or none)
3023 * format nodes associated with it which are responsible for the formatting
3024 * of that paragraph.
3026 * @subsection textblock_format_nodes Textblock Object Format Nodes
3027 * As explained in @ref textblock_paragraphs each one of the format nodes
3028 * is associated with a paragraph.
3029 * There are two types of format nodes, visible and invisible:
3030 * Visible: formats that a cursor can point to, i.e formats that
3031 * occupy space, for example: newlines, tabs, items and etc. Some visible items
3032 * are made of two parts, in this case, only the opening tag is visible.
3033 * A closing tag (i.e a \</tag\> tag) should NEVER be visible.
3034 * Invisible: formats that don't occupy space, for example: bold and underline.
3035 * Being able to access format nodes is very important for some uses. For
3036 * example, edje uses the "<a>" format to create links in the text (and pop
3037 * popups above them when clicked). For the textblock object a is just a
3038 * formatting instruction (how to color the text), but edje utilizes the access
3039 * to the format nodes to make it do more.
3040 * For more information, take a look at all the evas_textblock_node_format_*
3042 * The translation of "<tag>" tags to actual format is done according to the
3043 * tags defined in the style, see @ref evas_textblock_style_set
3045 * @subsection textblock_special_formats Special Formats
3046 * Textblock supports various format directives that can be used in markup. In
3047 * addition to the mentioned format directives, textblock allows creating
3048 * additional format directives using "tags" that can be set in the style see
3049 * @ref evas_textblock_style_set .
3051 * For more details see @ref evas_textblock_style_page
3053 * Textblock supports the following formats:
3054 * @li font - Font description in fontconfig like format, e.g: "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
3055 * @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".
3056 * @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".
3057 * @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".
3058 * @li lang - Overrides the language defined in "font". E.g: "lang=he" is the same as "font=:lang=he".
3059 * @li font_fallbacks - A comma delimited list of fonts to try if finding the main font fails.
3060 * @li font_size - The font size in points.
3061 * @li font_source - The source of the font, e.g an eet file.
3062 * @li color - Text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3063 * @li underline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3064 * @li underline2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3065 * @li outline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3066 * @li shadow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3067 * @li glow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3068 * @li glow2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3069 * @li strikethrough_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3070 * @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%.
3071 * @li valign - Either "top", "bottom", "middle", "center", "baseline", "base", a value between 0.0 and 1.0, or a value between 0% to 100%.
3072 * @li wrap - "word", "char", "mixed", or "none".
3073 * @li left_margin - Either "reset", or a pixel value indicating the margin.
3074 * @li right_margin - Either "reset", or a pixel value indicating the margin.
3075 * @li underline - "on", "off", "single", or "double".
3076 * @li strikethrough - "on" or "off"
3077 * @li backing_color - Background color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
3078 * @li backing - Enable/disable background color. ex) "on" or "off"
3079 * @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".
3080 * @li tabstops - Pixel value for tab width.
3081 * @li linesize - Force a line size in pixels.
3082 * @li linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
3083 * @li linegap - Force a line gap in pixels.
3084 * @li linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
3085 * @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.
3086 * @li linefill - Either a float value or percentage indicating how much to fill the line.
3087 * @li ellipsis - Value between 0.0-1.0 to indicate the type of ellipsis, or -1.0 to indicate ellipsis isn't wanted.
3088 * @li password - "on" or "off". This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off.
3090 * @warning We don't guarantee any proper results if you create a Textblock
3092 * without setting the evas engine.
3094 * @todo put here some usage examples
3096 * @ingroup Evas_Object_Specific
3101 typedef struct _Evas_Textblock_Style Evas_Textblock_Style;
3102 typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor;
3104 * @typedef Evas_Object_Textblock_Node_Format
3107 typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
3108 typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
3110 struct _Evas_Textblock_Rectangle
3112 Evas_Coord x, y, w, h;
3115 typedef enum _Evas_Textblock_Text_Type
3117 EVAS_TEXTBLOCK_TEXT_RAW,
3118 EVAS_TEXTBLOCK_TEXT_PLAIN,
3119 EVAS_TEXTBLOCK_TEXT_MARKUP
3120 } Evas_Textblock_Text_Type;
3122 typedef enum _Evas_Textblock_Cursor_Type
3124 EVAS_TEXTBLOCK_CURSOR_UNDER,
3125 EVAS_TEXTBLOCK_CURSOR_BEFORE
3126 } Evas_Textblock_Cursor_Type;
3129 * Returns the unescaped version of escape.
3130 * @param escape the string to be escaped
3131 * @return the unescaped version of escape
3133 EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3136 * Returns the escaped version of the string.
3137 * @param string to escape
3138 * @param len_ret the len of the part of the string that was used.
3139 * @return the escaped string.
3141 EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3144 * Return the unescaped version of the string between start and end.
3146 * @param escape_start the start of the string.
3147 * @param escape_end the end of the string.
3148 * @return the unescaped version of the range
3150 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);
3153 * Creates a new textblock style.
3154 * @return The new textblock style.
3156 EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
3159 * Destroys a textblock style.
3160 * @param ts The textblock style to free.
3162 EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
3165 * Sets the style ts to the style passed as text by text.
3166 * Expected a string consisting of many (or none) tag='format' pairs.
3168 * @param ts the style to set.
3169 * @param text the text to parse - NOT NULL.
3170 * @return Returns no value.
3172 EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
3175 * Return the text of the style ts.
3176 * @param ts the style to get it's text.
3177 * @return the text of the style or null on error.
3179 EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3182 * Prepends markup to the cursor cur.
3184 * @note assumes text does not include the unicode object replacement char (0xFFFC)
3186 * @param cur the cursor to prepend to.
3187 * @param text the markup text to prepend.
3188 * @return Return no value.
3190 EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
3193 * Free the cursor and unassociate it from the object.
3194 * @note do not use it to free unassociated cursors.
3196 * @param cur the cursor to free.
3197 * @return Returns no value.
3199 EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3202 * Sets the cursor to the start of the first text node.
3204 * @param cur the cursor to update.
3205 * @return Returns no value.
3207 EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3210 * sets the cursor to the end of the last text node.
3212 * @param cur the cursor to set.
3213 * @return Returns no value.
3215 EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3218 * Advances to the start of the next text node
3220 * @param cur the cursor to update
3221 * @return @c EINA_TRUE if it managed to advance a paragraph, @c EINA_FALSE
3224 EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3227 * Advances to the end of the previous text node
3229 * @param cur the cursor to update
3230 * @return @c EINA_TRUE if it managed to advance a paragraph, @c EINA_FALSE
3233 EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3236 * Returns the next format node (after n)
3238 * @param n the current format node - not null.
3239 * @return Returns the next format node, may be null.
3241 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
3244 * Returns the prev format node (after n)
3246 * @param n the current format node - not null.
3247 * @return Returns the prev format node, may be null.
3249 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
3252 * Sets the cursor to point to the place where format points to.
3254 * @param cur the cursor to update.
3255 * @param n the format node to update according.
3256 * @deprecated duplicate of evas_textblock_cursor_at_format_set
3258 EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
3261 * Return the format node at the position pointed by cur.
3263 * @param cur the position to look at.
3264 * @return the format node if found, @c NULL otherwise.
3265 * @see evas_textblock_cursor_format_is_visible_get()
3267 EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3270 * Get the text format representation of the format node.
3272 * @param fnode the format node.
3273 * @return the textual format of the format node.
3275 EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fnode) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3278 * Set the cursor to point to the position of fmt.
3280 * @param cur the cursor to update
3281 * @param fmt the format to update according to.
3283 EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
3286 * Check if the current cursor position is a visible format. This way is more
3287 * efficient than evas_textblock_cursor_format_get() to check for the existence
3288 * of a visible format.
3290 * @param cur the cursor to look at.
3291 * @return @c EINA_TRUE if the cursor points to a visible format, @c EINA_FALSE
3293 * @see evas_textblock_cursor_format_get()
3295 EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3298 * Advances to the next format node
3300 * @param cur the cursor to be updated.
3301 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3303 EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3306 * Advances to the previous format node.
3308 * @param cur the cursor to update.
3309 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3311 EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3314 * Returns true if the cursor points to a format.
3316 * @param cur the cursor to check.
3317 * @return @c EINA_TRUE if a cursor points to a format @c EINA_FALSE
3320 EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3323 * Advances 1 char forward.
3325 * @param cur the cursor to advance.
3326 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3328 EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3331 * Advances 1 char backward.
3333 * @param cur the cursor to advance.
3334 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3336 EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3339 * Moves the cursor to the start of the word under the cursor.
3341 * @param cur the cursor to move.
3342 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3345 EAPI Eina_Bool evas_textblock_cursor_word_start(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3348 * Moves the cursor to the end of the word under the cursor.
3350 * @param cur the cursor to move.
3351 * @return @c EINA_TRUE on success @c EINA_FALSE otherwise.
3354 EAPI Eina_Bool evas_textblock_cursor_word_end(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3357 * Go to the first char in the node the cursor is pointing on.
3359 * @param cur the cursor to update.
3360 * @return Returns no value.
3362 EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3365 * Go to the last char in a text node.
3367 * @param cur the cursor to update.
3368 * @return Returns no value.
3370 EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3373 * Go to the start of the current line
3375 * @param cur the cursor to update.
3376 * @return Returns no value.
3378 EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3381 * Go to the end of the current line.
3383 * @param cur the cursor to update.
3384 * @return Returns no value.
3386 EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3389 * Return the current cursor pos.
3391 * @param cur the cursor to take the position from.
3392 * @return the position or -1 on error
3394 EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3397 * Set the cursor pos.
3399 * @param cur the cursor to be set.
3400 * @param pos the pos to set.
3402 EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
3405 * Go to the start of the line passed
3407 * @param cur cursor to update.
3408 * @param line numer to set.
3409 * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
3411 EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
3414 * Compare two cursors.
3416 * @param cur1 the first cursor.
3417 * @param cur2 the second cursor.
3418 * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
3420 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);
3423 * Make cur_dest point to the same place as cur. Does not work if they don't
3424 * point to the same object.
3426 * @param cur the source cursor.
3427 * @param cur_dest destination cursor.
3428 * @return Returns no value.
3430 EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
3433 * Adds text to the current cursor position and set the cursor to *before*
3434 * the start of the text just added.
3436 * @param cur the cursor to where to add text at.
3437 * @param text the text to add.
3438 * @return Returns the len of the text added.
3439 * @see evas_textblock_cursor_text_prepend()
3441 EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
3444 * Adds text to the current cursor position and set the cursor to *after*
3445 * the start of the text just added.
3447 * @param cur the cursor to where to add text at.
3448 * @param text the text to add.
3449 * @return Returns the len of the text added.
3450 * @see evas_textblock_cursor_text_append()
3452 EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
3455 * Adds format to the current cursor position. If the format being added is a
3456 * visible format, add it *before* the cursor position, otherwise, add it after.
3457 * This behavior is because visible formats are like characters and invisible
3458 * should be stacked in a way that the last one is added last.
3460 * This function works with native formats, that means that style defined
3461 * tags like <br> won't work here. For those kind of things use markup prepend.
3463 * @param cur the cursor to where to add format at.
3464 * @param format the format to add.
3465 * @return Returns true if a visible format was added, false otherwise.
3466 * @see evas_textblock_cursor_format_prepend()
3470 * Check if the current cursor position points to the terminating null of the
3471 * last paragraph. (shouldn't be allowed to point to the terminating null of
3472 * any previous paragraph anyway.
3474 * @param cur the cursor to look at.
3475 * @return @c EINA_TRUE if the cursor points to the terminating null, @c EINA_FALSE otherwise.
3477 EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
3480 * Adds format to the current cursor position. If the format being added is a
3481 * visible format, add it *before* the cursor position, otherwise, add it after.
3482 * This behavior is because visible formats are like characters and invisible
3483 * should be stacked in a way that the last one is added last.
3484 * If the format is visible the cursor is advanced after it.
3486 * This function works with native formats, that means that style defined
3487 * tags like <br> won't work here. For those kind of things use markup prepend.
3489 * @param cur the cursor to where to add format at.
3490 * @param format the format to add.
3491 * @return Returns true if a visible format was added, false otherwise.
3492 * @see evas_textblock_cursor_format_prepend()
3494 EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
3497 * Delete the character at the location of the cursor. If there's a format
3498 * pointing to this position, delete it as well.
3500 * @param cur the cursor pointing to the current location.
3501 * @return Returns no value.
3503 EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
3506 * Delete the range between cur1 and cur2.
3508 * @param cur1 one side of the range.
3509 * @param cur2 the second side of the range
3510 * @return Returns no value.
3512 EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
3515 * Return the text of the paragraph cur points to - returns the text in markup.
3517 * @param cur the cursor pointing to the paragraph.
3518 * @return the text on success, @c NULL otherwise.
3520 EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3523 * Return the length of the paragraph, cheaper the eina_unicode_strlen()
3525 * @param cur the position of the paragraph.
3526 * @return the length of the paragraph on success, -1 otehrwise.
3528 EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3531 * Return the currently visible range.
3533 * @param start the start of the range.
3534 * @param end the end of the range.
3535 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
3538 EAPI Eina_Bool evas_textblock_cursor_visible_range_get(Evas_Textblock_Cursor *start, Evas_Textblock_Cursor *end) EINA_ARG_NONNULL(1, 2);
3541 * Return the format nodes in the range between cur1 and cur2.
3543 * @param cur1 one side of the range.
3544 * @param cur2 the other side of the range
3545 * @return the foramt nodes in the range. You have to free it.
3548 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);
3551 * Return the text in the range between cur1 and cur2
3553 * @param cur1 one side of the range.
3554 * @param cur2 the other side of the range
3555 * @param format The form on which to return the text. Markup - in textblock markup. Plain - UTF8.
3556 * @return the text in the range
3557 * @see elm_entry_markup_to_utf8()
3559 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);
3562 * Return the content of the cursor.
3564 * Free the returned string pointer when done (if it is not NULL).
3566 * @param cur the cursor
3567 * @return the text in the range, terminated by a nul byte (may be utf8).
3569 EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
3572 * Returns the geometry of two cursors ("split cursor"), if logical cursor is
3573 * between LTR/RTL text, also considering paragraph direction.
3574 * Upper cursor is shown for the text of the same direction as paragraph,
3575 * lower cursor - for opposite.
3577 * Split cursor geometry is valid only in '|' cursor mode.
3578 * In this case @c EINA_TRUE is returned and cx2, cy2, cw2, ch2 are set,
3579 * otherwise it behaves like cursor_geometry_get.
3581 * @param[in] cur the cursor.
3582 * @param[out] cx the x of the cursor (or upper cursor)
3583 * @param[out] cy the y of the cursor (or upper cursor)
3584 * @param[out] cw the width of the cursor (or upper cursor)
3585 * @param[out] ch the height of the cursor (or upper cursor)
3586 * @param[out] cx2 the x of the lower cursor
3587 * @param[out] cy2 the y of the lower cursor
3588 * @param[out] cw2 the width of the lower cursor
3589 * @param[out] ch2 the height of the lower cursor
3590 * @param[in] ctype the type of the cursor.
3591 * @return @c EINA_TRUE for split cursor, @c EINA_FALSE otherwise
3595 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);
3598 * Returns the geometry of the cursor. Depends on the type of cursor requested.
3599 * This should be used instead of char_geometry_get because there are weird
3600 * special cases with BiDi text.
3601 * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
3602 * get, except for the case of the last char of a line which depends on the
3603 * paragraph direction.
3605 * in '|' cursor mode (i.e a line between two chars) it is very variable.
3606 * For example consider the following visual string:
3607 * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
3608 * a '|' between the c and the C.
3610 * @param cur the cursor.
3611 * @param cx the x of the cursor
3612 * @param cy the y of the cursor
3613 * @param cw the width of the cursor
3614 * @param ch the height of the cursor
3615 * @param dir the direction of the cursor, can be NULL.
3616 * @param ctype the type of the cursor.
3617 * @return line number of the char on success, -1 on error.
3619 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);
3622 * Returns the geometry of the char at cur.
3624 * @param cur the position of the char.
3625 * @param cx the x of the char.
3626 * @param cy the y of the char.
3627 * @param cw the w of the char.
3628 * @param ch the h of the char.
3629 * @return line number of the char on success, -1 on error.
3631 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);
3634 * Returns the geometry of the pen at cur.
3636 * @param cur the position of the char.
3637 * @param cpen_x the pen_x of the char.
3638 * @param cy the y of the char.
3639 * @param cadv the adv of the char.
3640 * @param ch the h of the char.
3641 * @return line number of the char on success, -1 on error.
3643 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);
3646 * Returns the geometry of the line at cur.
3648 * @param cur the position of the line.
3649 * @param cx the x of the line.
3650 * @param cy the y of the line.
3651 * @param cw the width of the line.
3652 * @param ch the height of the line.
3653 * @return line number of the line on success, -1 on error.
3655 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);
3658 * Set the position of the cursor according to the X and Y coordinates.
3660 * @param cur the cursor to set.
3661 * @param x coord to set by.
3662 * @param y coord to set by.
3663 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
3665 EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
3668 * Set the cursor position according to the y coord.
3670 * @param cur the cur to be set.
3671 * @param y the coord to set by.
3672 * @return the line number found, -1 on error.
3674 EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
3677 * Get the geometry of a range.
3679 * @param cur1 one side of the range.
3680 * @param cur2 other side of the range.
3681 * @return a list of Rectangles representing the geometry of the range.
3683 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);
3684 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);
3687 * Checks if the cursor points to the end of the line.
3689 * @param cur the cursor to check.
3690 * @return @c EINA_TRUE if true, @c EINA_FALSE otherwise.
3692 EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
3699 * @defgroup Evas_Object_Textgrid Textgrid Object Functions
3701 * @todo put here some usage examples
3705 * @ingroup Evas_Object_Specific
3711 * @typedef Evas_Textgrid_Palette
3713 * The palette to use for the foreground and background colors.
3719 EVAS_TEXTGRID_PALETTE_NONE, /**< No palette is used */
3720 EVAS_TEXTGRID_PALETTE_STANDARD, /**< standard palette (around 16 colors) */
3721 EVAS_TEXTGRID_PALETTE_EXTENDED, /**< extended palette (at max 256 colors) */
3722 EVAS_TEXTGRID_PALETTE_LAST /**< ignore it */
3723 } Evas_Textgrid_Palette;
3726 * @typedef Evas_Textgrid_Font_Style
3728 * The style to give to each character of the grid.
3734 EVAS_TEXTGRID_FONT_STYLE_NORMAL = (1 << 0), /**< Normal style */
3735 EVAS_TEXTGRID_FONT_STYLE_BOLD = (1 << 1), /**< Bold style */
3736 EVAS_TEXTGRID_FONT_STYLE_ITALIC = (1 << 2) /**< Oblique style */
3737 } Evas_Textgrid_Font_Style;
3740 * @typedef Evas_Textgrid_Cell
3742 * The values that describes each cell.
3746 typedef struct _Evas_Textgrid_Cell Evas_Textgrid_Cell;
3749 * @struct _Evas_Textgrid_Cell
3751 * The values that describes each cell.
3755 struct _Evas_Textgrid_Cell
3757 Eina_Unicode codepoint; /**< the UNICODE value of the character */
3758 unsigned char fg; /**< the index of the palette for the foreground color */
3759 unsigned char bg; /**< the index of the palette for the background color */
3760 unsigned short bold : 1; /**< whether the character is bold */
3761 unsigned short italic : 1; /**< whether the character is oblique */
3762 unsigned short underline : 1; /**< whether the character is underlined */
3763 unsigned short strikethrough : 1; /**< whether the character is strikethrough'ed */
3764 unsigned short fg_extended : 1; /**< whether the extended palette is used for the foreground color */
3765 unsigned short bg_extended : 1; /**< whether the extended palette is used for the background color */
3766 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) */
3774 * @defgroup Evas_Line_Group Line Object Functions
3776 * Functions used to deal with evas line objects.
3778 * @warning We don't guarantee any proper results if you create a Line object
3779 * without setting the evas engine.
3781 * @ingroup Evas_Object_Specific
3786 * @defgroup Evas_Object_Polygon Polygon Object Functions
3788 * Functions that operate on evas polygon objects.
3790 * Hint: as evas does not provide ellipse, smooth paths or circle, one
3791 * can calculate points and convert these to a polygon.
3793 * @warning We don't guarantee any proper results if you create a Polygon
3794 * object without setting the evas engine.
3796 * @ingroup Evas_Object_Specific
3801 * @defgroup Evas_Smart_Group Smart Functions
3804 * Functions that deal with #Evas_Smart structs, creating definition
3805 * (classes) of objects that will have customized behavior for methods
3806 * like evas_object_move(), evas_object_resize(),
3807 * evas_object_clip_set() and others.
3809 * These objects will accept the generic methods defined in @ref
3810 * Evas_Object_Group and the extensions defined in @ref
3811 * Evas_Smart_Object_Group. There are a couple of existent smart
3812 * objects in Evas itself (see @ref Evas_Object_Box, @ref
3813 * Evas_Object_Table and @ref Evas_Smart_Object_Clipped).
3815 * See also some @ref Example_Evas_Smart_Objects "examples" of this
3816 * group of functions.
3823 * @def EVAS_SMART_CLASS_VERSION
3825 * The version you have to put into the version field in the
3826 * #Evas_Smart_Class struct. Used to safeguard from binaries with old
3827 * smart object intefaces running with newer ones.
3829 * @ingroup Evas_Smart_Group
3831 #define EVAS_SMART_CLASS_VERSION 4
3833 * @struct _Evas_Smart_Class
3835 * A smart object's @b base class definition
3837 * @ingroup Evas_Smart_Group
3839 struct _Evas_Smart_Class
3841 const char *name; /**< the name string of the class */
3843 void (*add)(Evas_Object *o); /**< code to be run when adding object to a canvas */
3844 void (*del)(Evas_Object *o); /**< code to be run when removing object from a canvas */
3845 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. */
3846 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. */
3847 void (*show)(Evas_Object *o); /**< code to be run when showing object on a canvas */
3848 void (*hide)(Evas_Object *o); /**< code to be run when hiding object on a canvas */
3849 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. */
3850 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. */
3851 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. */
3852 void (*calculate)(Evas_Object *o); /**< code to be run when object has rendering updates on a canvas */
3853 void (*member_add)(Evas_Object *o, Evas_Object *child); /**< code to be run when a child member is added to object */
3854 void (*member_del)(Evas_Object *o, Evas_Object *child); /**< code to be run when a child member is removed from object */
3856 const Evas_Smart_Class *parent; /**< this class inherits from this parent */
3857 const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, @c NULL terminated */
3858 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 */
3863 * @struct _Evas_Smart_Interface
3865 * A smart object's @b base interface definition
3867 * Every Evas interface must have a name field, pointing to a global,
3868 * constant string variable. This string pointer will be the only way
3869 * of retrieving back a given interface from a smart object. Two
3870 * function pointers must be defined, too, which will be called at
3871 * object creation and deletion times.
3873 * See also some @ref Example_Evas_Smart_Interfaces "examples" on
3878 * @ingroup Evas_Smart_Group
3880 struct _Evas_Smart_Interface
3882 const char *name; /**< Name of the given interface */
3883 unsigned private_size; /**< Size, in bytes, of the interface's private dada blob. This will be allocated and freed automatically for you. Get it with evas_object_smart_interface_data_get(). */
3884 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. */
3885 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. */
3889 * @struct _Evas_Smart_Cb_Description
3891 * Describes a callback issued by a smart object
3892 * (evas_object_smart_callback_call()), as defined in its smart object
3893 * class. This is particularly useful to explain to end users and
3894 * their code (i.e., introspection) what the parameter @c event_info
3897 * @ingroup Evas_Smart_Group
3899 struct _Evas_Smart_Cb_Description
3901 const char *name; /**< callback name ("changed", for example) */
3904 * @brief Hint on the type of @c event_info parameter's contents on
3905 * a #Evas_Smart_Cb callback.
3907 * The type string uses the pattern similar to
3908 * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures,
3909 * but extended to optionally include variable names within
3910 * brackets preceding types. Example:
3912 * @li Structure with two integers:
3915 * @li Structure called 'x' with two integers named 'a' and 'b':
3916 * @c "[x]([a]i[b]i)"
3918 * @li Array of integers:
3921 * @li Array called 'x' of struct with two integers:
3924 * @note This type string is used as a hint and is @b not validated
3925 * or enforced in any way. Implementors should make the best
3926 * use of it to help bindings, documentation and other users
3927 * of introspection features.
3933 * @def EVAS_SMART_CLASS_INIT_NULL
3934 * Initializer to zero a whole Evas_Smart_Class structure.
3936 * @see EVAS_SMART_CLASS_INIT_VERSION
3937 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
3938 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
3939 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
3940 * @ingroup Evas_Smart_Group
3942 #define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
3945 * @def EVAS_SMART_CLASS_INIT_VERSION
3946 * Initializer to zero a whole Evas_Smart_Class structure and set version.
3948 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
3949 * latest EVAS_SMART_CLASS_VERSION.
3951 * @see EVAS_SMART_CLASS_INIT_NULL
3952 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
3953 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
3954 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
3955 * @ingroup Evas_Smart_Group
3957 #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}
3960 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
3961 * Initializer to zero a whole Evas_Smart_Class structure and set name
3964 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
3965 * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
3967 * It will keep a reference to name field as a "const char *", that is,
3968 * name must be available while the structure is used (hint: static or global!)
3969 * and will not be modified.
3971 * @see EVAS_SMART_CLASS_INIT_NULL
3972 * @see EVAS_SMART_CLASS_INIT_VERSION
3973 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
3974 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
3975 * @ingroup Evas_Smart_Group
3977 #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}
3980 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
3981 * Initializer to zero a whole Evas_Smart_Class structure and set name,
3982 * version and parent class.
3984 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
3985 * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
3988 * It will keep a reference to name field as a "const char *", that is,
3989 * name must be available while the structure is used (hint: static or global!)
3990 * and will not be modified. Similarly, parent reference will be kept.
3992 * @see EVAS_SMART_CLASS_INIT_NULL
3993 * @see EVAS_SMART_CLASS_INIT_VERSION
3994 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
3995 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
3996 * @ingroup Evas_Smart_Group
3998 #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}
4001 * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
4002 * Initializer to zero a whole Evas_Smart_Class structure and set name,
4003 * version, parent class and callbacks definition.
4005 * Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
4006 * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
4007 * class and callbacks at this level.
4009 * It will keep a reference to name field as a "const char *", that is,
4010 * name must be available while the structure is used (hint: static or global!)
4011 * and will not be modified. Similarly, parent and callbacks reference
4014 * @see EVAS_SMART_CLASS_INIT_NULL
4015 * @see EVAS_SMART_CLASS_INIT_VERSION
4016 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4017 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
4018 * @ingroup Evas_Smart_Group
4020 #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}
4023 * @def EVAS_SMART_SUBCLASS_NEW
4025 * Convenience macro to subclass a given Evas smart class.
4027 * @param smart_name The name used for the smart class. e.g:
4028 * @c "Evas_Object_Box".
4029 * @param prefix Prefix used for all variables and functions defined
4030 * and referenced by this macro.
4031 * @param api_type Type of the structure used as API for the smart
4032 * class. Either #Evas_Smart_Class or something derived from it.
4033 * @param parent_type Type of the parent class API.
4034 * @param parent_func Function that gets the parent class. e.g:
4035 * evas_object_box_smart_class_get().
4036 * @param cb_desc Array of callback descriptions for this smart class.
4038 * This macro saves some typing when writing a smart class derived
4039 * from another one. In order to work, the user @b must provide some
4040 * functions adhering to the following guidelines:
4041 * - @<prefix@>_smart_set_user(): the @b internal @c _smart_set
4042 * function (defined by this macro) will call this one, provided by
4043 * the user, after inheriting everything from the parent, which
4044 * should <b>take care of setting the right member functions for
4045 * the class</b>, both overrides and extensions, if any.
4046 * - If this new class should be subclassable as well, a @b public
4047 * @c _smart_set() function is desirable to fill in the class used as
4048 * parent by the children. It's up to the user to provide this
4049 * interface, which will most likely call @<prefix@>_smart_set() to
4052 * After the macro's usage, the following will be defined for use:
4053 * - @<prefix@>_parent_sc: A pointer to the @b parent smart
4054 * class. When calling parent functions from overloaded ones, use
4055 * this global variable.
4056 * - @<prefix@>_smart_class_new(): this function returns the
4057 * #Evas_Smart needed to create smart objects with this class,
4058 * which should be passed to evas_object_smart_add().
4060 * @warning @p smart_name has to be a pointer to a globally available
4061 * string! The smart class created here will just have a pointer set
4062 * to that, and all object instances will depend on it for smart class
4065 * @ingroup Evas_Smart_Group
4067 #define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
4068 static const parent_type * prefix##_parent_sc = NULL; \
4069 static void prefix##_smart_set_user(api_type * api); \
4070 static void prefix##_smart_set(api_type * api) \
4072 Evas_Smart_Class *sc; \
4073 if (!(sc = (Evas_Smart_Class *)api)) \
4075 if (!prefix##_parent_sc) \
4076 prefix##_parent_sc = parent_func(); \
4077 evas_smart_class_inherit(sc, prefix##_parent_sc); \
4078 prefix##_smart_set_user(api); \
4080 static Evas_Smart *prefix##_smart_class_new(void) \
4082 static Evas_Smart *smart = NULL; \
4083 static api_type api; \
4086 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
4087 memset(&api, 0, sizeof(api_type)); \
4088 sc->version = EVAS_SMART_CLASS_VERSION; \
4089 sc->name = smart_name; \
4090 sc->callbacks = cb_desc; \
4091 prefix##_smart_set(&api); \
4092 smart = evas_smart_class_new(sc); \
4098 * @def EVAS_SMART_SUBCLASS_IFACE_NEW
4102 * Convenience macro to subclass a given Evas smart class. This is the
4103 * same as #EVAS_SMART_SUBCLASS_NEW, but now <b>declaring smart
4104 * interfaces</b> besides the smart callbacks.
4106 * @param smart_name The name used for the smart class. e.g:
4107 * @c "Evas_Object_Box".
4108 * @param prefix Prefix used for all variables and functions defined
4109 * and referenced by this macro.
4110 * @param api_type Type of the structure used as API for the smart
4111 * class. Either #Evas_Smart_Class or something
4113 * @param parent_type Type of the parent class API.
4114 * @param parent_func Function that gets the parent class. e.g:
4115 * evas_object_box_smart_class_get().
4116 * @param cb_desc Array of smart callback descriptions for this smart
4118 * @param ifaces Array of Evas smart interafaces for this smart
4121 * This macro saves some typing when writing a smart class derived
4122 * from another one. In order to work, the user @b must provide some
4123 * functions adhering to the following guidelines:
4124 * - @<prefix@>_smart_set_user(): the @b internal @c _smart_set
4125 * function (defined by this macro) will call this one, provided by
4126 * the user, after inheriting everything from the parent, which
4127 * should <b>take care of setting the right member functions for
4128 * the class</b>, both overrides and extensions, if any.
4129 * - If this new class should be subclassable as well, a @b public
4130 * @c _smart_set() function is desirable to fill in the class used as
4131 * parent by the children. It's up to the user to provide this
4132 * interface, which will most likely call @<prefix@>_smart_set() to
4135 * After the macro's usage, the following will be defined for use:
4136 * - @<prefix@>_parent_sc: A pointer to the @b parent smart
4137 * class. When calling parent functions from overloaded ones, use
4138 * this global variable.
4139 * - @<prefix@>_smart_class_new(): this function returns the
4140 * #Evas_Smart needed to create smart objects with this class,
4141 * which should be passed to evas_object_smart_add().
4143 * @warning @p smart_name has to be a pointer to a globally available
4144 * string! The smart class created here will just have a pointer set
4145 * to that, and all object instances will depend on it for smart class
4148 * @ingroup Evas_Smart_Group
4150 #define EVAS_SMART_SUBCLASS_IFACE_NEW(smart_name, \
4157 static const parent_type * prefix##_parent_sc = NULL; \
4158 static void prefix##_smart_set_user(api_type * api); \
4159 static void prefix##_smart_set(api_type * api) \
4161 Evas_Smart_Class *sc; \
4162 if (!(sc = (Evas_Smart_Class *)api)) \
4164 if (!prefix##_parent_sc) \
4165 prefix##_parent_sc = parent_func(); \
4166 evas_smart_class_inherit(sc, prefix##_parent_sc); \
4167 prefix##_smart_set_user(api); \
4169 static Evas_Smart *prefix##_smart_class_new(void) \
4171 static Evas_Smart *smart = NULL; \
4172 static api_type api; \
4175 Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
4176 memset(&api, 0, sizeof(api_type)); \
4177 sc->version = EVAS_SMART_CLASS_VERSION; \
4178 sc->name = smart_name; \
4179 sc->callbacks = cb_desc; \
4180 sc->interfaces = ifaces; \
4181 prefix##_smart_set(&api); \
4182 smart = evas_smart_class_new(sc); \
4188 * @def EVAS_SMART_DATA_ALLOC
4190 * Convenience macro to allocate smart data only if needed.
4192 * When writing a subclassable smart object, the @c .add() function
4193 * will need to check if the smart private data was already allocated
4194 * by some child object or not. This macro makes it easier to do it.
4196 * @note This is an idiom used when one calls the parent's @c .add()
4197 * after the specialized code. Naturally, the parent's base smart data
4198 * has to be contemplated as the specialized one's first member, for
4201 * @param o Evas object passed to the @c .add() function
4202 * @param priv_type The type of the data to allocate
4204 * @ingroup Evas_Smart_Group
4206 #define EVAS_SMART_DATA_ALLOC(o, priv_type) \
4208 priv = evas_object_smart_data_get(o); \
4210 priv = (priv_type *)calloc(1, sizeof(priv_type)); \
4211 if (!priv) return; \
4212 evas_object_smart_data_set(o, priv); \
4216 * Free an #Evas_Smart struct
4218 * @param s the #Evas_Smart struct to free
4220 * @warning If this smart handle was created using
4221 * evas_smart_class_new(), the associated #Evas_Smart_Class will not
4224 * @note If you're using the #EVAS_SMART_SUBCLASS_NEW schema to create your
4225 * smart object, note that an #Evas_Smart handle will be shared amongst all
4226 * instances of the given smart class, through a static variable.
4227 * Evas will internally count references on #Evas_Smart handles and free them
4228 * when they are not referenced anymore. Thus, this function is of no use
4229 * for Evas users, most probably.
4231 EAPI void evas_smart_free(Evas_Smart *s) EINA_ARG_NONNULL(1);
4234 * Creates a new #Evas_Smart from a given #Evas_Smart_Class struct
4236 * @param sc the smart class definition
4237 * @return a new #Evas_Smart pointer
4239 * #Evas_Smart handles are necessary to create new @b instances of
4240 * smart objects belonging to the class described by @p sc. That
4241 * handle will contain, besides the smart class interface definition,
4242 * all its smart callbacks infrastructure set, too.
4244 * @note If you are willing to subclass a given smart class to
4245 * construct yours, consider using the #EVAS_SMART_SUBCLASS_NEW macro,
4246 * which will make use of this function automatically for you.
4248 EAPI Evas_Smart *evas_smart_class_new(const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
4251 * Get the #Evas_Smart_Class handle of an #Evas_Smart struct
4253 * @param s a valid #Evas_Smart pointer
4254 * @return the #Evas_Smart_Class in it
4256 EAPI const Evas_Smart_Class *evas_smart_class_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4259 * @brief Get the data pointer set on an #Evas_Smart struct
4261 * @param s a valid #Evas_Smart handle
4263 * This data pointer is set as the data field in the #Evas_Smart_Class
4264 * passed in to evas_smart_class_new().
4266 EAPI void *evas_smart_data_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
4269 * Get the smart callbacks known by this #Evas_Smart handle's smart
4272 * @param s A valid #Evas_Smart handle.
4273 * @param[out] count Returns the number of elements in the returned
4275 * @return The array with callback descriptions known by this smart
4276 * class, with its size returned in @a count parameter. It
4277 * should not be modified in any way. If no callbacks are
4278 * known, @c NULL is returned. The array is sorted by event
4279 * names and elements refer to the original values given to
4280 * evas_smart_class_new()'s Evas_Smart_Class::callbacks
4281 * (pointer to them).
4283 * This is likely different from
4284 * evas_object_smart_callbacks_descriptions_get() as it will contain
4285 * the callbacks of @b all this class hierarchy sorted, while the
4286 * direct smart class member refers only to that specific class and
4287 * should not include parent's.
4289 * If no callbacks are known, this function returns @c NULL.
4291 * The array elements and thus their contents will be @b references to
4292 * original values given to evas_smart_class_new() as
4293 * Evas_Smart_Class::callbacks.
4295 * The array is sorted by Evas_Smart_Cb_Description::name. The last
4296 * array element is a @c NULL pointer and is not accounted for in @a
4297 * count. Loop iterations can check any of these size indicators.
4299 * @note objects may provide per-instance callbacks, use
4300 * evas_object_smart_callbacks_descriptions_get() to get those
4302 * @see evas_object_smart_callbacks_descriptions_get()
4304 EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
4307 * Find a callback description for the callback named @a name.
4309 * @param s The #Evas_Smart where to search for class registered smart
4311 * @param name Name of the desired callback, which must @b not be @c
4312 * NULL. The search has a special case for @a name being the
4313 * same pointer as registered with #Evas_Smart_Cb_Description.
4314 * One can use it to avoid excessive use of strcmp().
4315 * @return A reference to the description if found, or @c NULL, otherwise
4317 * @see evas_smart_callbacks_descriptions_get()
4319 EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2);
4322 * Sets one class to inherit from the other.
4324 * Copy all function pointers, set @c parent to @a parent_sc and copy
4325 * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
4326 * using @a parent_sc_size as reference.
4328 * This is recommended instead of a single memcpy() since it will take
4329 * care to not modify @a sc name, version, callbacks and possible
4332 * @param sc child class.
4333 * @param parent_sc parent class, will provide attributes.
4334 * @param parent_sc_size size of parent_sc structure, child should be at least
4335 * this size. Everything after @c Evas_Smart_Class size is copied
4336 * using regular memcpy().
4338 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);
4341 * Get the number of users of the smart instance
4343 * @param s The Evas_Smart to get the usage count of
4344 * @return The number of uses of the smart instance
4346 * This function tells you how many more uses of the smart instance are in
4347 * existence. This should be used before freeing/clearing any of the
4348 * Evas_Smart_Class that was used to create the smart instance. The smart
4349 * instance will refer to data in the Evas_Smart_Class used to create it and
4350 * thus you cannot remove the original data until all users of it are gone.
4351 * When the usage count goes to 0, you can evas_smart_free() the smart
4352 * instance @p s and remove from memory any of the Evas_Smart_Class that
4353 * was used to create the smart instance, if you desire. Removing it from
4354 * memory without doing this will cause problems (crashes, undefined
4355 * behavior etc. etc.), so either never remove the original
4356 * Evas_Smart_Class data from memory (have it be a constant structure and
4357 * data), or use this API call and be very careful.
4359 EAPI int evas_smart_usage_get(const Evas_Smart *s);
4362 * @def evas_smart_class_inherit
4363 * Easy to use version of evas_smart_class_inherit_full().
4365 * This version will use sizeof(parent_sc), copying everything.
4367 * @param sc child class, will have methods copied from @a parent_sc
4368 * @param parent_sc parent class, will provide contents to be copied.
4369 * @return 1 on success, 0 on failure.
4370 * @ingroup Evas_Smart_Group
4372 #define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, (Evas_Smart_Class *)parent_sc, sizeof(*parent_sc))
4378 * @defgroup Evas_Smart_Object_Group Smart Object Functions
4381 * Functions dealing with Evas smart objects (instances).
4383 * Smart objects are groupings of primitive Evas objects that behave
4384 * as a cohesive group. For instance, a file manager icon may be a
4385 * smart object composed of an image object, a text label and two
4386 * rectangles that appear behind the image and text when the icon is
4387 * selected. As a smart object, the normal Evas object API could be
4388 * used on the icon object.
4390 * Besides that, generally smart objects implement a <b>specific
4391 * API</b>, so that users interact with its own custom features. The
4392 * API takes form of explicit exported functions one may call and
4393 * <b>smart callbacks</b>.
4395 * @section Evas_Smart_Object_Group_Callbacks Smart events and callbacks
4397 * Smart objects can elect events (smart events, from now on) occurring
4398 * inside of them to be reported back to their users via callback
4399 * functions (smart callbacks). This way, you can extend Evas' own
4400 * object events. They are defined by an <b>event string</b>, which
4401 * identifies them uniquely. There's also a function prototype
4402 * definition for the callback functions: #Evas_Smart_Cb.
4404 * When defining an #Evas_Smart_Class, smart object implementors are
4405 * strongly encouraged to properly set the Evas_Smart_Class::callbacks
4406 * callbacks description array, so that the users of the smart object
4407 * can have introspection on its events API <b>at run time</b>.
4409 * See some @ref Example_Evas_Smart_Objects "examples" of this group
4412 * @see @ref Evas_Smart_Group for class definitions.
4416 * @addtogroup Evas_Smart_Object_Group
4420 * Registers an object type and its associated class. LEGACY MECHANISM SUPPORT.
4422 * This function is invoked in the class constructor of smart classes. It will
4423 * add the type and the class into a hash table that will then be used to check
4424 * the type of an object.
4425 * This function has been implemented to support legacy mechanism that checks
4426 * objects types by name.
4427 * USE IT ONLY FOR LEGACY SUPPORT.
4428 * Otherwise, it is HIGHLY recommended to use eo_isa.
4430 * @param type The type (name string) to add.
4431 * @param klass The class to associate to the type.
4435 * @ingroup Evas_Smart_Object_Group
4437 EAPI void evas_smart_legacy_type_register(const char *type, const Eo_Class *klass) EINA_ARG_NONNULL(1, 2);
4444 * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
4446 * Clipped smart object is a base to construct other smart objects
4447 * based on the concept of having an internal clipper that is applied
4448 * to all children objects. This clipper will control the visibility,
4449 * clipping and color of sibling objects (remember that the clipping
4450 * is recursive, and clipper color modulates the color of its
4451 * clippees). By default, this base will also move children relatively
4452 * to the parent, and delete them when parent is deleted. In other
4453 * words, it is the base for simple object grouping.
4455 * See some @ref Example_Evas_Smart_Objects "examples" of this group
4458 * @see evas_object_smart_clipped_smart_set()
4460 * @ingroup Evas_Smart_Object_Group
4466 * Every subclass should provide this at the beginning of their own
4467 * data set with evas_object_smart_data_set().
4469 typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
4470 struct _Evas_Object_Smart_Clipped_Data
4472 Evas_Object *clipper;
4477 * Set a given smart class' callbacks so it implements the <b>clipped smart
4478 * object"</b>'s interface.
4480 * @param sc The smart class handle to operate on
4482 * This call will assign all the required methods of the @p sc
4483 * #Evas_Smart_Class instance to the implementations set for clipped
4484 * smart objects. If one wants to "subclass" it, call this function
4485 * and then override desired values. If one wants to call any original
4486 * method, save it somewhere. Example:
4489 * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
4491 * static void my_class_smart_add(Evas_Object *o)
4494 * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
4498 * Evas_Smart_Class *my_class_new(void)
4500 * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
4501 * if (!parent_sc.name)
4503 * evas_object_smart_clipped_smart_set(&sc);
4505 * sc.add = my_class_smart_add;
4511 * Default behavior for each of #Evas_Smart_Class functions on a
4512 * clipped smart object are:
4513 * - @c add: creates a hidden clipper with "infinite" size, to clip
4514 * any incoming members;
4515 * - @c del: delete all children objects;
4516 * - @c move: move all objects relative relatively;
4517 * - @c resize: <b>not defined</b>;
4518 * - @c show: if there are children objects, show clipper;
4519 * - @c hide: hides clipper;
4520 * - @c color_set: set the color of clipper;
4521 * - @c clip_set: set clipper of clipper;
4522 * - @c clip_unset: unset the clipper of clipper;
4524 * @note There are other means of assigning parent smart classes to
4525 * child ones, like the #EVAS_SMART_SUBCLASS_NEW macro or the
4526 * evas_smart_class_inherit_full() function.
4528 EAPI void evas_object_smart_clipped_smart_set(Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
4531 * Get a pointer to the <b>clipped smart object's</b> class, to use
4532 * for proper inheritance
4534 * @see #Evas_Smart_Object_Clipped for more information on this smart
4537 EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get(void) EINA_CONST;
4543 * @defgroup Evas_Object_Box Box Smart Object
4545 * A box is a convenience smart object that packs children inside it
4546 * in @b sequence, using a layouting function specified by the
4547 * user. There are a couple of pre-made layouting functions <b>built-in
4548 * in Evas</b>, all of them using children size hints to define their
4549 * size and alignment inside their cell space.
4551 * Examples on this smart object's usage:
4552 * - @ref Example_Evas_Box
4553 * - @ref Example_Evas_Size_Hints
4555 * @see @ref Evas_Object_Group_Size_Hints
4557 * @ingroup Evas_Smart_Object_Group
4563 * @typedef Evas_Object_Box_Api
4565 * Smart class extension, providing extra box object requirements.
4567 * @ingroup Evas_Object_Box
4569 typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
4572 * @typedef Evas_Object_Box_Data
4574 * Smart object instance data, providing box object requirements.
4576 * @ingroup Evas_Object_Box
4578 typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
4581 * @typedef Evas_Object_Box_Option
4583 * The base structure for a box option. Box options are a way of
4584 * extending box items properties, which will be taken into account
4585 * for layouting decisions. The box layouting functions provided by
4586 * Evas will only rely on objects' canonical size hints to layout
4587 * them, so the basic box option has @b no (custom) property set.
4589 * Users creating their own layouts, but not depending on extra child
4590 * items' properties, would be fine just using
4591 * evas_object_box_layout_set(). But if one desires a layout depending
4592 * on extra child properties, he/she has to @b subclass the box smart
4593 * object. Thus, by using evas_object_box_smart_class_get() and
4594 * evas_object_box_smart_set(), the @c option_new() and @c
4595 * option_free() smart class functions should be properly
4596 * redefined/extended.
4598 * Object properties are bound to an integer identifier and must have
4599 * a name string. Their values are open to any data. See the API on
4600 * option properties for more details.
4602 * @ingroup Evas_Object_Box
4604 typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
4607 * @typedef Evas_Object_Box_Layout
4609 * Function signature for an Evas box object layouting routine. By
4610 * @a o it will be passed the box object in question, by @a priv it will
4611 * be passed the box's internal data and, by @a user_data, it will be
4612 * passed any custom data one could have set to a given box layouting
4613 * function, with evas_object_box_layout_set().
4615 * @ingroup Evas_Object_Box
4617 typedef void (*Evas_Object_Box_Layout)(Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
4620 * @def EVAS_OBJECT_BOX_API_VERSION
4622 * Current version for Evas box object smart class, a value which goes
4623 * to _Evas_Object_Box_Api::version.
4625 * @ingroup Evas_Object_Box
4627 #define EVAS_OBJECT_BOX_API_VERSION 1
4630 * @struct _Evas_Object_Box_Api
4632 * This structure should be used by any smart class inheriting from
4633 * the box's one, to provide custom box behavior which could not be
4634 * achieved only by providing a layout function, with
4635 * evas_object_box_layout_set().
4637 * @extends Evas_Smart_Class
4638 * @ingroup Evas_Object_Box
4640 struct _Evas_Object_Box_Api
4642 Evas_Smart_Class base; /**< Base smart class struct, need for all smart objects */
4643 int version; /**< Version of this smart class definition */
4644 Evas_Object_Box_Option *(*append)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to append child elements in boxes */
4645 Evas_Object_Box_Option *(*prepend)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to prepend child elements in boxes */
4646 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 */
4647 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 */
4648 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 */
4649 Evas_Object *(*remove)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to remove a child element from boxes */
4650 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 */
4651 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 */
4652 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 */
4653 const char *(*property_name_get)(const Evas_Object * o, int property); /**< Smart function to get the name of a custom property of box children */
4654 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 */
4655 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 */
4656 void (*option_free)(Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt); /**< Smart function to delete a box option struct */
4660 * @def EVAS_OBJECT_BOX_API_INIT
4662 * Initializer for a whole #Evas_Object_Box_Api structure, with
4663 * @c NULL values on its specific fields.
4665 * @param smart_class_init initializer to use for the "base" field
4666 * (#Evas_Smart_Class).
4668 * @see EVAS_SMART_CLASS_INIT_NULL
4669 * @see EVAS_SMART_CLASS_INIT_VERSION
4670 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
4671 * @see EVAS_OBJECT_BOX_API_INIT_NULL
4672 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
4673 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
4674 * @ingroup Evas_Object_Box
4676 #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}
4679 * @def EVAS_OBJECT_BOX_API_INIT_NULL
4681 * Initializer to zero out a whole #Evas_Object_Box_Api structure.
4683 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
4684 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
4685 * @see EVAS_OBJECT_BOX_API_INIT
4686 * @ingroup Evas_Object_Box
4688 #define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
4691 * @def EVAS_OBJECT_BOX_API_INIT_VERSION
4693 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
4694 * set a specific version on it.
4696 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will set
4697 * the version field of #Evas_Smart_Class (base field) to the latest
4698 * #EVAS_SMART_CLASS_VERSION.
4700 * @see EVAS_OBJECT_BOX_API_INIT_NULL
4701 * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
4702 * @see EVAS_OBJECT_BOX_API_INIT
4703 * @ingroup Evas_Object_Box
4705 #define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
4708 * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
4710 * Initializer to zero out a whole #Evas_Object_Box_Api structure and
4711 * set its name and version.
4713 * This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it will also
4714 * set the version field of #Evas_Smart_Class (base field) to the
4715 * latest #EVAS_SMART_CLASS_VERSION and name it to the specific value.
4717 * It will keep a reference to the name field as a <c>"const char *"</c>,
4718 * i.e., the name must be available while the structure is
4719 * used (hint: static or global variable!) and must not be modified.
4721 * @see EVAS_OBJECT_BOX_API_INIT_NULL
4722 * @see EVAS_OBJECT_BOX_API_INIT_VERSION
4723 * @see EVAS_OBJECT_BOX_API_INIT
4724 * @ingroup Evas_Object_Box
4726 #define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
4729 * @struct _Evas_Object_Box_Data
4731 * This structure augments clipped smart object's instance data,
4732 * providing extra members required by generic box implementation. If
4733 * a subclass inherits from #Evas_Object_Box_Api, then it may augment
4734 * #Evas_Object_Box_Data to fit its own needs.
4736 * @extends Evas_Object_Smart_Clipped_Data
4737 * @ingroup Evas_Object_Box
4739 struct _Evas_Object_Box_Data
4741 Evas_Object_Smart_Clipped_Data base;
4742 const Evas_Object_Box_Api *api;
4751 Eina_List *children;
4754 Evas_Object_Box_Layout cb;
4756 void (*free_data)(void *data);
4758 Eina_Bool layouting : 1;
4759 Eina_Bool children_changed : 1;
4762 struct _Evas_Object_Box_Option
4764 Evas_Object *obj; /**< Pointer to the box child object, itself */
4765 Eina_Bool max_reached : 1;
4766 Eina_Bool min_reached : 1;
4767 Evas_Coord alloc_size;
4768 }; /**< #Evas_Object_Box_Option struct fields */
4771 * Set the default box @a api struct (Evas_Object_Box_Api)
4772 * with the default values. May be used to extend that API.
4774 * @param api The box API struct to set back, most probably with
4775 * overridden fields (on class extensions scenarios)
4777 EAPI void evas_object_box_smart_set(Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
4780 * Get the Evas box smart class, for inheritance purposes.
4782 * @return the (canonical) Evas box smart class.
4784 * The returned value is @b not to be modified, just use it as your
4787 EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get(void) EINA_CONST;
4794 * @defgroup Evas_Object_Table Table Smart Object.
4796 * Convenience smart object that packs children using a tabular
4797 * layout using children size hints to define their size and
4798 * alignment inside their cell space.
4800 * @ref tutorial_table shows how to use this Evas_Object.
4802 * @see @ref Evas_Object_Group_Size_Hints
4804 * @ingroup Evas_Smart_Object_Group
4809 * @defgroup Evas_Object_Grid Grid Smart Object.
4811 * Convenience smart object that packs children under a regular grid
4812 * layout, using their virtual grid location and size to determine
4813 * children's positions inside the grid object's area.
4815 * @ingroup Evas_Smart_Object_Group
4820 * @defgroup Evas_Cserve Shared Image Cache Server
4823 * Evas has an (optional) module which provides client-server
4824 * infrastructure to <b>share bitmaps across multiple processes</b>,
4825 * saving data and processing power.
4827 * Be warned that it @b doesn't work when <b>threaded image
4828 * preloading</b> is enabled for Evas, though.
4830 typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
4831 typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
4832 typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
4833 typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
4836 * Statistics about the server that shares cached bitmaps.
4837 * @ingroup Evas_Cserve
4839 struct _Evas_Cserve_Stats
4841 int saved_memory; /**< current amount of saved memory, in bytes */
4842 int wasted_memory; /**< current amount of wasted memory, in bytes */
4843 int saved_memory_peak; /**< peak amount of saved memory, in bytes */
4844 int wasted_memory_peak; /**< peak amount of wasted memory, in bytes */
4845 double saved_time_image_header_load; /**< time, in seconds, saved in header loads by sharing cached loads instead */
4846 double saved_time_image_data_load; /**< time, in seconds, saved in data loads by sharing cached loads instead */
4850 * A handle of a cache of images shared by a server.
4851 * @ingroup Evas_Cserve
4853 struct _Evas_Cserve_Image_Cache
4864 * A handle to an image shared by a server.
4865 * @ingroup Evas_Cserve
4867 struct _Evas_Cserve_Image
4869 const char *file, *key;
4871 time_t file_mod_time;
4872 time_t file_checked_time;
4876 int memory_footprint;
4877 double head_load_time;
4878 double data_load_time;
4879 Eina_Bool alpha : 1;
4880 Eina_Bool data_loaded : 1;
4881 Eina_Bool active : 1;
4883 Eina_Bool useless : 1;
4887 * Configuration that controls the server that shares cached bitmaps.
4888 * @ingroup Evas_Cserve
4890 struct _Evas_Cserve_Config
4892 int cache_max_usage;
4893 int cache_item_timeout;
4894 int cache_item_timeout_check;
4898 * Retrieves if the system wants to share bitmaps using the server.
4899 * @return @c EINA_TRUE if it wants, @c EINA_FALSE otherwise.
4900 * @ingroup Evas_Cserve
4902 EAPI Eina_Bool evas_cserve_want_get(void) EINA_WARN_UNUSED_RESULT;
4905 * Retrieves if the system is connected to the server used to share
4908 * @return @c EINA_TRUE if it's connected, @c EINA_FALSE otherwise.
4909 * @ingroup Evas_Cserve
4911 EAPI Eina_Bool evas_cserve_connected_get(void) EINA_WARN_UNUSED_RESULT;
4914 * Retrieves statistics from a running bitmap sharing server.
4915 * @param stats pointer to structure to fill with statistics about the
4916 * bitmap cache server.
4918 * @return @c EINA_TRUE if @p stats were filled with data,
4919 * @c EINA_FALSE otherwise (when @p stats is untouched)
4920 * @ingroup Evas_Cserve
4922 EAPI Eina_Bool evas_cserve_stats_get(Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
4925 * Completely discard/clean a given images cache, thus re-setting it.
4927 * @param cache A handle to the given images cache.
4929 EAPI void evas_cserve_image_cache_contents_clean(Evas_Cserve_Image_Cache *cache);
4932 * Retrieves the current configuration of the Evas image caching
4935 * @param config where to store current image caching server's
4938 * @return @c EINA_TRUE if @p config was filled with data,
4939 * @c EINA_FALSE otherwise (when @p config is untouched)
4941 * The fields of @p config will be altered to reflect the current
4942 * configuration's values.
4944 * @see evas_cserve_config_set()
4946 * @ingroup Evas_Cserve
4948 EAPI Eina_Bool evas_cserve_config_get(Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
4951 * Changes the configurations of the Evas image caching server.
4953 * @param config A bitmap cache configuration handle with fields set
4954 * to desired configuration values.
4955 * @return @c EINA_TRUE if @p config was successfully applied,
4956 * @c EINA_FALSE otherwise.
4958 * @see evas_cserve_config_get()
4960 * @ingroup Evas_Cserve
4962 EAPI Eina_Bool evas_cserve_config_set(const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
4965 * Force the system to disconnect from the bitmap caching server.
4967 * @ingroup Evas_Cserve
4969 EAPI void evas_cserve_disconnect(void);
4972 * @defgroup Evas_Utils General Utilities
4975 * Some functions that are handy but are not specific of canvas or
4980 * Converts the given Evas image load error code into a string
4981 * describing it in english.
4983 * @param error the error code, a value in ::Evas_Load_Error.
4984 * @return Always returns a valid string. If the given @p error is not
4985 * supported, <code>"Unknown error"</code> is returned.
4987 * Mostly evas_object_image_file_set() would be the function setting
4988 * that error value afterwards, but also evas_object_image_load(),
4989 * evas_object_image_save(), evas_object_image_data_get(),
4990 * evas_object_image_data_convert(), evas_object_image_pixels_import()
4991 * and evas_object_image_is_inside(). This function is meant to be
4992 * used in conjunction with evas_object_image_load_error_get(), as in:
4995 * @dontinclude evas-images.c
4997 * @until ecore_main_loop_begin(
4999 * Here, being @c valid_path the path to a valid image and @c
5000 * bogus_path a path to a file which does not exist, the two outputs
5001 * of evas_load_error_str() would be (if no other errors occur):
5002 * <code>"No error on load"</code> and <code>"File (or file path) does
5003 * not exist"</code>, respectively. See the full @ref
5004 * Example_Evas_Images "example".
5006 * @ingroup Evas_Utils
5008 EAPI const char *evas_load_error_str(Evas_Load_Error error);
5010 /* Evas utility routines for color space conversions */
5011 /* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
5012 /* rgb color space has r,g,b in the range 0 to 255 */
5015 * Convert a given color from HSV to RGB format.
5017 * @param h The Hue component of the color.
5018 * @param s The Saturation component of the color.
5019 * @param v The Value component of the color.
5020 * @param r The Red component of the color.
5021 * @param g The Green component of the color.
5022 * @param b The Blue component of the color.
5024 * This function converts a given color in HSV color format to RGB
5027 * @ingroup Evas_Utils
5029 EAPI void evas_color_hsv_to_rgb(float h, float s, float v, int *r, int *g, int *b);
5032 * Convert a given color from RGB to HSV format.
5034 * @param r The Red component of the color.
5035 * @param g The Green component of the color.
5036 * @param b The Blue component of the color.
5037 * @param h The Hue component of the color.
5038 * @param s The Saturation component of the color.
5039 * @param v The Value component of the color.
5041 * This function converts a given color in RGB color format to HSV
5044 * @ingroup Evas_Utils
5046 EAPI void evas_color_rgb_to_hsv(int r, int g, int b, float *h, float *s, float *v);
5048 /* argb color space has a,r,g,b in the range 0 to 255 */
5051 * Pre-multiplies a rgb triplet by an alpha factor.
5053 * @param a The alpha factor.
5054 * @param r The Red component of the color.
5055 * @param g The Green component of the color.
5056 * @param b The Blue component of the color.
5058 * This function pre-multiplies a given rgb triplet by an alpha
5059 * factor. Alpha factor is used to define transparency.
5061 * @ingroup Evas_Utils
5063 EAPI void evas_color_argb_premul(int a, int *r, int *g, int *b);
5066 * Undo pre-multiplication of a rgb triplet by an alpha factor.
5068 * @param a The alpha factor.
5069 * @param r The Red component of the color.
5070 * @param g The Green component of the color.
5071 * @param b The Blue component of the color.
5073 * This function undoes pre-multiplication a given rbg triplet by an
5074 * alpha factor. Alpha factor is used to define transparency.
5076 * @see evas_color_argb_premul().
5078 * @ingroup Evas_Utils
5080 EAPI void evas_color_argb_unpremul(int a, int *r, int *g, int *b);
5083 * Pre-multiplies data by an alpha factor.
5085 * @param data The data value.
5086 * @param len The length value.
5088 * This function pre-multiplies a given data by an alpha
5089 * factor. Alpha factor is used to define transparency.
5091 * @ingroup Evas_Utils
5093 EAPI void evas_data_argb_premul(unsigned int *data, unsigned int len);
5096 * Undo pre-multiplication data by an alpha factor.
5098 * @param data The data value.
5099 * @param len The length value.
5101 * This function undoes pre-multiplication of a given data by an alpha
5102 * factor. Alpha factor is used to define transparency.
5104 * @ingroup Evas_Utils
5106 EAPI void evas_data_argb_unpremul(unsigned int *data, unsigned int len);
5108 /* string and font handling */
5111 * Gets the next character in the string
5113 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
5114 * this function will place in @p decoded the decoded code point at @p pos
5115 * and return the byte index for the next character in the string.
5117 * The only boundary check done is that @p pos must be >= 0. Other than that,
5118 * no checks are performed, so passing an index value that's not within the
5119 * length of the string will result in undefined behavior.
5121 * @param str The UTF-8 string
5122 * @param pos The byte index where to start
5123 * @param decoded Address where to store the decoded code point. Optional.
5125 * @return The byte index of the next character
5127 * @ingroup Evas_Utils
5129 EAPI int evas_string_char_next_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
5132 * Gets the previous character in the string
5134 * Given the UTF-8 string in @p str, and starting byte position in @p pos,
5135 * this function will place in @p decoded the decoded code point at @p pos
5136 * and return the byte index for the previous character in the string.
5138 * The only boundary check done is that @p pos must be >= 1. Other than that,
5139 * no checks are performed, so passing an index value that's not within the
5140 * length of the string will result in undefined behavior.
5142 * @param str The UTF-8 string
5143 * @param pos The byte index where to start
5144 * @param decoded Address where to store the decoded code point. Optional.
5146 * @return The byte index of the previous character
5148 * @ingroup Evas_Utils
5150 EAPI int evas_string_char_prev_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
5153 * Get the length in characters of the string.
5154 * @param str The string to get the length of.
5155 * @return The length in characters (not bytes)
5156 * @ingroup Evas_Utils
5158 EAPI int evas_string_char_len_get(const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5161 * @defgroup Evas_Keys Key Input Functions
5163 * Functions which feed key events to the canvas.
5165 * As explained in @ref intro_not_evas, Evas is @b not aware of input
5166 * systems at all. Then, the user, if using it crudely (evas_new()),
5167 * will have to feed it with input events, so that it can react
5168 * somehow. If, however, the user creates a canvas by means of the
5169 * Ecore_Evas wrapper, it will automatically bind the chosen display
5170 * engine's input events to the canvas, for you.
5172 * This group presents the functions dealing with the feeding of key
5173 * events to the canvas. On most of them, one has to reference a given
5174 * key by a name (<code>keyname</code> argument). Those are
5175 * <b>platform dependent</b> symbolic names for the keys. Sometimes
5176 * you'll get the right <code>keyname</code> by simply using an ASCII
5177 * value of the key name, but it won't be like that always.
5179 * Typical platforms are Linux frame buffer (Ecore_FB) and X server
5180 * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
5181 * to your display engine's documentation when using evas through an
5182 * Ecore helper wrapper when you need the <code>keyname</code>s.
5185 * @dontinclude evas-events.c
5186 * @skip mods = evas_key_modifier_get(evas);
5189 * All the other @c evas_key functions behave on the same manner. See
5190 * the full @ref Example_Evas_Events "example".
5192 * @ingroup Evas_Canvas
5196 * @addtogroup Evas_Keys
5200 * Checks the state of a given modifier key, at the time of the
5201 * call. If the modifier is set, such as shift being pressed, this
5202 * function returns @c Eina_True.
5204 * @param m The current modifiers set, as returned by
5205 * evas_key_modifier_get().
5206 * @param keyname The name of the modifier key to check status for.
5208 * @return @c Eina_True if the modifier key named @p keyname is on, @c
5209 * Eina_False otherwise.
5211 * @see evas_key_modifier_add
5212 * @see evas_key_modifier_del
5213 * @see evas_key_modifier_get
5214 * @see evas_key_modifier_on
5215 * @see evas_key_modifier_off
5217 EAPI Eina_Bool evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
5220 * Checks the state of a given lock key, at the time of the call. If
5221 * the lock is set, such as caps lock, this function returns @c
5224 * @param l The current locks set, as returned by evas_key_lock_get().
5225 * @param keyname The name of the lock key to check status for.
5227 * @return @c Eina_True if the @p keyname lock key is set, @c
5228 * Eina_False otherwise.
5230 * @see evas_key_lock_get
5231 * @see evas_key_lock_add
5232 * @see evas_key_lock_del
5233 * @see evas_key_lock_on
5234 * @see evas_key_lock_off
5236 EAPI Eina_Bool evas_key_lock_is_set(const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
5243 * @defgroup Evas_Touch_Point_List Touch Point List Functions
5245 * Functions to get information of touched points in the Evas.
5247 * Evas maintains list of touched points on the canvas. Each point has
5248 * its co-ordinates, id and state. You can get the number of touched
5249 * points and information of each point using evas_touch_point_list
5252 * @ingroup Evas_Canvas
5255 typedef Eo Evas_Out;