You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

3515 lines
129 KiB

#ifndef _EVAS_H
# error You shall not include this header directly
#endif
/**
* @def EVAS_VERSION_MAJOR
* The major number of evas version
*/
#define EVAS_VERSION_MAJOR EFL_VERSION_MAJOR
/**
* @def EVAS_VERSION_MINOR
* The minor number of evas version
*/
#define EVAS_VERSION_MINOR EFL_VERSION_MINOR
/**
* @typedef Evas_Version
*
* This is the Evas version information structure that can be used at
* runtime to detect which version of evas is being used and adapt
* appropriately as follows for example:
*
* @code
* #if defined(EVAS_VERSION_MAJOR) && (EVAS_VERSION_MAJOR >= 1) && defined(EVAS_VERSION_MINOR) && (EVAS_VERSION_MINOR > 0)
* printf("Evas version: %i.%i.%i\n",
* evas_version->major,
* evas_version->minor,
* evas_version->micro);
* if (evas_version->revision > 0)
* {
* printf(" Built from Git revision # %i\n", evas_version->revision);
* }
* #endif
* @endcode
*
*/
typedef struct _Evas_Version
{
int major; /**< major (binary or source incompatible changes) */
int minor; /**< minor (new features, bugfixes, major improvements version) */
int micro; /**< micro (bugfix, internal improvements, no new features version) */
int revision; /**< git revision (0 if a proper release or the git revision number Evas is built from) */
} Evas_Version;
EAPI extern Evas_Version * evas_version;
/**
* @file
* @brief These routines are used for Evas library interaction.
*
* @todo check boolean return values and convert to Eina_Bool
* @todo change all api to use EINA_SAFETY_*
* @todo finish api documentation
*/
/**
* @def EVAS_CALLBACK_PRIORITY_BEFORE
* Slightly more prioritized than default.
* @since 1.1
*/
#define EVAS_CALLBACK_PRIORITY_BEFORE -100
/**
* @def EVAS_CALLBACK_PRIORITY_DEFAULT
* Default callback priority level
* @since 1.1
*/
#define EVAS_CALLBACK_PRIORITY_DEFAULT 0
/**
* @def EVAS_CALLBACK_PRIORITY_AFTER
* Slightly less prioritized than default.
* @since 1.1
*/
#define EVAS_CALLBACK_PRIORITY_AFTER 100
/**
* @typedef Evas_Callback_Priority
*
* Callback priority value. Range is -32k - 32k. The lower the number, the
* bigger the priority.
*
* @see EVAS_CALLBACK_PRIORITY_AFTER
* @see EVAS_CALLBACK_PRIORITY_BEFORE
* @see EVAS_CALLBACK_PRIORITY_DEFAULT
*
* @since 1.1
*/
// Support not having eo available
#ifdef EFL_BETA_API_SUPPORT
typedef Efl_Callback_Priority Evas_Callback_Priority;
#else
typedef short Evas_Callback_Priority;
#endif
// TODO: Mark as EINA_DEPRECATED
typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< A generic rectangle handle. @deprecated Use Eina_Rectangle instead */
typedef struct _Evas_Point Evas_Point; /**< integer point */
typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */
typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */
typedef struct _Evas_Coord_Size Evas_Coord_Size; /**< Evas_Coord size @since 1.8 */
typedef struct _Evas_Coord_Precision_Size Evas_Coord_Precision_Size; /**< Evas_Coord size with sub-pixel precision @since 1.8 */
typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */
typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */
typedef int Evas_Coord; /**< Type used for coordinates (in pixels, int). */
typedef int Evas_Font_Size; /**< Type used for font sizes (int). */
/**
* @typedef Evas_Smart_Class
*
* A smart object's @b base class definition
*
* @ingroup Evas_Smart_Group
*/
typedef struct _Evas_Smart_Class Evas_Smart_Class;
/**
* @typedef Evas_Smart_Interface
*
* A smart object's @b base interface definition
*
* An Evas interface is exactly like the OO-concept: a 'contract' or
* API a given object is declared to support. A smart object may have
* more than one interface, thus extending the behavior it gets from
* sub-classing.
*
* @since 1.7
*
* @ingroup Evas_Smart_Group
*/
typedef struct _Evas_Smart_Interface Evas_Smart_Interface;
/**
* @typedef Evas_Smart_Cb_Description
*
* A smart object callback description, used to provide introspection
*
* @ingroup Evas_Smart_Group
*/
typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
/**
* @typedef Evas
*
* An opaque handle to an Evas canvas.
*
* @see evas_new()
* @see evas_free()
*
* @ingroup Evas_Canvas
*/
typedef Eo Evas;
/**
* @typedef Evas_Public_Data
* Public data for an Evas.
* @ingroup Evas_Canvas
*/
typedef struct _Evas_Public_Data Evas_Public_Data;
/**
* @typedef Efl_Canvas_Object
* An Evas Object handle
* @see Evas_Object
* @ingroup Evas_Object_Group
*/
typedef Eo Efl_Canvas_Object;
/**
* @typedef Evas_Object
* An Evas Object handle.
* @ingroup Evas_Object_Group
*/
typedef Efl_Canvas_Object Evas_Object;
/* These defines are used in H files generated by Eolian to avoid
* redefinition of types */
#define _EFL_CANVAS_OBJECT_EO_CLASS_TYPE
/**
* Type of abstract VG node
*/
typedef Eo Efl_VG;
typedef void Evas_Performance; /**< An Evas Performance handle */
typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
typedef int Evas_Angle; /**< A type for angle */
// FIXME: This can be a simple alias to Eina_Rectangle instead.
struct _Evas_Coord_Rectangle /** A rectangle in Evas_Coord */
{
Evas_Coord x; /**< top-left x co-ordinate of rectangle */
Evas_Coord y; /**< top-left y co-ordinate of rectangle */
Evas_Coord w; /**< width of rectangle */
Evas_Coord h; /**< height of rectangle */
};
struct _Evas_Coord_Point /** A Point in Evas_Coord */
{
Evas_Coord x; /**< x co-ordinate */
Evas_Coord y; /**< y co-ordinate */
};
struct _Evas_Coord_Size /** A size in Evas_Coord */
{
Evas_Coord w; /**< width */
Evas_Coord h; /**< height */
};
struct _Evas_Coord_Precision_Size /** A size in Evas_Coord with subpixel precision*/
{
Evas_Coord w; /**< width */
Evas_Coord h; /**< height */
double wsub; /**< subpixel precision for width */
double ysub; /**< subpixel precision for height */
};
struct _Evas_Coord_Precision_Point /** A point in Evas_Coord with subpixel precision*/
{
Evas_Coord x; /**< x co-ordinate */
Evas_Coord y; /**< y co-ordinate */
double xsub; /**< subpixel precision for x */
double ysub; /**< subpixel precision for y */
};
struct _Evas_Point /** A point */
{
int x; /**< x co-ordinate */
int y; /**< y co-ordinate */
};
struct _Evas_Position /** A position */
{
Evas_Point output; /**< position on the output */
Evas_Coord_Point canvas; /**< position on the canvas */
};
struct _Evas_Precision_Position /** A position with precision*/
{
Evas_Point output; /**< position on the output */
Evas_Coord_Precision_Point canvas; /**< position on the canvas */
};
typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< A source description of pixels for importing pixels */
/* Opaque types */
typedef Eo Evas_Device; /**< A source device handle - where the event came from */
typedef enum _Evas_Image_Content_Hint
{
EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents will change over time */
EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents won't change over time */
} Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
typedef enum _Evas_Alloc_Error
{
EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */
EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */
EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded after freeing up speculative resource memory */
} Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */
typedef enum _Evas_Pixel_Import_Pixel_Format
{
EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */
EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */
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 */
} Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */
struct _Evas_Pixel_Import_Source
{
Evas_Pixel_Import_Pixel_Format format; /**< pixel format type ie ARGB32, YUV420P_601 etc. */
int w, h; /**< width and height of source in pixels */
void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */
};
#define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */
#define EVAS_LAYER_MAX 32767 /**< top-most layer number */
#define EVAS_COLOR_SPACE_ARGB 0 /**< Not used for anything */
#define EVAS_COLOR_SPACE_AHSV 1 /**< Not used for anything */
#define EVAS_TEXT_INVALID -1 /**< Not used for anything */
#define EVAS_TEXT_SPECIAL -2 /**< Not used for anything */
#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() */
#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() */
#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) */
#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) */
#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 */
#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 */
typedef enum _Evas_Engine_Render_Mode
{
EVAS_RENDER_MODE_BLOCKING = 0, /**< The rendering is blocking mode*/
EVAS_RENDER_MODE_NONBLOCKING = 1, /**< The rendering is non blocking mode*/
} Evas_Engine_Render_Mode; /**< behaviour of the renderer*/
typedef Efl_Gfx_Event_Render_Post Evas_Event_Render_Post; /**< Event info sent after a frame was rendered. @since 1.18 */
typedef enum _Evas_Device_Class
{
EVAS_DEVICE_CLASS_NONE, /**< Not a device @since 1.8 */
EVAS_DEVICE_CLASS_SEAT, /**< The user/seat (the user themselves) @since 1.8 */
EVAS_DEVICE_CLASS_KEYBOARD, /**< A regular keyboard, numberpad or attached buttons @since 1.8 */
EVAS_DEVICE_CLASS_MOUSE, /**< A mouse, trackball or touchpad relative motion device @since 1.8 */
EVAS_DEVICE_CLASS_TOUCH, /**< A touchscreen with fingers or stylus @since 1.8 */
EVAS_DEVICE_CLASS_PEN, /**< A special pen device @since 1.8 */
#define EVAS_DEVICE_CLASS_WAND EVAS_DEVICE_CLASS_POINTER
EVAS_DEVICE_CLASS_POINTER, /**< A laser pointer, wii-style or "minority report" pointing device @since 1.8 */
EVAS_DEVICE_CLASS_GAMEPAD /**< A gamepad controller or joystick @since 1.8 */
} Evas_Device_Class; /**< A general class of device @since 1.8 */
/**
* @brief Specific type of input device.
*
* Note: Currently not used inside EFL.
*
* @since 1.8
*/
typedef enum
{
EVAS_DEVICE_SUBCLASS_NONE = 0, /**< Not a device. */
EVAS_DEVICE_SUBCLASS_FINGER, /**< The normal flat of your finger. */
EVAS_DEVICE_SUBCLASS_FINGERNAIL, /**< A fingernail. */
EVAS_DEVICE_SUBCLASS_KNUCKLE, /**< A Knuckle. */
EVAS_DEVICE_SUBCLASS_PALM, /**< The palm of a users hand. */
EVAS_DEVICE_SUBCLASS_HAND_SIZE, /**< The side of your hand. */
EVAS_DEVICE_SUBCLASS_HAND_FLAT, /**< The flat of your hand. */
EVAS_DEVICE_SUBCLASS_PEN_TIP, /**< The tip of a pen. */
EVAS_DEVICE_SUBCLASS_TRACKPAD, /**< A trackpad style mouse. */
EVAS_DEVICE_SUBCLASS_TRACKPOINT, /**< A trackpoint style mouse. */
EVAS_DEVICE_SUBCLASS_TRACKBALL /**< A trackball style mouse. */
} Evas_Device_Subclass;
/**
* Flags for Mouse Button events
*/
typedef enum _Evas_Button_Flags
{
EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< This mouse button press was the 2nd press of a double click */
EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< This mouse button press was the 3rd press of a triple click */
} Evas_Button_Flags; /**< Flags for Mouse Button events */
/**
* Flags for Events
*/
typedef enum _Evas_Event_Flags
{
EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
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 */
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 */
} Evas_Event_Flags; /**< Flags for Events */
typedef enum _Evas_Aspect_Control
{
EVAS_ASPECT_CONTROL_NONE = 0, /**< Preference on scaling unset */
EVAS_ASPECT_CONTROL_NEITHER = 1, /**< Same effect as unset preference on scaling */
EVAS_ASPECT_CONTROL_HORIZONTAL = 2, /**< Use all horizontal container space to place an object, using the given aspect */
EVAS_ASPECT_CONTROL_VERTICAL = 3, /**< Use all vertical container space to place an object, using the given aspect */
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 */
} Evas_Aspect_Control; /**< Aspect types/policies for scaling size hints, used for evas_object_size_hint_aspect_set() */
typedef Efl_Text_Bidirectional_Type Evas_BiDi_Direction;
#define EVAS_BIDI_DIRECTION_NEUTRAL EFL_TEXT_BIDIRECTIONAL_TYPE_NEUTRAL
#define EVAS_BIDI_DIRECTION_NATURAL EFL_TEXT_BIDIRECTIONAL_TYPE_NATURAL
#define EVAS_BIDI_DIRECTION_LTR EFL_TEXT_BIDIRECTIONAL_TYPE_LTR
#define EVAS_BIDI_DIRECTION_RTL EFL_TEXT_BIDIRECTIONAL_TYPE_RTL
#define EVAS_BIDI_DIRECTION_INHERIT EFL_TEXT_BIDIRECTIONAL_TYPE_INHERIT
/**
* How the mouse pointer should be handled by Evas.
*
* In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button
* is pressed down over an object and held, with the mouse pointer
* being moved outside of it, the pointer still behaves as being bound
* to that object, albeit out of its drawing region. When the button
* is released, the event will be fed to the object, that may check if
* the final position is over it or not and do something about it.
*
* In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer will
* always be bound to the object right below it.
*
* @ingroup Evas_Object_Group_Extras
*/
typedef enum _Evas_Object_Pointer_Mode
{
EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< default, X11-like */
EVAS_OBJECT_POINTER_MODE_NOGRAB, /**< pointer always bound to the object right below it */
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 */
} Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
// FIXME: Move to Evas_Legacy.h
/** Identifier of callbacks to be set for Evas canvases or Evas objects. */
typedef enum
{
EVAS_CALLBACK_MOUSE_IN = 0, /**< Mouse In Event */
EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */
EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */
EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */
EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */
EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */
EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */
EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */
EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */
EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */
EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */
EVAS_CALLBACK_KEY_UP, /**< Key Release Event */
EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */
EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */
EVAS_CALLBACK_SHOW, /**< Show Event */
EVAS_CALLBACK_HIDE, /**< Hide Event */
EVAS_CALLBACK_MOVE, /**< Move Event */
EVAS_CALLBACK_RESIZE, /**< Resize Event */
EVAS_CALLBACK_RESTACK, /**< Restack Event */
EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */
EVAS_CALLBACK_HOLD, /**< Events go on/off hold */
EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */
EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */
EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */
EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called after render update regions have
* been calculated, but only if update regions exist */
EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called after render update regions have
* been sent to the display server, but only
* if update regions existed for the most recent frame */
EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanism in Evas that throw out original image data) */
EVAS_CALLBACK_RENDER_PRE, /**< Called just before rendering starts on the canvas target. @since 1.2 */
EVAS_CALLBACK_RENDER_POST, /**< Called just after rendering stops on the canvas target. @since 1.2 */
EVAS_CALLBACK_IMAGE_RESIZE, /**< Image size is changed. @since 1.8 */
EVAS_CALLBACK_DEVICE_CHANGED, /**< Devices added, removed or changed on canvas. @since 1.8 */
EVAS_CALLBACK_AXIS_UPDATE, /**< Input device changed value on some axis. @since 1.13 */
EVAS_CALLBACK_CANVAS_VIEWPORT_RESIZE, /**< Canvas viewport resized. @since 1.15 */
EVAS_CALLBACK_LAST /**< Sentinel value to indicate last enum field during
* iteration */
} Evas_Callback_Type;
typedef void (*Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info); /**< Evas smart objects' "smart callback" function signature */
typedef void (*Evas_Event_Cb)(void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e); /**< Evas object event (post) callback function signature */
typedef void (*Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info); /**< Evas object event callback function signature */
typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info); /**< Evas async callback function signature */
/**
* @defgroup Evas_Main_Group Top Level Functions
* @ingroup Evas
*
* Functions that affect Evas as a whole.
*/
/**
* @deprecated This function now returns NULL as cserve2 support has been removed
*
* Get the path for the cserve binary to execute
*
* There is little need for anyone except a desktop environment to call this.
* This can be called before evas_init() has been called. It will try and find
* the full path to the to the cserve binary to run to provide cserve image
* and font caching services for evas.
*
* @return NULL if error, or a string with the full path to the cserve binary.
*
* @since 1.8
*/
EINA_DEPRECATED
EAPI const char *evas_cserve_path_get(void);
/**
* @brief Directly initialize Evas and its required dependencies.
*
* @return The number of times evas_init() has been called.
*
* Permits use of Evas independently from @ref Ecore. This can be
* useful in certain types of examples and test programs, as well as by
* Ecore-Evas' @c ecore_evas_init() itself (which is what most EFL
* applications will be using instead).
*
* The @ref Example_Evas_Buffer_Simple "evas-buffer-simple.c" example
* demonstrates use of evas_init(), and then manually setting up the
* canvas:
*
* @dontinclude evas-buffer-simple.c
* @skip int main
* @until return -1;
*
* The canvas is set up using the example's create_canvas() routine,
* which forces selection of Evas' "buffer" rendering engine. The
* buffer engine simply renders to a memory buffer with no hardware
* acceleration.
*
* @skip static Evas *create_canvas
* @until evas_output_viewport_set(canvas,
*
* @see evas_shutdown().
*
* @ingroup Evas_Main_Group
*/
EAPI int evas_init(void);
/**
* @brief Directly shutdown Evas.
*
* @return The (decremented) init reference counter.
*
* Low level routine to finalize Evas. Decrements a counter of the
* number of times evas_init() has been called, and, if appropriate,
* shuts down associated dependency modules and libraries. A return
* value of 0 indicates that everything has been properly shut down.
*
* Ecore-Evas applications will typically use ecore_evas_shutdown()
* instead, as described in evas_init().
*
* The @ref Example_Evas_Buffer_Simple "evas-buffer-simple.c" example
* shows use of evas_shutdown() in its destroy_canvas() routine:
*
* @dontinclude evas-buffer-simple.c
* @skip static void destroy_canvas
* @until evas_free(canvas)
*
* @see evas_init().
*
* @ingroup Evas_Main_Group
*/
EAPI int evas_shutdown(void);
/**
* @brief Get the error status of the most recent memory allocation call
*
* @return Allocation error codes EVAS_ALLOC_ERROR_NONE,
* EVAS_ALLOC_ERROR_FATAL or EVAS_ALLOC_ERROR_RECOVERED.
*
* Accesses the current error status for memory allocation, or
* EVAS_ALLOC_ERROR_NONE if allocation succeeded with no errors.
*
* EVAS_ALLOC_ERROR_FATAL means that no memory allocation was possible, but
* the function call exited as cleanly as possible. This is a sign of very low
* memory, and indicates the caller should attempt a safe recovery and possibly
* re-try after freeing up additional memory.
*
* EVAS_ALLOC_ERROR_RECOVERED indicates that Evas was able to free up
* sufficient memory internally to perform the requested memory
* allocation and the program will continue to function normally, but
* memory is in a low state and the program should strive to free memory
* itself. Evas' approach to free memory internally may reduce the
* resolution of images, free cached fonts or images, throw out
* pre-rendered data, or reduce the complexity of change lists.
*
* Example:
* @code
* extern Evas_Object *object;
* void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
*
* evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL);
* if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL)
* {
* fprintf(stderr, "ERROR: Failed to attach callback. Out of memory.\n");
* fprintf(stderr, " Must destroy object now as it cannot be used.\n");
* evas_object_del(object);
* object = NULL;
* fprintf(stderr, "WARNING: Cleaning out RAM.\n");
* my_memory_cleanup();
* }
* if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED)
* {
* fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n");
* my_memory_cleanup();
* }
* @endcode
*
* @ingroup Evas_Main_Group
*/
EAPI Evas_Alloc_Error evas_alloc_error(void);
/**
* @brief Access the canvas' asynchronous event queue.
*
* @return A file descriptor to the asynchronous events.
*
* Normally, Evas handles asynchronous events internally, particularly
* in Evas-using modules that are part of the EFL infrastructure.
* Notably, ecore-evas takes care of processing these events for
* canvases instantiated through it.
*
* However, when asynchronous calculations need to be done outside the
* main thread (in some other mainloop) with some followup action, this
* function permits accessing the events. An example would be
* asynchronous image preloading.
*
* @ingroup Evas_Main_Group
*/
EAPI int evas_async_events_fd_get(void) EINA_WARN_UNUSED_RESULT;
/**
* @brief Process the asynchronous event queue.
*
* @return The number of events processed.
*
* Triggers the callback functions for asynchronous events that were
* queued up by evas_async_events_put(). The callbacks are called in
* the same order that they were queued.
*
* @ingroup Evas_Main_Group
*/
EAPI int evas_async_events_process(void);
/**
* @brief Insert asynchronous events on the canvas.
*
* @param target The target to be affected by the events.
* @param type The type of callback function.
* @param event_info Information about the event.
* @param func The callback function pointer.
*
* @return EINA_FALSE if an error occurred, EINA_TRUE otherwise.
*
* Allows routines running outside Evas' main thread to report an
* asynchronous event. The target, type, and event info will be passed
* to the callback function when evas_async_events_process() is called.
*
* @ingroup Evas_Main_Group
*/
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);
/**
* @defgroup Evas_Canvas Canvas Functions
* @ingroup Evas
*
* Low level Evas canvas functions. Sub groups will present more high
* level ones, though.
*
* Most of these functions deal with low level Evas actions, like:
* @li create/destroy raw canvases, not bound to any displaying engine
* @li tell a canvas i got focused (in a windowing context, for example)
* @li tell a canvas a region should not be calculated anymore in rendering
* @li tell a canvas to render its contents, immediately
*
* Most users will be using Evas by means of the @c Ecore_Evas
* wrapper, which deals with all the above mentioned issues
* automatically for them. Thus, you'll be looking at this section
* only if you're building low level stuff.
*
* The groups within present you functions that deal with the canvas
* directly, too, and not yet with its @b objects. They are the
* functions you need to use at a minimum to get a working canvas.
*
* Some of the functions in this group are exemplified @ref
* Example_Evas_Events "here".
*/
/**
* @}
*/
/**
* @defgroup Evas_Output_Method Render Engine Functions
*
* Functions that are used to set the render engine for a given
* function, and then get that engine working.
*
* The following code snippet shows how they can be used to
* initialise an evas that uses the X11 software engine:
* @code
* Evas *evas;
* Evas_Engine_Info_Software_X11 *einfo;
* extern Display *display;
* extern Window win;
*
* evas_init();
*
* evas = evas_new();
* evas_output_method_set(evas, evas_render_method_lookup("software_x11"));
* evas_output_size_set(evas, 640, 480);
* evas_output_viewport_set(evas, 0, 0, 640, 480);
* einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas);
* einfo->info.display = display;
* einfo->info.visual = DefaultVisual(display, DefaultScreen(display));
* einfo->info.colormap = DefaultColormap(display, DefaultScreen(display));
* einfo->info.drawable = win;
* einfo->info.depth = DefaultDepth(display, DefaultScreen(display));
* evas_engine_info_set(evas, (Evas_Engine_Info *)einfo);
* @endcode
*
* @ingroup Evas_Canvas
*/
/**
* Look up a numeric ID from a string name of a rendering engine.
*
* @param name the name string of an engine
* @return A numeric (opaque) ID for the rendering engine
* @ingroup Evas_Output_Method
*
* This function looks up a numeric return value for the named engine
* in the string @p name. This is a normal C string, NUL byte
* terminated. The name is case sensitive. If the rendering engine is
* available, a numeric ID for that engine is returned that is not
* 0. If the engine is not available, 0 is returned, indicating an
* invalid engine.
*
* The programmer should NEVER rely on the numeric ID of an engine
* unless it is returned by this function. Programs should NOT be
* written accessing render method ID's directly, without first
* obtaining it from this function.
*
* @attention it is mandatory that one calls evas_init() before
* looking up the render method.
*
* Example:
* @code
* int engine_id;
* Evas *evas;
*
* evas_init();
*
* evas = evas_new();
* if (!evas)
* {
* fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
* exit(-1);
* }
* engine_id = evas_render_method_lookup("software_x11");
* if (!engine_id)
* {
* fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
* exit(-1);
* }
* evas_output_method_set(evas, engine_id);
* @endcode
*/
EAPI int evas_render_method_lookup(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* List all the rendering engines compiled into the copy of the Evas library
*
* @return A linked list whose data members are C strings of engine names
* @ingroup Evas_Output_Method
*
* Calling this will return a handle (pointer) to an Evas linked
* list. Each node in the linked list will have the data pointer be a
* (char *) pointer to the name string of the rendering engine
* available. The strings should never be modified, neither should the
* list be modified. This list should be cleaned up as soon as the
* program no longer needs it using evas_render_method_list_free(). If
* no engines are available from Evas, @c NULL will be returned.
*
* Example:
* @code
* Eina_List *engine_list, *l;
* char *engine_name;
*
* engine_list = evas_render_method_list();
* if (!engine_list)
* {
* fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
* exit(-1);
* }
* printf("Available Evas Engines:\n");
* EINA_LIST_FOREACH(engine_list, l, engine_name)
* printf("%s\n", engine_name);
* evas_render_method_list_free(engine_list);
* @endcode
*/
EAPI Eina_List *evas_render_method_list(void) EINA_WARN_UNUSED_RESULT;
/**
* This function should be called to free a list of engine names
*
* @param list The Eina_List base pointer for the engine list to be freed
* @ingroup Evas_Output_Method
*
* When this function is called it will free the engine list passed in
* as @p list. The list should only be a list of engines generated by
* calling evas_render_method_list(). If @p list is NULL, nothing will
* happen.
*
* Example:
* @code
* Eina_List *engine_list, *l;
* char *engine_name;
*
* engine_list = evas_render_method_list();
* if (!engine_list)
* {
* fprintf(stderr,