aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/evas/Evas.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/evas/Evas.h')
-rwxr-xr-x[-rw-r--r--]src/lib/evas/Evas.h14734
1 files changed, 14481 insertions, 253 deletions
diff --git a/src/lib/evas/Evas.h b/src/lib/evas/Evas.h
index 71d91eab8b..8a4f23630a 100644..100755
--- a/src/lib/evas/Evas.h
+++ b/src/lib/evas/Evas.h
@@ -1,260 +1,233 @@
/**
- @page evas_main Evas
-
- @date 2000 (created)
-
- @section toc Table of Contents
-
- @li @ref evas_main_intro
- @li @ref evas_main_work
- @li @ref evas_main_compiling
- @li @ref evas_main_next_steps
- @li @ref evas_main_intro_example
-
-
- @section evas_main_intro Introduction
-
- Evas is a clean display canvas API for several target display systems
- that can draw anti-aliased text, smooth super and sub-sampled scaled
- images, alpha-blend objects and much more.
-
- It abstracts any need to know much about what the characteristics of
- your display system are or what graphics calls are used to draw them
- and how. It deals on an object level where all you do is create and
- manipulate objects in a canvas, set their properties, and the rest is
- done for you.
-
- Evas optimises the rendering pipeline to minimise effort in redrawing
- changes made to the canvas and so takes this work out of the
- programmers hand, saving a lot of time and energy.
-
- It is small and lean, and is designed to work on embedded systems all the way
- to large and powerful multi-CPU workstations. It can be compiled to
- only have the features you need for your target platform if you so
- wish, thus keeping it small and lean. It has several display
- back-ends, letting it display on several display systems, making it
- portable for cross-device and cross-platform development.
-
- @subsection evas_main_intro_not_evas What Evas is not?
-
- Evas is not a widget set or widget toolkit, however it is their
- base. See Elementary (http://docs.enlightenment.org/auto/elementary/)
- for a toolkit based on @ref Evas, @ref Edje, @ref Ecore and other
- Enlightenment technologies.
-
- It is not dependent or aware of main loops, input or output
- systems. Input should be polled from various sources and fed to
- Evas. Similarly, it does not create windows or report windows updates
- to your system, but just draws the pixels and report to the
- user the areas that were changed. Of course these operations are quite
- common and thus they are ready to use in @ref Ecore, particularly in
- @ref Ecore_Evas_Group.
-
-
- @section evas_main_work How does Evas work?
-
- Evas is a canvas display library. This is markedly different from most
- display and windowing systems as a canvas is structural and is also a
- state engine, whereas most display and windowing systems are immediate
- mode display targets. Evas handles the logic between a structural
- display via its state engine, and controls the target windowing system
- in order to produce rendered results of the current canvas' state on
- the display.
-
- Immediate mode display systems retain very little, or no state. A
- program executes a series of commands, as in the pseudo code:
-
- @verbatim
- draw line from position (0, 0) to position (100, 200);
-
- draw rectangle from position (10, 30) to position (50, 500);
-
- bitmap_handle = create_bitmap();
- scale bitmap_handle to size 100 x 100;
- draw image bitmap_handle at position (10, 30);
- @endverbatim
-
- The series of commands is executed by the windowing system and the
- results are displayed on the screen (normally). Once the commands are
- executed the display system has little or no idea of how to reproduce
- this image again, and so has to be instructed by the application on how
- to redraw sections of the screen whenever needed. Each successive
- command is executed as instructed by the application and either
- emulated by software or sent to the graphics hardware on the device to
- be performed.
-
- The advantage of such a system is that it is simple, and gives a
- program tight control over how something looks and is drawn. Given the
- increasing complexity of displays and demands by users to have better
- looking interfaces, more and more work is needing to be done at this
- level by the internals of widget sets, custom display widgets and
- other programs. This means that more and more logic and display rendering
- code needs to be written each time the application needs to figure out
- how to minimise redraws so that display is fast and interactive, and
- keeps track of redraw logic. The power comes at a high-price with lots
- of extra code and work. Programmers not very familiar with graphics
- programming often make mistakes at this level and produce code that
- is sub optimal. Those familiar with this kind of programming simply
- get bored by writing the same code again and again.
-
- For example, if in the above scene, the windowing system requires the
- application to redraw the area from 0, 0 to 50, 50 (also referred as
- "expose event"), then the programmer must calculate manually the
- updates and repaint it again:
-
- @verbatim
- Redraw from position (0, 0) to position (50, 50):
-
- // what is in area (0, 0, 50, 50)?
-
- // 1. intersection part of line (0, 0) to (100, 200)?
- draw line from position (0, 0) to position (25, 50);
-
- // 2. intersection part of rectangle (10, 30) to (50, 500)?
- draw rectangle from position (10, 30) to position (50, 50)
-
- // 3. intersection part of image at (10, 30), size 100 x 100?
- bitmap_subimage = subregion from position (0, 0) to position (40, 20)
- draw image bitmap_subimage at position (10, 30);
- @endverbatim
-
- You might have noticed that, if all elements in the
- above scene are opaque, then the system is doing useless paints: part
- of the line is behind the rectangle, and part of the rectangle is
- behind the image. These useless paints tend to be very costly, as
- pixels tend to be 4 bytes in size; thus an overlapping region of 100 x
- 100 pixels is around 40000 useless writes! You could write
- code to calculate the overlapping areas and avoid painting then, but
- then it should be mixed with the "expose event" handling mentioned
- above and you quickly realize that the initially simpler method became
- really complex.
-
- Evas is a structural system in which the programmer creates and
- manages display objects and their properties, and as a result of this
- higher level state management, the canvas is able to redraw the set of
- objects when needed to represent the current state of the canvas.
-
- For example, the pseudo code:
-
- @verbatim
- line_handle = create_line();
- set line_handle from position (0, 0) to position (100, 200);
- show line_handle;
-
- rectangle_handle = create_rectangle();
- move rectangle_handle to position (10, 30);
- resize rectangle_handle to size 40 x 470;
- show rectangle_handle;
-
- bitmap_handle = create_bitmap();
- scale bitmap_handle to size 100 x 100;
- move bitmap_handle to position (10, 30);
- show bitmap_handle;
-
- render scene;
- @endverbatim
-
- This may look longer, but when the display needs to be refreshed or
- updated, you move, resize, show, or hide the objects that need to change.
- You can simply think at the object logic level, and the canvas software
- does the rest of the work for you, figuring out what actually changed in the
- canvas since it had been last drawn, how to most efficiently redraw the canvas and
- its contents to reflect the current state, and then it can go off and do
- the actual drawing of the canvas.
-
- This lets you think in a more natural way when dealing with
- a display, and saves time and effort of working out how to load and
- display images, render given the current display system, and so on. Since
- Evas also is portable across different display systems, this also
- gives you the ability to have their code ported and
- displayed on different display systems with very little work.
-
- Evas can be seen as a display system that stands somewhere between a
- widget set and an immediate mode display system. It retains basic
- display logic, but does very little high-level logic such as
- scrollbars, sliders, and push buttons.
-
-
- @section evas_main_compiling How to compile
-
- Evas is a library your application links to. The procedure for this is
- very simple. You simply have to compile your application with the
- appropriate compiler flags that the @c pkg-config script outputs. For
- example:
-
- Compiling C or C++ files into object files:
-
- @verbatim
- gcc -c -o main.o main.c `pkg-config --cflags evas`
- @endverbatim
-
- Linking object files into a binary executable:
-
- @verbatim
- gcc -o my_application main.o `pkg-config --libs evas`
- @endverbatim
-
- See @ref pkgconfig
-
- @section evas_main_next_steps Next Steps
-
- After you understood what Evas is and installed it in your system
- you should proceed understanding the programming interface for all
- objects, then see the specific for the most used elements. We'd
- recommend you to take a while to learn @ref Ecore, @ref Edje and
- Elementary (http://docs.enlightenment.org/auto/elementary/) as they
- will likely save you tons of work compared to using just Evas
- directly.
-
- Recommended reading:
-
- @li @ref Evas_Object_Group, where you'll get how to basically
- manipulate generic objects lying on an Evas canvas, handle canvas
- and object events, etc.
- @li @ref Evas_Object_Rectangle, to learn about the most basic object
- type on Evas -- the rectangle.
- @li @ref Evas_Object_Polygon, to learn how to create polygon elements
- on the canvas.
- @li @ref Evas_Line_Group, to learn how to create line elements on the
- canvas.
- @li @ref Evas_Object_Image, to learn about image objects, over which
- Evas can do a plethora of operations.
- @li @ref Evas_Object_Text, to learn how to create textual elements on
- the canvas.
- @li @ref Evas_Object_Textblock, to learn how to create multiline
- textual elements on the canvas.
- @li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define
- new objects that provide @b custom functions to handle clipping,
- hiding, moving, resizing, color setting and more. These could
- be as simple as a group of objects that move together (see @ref
- Evas_Smart_Object_Clipped) up to implementations of what
- ends to be a widget, providing some intelligence (thus the name)
- to Evas objects -- like a button or check box, for example.
-
- @section evas_main_intro_example Introductory Example
-
- @include evas-buffer-simple.c
-
- More examples can be found at @ref evas_examples.
+ * @defgroup Evas Evas
+ * @ingroup EFL_Group
+ *
+ * @brief Evas provide a clean display canvas API.
+ *
+ * See @ref evas_main for more details
+ *
+ * @{
+ */
+/**
+ * @page evas_main Evas
+ *
+ * @date 2000 (created)
+ *
+ * @section toc Table of Contents
+ *
+ * @li @ref evas_main_intro
+ * @li @ref evas_main_work
+ * @li @ref evas_main_next_steps
+ *
+ *
+ * @section evas_main_intro Introduction
+ *
+ * Evas is a clean display canvas API for several target display systems
+ * that can draw anti-aliased text, smooth super and sub-sampled scaled
+ * images, alpha-blend objects, and much more.
+ *
+ * It abstracts any need to know much about what the characteristics of
+ * your display system are or what graphics calls are used to draw them
+ * and how. It deals on an object level where all you do is create and
+ * manipulate objects in a canvas, set their properties, and the rest is
+ * done for you.
+ *
+ * Evas optimises the rendering pipeline to minimise effort in redrawing
+ * changes made to the canvas and so takes this work out of the
+ * programmers hand, saving a lot of time and energy.
+ *
+ * It is small and lean, and is designed to work on embedded systems all the way
+ * to large and powerful multi-CPU workstations. It can be compiled to
+ * only have the features you need for your target platform if you so
+ * wish, thus keeping it small and lean. It has several display
+ * back-ends, letting it display on several display systems, making it
+ * portable for cross-device and cross-platform development.
+ *
+ * @subsection evas_main_intro_not_evas What Evas is not?
+ *
+ * Evas is not a widget set or widget toolkit, however it is their
+ * base. See @ref Elementary for a toolkit based on @ref Evas, @ref Edje_Group,
+ * @ref Ecore_Group and other Enlightenment technologies.
+ *
+ * It is not dependent or aware of main loops, input or output
+ * systems. Input should be polled from various sources and fed to
+ * Evas. Similarly, it does not create windows or report windows updates
+ * to your system, but just draws the pixels and report to the
+ * user the areas that were changed.
+ * @internal
+ * Of course, these operations are quite
+ * common and thus they are ready to use in Ecore, particularly in @ref
+ * Ecore_Evas_Group.
+ * @endinternal
+ *
+ *
+ * @section evas_main_work How does Evas work?
+ *
+ * Evas is a canvas display library. This is markedly different from most
+ * display and windowing systems as a canvas is structural and is also a
+ * state engine, whereas most display and windowing systems are immediate
+ * mode display targets. Evas handles the logic between a structural
+ * display via its state engine, and controls the target windowing system
+ * in order to produce rendered results of the current canvas' state on
+ * the display.
+ *
+ * Immediate mode display systems retain very little, or no state. A
+ * program executes a series of commands, as in the pseudo code:
+ *
+ * @verbatim
+ * draw line from position (0, 0) to position (100, 200);
+ *
+ * draw rectangle from position (10, 30) to position (50, 500);
+ *
+ * bitmap_handle = create_bitmap();
+ * scale bitmap_handle to size 100 x 100;
+ * draw image bitmap_handle at position (10, 30);
+ * @endverbatim
+ *
+ * The series of commands is executed by the windowing system and the
+ * results are displayed on the screen (normally). Once the commands are
+ * executed the display system has little or no idea of how to reproduce
+ * this image again, and so has to be instructed by the application on how
+ * to redraw sections of the screen whenever needed. Each successive
+ * command is executed as instructed by the application and either
+ * emulated by software or sent to the graphics hardware on the device to
+ * be performed.
+ *
+ * The advantage of such a system is that it is simple, and gives a
+ * program tight control over how something looks and is drawn. Given the
+ * increasing complexity of displays and demands by users to have better
+ * looking interfaces, more and more work is needing to be done at this
+ * level by the internals of widget sets, custom display widgets and
+ * other programs. This means that more and more logic and display rendering
+ * code needs to be written each time the application needs to figure
+ * out how to minimise redraws so that display is fast and interactive,
+ * and keeps track of redraw logic. The power comes at a high-price,
+ * with lots of extra code and work. Programmers not very familiar with
+ * graphics programming often make mistakes at this level and produce
+ * code that is sub optimal. Those familiar with this kind of programming
+ * simply get bored by writing the same code again and again.
+ *
+ * For example, if in the above scene, the windowing system requires the
+ * application to redraw the area from 0, 0 to 50, 50 (also referred as
+ * "expose event"), then the programmer must calculate manually the
+ * updates and repaint it again:
+ *
+ * @verbatim
+ * Redraw from position (0, 0) to position (50, 50):
+ *
+ * // what is in area (0, 0, 50, 50)?
+ *
+ * // 1. intersection part of line (0, 0) to (100, 200)?
+ * draw line from position (0, 0) to position (25, 50);
+ *
+ * // 2. intersection part of rectangle (10, 30) to (50, 500)?
+ * draw rectangle from position (10, 30) to position (50, 50)
+ *
+ * // 3. intersection part of image at (10, 30), size 100 x 100?
+ * bitmap_subimage = subregion from position (0, 0) to position (40, 20)
+ * draw image bitmap_subimage at position (10, 30);
+ * @endverbatim
+ *
+ * You might have noticed that, if all elements in the above scene are
+ * opaque, then the system is doing useless paints: part of the line is
+ * behind the rectangle, and part of the rectangle is behind the image.
+ * These useless paints tend to be very costly, as pixels tend to be 4 bytes
+ * in size; thus an overlapping region of 100 x 100 pixels is around 40000
+ * useless writes! You could write code to calculate the overlapping
+ * areas and avoid painting then, but then it should be mixed with the
+ * "expose event" handling mentioned above and you quickly realize that
+ * the initially simpler method became really complex.
+ *
+ * Evas is a structural system in which the programmer creates and
+ * manages display objects and their properties, and as a result of this
+ * higher level state management, the canvas is able to redraw the set of
+ * objects when needed to represent the current state of the canvas.
+ *
+ * For example, the pseudo code:
+ *
+ * @verbatim
+ * line_handle = create_line();
+ * set line_handle from position (0, 0) to position (100, 200);
+ * show line_handle;
+ *
+ * rectangle_handle = create_rectangle();
+ * move rectangle_handle to position (10, 30);
+ * resize rectangle_handle to size 40 x 470;
+ * show rectangle_handle;
+ *
+ * bitmap_handle = create_bitmap();
+ * scale bitmap_handle to size 100 x 100;
+ * move bitmap_handle to position (10, 30);
+ * show bitmap_handle;
+ *
+ * render scene;
+ * @endverbatim
+ *
+ * This may look longer, but when the display needs to be refreshed or
+ * updated, you move, resize, show, or hide the objects that need to change.
+ * You can simply think at the object logic level, and the canvas software
+ * does the rest of the work for you, figuring out what actually changed in the
+ * canvas since it had been last drawn, how to most efficiently redraw the canvas and
+ * its contents to reflect the current state, and then it can go off and do
+ * the actual drawing of the canvas.
+ *
+ * This lets you think in a more natural way when dealing with
+ * a display, and saves time and effort of working out how to load and
+ * display images, render given the current display system, and so on. Since
+ * Evas also is portable across different display systems, this also
+ * gives you the ability to have their code ported and
+ * displayed on different display systems with very little work.
+ *
+ * Evas can be seen as a display system that stands somewhere between a
+ * widget set and an immediate mode display system. It retains basic
+ * display logic, but does very little high-level logic such as
+ * scrollbars, sliders, and push buttons.
+ *
+ * @section evas_main_next_steps Next Steps
+ *
+ * After you understood what Evas is and installed it in your system you
+ * should proceed to understand the programming interface for all
+ * objects, and then see the specifics for the most used elements.
+ * You should take a while to learn @ref Ecore_Group and @ref Edje_Group as they
+ * likely save you tons of work compared to using just Evas directly.
+ *
+ * Recommended reading:
+ *
+ * @li @ref Evas_Object_Group, where you get information on how to basically
+ * manipulate generic objects lying on an Evas canvas, handle canvas
+ * and object events, and so on.
+ * @li @ref Evas_Object_Rectangle, to learn about the most basic object
+ * type on Evas -- the rectangle.
+ * @li @ref Evas_Object_Polygon, to learn how to create polygon elements
+ * on the canvas.
+ * @li @ref Evas_Line_Group, to learn how to create line elements on the
+ * canvas.
+ * @li @ref Evas_Object_Image, to learn about image objects, over which
+ * Evas can do a plethora of operations.
+ * @li @ref Evas_Object_Text, to learn how to create textual elements on
+ * the canvas.
+ * @li @ref Evas_Object_Textblock, to learn how to create multiline
+ * textual elements on the canvas.
+ * @internal
+ * @li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define
+ * new objects that provide @b custom functions to handle clipping,
+ * hiding, moving, resizing, color setting and more. These could
+ * be as simple as a group of objects that move together (see @ref
+ * Evas_Smart_Object_Clipped) up to implementations of what
+ * ends to be a widget, providing some intelligence (thus the name)
+ * to Evas objects -- like a button or check box, for example.
+ * @endinternal
+ *
*/
#ifndef _EVAS_H
#define _EVAS_H
-#include <Efl_Config.h>
-
#include <time.h>
#include <Eina.h>
-/* This include has been added to support Eo in Evas */
-#include <Eo.h>
-#include <Efl.h>
-
-
-#include <Evas_Loader.h>
-
#ifdef EAPI
# undef EAPI
#endif
@@ -285,13 +258,14268 @@
extern "C" {
#endif
-#include <Evas_Common.h>
-#ifndef EFL_NOLEGACY_API_SUPPORT
-#include <Evas_Legacy.h>
-#endif
-#ifdef EFL_EO_API_SUPPORT
-#include <Evas_Eo.h>
-#endif
+#define EVAS_VERSION_MAJOR 1
+#define EVAS_VERSION_MINOR 8
+
+/**
+ * @typedef Evas_Version
+ * @brief The version of Evas.
+ */
+typedef struct _Evas_Version
+{
+ int major; /**< Major component of the version */
+ int minor; /**< Minor component of the version */
+ int micro; /**< Micro component of the version */
+ int revision; /**< Revision component of the version */
+} 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
+ */
+
+/* BiDi exposed stuff */
+/*FIXME: document */
+typedef enum _Evas_BiDi_Direction
+{
+ EVAS_BIDI_DIRECTION_NATURAL,
+ EVAS_BIDI_DIRECTION_NEUTRAL = EVAS_BIDI_DIRECTION_NATURAL,
+ EVAS_BIDI_DIRECTION_LTR,
+ EVAS_BIDI_DIRECTION_RTL
+} Evas_BiDi_Direction;
+
+/**
+ * @brief Identifier of callbacks to be set for Evas canvases or Evas objects.
+ *
+ * The following figure illustrates some Evas callbacks:
+ *
+ * @image html evas-callbacks.png
+ * @image rtf evas-callbacks.png
+ * @image latex evas-callbacks.eps
+ *
+ * @see evas_object_event_callback_add()
+ * @see evas_event_callback_add()
+ */
+typedef enum _Evas_Callback_Type
+{
+ /*
+ * The following events are only for use with Evas objects, with
+ * evas_object_event_callback_add():
+ */
+ EVAS_CALLBACK_MOUSE_IN, /**< 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, /**< Hold Event, Informational purpose event to indicate something */
+ EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */
+ EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */
+
+ /*
+ * The following events are only for use with Evas canvases, with
+ * evas_event_callback_add():
+ */
+ 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 just before rendering is updated on the canvas target */
+ EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */
+ EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */
+ EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */
+
+ /*
+ * More Evas object event types - see evas_object_event_callback_add():
+ */
+ 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_LAST /**< Last element/sentinel -- not really an event */
+} Evas_Callback_Type; /**< The types of events triggering a callback */
+
+/**
+ * @def EVAS_CALLBACK_PRIORITY_BEFORE
+ * @brief Slightly more prioritized than default.
+ * @since 1.1
+ */
+#define EVAS_CALLBACK_PRIORITY_BEFORE -100
+/**
+ * @def EVAS_CALLBACK_PRIORITY_DEFAULT
+ * @brief Default callback priority level
+ * @since 1.1
+ */
+#define EVAS_CALLBACK_PRIORITY_DEFAULT 0
+/**
+ * @def EVAS_CALLBACK_PRIORITY_AFTER
+ * @brief Slightly less prioritized than default.
+ * @since 1.1
+ */
+#define EVAS_CALLBACK_PRIORITY_AFTER 100
+
+/**
+ * @typedef Evas_Callback_Priority
+ *
+ * @brief Callback priority value. Range is -32k to 32k. The lower the number, the
+ * higher the priority.
+ *
+ * @since 1.1
+ *
+ * @see EVAS_CALLBACK_PRIORITY_AFTER
+ * @see EVAS_CALLBACK_PRIORITY_BEFORE
+ * @see EVAS_CALLBACK_PRIORITY_DEFAULT
+ */
+typedef short Evas_Callback_Priority;
+
+/**
+ * @brief Enumeration for Mouse Button events.
+ */
+typedef enum _Evas_Button_Flags
+{
+ EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */
+ EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< Second press of a double click */
+ EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< Third press of a triple click */
+} Evas_Button_Flags; /**< Flags for Mouse Button events */
+
+/**
+ * @brief Enumeration for events.
+ */
+typedef enum _Evas_Event_Flags
+{
+ EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */
+ EVAS_EVENT_FLAG_ON_HOLD = (1 << 0), /**< The event is being delivered but should be put "on hold" until the on hold flag is unset \n
+ The event should be used for informational purposes and maybe for some indications visually, but should not actually perform anything. */
+ EVAS_EVENT_FLAG_ON_SCROLL = (1 << 1) /**< The event occurs while scrolling \n
+ For example, DOWN event occurs during scrolling; the event should be used for informational purposes and maybe for some indications visually, but should not actually perform anything. */
+} Evas_Event_Flags; /**< Flags for Events */
+
+/**
+ * @brief Enumeration for touch point states.
+ */
+typedef enum _Evas_Touch_Point_State
+{
+ EVAS_TOUCH_POINT_DOWN, /**< Touch point is pressed down */
+ EVAS_TOUCH_POINT_UP, /**< Touch point is released */
+ EVAS_TOUCH_POINT_MOVE, /**< Touch point is moved */
+ EVAS_TOUCH_POINT_STILL, /**< Touch point is not moved after pressed */
+ EVAS_TOUCH_POINT_CANCEL /**< Touch point is cancelled */
+} Evas_Touch_Point_State;
+
+/**
+ * @brief Enumeration for font hinting.
+ * @ingroup Evas_Font_Group
+ */
+typedef enum _Evas_Font_Hinting_Flags
+{
+ EVAS_FONT_HINTING_NONE, /**< No font hinting */
+ EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
+ EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
+} Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */
+
+/**
+ * @brief Enumeration for pixel data of colorspaces supported by Evas.
+ * @ingroup Evas_Object_Image
+ */
+typedef enum _Evas_Colorspace
+{
+ EVAS_COLORSPACE_ARGB8888, /**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */
+ /* The following are not currently supported - but planned for the future */
+ 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 */
+ 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 */
+ EVAS_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */
+ EVAS_COLORSPACE_GRY8, /**< 8bit grayscale */
+ 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 */
+ 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. */
+ 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. */
+ EVAS_COLORSPACE_AGRY88, /**< AY 8bits Alpha and 8bits Grey, accessed 1 16bits at a time */
+ EVAS_COLORSPACE_ETC1, /**< OpenGL ETC1 encoding of RGB texture (4 bit per pixel) @since 1.10 */
+ EVAS_COLORSPACE_RGB8_ETC2, /**< OpenGL GL_COMPRESSED_RGB8_ETC2 texture compression format (4 bit per pixel) @since 1.10 */
+ EVAS_COLORSPACE_RGBA8_ETC2_EAC, /**< OpenGL GL_COMPRESSED_RGBA8_ETC2_EAC texture compression format, supports alpha (8 bit per pixel) @since 1.10 */
+ EVAS_COLORSPACE_ETC1_ALPHA, /**< ETC1 with alpha support using two planes: ETC1 RGB and ETC1 grey for alpha @since 1.11 */
+} Evas_Colorspace; /**< Colorspaces for pixel data supported by Evas */
+
+/**
+ * @brief Enumeration for modes of packing items into cells in a table.
+ *
+ * @see evas_object_table_homogeneous_set() for an explanation of the function of
+ * each one.
+ * @ingroup Evas_Object_Table
+ */
+typedef enum _Evas_Object_Table_Homogeneous_Mode
+{
+ EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0,
+ EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1,
+ EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2
+} Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode */
+
+typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< @brief A generic rectangle handle */
+typedef struct _Evas_Point Evas_Point; /**< @brief Integer point */
+
+typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< @brief Evas_Coord point */
+typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< @brief Evas_Coord point with sub-pixel precision */
+
+typedef struct _Evas_Coord_Size Evas_Coord_Size; /**< @brief Evas_Coord size @since 1.8 */
+typedef struct _Evas_Position Evas_Position; /**< @brief Associates the given point in Canvas and Output */
+typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< @brief Associates the given point in Canvas and Output, with sub-pixel precision */
+
+/**
+ * @typedef Evas_Smart_Class
+ *
+ * @brief A smart object @b base class definition.
+ *
+ * @ingroup Evas_Smart_Group
+ */
+typedef struct _Evas_Smart_Class Evas_Smart_Class;
+
+/**
+ * @typedef Evas_Smart_Interface
+ *
+ * @brief A smart object @b base interface definition.
+ *
+ * @since 1.7
+ *
+ * @remarks An Evas interface is exactly like the OO-concept: It is a 'contract' or
+ * API that the object is declared to support. A smart object may have
+ * more than one interface, thus extending the behavior it gets from
+ * sub-classing.
+ *
+ * @ingroup Evas_Smart_Group
+ */
+typedef struct _Evas_Smart_Interface Evas_Smart_Interface;
+
+/**
+ * @typedef Evas_Smart_Cb_Description
+ *
+ * @brief 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_Map
+ *
+ * @brief An opaque handle to map points.
+ *
+ * @see evas_map_new()
+ * @see evas_map_free()
+ * @see evas_map_dup()
+ *
+ * @ingroup Evas_Object_Group_Map
+ */
+typedef struct _Evas_Map Evas_Map;
+
+/**
+ * @typedef Evas
+ *
+ * @brief An opaque handle to an Evas canvas.
+ *
+ * @see evas_new()
+ * @see evas_free()
+ *
+ * @ingroup Evas_Canvas
+ */
+typedef struct _Evas Evas;
+
+/**
+ * @typedef Evas_Object
+ * @brief An Evas Object handle.
+ * @ingroup Evas_Object_Group
+ */
+typedef struct _Evas_Object Evas_Object;
+
+typedef void Evas_Performance; /**< @brief Evas Performance handle */
+typedef struct _Evas_Modifier Evas_Modifier; /**< @brief Opaque type containing information on which modifier keys are registered in an Evas canvas */
+typedef struct _Evas_Lock Evas_Lock; /**< @brief Opaque type containing information on which lock keys are registered in an Evas canvas */
+typedef struct _Evas_Smart Evas_Smart; /**< @brief Evas Smart Object handle */
+typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< @brief Generic datatype for engine specific native surface information */
+
+/**
+ * @typedef Evas_Video_Surface
+ *
+ * @brief A generic data type for video specific surface information.
+ *
+ * @since 1.1
+ *
+ * @see evas_object_image_video_surface_set
+ * @see evas_object_image_video_surface_get
+ */
+typedef struct _Evas_Video_Surface Evas_Video_Surface;
+
+typedef unsigned long long Evas_Modifier_Mask; /**< @brief An Evas modifier mask type */
+
+typedef int Evas_Coord; /**< @brief Evas x y coordinates */
+typedef int Evas_Font_Size; /**< @brief Evas Font Sizes */
+typedef int Evas_Angle; /**< @brief Evas angle */
+
+struct _Evas_Coord_Rectangle /**< @brief 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_Point
+{
+ int x, y;
+};
+
+struct _Evas_Coord_Point
+{
+ Evas_Coord x; /**< X co-ordinate */
+ Evas_Coord y; /**< Y co-ordinate */
+};
+
+struct _Evas_Coord_Size
+{
+ Evas_Coord w; /**< Width */
+ Evas_Coord h; /**< Height */
+};
+
+struct _Evas_Coord_Precision_Point
+{
+ Evas_Coord x, y;
+ double xsub, ysub;
+};
+
+struct _Evas_Position
+{
+ Evas_Point output;
+ Evas_Coord_Point canvas; /**< Position on the canvas */
+};
+
+struct _Evas_Precision_Position
+{
+ Evas_Point output;
+ Evas_Coord_Precision_Point canvas;
+};
+
+/**
+ * @brief Enumeration for aspect types or policies for scaling size hints, used for evas_object_size_hint_aspect_set().
+ */
+typedef enum _Evas_Aspect_Control
+{
+ EVAS_ASPECT_CONTROL_NONE = 0, /**< Unset scaling preference */
+ 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 or policies for scaling size hints, used for evas_object_size_hint_aspect_set() */
+
+/**
+ * @brief Enumeration for object's display modes.
+ */
+typedef enum _Evas_Display_Mode
+{
+ EVAS_DISPLAY_MODE_NONE = 0, /**<Default display mode */
+ EVAS_DISPLAY_MODE_INHERIT = 1, /**< Object display mode depends on its ancestor display mode */
+ EVAS_DISPLAY_MODE_COMPRESS = 2, /**< Give compress display mode hint to object */
+ EVAS_DISPLAY_MODE_EXPAND = 3, /**< Give expand display mode hint to object */
+ EVAS_DISPLAY_MODE_DONT_CHANGE = 4 /**< Object does not change display mode */
+} Evas_Display_Mode; /**< Object display mode type related with compress and expand or etc mode */
+
+typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< @brief A source description of pixels for importing pixels */
+typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< @brief A generic Evas Engine information structure */
+typedef struct _Evas_Device Evas_Device; /**< @brief A source device handle - where the event came from */
+typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
+typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
+typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
+typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
+typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
+typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
+typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< @brief Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
+typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< @brief Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
+typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< @brief Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
+typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< @brief Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
+typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< @brief Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
+typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< @brief Event structure for #EVAS_CALLBACK_HOLD event callbacks */
+
+/**
+ * @brief Enumeration for load errors.
+ */
+typedef enum _Evas_Load_Error
+{
+ EVAS_LOAD_ERROR_NONE = 0, /**< No error on load */
+ EVAS_LOAD_ERROR_GENERIC = 1, /**< A non-specific error occurred */
+ EVAS_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< File (or file path) does not exist */
+ EVAS_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission denied to an existing file (or path) */
+ EVAS_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Allocation of resources failure prevented load */
+ EVAS_LOAD_ERROR_CORRUPT_FILE = 5, /**< File corrupt (but is detected as a known format) */
+ EVAS_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */
+} Evas_Load_Error; /**< Evas image load error codes one can get - see evas_load_error_str() */
+
+/**
+ * @brief Enumeration for allocation errors.
+ */
+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, but extra memory had to be found by freeing up speculative resources */
+} Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */
+
+/**
+ * @brief Enumeration for spread of image fill.
+ */
+typedef enum _Evas_Fill_Spread
+{
+ EVAS_TEXTURE_REFLECT = 0, /**< Image fill tiling mode - tiling reflects */
+ EVAS_TEXTURE_REPEAT = 1, /**< Tiling repeats */
+ EVAS_TEXTURE_RESTRICT = 2, /**< Tiling clamps - range offset ignored */
+ EVAS_TEXTURE_RESTRICT_REFLECT = 3, /**< Tiling clamps and any range offset reflects */
+ EVAS_TEXTURE_RESTRICT_REPEAT = 4, /**< Tiling clamps and any range offset repeats */
+ EVAS_TEXTURE_PAD = 5 /**< Tiling extends with end values */
+} Evas_Fill_Spread; /**< Fill types used for evas_object_image_fill_spread_set() */
+
+/**
+ * @brief Enumeration for aspect types or policies.
+ */
+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 i.e. ARGB32, YUV420P_601, and so on */
+ int w, h; /**< Width and height of source in pixels */
+ void **rows; /**< Array of pointers (size depends on format) pointing to left edge of each scanline */
+};
+
+/* Magic version number to know what the native surf struct looks like */
+#define EVAS_NATIVE_SURFACE_VERSION 3
+
+/**
+ * @brief Native surface types that image object supports
+ *
+ * @see Evas_Native_Surface
+ * @see evas_object_image_native_surface_set()
+ */
+typedef enum _Evas_Native_Surface_Type
+{
+ EVAS_NATIVE_SURFACE_NONE, /**< No surface type */
+ EVAS_NATIVE_SURFACE_X11, /**< X Window system based type. pixmap id or visual of the pixmap */
+ EVAS_NATIVE_SURFACE_OPENGL, /**< OpenGL system based type. texture or framebuffer id*/
+ EVAS_NATIVE_SURFACE_TIZEN, /**< @internal don't use this type but @see EVAS_NATIVE_SURFACE_TBM */
+ EVAS_NATIVE_SURFACE_TBM /**< Tizen system based type. This is used for tizen buffer manager. */
+} Evas_Native_Surface_Type;
+
+/**
+ * @brief A generic datatype for engine specific native surface information.
+ *
+ * Please fill up Evas_Native_Surface fields that regarded with current surface
+ * type. If you want to set the native surface type to
+ * EVAS_NATIVE_SURFACE_X11, you need to set union data with x11.visual or
+ * x11.pixmap. If you need to set the native surface as
+ * EVAS_NATIVE_SURFACE_OPENGL, on the other hand, you need to set union data
+ * with opengl.texture_id or opengl.framebuffer_id and so on. The version field
+ * should be set with EVAS_NATIVE_SURFACE_VERSION in order to check abi
+ * break in your application on the different efl library versions.
+ *
+ * @warning Native surface types totally depend on the system. Please
+ * be aware that the types are supported on your system before using
+ * them.
+ * @see evas_object_image_native_surface_set()
+ */
+struct _Evas_Native_Surface
+{
+ int version; /**< Current Native Surface Version. Use EVAS_NATIVE_SURFACE_VERSION */
+ Evas_Native_Surface_Type type; /**< Surface type. @see Evas_Native_Surface_Type */
+ union {
+ struct
+ {
+ void *visual; /**< Visual of the pixmap to use (Visual) */
+ unsigned long pixmap; /**< Pixmap ID to use (Pixmap) */
+ } x11; /**< Set this struct fields if your surface data is X11 based. */
+ struct
+ {
+ unsigned int texture_id; /**< opengl texture ID to use from glGenTextures() */
+ unsigned int framebuffer_id; /**< 0 if this is not an FBO, otherwise FBO ID from glGenFramebuffers() */
+ unsigned int internal_format; /**< Same as 'internalFormat' for glTexImage2D() */
+ unsigned int format; /**< Same as 'format' for glTexImage2D() */
+ 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) */
+ } opengl; /**< Set this struct fields if your surface data is OpenGL based. */
+ struct
+ {
+ void *buffer; /**< tbm surface */
+ int rot; /**< rotation (0, 90, 180, 270) */
+ float ratio; /**< width/height ratio of the source image */
+ int flip; /**< flip (0:none, 1:horizontal, 2:vertical, 3:both) */
+ } tizen; /**< Set this struct fields if your surface data is Tizen based. */
+ } data; /**< Choose one union data according to your surface. */
+};
+
+/**
+ * @def EVAS_VIDEO_SURFACE_VERSION
+ * @brief Definition of the magic version number to know what the video surf struct looks like.
+ * @since 1.1
+ */
+#define EVAS_VIDEO_SURFACE_VERSION 1
+
+typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface);
+typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b);
+
+/**
+ * @brief Struct of Evas Video Surface.
+ */
+struct _Evas_Video_Surface
+{
+ int version;
+
+ Evas_Video_Coord_Cb move; /**< Moves the video surface to this position */
+ Evas_Video_Coord_Cb resize; /**< Resizes the video surface to that size */
+ Evas_Video_Cb show; /**< Shows the video overlay surface */
+ Evas_Video_Cb hide; /**< Hides the video overlay surface */
+ Evas_Video_Cb update_pixels; /**< Updates the Evas_Object_Image pixels when called */
+
+ Evas_Object *parent;
+ void *data;
+};
+
+#define EVAS_LAYER_MIN -32768 /**< @brief Bottom-most layer number */
+#define EVAS_LAYER_MAX 32767 /**< @brief Top-most layer number */
+
+#define EVAS_COLOR_SPACE_ARGB 0 /**< @brief Not used for anything */
+#define EVAS_COLOR_SPACE_AHSV 1 /**< @brief Not used for anything */
+#define EVAS_TEXT_INVALID -1 /**< @brief Not used for anything */
+#define EVAS_TEXT_SPECIAL -2 /**< @brief Not used for anything */
+
+#define EVAS_HINT_EXPAND 1.0 /**< @brief 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 /**< @brief 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() */
+
+/**
+ * @brief Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align)
+ * @ingroup Evas_Object_Group_Size_Hints
+ */
+#define evas_object_size_hint_fill_set evas_object_size_hint_align_set
+
+/**
+ * @brief Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align)
+ * @ingroup Evas_Object_Group_Size_Hints
+ */
+#define evas_object_size_hint_fill_get evas_object_size_hint_align_get
+
+/**
+ * @brief Convenience macro to make it easier to understand that weight is also used for expand properties
+ * @ingroup Evas_Object_Group_Size_Hints
+ */
+#define evas_object_size_hint_expand_set evas_object_size_hint_weight_set
+
+/**
+ * @brief Convenience macro to make it easier to understand that weight is also used for expand properties
+ * @ingroup Evas_Object_Group_Size_Hints
+ */
+#define evas_object_size_hint_expand_get evas_object_size_hint_weight_get
+
+/**
+ * @brief Enumeration for modes of object rendering to output.
+ * @ingroup Evas_Object_Group_Extras
+ */
+typedef enum _Evas_Render_Op
+{
+ EVAS_RENDER_BLEND = 0, /**< Default op: d = d*(1-sa) + s */
+ EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */
+ EVAS_RENDER_COPY = 2, /**< d = s */
+ EVAS_RENDER_COPY_REL = 3, /**< d = s*da */
+ EVAS_RENDER_ADD = 4, /* d = d + s */
+ EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */
+ EVAS_RENDER_SUB = 6, /**< d = d - s */
+ EVAS_RENDER_SUB_REL = 7, /* d = d - s*da */
+ EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */
+ EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */
+ EVAS_RENDER_MASK = 10, /**< d = d*sa */
+ EVAS_RENDER_MUL = 11 /**< d = d*s */
+} Evas_Render_Op; /**< How the object should be rendered to output */
+
+/**
+ * @brief Enumeration for border fill mode.
+ */
+typedef enum _Evas_Border_Fill_Mode
+{
+ EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */
+ 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 */
+ EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */
+} Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */
+
+/**
+ * @brief Enumeration for image scale hints.
+ */
+typedef enum _Evas_Image_Scale_Hint
+{
+ EVAS_IMAGE_SCALE_HINT_NONE = 0, /**< No scale hint at all */
+ EVAS_IMAGE_SCALE_HINT_DYNAMIC = 1, /**< Image is being re-scaled over time, thus turning scaling cache @b off for its data */
+ EVAS_IMAGE_SCALE_HINT_STATIC = 2 /**< Image is not being re-scaled over time, thus turning scaling cache @b on for its data */
+} Evas_Image_Scale_Hint; /**< How an image's data is to be treated by Evas, with regard to scaling cache */
+
+/**
+ * @brief Enumeration for animated loop hints.
+ */
+typedef enum _Evas_Image_Animated_Loop_Hint
+{
+ EVAS_IMAGE_ANIMATED_HINT_NONE = 0,
+ EVAS_IMAGE_ANIMATED_HINT_LOOP = 1, /**< Image's animation mode is loop like 1->2->3->1->2->3 */
+ EVAS_IMAGE_ANIMATED_HINT_PINGPONG = 2 /**< Image's animation mode is pingpong like 1->2->3->2->1-> ... */
+} Evas_Image_Animated_Loop_Hint;
+
+/**
+ * @brief Enumeration for engine rendering modes.
+ */
+typedef enum _Evas_Engine_Render_Mode
+{
+ EVAS_RENDER_MODE_BLOCKING = 0,
+ EVAS_RENDER_MODE_NONBLOCKING = 1,
+} Evas_Engine_Render_Mode;
+
+/**
+ * @brief Enumeration for image content hints.
+ */
+typedef enum _Evas_Image_Content_Hint
+{
+ EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
+ EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents change over time */
+ EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents do not change over time */
+} Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
+
+/**
+ * @brief Enumeration for device class.
+ */
+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, /**< Regular keyboard, numberpad or attached buttons @since 1.8 */
+ EVAS_DEVICE_CLASS_MOUSE, /**< Mouse, trackball or touchpad relative motion device @since 1.8 */
+ EVAS_DEVICE_CLASS_TOUCH, /**< Touchscreen with fingers or stylus @since 1.8 */
+ EVAS_DEVICE_CLASS_PEN, /**< Special pen device @since 1.8 */
+ EVAS_DEVICE_CLASS_POINTER, /**< Laser pointer, wii-style or "minority report" pointing device @since 1.8 */
+ EVAS_DEVICE_CLASS_GAMEPAD /**< Gamepad controller or joystick @since 1.8 */
+} Evas_Device_Class;
+
+struct _Evas_Engine_Info /** @brief Generic engine information. Generic info is not of much use. */
+{
+ int magic; /**< Magic number */
+};
+
+struct _Evas_Event_Mouse_Down /** @brief Mouse button press event */
+{
+ int button; /**< Mouse button number that went down (1 - 32) */
+
+ Evas_Point output; /**< The X/Y location of the cursor */
+ Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+
+ Evas_Button_Flags flags; /**< Button flags set during the event */
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Mouse_Up /** @brief Mouse button release event */
+{
+ int button; /**< Mouse button number that is raised (1 - 32) */
+
+ Evas_Point output; /**< The X/Y location of the cursor */
+ Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+
+ Evas_Button_Flags flags; /**< Button flags set during the event */
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Mouse_In /** @brief Mouse enter event */
+{
+ int buttons; /**< Button pressed mask, Bits set to @c 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 and so on) */
+
+ Evas_Point output; /**< The X/Y location of the cursor */
+ Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Mouse_Out /** @brief Mouse leave event */
+{
+ int buttons; /**< Button pressed mask, Bits set to @c 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 and so on) */
+
+ Evas_Point output; /**< The X/Y location of the cursor */
+ Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Mouse_Move /** @brief Mouse move event */
+{
+ int buttons; /**< Button pressed mask, Bits set to @c 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 and so on) */
+
+ Evas_Position cur; /**< Current mouse position */
+ Evas_Position prev; /**< Previous mouse position */
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Mouse_Wheel /** @brief Wheel event */
+{
+ int direction; /* 0 = default up/down wheel FIXME: more wheel types */
+ int z; /* ...,-2,-1 = down, 1,2,... = up */
+
+ Evas_Point output; /**< The X/Y location of the cursor */
+ Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Multi_Down /** @brief Multi button press event */
+{
+ int device; /**< Multi device number that went down (1 or more for extra touches) */
+ double radius, radius_x, radius_y;
+ double pressure, angle;
+
+ Evas_Point output;
+ Evas_Coord_Precision_Point canvas;
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+
+ Evas_Button_Flags flags; /**< Button flags set during the event */
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Multi_Up /** @brief Multi button release event */
+{
+ int device; /**< Multi device number that went up (1 or more for extra touches) */
+ double radius, radius_x, radius_y;
+ double pressure, angle;
+
+ Evas_Point output;
+ Evas_Coord_Precision_Point canvas;
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+
+ Evas_Button_Flags flags; /**< Button flags set during the event */
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Multi_Move /** @brief Multi button down event */
+{
+ int device; /**< Multi device number that moved (1 or more for extra touches) */
+ double radius, radius_x, radius_y;
+ double pressure, angle;
+
+ Evas_Precision_Position cur;
+
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Key_Down /** @brief Key press event */
+{
+ char *keyname; /**< Name string of the key pressed */
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+
+ const char *key; /**< Logical key : (example, shift+1 == exclamation) */
+ const char *string; /**< UTF8 string if this keystroke has produced a visible string to be ADDED */
+ const char *compose; /**< UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Key_Up /** @brief Key release event */
+{
+ char *keyname; /**< Name string of the key released */
+ void *data;
+ Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */
+ Evas_Lock *locks;
+
+ const char *key; /**< Logical key : (example, shift+1 == exclamation) */
+ const char *string; /**< UTF8 string if this keystroke has produced a visible string to be ADDED */
+ const char *compose; /**< UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+struct _Evas_Event_Hold /** @brief Hold change event */
+{
+ int hold; /**< Hold flag */
+ void *data;
+
+ unsigned int timestamp;
+ Evas_Event_Flags event_flags;
+ Evas_Device *dev;
+};
+
+/**
+ * @brief Enumeration for handling mouse pointer.
+ *
+ * @remarks 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 is fed to the object, that may check if
+ * the final position is over it or not and do something about it.
+ *
+ * @remarks In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer is
+ * always 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 and touch up and down events ARE NOT repeated to objects and these objects are not auto-grabbed @since 1.2 */
+} Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas */
+
+/**
+ * @brief Evas smart objects' "smart callback" function signature
+ * @since_tizen 2.3
+ * @ingroup Evas_Smart_Object_Group
+ */
+typedef void (*Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info);
+
+/**
+ * @brief Evas event callback function signature
+ * @since_tizen 2.3
+ * @ingroup Evas_Canvas_Events
+ */
+typedef void (*Evas_Event_Cb)(void *data, Evas *e, void *event_info);
+
+/**
+ * @brief Evas event callback Post function signature
+ * @since_tizen 2.3
+ * @ingroup Evas_Canvas_Events
+ */
+typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e);
+
+/**
+ * @brief Evas object event callback function signature
+ * @since_tizen 2.3
+ * @ingroup Evas_Object_Group_Events
+ */
+typedef void (*Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info);
+
+/**
+ * @brief Evas Async events put function signature
+ * @since_tizen 2.3
+ * @ingroup Evas_Top_Group
+ */
+typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Top_Group Top Level Functions
+ @ingroup Evas
+ *
+ * @brief This group provides functions that affect Evas as a whole.
+ * @{
+ */
+
+/**
+ * @brief Initializes Evas.
+ *
+ * @details This function initializes Evas and increments a counter of the
+ * number of calls to it. It returns the new counter value.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Most EFL users do not use this function directly, because
+ * they do not access Evas directly by themselves. Instead, they
+ * use higher level helpers, like @c ecore_evas_init().
+ * See http://docs.enlightenment.org/auto/ecore/
+ *
+ * @return The init counter value
+ *
+ * @see evas_shutdown()
+ *
+ * @ingroup Evas_Top_Group
+ */
+EAPI int evas_init(void);
+
+/**
+ * @brief Shuts down Evas.
+ *
+ * @details This function finalizes Evas, decrementing the counter of the
+ * number of calls to the function evas_init(). This new value for the
+ * counter is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you are the sole user of Evas, you can use evas_init() to
+ * check if it is being properly shut down by expecting a return value
+ * of @c 0.
+ *
+ * @return The Evas init counter value
+ *
+ * @see evas_init()
+ *
+ * @ingroup Evas_Top_Group
+ */
+EAPI int evas_shutdown(void);
+
+/**
+ * @brief Gets the allocation errors that have occurred during the execution of the prior function.
+ *
+ * @details This function returns any memory allocation errors that occurred during the execution
+ * and the kind of errors. Valid return values are @c EVAS_ALLOC_ERROR_NONE,
+ * @c EVAS_ALLOC_ERROR_FATAL, and @c EVAS_ALLOC_ERROR_RECOVERED.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks @c EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function
+ * worked as expected.
+ *
+ * @remarks @c EVAS_ALLOC_ERROR_FATAL means the function is completely unable to perform
+ * its job and exited as cleanly as possible. You should consider this as a
+ * sign of very low memory and should try and safely recover from the prior function
+ * failure. You can also try to free up memory elsewhere and try again after memory is freed.
+ *
+ * @remarks @c EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but Evas
+ * recovered from it by finding memory of its own that it has allocated and
+ * freeing what it sees as not really usefully allocated memory. What is freed
+ * may vary. Evas may reduce the resolution of images, free cached images or
+ * fonts, throw out pre-rendered data, reduce the complexity of change lists,
+ * and so on. Evas and the program functions as per normal after this, but this
+ * is a sign of low memory, and it is suggested that your program try and
+ * identify memory it does not need, and free it.
+ *
+ * @remarks The following is an 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: Completely unable to attach callback. Must\n");
+ * fprintf(stderr, " destroy object now as it cannot be used.\n");
+ * evas_object_del(object);
+ * object = NULL;
+ * fprintf(stderr, "WARNING: Memory is really low. 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
+ *
+ * @return The allocation error flag
+ *
+ * @ingroup Evas_Top_Group
+ */
+EAPI Evas_Alloc_Error evas_alloc_error(void);
+
+/**
+ * @brief Gets the Evas internal asynchronous events read file descriptor.
+ *
+ * @details This function returns the read file descriptor of the
+ * asynchronous events of the canvas. Other mainloops,
+ * apart from ecore, may make use of it.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The Evas asynchronous events are meant to be dealt with internally,
+ * i.e., when building stuff to be glued together into the EFL
+ * infrastructure - a module, for example. The context which demands
+ * its use is when calculations need to be done out of the main
+ * thread, asynchronously, and some action must be performed after
+ * that.
+ *
+ * @remarks An example of the actual use of this API is for image asynchronous
+ * preload inside Evas. If the canvas is instantiated through
+ * ecore-evas usage, ecore itself takes care of calling those
+ * event processing.
+ *
+ * @return The asynchronous events read file descriptor of the canvas
+ *
+ * @ingroup Evas_Top_Group
+ */
+EAPI int evas_async_events_fd_get(void) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Triggers the processing of all events waiting on the file
+ * descriptor returned by evas_async_events_fd_get().
+ *
+ * @details All asynchronous events queued up by evas_async_events_put() are
+ * processed here. More precisely, the callback functions, informed
+ * together with other event parameters, when queued, get called (with
+ * those parameters), in that order.
+ *
+ * @since_tizen 2.3
+ *
+ * @return The number of events processed
+ *
+ * @ingroup Evas_Top_Group
+ */
+EAPI int evas_async_events_process(void);
+
+/**
+ * @brief Inserts asynchronous events on the canvas.
+ *
+ * @details This is the way, for a routine running outside evas' main thread,
+ * to report an asynchronous event. A callback function is informed,
+ * whose call is to happen after evas_async_events_process() is
+ * called.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] target The target to be affected by the events
+ * @param[in] type The type of callback function
+ * @param[in] event_info The information about the event
+ * @param[in] func The callback function pointer
+ * @return #EINA_TRUE if the events are inserted successfully, \n
+ * otherwise #EINA_FALSE on failure
+ *
+ * @ingroup Evas_Top_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
+ *
+ * @brief This group provides low level Evas canvas functions. Sub-groups
+ * present more high level ones, though.
+ *
+ * @remarks Most of these functions deal with low level Evas actions, like:
+ * @li creating or destroying raw canvases, not bound to any displaying engine
+ * @li telling a canvas that it got focused (in a windowing context, for example)
+ * @li telling a canvas that a region should not be calculated anymore in rendering
+ * @li telling a canvas to render its contents, immediately
+ *
+ * @remarks You mostly use Evas with the @c Ecore_Evas wrapper, which
+ * deals with all the above mentioned issues automatically. Thus, you
+ * need this section only if you are building low level stuff.
+ *
+ * @remarks The groups 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.
+ *
+ * @{
+ */
+
+/**
+ * @brief Creates a new empty evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function should only fail if the memory allocation fails.
+ *
+ * @remarks This function is a very low level function. Instead of using it
+ * directly, consider using the high level functions in
+ * Ecore_Evas such as @c ecore_evas_new(). See
+ * http://docs.enlightenment.org/auto/ecore/
+ *
+ * @remarks It is recommended that you call evas_init() before creating new canvas.
+ *
+ * @return A new uninitialised Evas canvas on success, \n
+ * otherwise @c NULL on failure
+ *
+ * @pre Note that before you can use evas, you have to:
+ * @li Set its render method with @ref evas_output_method_set.
+ * @li Set its viewport size with @ref evas_output_viewport_set.
+ * @li Set its size of the canvas with @ref evas_output_size_set.
+ * @li Ensure that the render engine is given the correct settings
+ * with @ref evas_engine_info_set.
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI Evas *evas_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
+
+/**
+ * @brief Frees the given evas and any objects created on it.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Any objects with 'free' callbacks have those callbacks called
+ * in this function.
+ *
+ * @param[in] e The given evas
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_free(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Informs evas that it has got focus.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The evas to inform
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_focus_in(Evas *e);
+
+/**
+ * @brief Informs the evas that it has lost focus.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The evas to inform
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_focus_out(Evas *e);
+
+/**
+ * @brief Gets the focus state of the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The evas to query information
+ * @return #EINA_TRUE if it is focused, otherwise #EINA_FALSE.
+ * @ingroup Evas_Canvas
+ */
+EAPI Eina_Bool evas_focus_state_get(const Evas *e);
+
+/**
+ * @brief Pushes the nochange flag up @c 1.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This tells evas that while the nochange flag is greater than 0, do not
+ * mark objects as "changed" when making changes.
+ *
+ * @param[in] e The evas to changes information
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_nochange_push(Evas *e);
+
+/**
+ * @brief Pops the nochange flag down @c 1.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This tells evas that while the nochange flag is greater than 0, do not
+ * mark objects as "changed" when making changes.
+ *
+ * @param[in] e The evas to change information
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_nochange_pop(Evas *e);
+
+/**
+ * @brief Attaches a specific pointer to evas for fetching later.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The canvas to attach the pointer to
+ * @param[in] data The pointer to attach
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_data_attach_set(Evas *e, void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the pointer attached by evas_data_attach_set().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The canvas to attach the pointer to
+ * @return The pointer attached
+ * @ingroup Evas_Canvas
+ */
+EAPI void *evas_data_attach_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Adds a damage rectangle.
+ *
+ * @details You can use this function to inform evas that a part of the
+ * canvas has to be repainted.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks All newly created Evas rectangles get the default color values
+ * of 255 255 255 255 (opaque white).
+ *
+ * @param[in] e The given canvas pointer
+ * @param[in] x The rectangle's left position
+ * @param[in] y The rectangle's top position
+ * @param[in] w The rectangle's width
+ * @param[in] h The rectangle's height
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_damage_rectangle_add(Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Adds an "obscured region" to an Evas canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks You can use this function to inform an Evas canvas that a part
+ * of it <b>must not</b> be repainted. The region must be
+ * rectangular and its coordinates inside the canvas viewport are
+ * passed in the call. After this call, the region specified do not
+ * participate in any form in Evas' calculations and actions during
+ * its rendering updates, having its displaying content frozen as it
+ * is just after this function is executed.
+ *
+ * @remarks This is called "obscured region" because the most common use case for
+ * this rendering (partial) freeze is something else (most probably
+ * other canvas) being on top of the specified rectangular region,
+ * thus shading it completely from the user's final scene in a
+ * display. To avoid unnecessary processing, one should indicate to the
+ * obscured canvas not to bother about the non-important area.
+ *
+ * @remarks The majority of users do not have to worry about this function, as
+ * they use just one canvas in their applications, with
+ * nothing inset or on top of it in any form.
+ *
+ * @remarks To make this region one that @b has to be repainted again, call the
+ * function evas_obscured_clear().
+ *
+ * @remarks This is a <b>very low level function</b>, which you may not use.
+ *
+ * @remarks This function does @b not flag the canvas as having its state
+ * changed. If you want to re-render it afterwards expecting new
+ * contents, you have to add "damage" regions yourself (see
+ * evas_damage_rectangle_add()).
+ *
+ * @param[in] e The given canvas pointer
+ * @param[in] x The rectangle's top left corner's horizontal coordinate
+ * @param[in] y The rectangle's top left corner's vertical coordinate
+ * @param[in] w The rectangle's width
+ * @param[in] h The rectangle's height
+ *
+ * @see evas_obscured_clear()
+ * @see evas_render_updates()
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_obscured_rectangle_add(Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Removes all "obscured regions" from an Evas canvas.
+ *
+ * @details This function removes all the rectangles from the obscured regions
+ * list of the canvas @a e. It takes obscured areas added with
+ * evas_obscured_rectangle_add() and make them again a regions that @b
+ * have to be repainted on rendering updates.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a <b>very low level function</b>, which you may not use.
+ *
+ * @remarks This function does @b not flag the canvas as having its state
+ * changed. If you want to re-render it afterwards expecting new
+ * contents, you have to add "damage" regions yourself (see
+ * evas_damage_rectangle_add()).
+ *
+ * @param[in] e The given canvas pointer
+ *
+ * @see evas_obscured_rectangle_add() for an example
+ * @see evas_render_updates()
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_obscured_clear(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Forces immediate renderization of the given Evas canvas.
+ *
+ * @details This function forces an immediate renderization update of the given
+ * canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a <b>very low level function</b>, which you may not use.
+ * You would use it, for example, to grab an Evas' canvas update regions
+ * and paint them back, using the canvas' pixmap, on a displaying system
+ * working below Evas.
+ *
+ * @remarks Evas is a stateful canvas. If no operations changing its
+ * state took place since the last rendering action, you do not see any
+ * changes and this call becomes a no-op.
+ *
+ * @param[in] e The given canvas pointer
+ * @return A newly allocated list of updated rectangles of the canvas (@c Eina_Rectangle structs) \n
+ * Free this list with evas_render_updates_free().
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI Eina_List *evas_render_updates(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Frees the rectangles returned by evas_render_updates().
+ *
+ * @details This function removes the region from the render updates list.
+ * The region does not get render updated anymore.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] updates The list of updated rectangles of the canvas
+ *
+ * @see evas_render_updates() for an example
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_render_updates_free(Eina_List *updates);
+
+/**
+ * @brief Forces rendering of the given canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given canvas pointer
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_render(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Updates the canvas internal objects but does not trigger immediate rendering.
+ *
+ * @details This function updates the canvas internal objects not triggering
+ * rendering. To force rendering, use evas_render().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given canvas pointer
+ *
+ * @see evas_render
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_norender(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Makes the canvas discard internally cached data used for rendering.
+ *
+ * @details This function flushes the arrays of delete, active and render objects.
+ * The other things it may discard include shared memory segments,
+ * temporary scratch buffers, and cached data to avoid re-compute of that data.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given canvas pointer
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_render_idle_flush(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Makes the canvas discard as much data as possible used by the engine at runtime.
+ *
+ * @details This function unloads images, deletes textures and much more, where
+ * possible. You may also want to call evas_render_idle_flush() immediately
+ * prior to this to perhaps discard a little more, though evas_render_dump()
+ * should implicitly delete most of what evas_render_idle_flush() might
+ * discard too.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given canvas pointer
+ *
+ * @ingroup Evas_Canvas
+ */
+EAPI void evas_render_dump(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Output_Method Render Engine Functions
+ * @ingroup Evas_Canvas
+ *
+ * @brief This goup provides functions that are used to set the render engine for a given
+ * function, and then get that engine working.
+ *
+ * @remarks 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
+ *
+ * @{
+ */
+
+/**
+ * @brief Looks up a numeric ID from a string name of a rendering engine.
+ *
+ * @details This function looks up a numeric return value for the named engine
+ * in the string @a name. This is a normal C string, NULL byte
+ * terminated. The name is case sensitive. If the rendering engine is
+ * available, a numeric ID for that engine is returned that is not
+ * @c 0. If the engine is not available, @c 0 is returned, indicating an
+ * invalid engine.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks You should NEVER rely on the numeric ID of an engine unless it is returned
+ * by this function. You should NOT write programs written accessing render
+ * method ID's directly, without first obtaining it from this function.
+ *
+ * @remarks It is mandatory that you call evas_init() before
+ * looking up the render method.
+ *
+ * @remarks The following is an 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
+ *
+ * @param[in] name The name string of an engine
+ * @return A numeric (opaque) ID for the rendering engine
+ *
+ * @ingroup Evas_Output_Method
+ */
+EAPI int evas_render_method_lookup(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Lists all the rendering engines compiled into the copy of the Evas library.
+ *
+ * @since_tizen 2.3
+ *
+ *
+ * @remarks Calling this returns a handle (pointer) to an Evas linked
+ * list. Each node in the linked list has 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 is returned.
+ *
+ * @remarks The following is an 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
+ *
+ * @return A linked list whose data members are C strings of engine names
+ *
+ * @ingroup Evas_Output_Method
+ */
+EAPI Eina_List *evas_render_method_list(void) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Frees the list of engine names.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When this function is called it frees the engine list passed in
+ * as @a list. The list should only be a list of engines generated by
+ * calling evas_render_method_list(). If @a list is NULL, nothing happens.
+ *
+ * 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
+ *
+ * @param[in] list The Eina_List base pointer for the engine list to be freed
+ * @ingroup Evas_Output_Method
+ */
+EAPI void evas_render_method_list_free(Eina_List *list);
+
+/**
+ * @brief Sets the output engine for the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Once the output engine for an evas is set, any attempt to change it
+ * is ignored. The value for @a render_method can be found using
+ * @ref evas_render_method_lookup.
+ *
+ * @remarks It is mandatory that you call evas_init() before setting the output method.
+ *
+ * @param[in] e The given evas
+ * @param[in] render_method The numeric engine value to use
+ *
+ * @ingroup Evas_Output_Method
+ */
+EAPI void evas_output_method_set(Evas *e, int render_method) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the number of the output engines used for the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @return The ID number of the output engine being used \n
+ * @c 0 is returned if there is an error.
+ *
+ * @ingroup Evas_Output_Method
+ */
+EAPI int evas_output_method_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the current render engine info struct from the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The returned structure is publicly modifiable. The contents are
+ * valid until either @ref evas_engine_info_set or @ref evas_render
+ * are called.
+ *
+ * @remarks You do not have to free this structure.
+ *
+ * @param[in] e The given evas
+ * @return A pointer to the Engine Info structure \n
+ * @c NULL is returned if an engine has not yet been assigned.
+ *
+ * @ingroup Evas_Output_Method
+ */
+EAPI Evas_Engine_Info *evas_engine_info_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Applies the engine settings for the given evas from the given @c
+ * Evas_Engine_Info structure.
+ *
+ @ @since_tizen 2.3
+ *
+ * @remarks To get the Evas_Engine_Info structure to use, call @ref
+ * evas_engine_info_get. Do not try to obtain a pointer to an
+ * @c Evas_Engine_Info structure in any other way.
+ *
+ * @remarks You need to call this function at least once before you can
+ * create objects on an evas or render that evas. Some engines allow
+ * their settings to be changed more than once.
+ *
+ * @remarks Once called, the @a info pointer should be considered invalid.
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] info The pointer to the Engine Info to use
+ * @return #EINA_TRUE if the engine setting is applied successfully, \n
+ * otherwise #EINA_FALSE if an error occurred
+ * @ingroup Evas_Output_Method
+ */
+EAPI Eina_Bool evas_engine_info_set(Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Output_Size Output and Viewport Resizing Functions
+ * @ingroup Evas_Canvas
+ *
+ * @brief This group provides functions that set and retrieve the output and viewport size of an evas.
+ *
+ * @{
+ */
+
+/**
+ * @brief Sets the output size of the render engine of the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The evas renders to a rectangle of the given size once this
+ * function is called. The output size is independent of the viewport
+ * size. The viewport is stretched to fill the given rectangle.
+ *
+ * @remarks The units used for @a w and @a h depend on the engine used by the evas.
+ *
+ * @param[in] e The given evas
+ * @param[in] w The width in output units, usually pixels
+ * @param[in] h The height in output units, usually pixels
+ *
+ * @ingroup Evas_Output_Size
+ */
+EAPI void evas_output_size_set(Evas *e, int w, int h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the output size of the render engine of the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The output size is in the output units for the engine.
+ *
+ * @remarks If either @a w or @a h is @c NULL, then it is ignored. If @a e is
+ * invalid, the returned results are undefined.
+ *
+ * @param[in] e The given evas
+ * @param[out] w The pointer to an integer to store the width in
+ * @param[out] h The pointer to an integer to store the height in
+ *
+ * @ingroup Evas_Output_Size
+ */
+EAPI void evas_output_size_get(const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the output viewport of the given evas in evas units.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The output viewport is the area of the evas that is visible to the viewer.
+ * The viewport is stretched to fit the output target of the evas when
+ * rendering is performed.
+ *
+ * @remarks The coordinate values do not have to map 1-to-1 with the output
+ * target. However, it is generally advised that it is done for ease of use.
+ *
+ * @param[in] e The given evas
+ * @param[in] x The top-left corner x value of the viewport
+ * @param[in] y The top-left corner y value of the viewport
+ * @param[in] w The width of the viewport \n
+ * Must be greater than @c 0.
+ * @param[in] h The height of the viewport \n
+ * Must be greater than @c 0.
+ * @ingroup Evas_Output_Size
+ */
+EAPI void evas_output_viewport_set(Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the render engine's output viewport co-ordinates in canvas units.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Calling this function writes the current canvas output viewport
+ * size and location values into the variables pointed to by @a x, @a y,
+ * @a w and @a h. On success, the variables have the output
+ * location and size values written to them in canvas units. Any of @a x,
+ * @a y, @a w or @a h that are @c NULL is not written to. If @a e
+ * is invalid, the results are undefined.
+ *
+ * @remarks The following is an example.
+ * @code
+ * extern Evas *evas;
+ * Evas_Coord x, y, width, height;
+ *
+ * evas_output_viewport_get(evas, &x, &y, &w, &h);
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas Canvas
+ * @param[out] x The pointer to the x variable to be filled in
+ * @param[out] y The pointer to the y variable to be filled in
+ * @param[out] w The pointer to the width variable to be filled in
+ * @param[out] h The pointer to the height variable to be filled in
+ * @ingroup Evas_Output_Size
+ */
+EAPI void evas_output_viewport_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the output framespace size of the render engine of the given evas.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The framespace size is used in the Wayland engines to denote space where
+ * the output is not drawn. This is mainly used in ecore_evas to draw borders.
+ *
+ * @remarks The units used for @a w and @a h depend on the engine used by the evas.
+ *
+ * @param[in] e The given evas
+ * @param[in] x The left coordinate in output units, usually pixels
+ * @param[in] y The top coordinate in output units, usually pixels
+ * @param[in] w The width in output units, usually pixels
+ * @param[in] h The height in output units, usually pixels
+ * @ingroup Evas_Output_Size
+ */
+EAPI void evas_output_framespace_set(Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h);
+
+/**
+ * @brief Gets the render engine's output framespace co-ordinates in canvas units.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The pointer to the Evas Canvas
+ * @param[out] x The pointer to the x variable to be filled in
+ * @param[out] y The pointer to the y variable to be filled in
+ * @param[out] w The pointer to the width variable to be filled in
+ * @param[out] h The pointer to the height variable to be filled in
+ * @ingroup Evas_Output_Size
+ */
+EAPI void evas_output_framespace_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions
+ * @ingroup Evas_Canvas
+ *
+ * @brief This group provides functions that are used to map coordinates from the canvas to the
+ * screen or the screen to the canvas.
+ *
+ * @{
+ */
+
+/**
+ * @brief Converts or scales an ouput screen co-ordinate into canvas co-ordinates.
+ *
+ * @details This function takes in a horizontal co-ordinate as the @a x
+ * parameter and converts it into canvas units, accounting for output
+ * size, viewport size and location, returning it as the function
+ * return value. If @a e is invalid, the results are undefined.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * extern int screen_x;
+ * Evas_Coord canvas_x;
+ *
+ * canvas_x = evas_coord_screen_x_to_world(evas, screen_x);
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas Canvas
+ * @param[in] x The screen or output x co-ordinate
+ * @return The screen co-ordinate translated to canvas unit co-ordinates
+ * @ingroup Evas_Coord_Mapping_Group
+ */
+EAPI Evas_Coord evas_coord_screen_x_to_world(const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Converts or scales an ouput screen co-ordinate into canvas co-ordinates.
+ *
+ * @details This function takes in a vertical co-ordinate as the @a y parameter
+ * and converts it into canvas units, accounting for output size,
+ * viewport size and location, returning it as the function return
+ * value. If @a e is invalid, the results are undefined.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * extern int screen_y;
+ * Evas_Coord canvas_y;
+ *
+ * canvas_y = evas_coord_screen_y_to_world(evas, screen_y);
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas Canvas
+ * @param[in] y The screen or output y co-ordinate
+ * @return The screen co-ordinate translated to canvas unit co-ordinates
+ * @ingroup Evas_Coord_Mapping_Group
+ */
+EAPI Evas_Coord evas_coord_screen_y_to_world(const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Converts or scales a canvas co-ordinate into output screen co-ordinates.
+ *
+ * @details This function takes in a horizontal co-ordinate as the @a x
+ * parameter and converts it into output units, accounting for output
+ * size, viewport size and location, returning it as the function
+ * return value. If @a e is invalid, the results are undefined.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * int screen_x;
+ * extern Evas_Coord canvas_x;
+ *
+ * screen_x = evas_coord_world_x_to_screen(evas, canvas_x);
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] x The canvas x co-ordinate
+ * @return The output or screen co-ordinate translated to output co-ordinates
+ * @ingroup Evas_Coord_Mapping_Group
+ */
+EAPI int evas_coord_world_x_to_screen(const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Converts or scales a canvas co-ordinate into output screen co-ordinates.
+ *
+ * @details This function takes in a vertical co-ordinate as the @a x parameter
+ * and converts it into output units, accounting for output size,
+ * viewport size and location, returning it as the function return
+ * value. If @a e is invalid, the results are undefined.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * int screen_y;
+ * extern Evas_Coord canvas_y;
+ *
+ * screen_y = evas_coord_world_y_to_screen(evas, canvas_y);
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas Canvas
+ * @param[in] y The canvas y co-ordinate
+ * @return The output or screen co-ordinate translated to output co-ordinates
+ * @ingroup Evas_Coord_Mapping_Group
+ */
+EAPI int evas_coord_world_y_to_screen(const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions
+ * @ingroup Evas_Canvas
+ *
+ * @brief This group provides functions that deal with the status of the pointer (mouse cursor).
+ *
+ * @{
+ */
+
+/**
+ * @brief Gets the current known pointer co-ordinates.
+ *
+ * @details This function returns the current known screen or output co-ordinates
+ * of the mouse pointer and sets the contents of the integers pointed
+ * to by @a x and @a y to contain these co-ordinates. If @a e is not a
+ * valid canvas the results of this function are undefined.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * int mouse_x, mouse_y;
+ *
+ * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
+ * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y);
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas Canvas
+ * @param[out] x The pointer to an integer to be filled in
+ * @param[out] y The pointer to an integer to be filled in
+ * @ingroup Evas_Pointer_Group
+ */
+EAPI void evas_pointer_output_xy_get(const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the current known pointer co-ordinates.
+ *
+ * @details This function returns the current known canvas unit co-ordinates of
+ * the mouse pointer and sets the contents of the Evas_Coords pointed
+ * to by @a x and @a y to contain these co-ordinates. If @a e is not a
+ * valid canvas the results of this function are undefined.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * Evas_Coord mouse_x, mouse_y;
+ *
+ * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
+ * printf("Mouse is at canvas position %f, %f\n", mouse_x, mouse_y);
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas Canvas
+ * @param[out] x The pointer to a Evas_Coord to be filled in
+ * @param[out] y The pointer to a Evas_Coord to be filled in
+ * @ingroup Evas_Pointer_Group
+ */
+EAPI void evas_pointer_canvas_xy_get(const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets a bitmask with the mouse buttons currently pressed, set to @c 1.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function returns a 32-bit integer with the
+ * appropriate bits set to @c 1 that correspond to a mouse button being
+ * depressed. This limits Evas to mouse devices with a maximum of 32
+ * buttons, but that is generally in excess of any host system's
+ * pointing device abilities.
+ *
+ * @remarks The least significant bit corresponds to the first mouse button
+ * (button 1) and the most significant bit corresponds to the last
+ * mouse button (button 32).
+ *
+ * @remarks If @a e is not a valid canvas, the return value is undefined.
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * int button_mask, i;
+ *
+ * button_mask = evas_pointer_button_down_mask_get(evas);
+ * printf("Buttons currently pressed:\n");
+ * for (i = 0; i < 32; i++)
+ * {
+ * if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1);
+ * }
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @return A bitmask of the currently depressed buttons on the canvas
+ * @ingroup Evas_Pointer_Group
+ */
+EAPI int evas_pointer_button_down_mask_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the mouse pointer is logically inside the canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When this function is called it returns a value of either @c 0 or
+ * @c 1.
+ *
+ * @remarks A return value of @c 1 indicates the mouse is logically inside the
+ * canvas, and @c 0 implies it is logically outside the canvas.
+ *
+ * @remarks A canvas begins with the mouse being assumed outside (0).
+ *
+ * @remarks If @a e is not a valid canvas, the return value is undefined.
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ *
+ * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n");
+ * else printf("Mouse is out!\n");
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas Canvas
+ * @return #EINA_TRUE if the mouse is inside the canvas,
+ * otherwise #EINA_FALSE
+ * @ingroup Evas_Pointer_Group
+ */
+EAPI Eina_Bool evas_pointer_inside_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Canvas_Events Canvas Events
+ * @ingroup Evas_Canvas
+ *
+ * @brief This group provides functions relating to canvas events, which are mainly reports on
+ * its internal states changing such as an object getting focused, the rendering being updated,
+ * and so on.
+ *
+ * @{
+ */
+
+/**
+ * @brief Adds or registers a callback function to a given canvas event.
+ *
+ * @details This function adds a function callback to the canvas @a e when the
+ * event of type @a type occurs on it. The function pointer is @a func.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks In the event of a memory allocation error during the addition of
+ * the callback to the canvas, evas_alloc_error() should be used to
+ * determine the nature of the error, if any, and the program should
+ * sensibly try and recover.
+ *
+ * @remarks A callback function must have the ::Evas_Event_Cb prototype
+ * definition. The first parameter (@a data) in this definition has
+ * the same value passed to evas_event_callback_add() as the @a data
+ * parameter, at runtime. The second parameter @a e is the canvas
+ * pointer on which the event occurred. The third parameter @a
+ * event_info is a pointer to a data structure that may or may not be
+ * passed to the callback, depending on the event type that triggered
+ * the callback. This is so because some events do not carry extra
+ * context with them, but others do.
+ *
+ * @remarks The valid event types @a type to trigger the function are
+ * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST,
+ * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT,
+ * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and
+ * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of
+ * event that triggers the callback to be called. Only the last
+ * two event types listed here provide useful event information
+ * data -- a pointer to the recently focused Evas object. For the
+ * others the @a event_info pointer is going to be @c NULL.
+ *
+ * @remarks The canvas flushes its rendering pipeline
+ * (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb
+ * routine takes place: it has to redraw that image at a different
+ * size. Also, the callback on an object being focused comes just
+ * after you focus it explicitly, on code.
+ *
+ * @remarks Be careful not to add the same callback multiple times, if
+ * that is not what you want, because Evas does not check if a callback
+ * existed before exactly as the one being registered (and thus, call
+ * it more than once on the event, in this case). This would make
+ * sense if you passed different functions and/or callback data, only.
+ *
+ * @param[in] e The canvas to attach a callback to
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] func The (callback) function to be called when the event is triggered
+ * @param[in] data The data pointer to be passed to @a func
+ */
+EAPI void evas_event_callback_add(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
+
+/**
+ * @brief Adds or registers a callback function to a given canvas event with a
+ * non-default priority set. Except for the priority field, it is exactly the
+ * same as @ref evas_event_callback_add
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The canvas to attach a callback to
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] priority The priority of the callback, lower values called first
+ * @param[in] func The (callback) function to be called when the event is triggered
+ * @param[in] data The data pointer to be passed to @a func
+ *
+ * @see evas_event_callback_add
+ */
+EAPI void evas_event_callback_priority_add(Evas *e, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 4);
+
+/**
+ * @brief Deletes a callback function from the canvas.
+ *
+ * @details This function removes the most recently added callback from the
+ * canvas @a e which is triggered by the event type @a type and is
+ * calling the function @a func when triggered. If the removal is
+ * successful it also returns the data pointer that is passed to
+ * evas_event_callback_add() when the callback is added to the
+ * canvas. If not successful @c NULL is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *e;
+ * void *my_data;
+ * void focus_in_callback(void *data, Evas *e, void *event_info);
+ *
+ * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
+ * @endcode
+ *
+ * @param[in] e The canvas to remove a callback from
+ * @param[in] type The type of event that is triggering the callback
+ * @param[in] func The function that is to be called when the event is triggered
+ * @return The data pointer that is to be passed to the callback
+ */
+EAPI void *evas_event_callback_del(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
+
+/**
+ * @brief Deletes (unregisters) a callback function registered to a given canvas event.
+ *
+ * @details This function removes <b>the first</b> added callback from the
+ * canvas @a e matching the event type @a type, the registered
+ * function pointer @a func and the callback data pointer @a data. If
+ * the removal is successful it also returns the data pointer that
+ * is passed to evas_event_callback_add() (that is the same as
+ * the parameter) when the callback(s) is (were) added to the
+ * canvas. If not successful @c NULL is returned. A common use
+ * would be to remove an exact match of a callback.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks For deleting canvas events callbacks filtering by just
+ * type and function pointer, use evas_event_callback_del().
+ *
+ * @param[in] e The Canvas to remove an event callback from
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] func The function that is to be called when the event is triggered
+ * @param[in] data The data pointer that is to be passed to the callback
+ * @return The data pointer that is to be passed to the callback
+ */
+EAPI void *evas_event_callback_del_full(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
+
+/**
+ * @brief Pushes a callback on the post-event callback stack.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Evas has a stack of callbacks that get called after all the callbacks for
+ * an event have triggered (all the objects it triggers on and all the callbacks
+ * in each object triggered). When all these have been called, the stack is
+ * unwound from most recently to least recently pushed item and removed from the
+ * stack calling the callback set for it.
+ *
+ * @remarks This is intended for doing reverse logic-like processing, for example - when a
+ * child object that happens to get the event later is meant to be able to
+ * "steal" functions from a parent and when this stack is unwound, have its
+ * function called first, thus being able to set flags, or return @c 0 from the
+ * post-callback, that stops all other post-callbacks in the current stack from
+ * being called (thus basically allowing a child to take control, if the event
+ * callback prepares information ready for taking action, but the post callback
+ * actually does the action).
+ *
+ * @param[in] e The canvas to push the callback on
+ * @param[in] func The function that to be called when the stack is unwound
+ * @param[in] data The data pointer to be passed to the callback
+ */
+EAPI void evas_post_event_callback_push(Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
+
+/**
+ * @brief Removes a callback from the post-event callback stack.
+ *
+ * @details This removes a callback from the stack added with
+ * evas_post_event_callback_push(). The first instance of the function in
+ * the callback stack is removed from being executed when the stack is
+ * unwound. Further instances may still be run on unwind.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The canvas to push the callback on
+ * @param[in] func The function that to be called when the stack is unwound
+ */
+EAPI void evas_post_event_callback_remove(Evas *e, Evas_Object_Event_Post_Cb func);
+
+/**
+ * @brief Removes a callback from the post-event callback stack.
+ *
+ * @details This removes a callback from the stack added with
+ * evas_post_event_callback_push(). The first instance of the function and data
+ * in the callback stack is removed from being executed when the stack is
+ * unwound. Further instances may still be run on unwind.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The canvas to push the callback on
+ * @param[in] func The function that to be called when the stack is unwound
+ * @param[in] data The data pointer to be passed to the callback
+ */
+EAPI void evas_post_event_callback_remove_full(Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
+ * @ingroup Evas_Canvas_Events
+ *
+ * @brief This group provides functions that deal with the freezing of input event processing of
+ * an Evas canvas.
+ *
+ * @remarks There might be scenarios during a graphical user interface
+ * program's use when the developer wishes the users would not be able
+ * to deliver input events to this application. It may, for example,
+ * be the time for it to populate a view or to change some
+ * layout. Assuming proper behavior with user interaction during this
+ * exact time would be hard, as things are in a changing state. The
+ * programmer can then tell the canvas to ignore input events,
+ * bringing it back to normal behavior when he or she wants.
+ *
+ * @remarks Most of the time, the freezing events is used like this:
+ * @code
+ * evas_event_freeze(my_evas_canvas);
+ * function_that_does_work_which_cant_be_interrupted_by_events();
+ * evas_event_thaw(my_evas_canvas);
+ * @endcode
+ *
+ * @{
+ */
+
+/**
+ * @brief Sets the default set of flags an event begins with.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Events in evas can have an event_flags member. This starts out with
+ * an initial value (no flags). This lets you set the default flags that
+ * an event begins with to be @a flags.
+ *
+ * @param[in] e The canvas to set the default event flags of
+ * @param[in] flags The default flags to use
+ */
+EAPI void evas_event_default_flags_set(Evas *e, Evas_Event_Flags flags) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the default set of flags an event begins with.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This gets the default event flags with which the events are produced.
+ *
+ * @param[in] e The canvas to get the default event flags from
+ * @return The default event flags for that canvas
+ *
+ * @see evas_event_default_flags_set()
+ */
+EAPI Evas_Event_Flags evas_event_default_flags_get(const Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Freezes all input events processing.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function indicates to Evas that the canvas @a e is to have
+ * all input event processing frozen until a matching
+ * evas_event_thaw() function is called on the same canvas. All events
+ * of this kind during the freeze get @b discarded. Every freeze
+ * call must be matched by a thaw call in order to completely thaw out
+ * a canvas (i.e. these calls may be nested). The most common use is
+ * when you do not want the user to interact with your user interface
+ * when you are populating a view or changing the layout.
+ *
+ * @param[in] e The canvas to freeze input events processing on
+ */
+EAPI void evas_event_freeze(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Thaws a canvas out after freezing (for input events).
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This thaws out a canvas after a matching evas_event_freeze()
+ * call. If this call completely thaws out a canvas, i.e., there is no
+ * other unbalanced call to evas_event_freeze(), events start to
+ * be processed again, but any "missed" events are @b not be evaluated.
+ *
+ * @param[in] e The canvas to thaw out
+ *
+ * @see evas_event_freeze() for an example.
+ */
+EAPI void evas_event_thaw(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the freeze count on input events of a given canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This returns the number of times the canvas has been told to freeze
+ * input events. It is possible to call evas_event_freeze() multiple
+ * times, and these must be matched by evas_event_thaw() calls. This
+ * call allows the program to discover just how many times things have
+ * been frozen in case it may want to break out of a deep freeze state
+ * where the count is high.
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ *
+ * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
+ * @endcode
+ *
+ * @param[in] e The canvas to fetch the freeze count from
+ * @return The freeze count
+ */
+EAPI int evas_event_freeze_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Re-evaluates the state of objects and call callbacks after thaw of a canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is normally called after evas_event_thaw() to re-evaluate mouse
+ * containment and other states and thus also call callbacks for mouse in and
+ * out on new objects if the state change demands it.
+ *
+ * @param[in] e The canvas to evaluate after a thaw
+ */
+EAPI void evas_event_thaw_eval(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
+ * @ingroup Evas_Canvas_Events
+ *
+ * @brief This group provides functions to tell Evas that input events happened and should be processed.
+ *
+ * @remarks Most of the time these functions are @b not what you are looking for.
+ * These functions should only be used if you are not working with ecore evas(or
+ * another input handling system). If you are not using ecore evas, please
+ * consider using it, as in most situation it makes life a lot easier.
+ *
+ * @remarks As explained in @ref evas_main_intro_not_evas, Evas does not know how to poll
+ * for input events, so you should do it and then feed such
+ * events to the canvas to be processed. This is only required if
+ * operating Evas directly. Modules such as Ecore_Evas do that for you.
+ *
+ * @{
+ */
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI Evas_Device *evas_device_new(Evas *e);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI void evas_device_free(Evas_Device *dev);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI void evas_device_push(Evas *e, Evas_Device *dev);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI void evas_device_pop(Evas *e);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI void evas_device_name_set(Evas_Device *dev, const char *name);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI const char *evas_device_name_get(const Evas_Device *dev);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI void evas_device_description_set(Evas_Device *dev, const char *desc);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI const char *evas_device_description_get(const Evas_Device *dev);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src);
+
+/**
+ * @internal
+ * @since 1.8
+ */
+EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev);
+
+/**
+ * @internal
+ * @brief Gets the number of mouse or multi presses currently active.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given canvas pointer
+ * @return The number of presses, \n
+ * otherwise @c 0 if none active
+ *
+ */
+EAPI int evas_event_down_count_get(const Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the mouse down event for the given canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function sets some evas properties that is necessary when
+ * the mouse button is pressed. It prepares information to be treated
+ * by the callback function.
+ *
+ * @param[in] e The given canvas pointer
+ * @param[in] b The button number
+ * @param[in] flags The evas button flags
+ * @param[in] timestamp The timestamp of the mouse down event
+ * @param[in] data The data for canvas
+ */
+EAPI void evas_event_feed_mouse_down(Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the mouse up event for the given canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function sets some evas properties that is necessary when
+ * the mouse button is released. It prepares information to be treated
+ * by the callback function.
+ *
+ * @param[in] e The given canvas pointer
+ * @param[in] b The button number
+ * @param[in] flags The evas button flags
+ * @param[in] timestamp The timestamp of the mouse up event
+ * @param[in] data The data for canvas
+ */
+EAPI void evas_event_feed_mouse_up(Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the mouse move event for the given canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function sets some evas properties that is necessary when
+ * the mouse is moved from its last position. It prepares information
+ * to be treated by the callback function.
+ *
+ * @param[in] e The given canvas pointer
+ * @param[in] x The horizontal position of the mouse pointer
+ * @param[in] y The vertical position of the mouse pointer
+ * @param[in] timestamp The timestamp of the mouse up event
+ * @param[in] data The data for canvas
+ */
+EAPI void evas_event_feed_mouse_move(Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the mouse in event for the given canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function sets some evas properties that is necessary when
+ * the mouse in event happens. It prepares information to be treated
+ * by the callback function.
+ *
+ * @param[in] e The given canvas pointer
+ * @param[in] timestamp The timestamp of the mouse up event
+ * @param[in] data The data for canvas
+ */
+EAPI void evas_event_feed_mouse_in(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the mouse out event for the given canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function sets some evas properties that is necessary when
+ * the mouse out event happens. It prepares information to be treated
+ * by the callback function.
+ *
+ * @param[in] e The given canvas pointer
+ * @param[in] timestamp The timestamp of the mouse up event
+ * @param[in] data The data for canvas
+ */
+EAPI void evas_event_feed_mouse_out(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+EAPI void evas_event_feed_multi_down(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
+EAPI void evas_event_feed_multi_up(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
+EAPI void evas_event_feed_multi_move(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, unsigned int timestamp, const void *data);
+
+/**
+ * @internal
+ * @brief Feeds the mouse cancel event for the given canvas @a e.
+ *
+ * @remarks This function calls evas_event_feed_mouse_up() when a
+ * mouse cancel event happens.
+ *
+ * @param e The given canvas pointer
+ * @param timestamp The timestamp of the mouse up event
+ * @param data The data for canvas
+ */
+EAPI void evas_event_feed_mouse_cancel(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the mouse wheel event for the given canvas @a e.
+ *
+ * @remarks This function sets some evas properties that is necessary when
+ * the mouse wheel is scrolled up or down. It prepares information to
+ * be treated by the callback function.
+ *
+ * @param e The given canvas pointer
+ * @param direction The wheel mouse direction
+ * @param z The amount of up or down mouse wheel scrolling
+ * @param timestamp The timestamp of the mouse up event
+ * @param data The data for canvas
+ */
+EAPI void evas_event_feed_mouse_wheel(Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the key down event for the given canvas @a e.
+ *
+ * @remarks This function sets some evas properties that is necessary when
+ * a key is pressed. It prepares information to be treated by the
+ * callback function.
+ *
+ * @param e The canvas to thaw out
+ * @param keyname The name of the key
+ * @param key The key pressed
+ * @param string The UTF8 string
+ * @param compose The compose string
+ * @param timestamp The timestamp of the mouse up event
+ * @param data The data for canvas
+ */
+EAPI void evas_event_feed_key_down(Evas *e, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the key up event feed for the given canvas @a e.
+ *
+ * @remarks This function sets some evas properties that is necessary when
+ * a key is released. It prepares information to be treated by the
+ * callback function.
+ *
+ * @param e The canvas to thaw out
+ * @param keyname The name of the key
+ * @param key The key released
+ * @param string The UTF8 string
+ * @param compose The compose string
+ * @param timestamp The timestamp of the mouse up event
+ * @param data The data for canvas
+ */
+EAPI void evas_event_feed_key_up(Evas *e, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Feeds the hold event for the given canvas @a e.
+ *
+ * @remarks This function makes the object to stop sending events.
+ *
+ * @param e The given canvas pointer
+ * @param hold The hold
+ * @param timestamp The timestamp of the mouse up event
+ * @param data The data for canvas
+ *
+ */
+EAPI void evas_event_feed_hold(Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Re-feeds the event for the given canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function re-feeds the event pointed by event_copy.
+ *
+ * @remarks This function call evas_event_feed_* functions, so it can
+ * cause havoc if not used wisely. Please use it responsibly.
+ *
+ * @param[in] e The given canvas pointer
+ * @param[in] event_copy The event to re-feed
+ * @param[in] event_type The event type
+ */
+EAPI void evas_event_refeed_event(Evas *e, void *event_copy, Evas_Callback_Type event_type) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Gets a list of Evas objects lying over a given position in a canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function traverses all the layers of the given canvas,
+ * from top to bottom, querying for objects with areas covering the
+ * given position. It enters the smart objects.
+ *
+ * @param[in] eo_e A handle to the canvas
+ * @param[in] stop The Evas object at which to stop searching
+ * @param[in] x The horizontal coordinate of the position
+ * @param[in] y The vertical coordinate of the position
+ */
+EAPI Eina_List *evas_tree_objects_at_xy_get(Evas *eo_e, Evas_Object *stop, int x, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Image_Group Image Functions
+ * @ingroup Evas_Canvas
+ *
+ * @brief This group provides functions that deals with images at canvas level.
+ *
+ * @{
+ */
+
+/**
+ * @brief Flushes the image cache of the canvas.
+ *
+ * @details This function flushes image cache of canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas pointer
+ *
+ */
+EAPI void evas_image_cache_flush(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Reloads the image cache.
+ *
+ * @details This function reloads the image cache of canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas pointer
+ *
+ */
+EAPI void evas_image_cache_reload(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the image cache.
+ *
+ * @details This function sets the image cache of canvas in bytes.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas pointer
+ * @param[in] size The cache size
+ */
+EAPI void evas_image_cache_set(Evas *e, int size) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the image cache
+ *
+ * @details This function returns the image cache size of canvas in bytes.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas pointer
+ * @return The image cache size of canvas in bytes
+ */
+EAPI int evas_image_cache_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the maximum image size evas can possibly handle.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function returns the largest image or surface size that evas can handle
+ * in pixels, and if there is one, returns #EINA_TRUE. It returns
+ * #EINA_FALSE if no extra constraint on maximum image size exists. You still
+ * should check the return values of @a maxw and @a maxh as there may still be
+ * a limit, just a much higher one.
+ *
+ * @param[in] e The given evas pointer
+ * @param[out] maxw The pointer to hold the return value in pixels of the maximum width
+ * @param[out] maxh The pointer to hold the return value in pixels of the maximum height
+ * @return #EINA_TRUE if there is a maximum size that evas can handle, \n
+ * otherwise #EINA_FALSE if there is no maximum image size constraint
+ */
+EAPI Eina_Bool evas_image_max_size_get(const Evas *e, int *maxw, int *maxh) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Font_Group Font Functions
+ *
+ * @brief This group provides functions that deals with fonts.
+ *
+ * @ingroup Evas_Canvas
+ *
+ * @{
+ */
+
+/**
+ * @brief Changes the font hinting for the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @param[in] hinting The hinting to use \n
+ * Valid values are #EVAS_FONT_HINTING_NONE,
+ * #EVAS_FONT_HINTING_AUTO, and #EVAS_FONT_HINTING_BYTECODE.
+ * @ingroup Evas_Font_Group
+ */
+EAPI void evas_font_hinting_set(Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the font hinting used by the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas to query
+ * @return The hinting in use \n
+ * Valid return values are #EVAS_FONT_HINTING_NONE,
+ * #EVAS_FONT_HINTING_AUTO, and #EVAS_FONT_HINTING_BYTECODE.
+ * @ingroup Evas_Font_Group
+ */
+EAPI Evas_Font_Hinting_Flags evas_font_hinting_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the font hinting is supported by the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas to query
+ * @param[in] hinting The hinting to use \n
+ * Valid values are #EVAS_FONT_HINTING_NONE,
+ * #EVAS_FONT_HINTING_AUTO, and #EVAS_FONT_HINTING_BYTECODE.
+ * @return #EINA_TRUE if it is supported, \n
+ * otherwise #EINA_FALSE
+ * @ingroup Evas_Font_Group
+ */
+EAPI Eina_Bool evas_font_hinting_can_hint(const Evas *e, Evas_Font_Hinting_Flags hinting) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Forces the given evas and associated engine to flush its font cache.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas to flush font cache
+ * @ingroup Evas_Font_Group
+ */
+EAPI void evas_font_cache_flush(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Changes the size of font cache of the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas to flush font cache
+ * @param[in] size The size in bytes
+ *
+ * @ingroup Evas_Font_Group
+ */
+EAPI void evas_font_cache_set(Evas *e, int size) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Changes the size of font cache of the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas to flush font cache
+ * @return The size in bytes
+ *
+ * @ingroup Evas_Font_Group
+ */
+EAPI int evas_font_cache_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the list of available font descriptions known or found by this evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The list depends on Evas compile time configuration, such as
+ * fontconfig support, and the paths provided at runtime as explained
+ * in @ref Evas_Font_Path_Group.
+ *
+ * @param[in] e The evas instance to query
+ * @return The newly allocated list of strings \n
+ * Do not change the strings. Be sure to call evas_font_available_list_free()
+ * after you are done.
+ *
+ * @ingroup Evas_Font_Group
+ */
+EAPI Eina_List *evas_font_available_list(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Frees the list of font descriptions returned by evas_font_dir_available_list().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The evas instance that returned such list
+ * @param[in] available The list returned by evas_font_dir_available_list()
+ *
+ * @ingroup Evas_Font_Group
+ */
+EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Reinitializes Evas by orphaning existing font data until it is unreferenced and
+ * starts with a fresh font configuration read from any appropriate
+ * system resources for all newly loaded and created fonts.
+ *
+ * @since_tizen 2.3
+ *
+ * @ingroup Evas_Font_Group
+ */
+EAPI void evas_font_reinit(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Font_Path_Group Font Path Functions
+ *
+ * @brief This group provides functions that edit the paths being used to load fonts.
+ *
+ * @ingroup Evas_Font_Group
+ *
+ * @{
+ */
+
+/**
+ * @brief Removes all font paths loaded into memory for the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @ingroup Evas_Font_Path_Group
+ */
+EAPI void evas_font_path_clear(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Appends a font path to the list of font paths used by the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @param[in] path The new font path
+ * @ingroup Evas_Font_Path_Group
+ */
+EAPI void evas_font_path_append(Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Prepends a font path to the list of font paths used by the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @param[in] path The new font path
+ * @ingroup Evas_Font_Path_Group
+ */
+EAPI void evas_font_path_prepend(Evas *e, const char *path) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the list of font paths used by the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @return The list of font paths used
+ * @ingroup Evas_Font_Path_Group
+ */
+EAPI const Eina_List *evas_font_path_list(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Removes all font paths loaded into memory by evas_font_path_app_* APIs for the application.
+ * @since 1.9
+ *
+ * @since_tizen 2.3
+ *
+ * @ingroup Evas_Font_Path_Group
+ */
+EAPI void evas_font_path_global_clear(void);
+
+/**
+ * @brief Appends a font path to the list of font paths used by the application.
+ * @since 1.9
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] path The new font path
+ * @ingroup Evas_Font_Path_Group
+ */
+EAPI void evas_font_path_global_append(const char *path) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Prepends a font path to the list of font paths used by the application.
+ * @since 1.9
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] path The new font path
+ * @ingroup Evas_Font_Path_Group
+ */
+EAPI void evas_font_path_global_prepend(const char *path) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the list of font paths used by the application.
+ * @since 1.9
+ *
+ * @since_tizen 2.3
+ *
+ * @return The list of font paths used
+ * @ingroup Evas_Font_Path_Group
+ */
+EAPI const Eina_List *evas_font_path_global_list(void) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Group Generic Object Functions
+ @ingroup Evas
+ *
+ * @brief This group provides functions that manipulate generic Evas objects.
+ *
+ * @remarks All Evas displaying units are Evas objects. You can handle them all by
+ * means of the handle ::Evas_Object. Besides Evas treats their
+ * objects equally, they have @b types, which define their specific
+ * behavior (and individual API).
+ *
+ * @remarks Evas comes with a set of built-in object types:
+ * - rectangle,
+ * - line,
+ * - polygon,
+ * - text,
+ * - textblock, and
+ * - image.
+ *
+ * @remarks These functions apply to @b any Evas object, whichever type that
+ * may have.
+ *
+ * @remarks The built-in types which are most used are rectangles, text
+ * and images. In fact, with these ones one can create 2D interfaces
+ * of arbitrary complexity and EFL makes it easy.
+ */
+
+/**
+ * @defgroup Evas_Object_Group_Basic Basic Object Manipulation
+ * @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions for basic object manipulation.
+ *
+ * @remarks Almost every evas object created has some generic function used to
+ * manipulate it. That is because there are a number of basic actions to be done
+ * to objects that are irrespective of the object's type like:
+ * @li Showing/Hiding
+ * @li Setting(and getting) geometry
+ * @li Bring up or down a layer
+ * @li Color management
+ * @li Handling focus
+ * @li Clipping
+ * @li Reference counting
+ *
+ * @{
+ */
+
+/**
+ * @brief Clips one object to another.
+ *
+ * @details This function clips the object @a obj to the area occupied by
+ * the object @a clip. This means the object @a obj is only
+ * visible within the area occupied by the clipping object (@a clip).
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The color of the object being clipped is multiplied by the
+ * color of the clipping one, so the resulting color for the former
+ * is <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color
+ * element (red, green, blue and alpha).
+ *
+ * @remarks Clipping is recursive, so clipping objects may be clipped by
+ * others, and their color is in term multiplied. You may @b not
+ * set up circular clipping lists (i.e. object 1 clips object 2, which
+ * clips object 1): the behavior of Evas is undefined in this case.
+ *
+ * @remarks Objects which do not clip others are visible in the canvas as
+ * normal; <b>those that clip one or more objects become invisible
+ * themselves</b>, only affecting what they clip. If an object ceases
+ * to have other objects being clipped by it, it becomes visible
+ * again.
+ *
+ * @remarks The visibility of an object affects the objects that are clipped by
+ * it, so if the object clipping others is not shown (as in
+ * evas_object_show()), the objects clipped by it is not shown
+ * either.
+ *
+ * @remarks If @a obj is being clipped by another object when this function is
+ * called, it gets implicitly removed from the old clipper's domain
+ * and is made now to be clipped by its new clipper.
+ *
+ * @remarks The following figure illustrates some clipping in Evas:
+ *
+ * @image html clipping.png
+ * @image rtf clipping.png
+ * @image latex clipping.eps
+ *
+ * @remarks At the moment the <b>only objects that can validly be used to
+ * clip other objects are rectangle objects</b>. All other object
+ * types are invalid and the result of using them is undefined. The
+ * clip object @a clip must be a valid object, but can also be @c
+ * NULL, in which case the effect of this function is the same as
+ * calling evas_object_clip_unset() on the @a obj object.
+ *
+ * @param[in] obj The object to be clipped
+ * @param[in] clip The object to clip @a obj by
+ */
+EAPI void evas_object_clip_set(Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the object clipping @a obj (if any).
+ *
+ * @details This function returns the object clipping @a obj. If @a obj is
+ * not being clipped at all, @c NULL is returned. The object @a obj
+ * must be a valid ::Evas_Object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks See also evas_object_clip_set(), evas_object_clip_unset() and
+ * evas_object_clipees_get().
+ *
+ * @param[in] obj The object to get the clipper from
+ * @return The object clipping @a obj \n
+ * If @a obj object is not being clipped, @c NULL is returned.
+ */
+EAPI Evas_Object *evas_object_clip_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Disables or ceases clipping on a clipped @a obj object.
+ *
+ * @details This function disables clipping for the object @a obj, if it is
+ * already clipped, i.e., its visibility and color get detached from
+ * the previous clipper. If it is not already clipped, this has no effect. The object
+ * @a obj must be a valid ::Evas_Object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks See also evas_object_clip_set() (for an example),
+ * evas_object_clipees_get() and evas_object_clip_get().
+ *
+ * @param[in] obj The object to cease clipping on
+ */
+EAPI void evas_object_clip_unset(Evas_Object *obj);
+
+/**
+ * @brief Gets a list of objects currently clipped by @a obj.
+ *
+ * @details This returns the internal list handle that contains all objects
+ * clipped by the object @a obj. If none are clipped by it, the call
+ * returns @c NULL. This list is only valid until the clip list is
+ * changed and should be fetched again with another call to
+ * evas_object_clipees_get() if any objects being clipped by this
+ * object are unclipped, clipped by a new object, deleted or get the
+ * clipper deleted. These operations invalidate the list
+ * returned, so it should not be used anymore after that point. Any
+ * use of the list after this may have undefined results, possibly
+ * leading to crashes. The object @a obj must be a valid
+ * ::Evas_Object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks See also evas_object_clip_set(), evas_object_clip_unset() and
+ * evas_object_clip_get().
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas_Object *obj;
+ * Evas_Object *clipper;
+ *
+ * clipper = evas_object_clip_get(obj);
+ * if (clipper)
+ * {
+ * Eina_List *clippees, *l;
+ * Evas_Object *obj_tmp;
+ *
+ * clippees = evas_object_clipees_get(clipper);
+ * printf("Clipper clips %i objects\n", eina_list_count(clippees));
+ * EINA_LIST_FOREACH(clippees, l, obj_tmp)
+ * evas_object_show(obj_tmp);
+ * }
+ * @endcode
+ *
+ * @param[in] obj The object to get a list of clippees from
+ * @return The list of objects being clipped by @a obj
+ */
+EAPI const Eina_List *evas_object_clipees_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets or unsets a given object as the currently focused one on its canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Changing focus only affects where (key) input events go. There can
+ * be only one object focused at any time. If @a focus is #EINA_TRUE,
+ * @a obj is set as the currently focused object and it
+ * receives all keyboard events that are not exclusive key grabs on
+ * other objects.
+ *
+ * @param[in] obj The object to be focused or unfocused
+ * @param[in] focus #EINA_TRUE to set it as focused, \n
+ * otherwise #EINA_FALSE to take away the focus from it
+ *
+ * @see evas_object_focus_get
+ * @see evas_focus_get
+ * @see evas_object_key_grab
+ * @see evas_object_key_ungrab
+ */
+EAPI void evas_object_focus_set(Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether an object has the focus.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the passed object is the currently focused one, #EINA_TRUE is
+ * returned. #EINA_FALSE is returned, otherwise.
+ *
+ * @param[in] obj The object to retrieve focus information from
+ * @return #EINA_TRUE if the object has the focus, \n
+ * otherwise #EINA_FALSE
+ *
+ * @see evas_object_focus_set
+ * @see evas_focus_get
+ * @see evas_object_key_grab
+ * @see evas_object_key_ungrab
+ */
+EAPI Eina_Bool evas_object_focus_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the layer of its canvas that the given object is part of.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you do not use this function, you are dealing with a @b unique
+ * layer of objects, the default one. Additional layers are handy when
+ * you do not want a set of objects to interfere with another set with
+ * regard to @b stacking. Two layers are completely disjoint in that matter.
+ *
+ * @remarks This is a low-level function, which you would be using when something
+ * should be always on top, for example.
+ *
+ * @remarks Be careful, it does not make sense to change the layer of the children of
+ * smart objects. Smart objects have a layer of their own,
+ * which should contain all their children objects.
+ *
+ * @param[in] obj The given Evas object
+ * @param[in] l The number of the layer to place the object on \n
+ * This must be between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
+ *
+ * @see evas_object_layer_get()
+ */
+EAPI void evas_object_layer_set(Evas_Object *obj, short l) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the layer of its canvas that the given object is part of.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object to query the layer from
+ * @return The number of its layer
+ *
+ * @see evas_object_layer_set()
+ */
+EAPI short evas_object_layer_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the name of the given Evas object to the given name.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks There might be occasions where you would like to name your objects.
+ *
+ * @param[in] obj The given object
+ * @param[in] name The given name
+ */
+EAPI void evas_object_name_set(Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the name of the given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given object
+ * @return The name of the object, \n
+ * otherwise @c NULL if no name has been given to it
+ */
+EAPI const char *evas_object_name_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Increments object reference count to defer its deletion.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This increments the reference count of an object, which if greater
+ * than @c 0 defers deletion by evas_object_del() until all
+ * references are released back (counter back to @c 0). References cannot
+ * go below @c 0 and unreferencing past that results in the reference
+ * count being limited to @c 0. References are limited to <c>2^32 - 1</c>
+ * for an object. Referencing it more than this results in it
+ * being limited to this value.
+ *
+ * @remarks This is a <b>very simple</b> reference counting mechanism. For
+ * instance, Evas is not ready to check for pending references on a
+ * canvas deletion, or things like that. This is useful on scenarios
+ * where, inside a code block, callbacks exist which would possibly
+ * delete an object that you are operating on afterwards. Then, you would
+ * evas_object_ref() it on the beginning of the block and
+ * evas_object_unref() it on the end. It would then be deleted at this
+ * point, if it should be.
+ *
+ * @remarks The following is an example:
+ * @code
+ * evas_object_ref(obj);
+ *
+ * // action here...
+ * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
+ * // more action here...
+ * evas_object_unref(obj);
+ * @endcode
+ *
+ * @param[in] obj The given Evas object to reference
+ *
+ * @see evas_object_unref()
+ * @see evas_object_del()
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_ref(Evas_Object *obj);
+
+/**
+ * @brief Decrements object reference count.
+ *
+ * @details This decrements the reference count of an object. If the object has
+ * had evas_object_del() called on it while references were more than
+ * @c 0, it is deleted at the time this function is called and puts
+ * the counter back to @c 0. See evas_object_ref() for more information.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object to unreference
+ *
+ * @see evas_object_ref() (for an example)
+ * @see evas_object_del()
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_unref(Evas_Object *obj);
+
+/**
+ * @brief Gets the object reference count.
+ *
+ * @details This gets the reference count for an object (normally @c 0 until it is
+ * referenced). Values of @c 1 or greater mean that someone is holding a
+ * reference to this object that needs to be unreffed before it can be
+ * deleted.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object to query
+ * @return The object reference count
+ *
+ * @see evas_object_ref()
+ * @see evas_object_unref()
+ * @see evas_object_del()
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI int evas_object_ref_get(const Evas_Object *obj);
+
+/**
+ * @brief Marks the given Evas object for deletion (when Evas frees its memory).
+ *
+ * @details This call marks @a obj for deletion, which takes place
+ * whenever it has no more references to it (see evas_object_ref() and
+ * evas_object_unref()).
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks At actual deletion time, which may or may not be just after this
+ * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks are
+ * called. If the object currently had the focus, its
+ * ::EVAS_CALLBACK_FOCUS_OUT callback is also called.
+ *
+ * @param[in] obj The given Evas object
+ *
+ * @see evas_object_ref()
+ * @see evas_object_unref()
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_del(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Moves the given Evas object to the given location inside its canvas' viewport.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback is called.
+ *
+ * @remarks Naturally, newly created objects are placed at the canvas' origin: <code>0, 0</code>.
+ *
+ * @param[in] obj The given Evas object
+ * @param[in] x The X position to move the object to, in canvas units
+ * @param[in] y The Y position to move the object to, in canvas units
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Changes the size of the given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback
+ * is called.
+ *
+ * @remarks Newly created objects have zeroed dimensions. Then, you most
+ * probably want to use evas_object_resize() on them after they are
+ * created.
+ *
+ * @remarks Be aware that resizing an object changes its drawing area,
+ * but that does imply the object is rescaled. For instance, images
+ * are filled inside their drawing area using the specifications of
+ * evas_object_image_fill_set(). Thus to scale the image to match
+ * exactly your drawing area, you need to change the
+ * evas_object_image_fill_set() as well.
+ *
+ * @remarks This is more evident in images, but text, textblock, lines
+ * and polygons behave similarly. Check their specific APIs to
+ * know how to achieve your desired behavior. Consider the following example:
+ *
+ * @code
+ * // rescale image to fill exactly its area without tiling:
+ * evas_object_resize(img, w, h);
+ * evas_object_image_fill_set(img, 0, 0, w, h);
+ * @endcode
+ *
+ * @param[in] obj The given Evas object
+ * @param[in] w The new width of the Evas object
+ * @param[in] h The new height of the Evas object
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the position and (rectangular) size of the given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The position is relative to the top left corner of
+ * the canvas' viewport.
+ *
+ * @remarks Use @c NULL pointers on the geometry components you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas object
+ * @param[out] x The pointer to an integer in which to store the X coordinate
+ * of the object
+ * @param[out] y The pointer to an integer in which to store the Y coordinate
+ * of the object
+ * @param[out] w The pointer to an integer in which to store the width of the object
+ * @param[out] h The pointer to an integer in which to store the height of the object
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Makes the given Evas object visible.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW
+ * callback are called.
+ *
+ * @param[in] obj The given Evas object
+ *
+ * @see evas_object_hide() for more on object visibility.
+ * @see evas_object_visible_get()
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_show(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Makes the given Evas object invisible.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Hidden objects, besides not being shown at all in your canvas,
+ * are not checked for changes on the canvas rendering
+ * process. Furthermore, they do not catch input events. Thus, they
+ * are much lighter (in processing needs) than an object that is
+ * invisible due to indirect causes, such as being clipped or out of
+ * the canvas' viewport.
+ *
+ * @remarks Besides becoming hidden, @a obj object's ::EVAS_CALLBACK_SHOW
+ * callback is called.
+ *
+ * @remarks All objects are created in the hidden state. If you want to
+ * show them, use evas_object_show() after their creation.
+ *
+ * @param[in] obj The given Evas object
+ *
+ * @see evas_object_show()
+ * @see evas_object_visible_get()
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_hide(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the given Evas object is visible.
+ *
+ * @since_tizen 2.3
+ *
+ * @details This retrieves an object's visibility as the one enforced by
+ * evas_object_show() and evas_object_hide().
+ *
+ * @remarks The value returned is not, by any means, influenced by
+ * clippers covering @a obj, it being out of its canvas' viewport or
+ * stacked below other object.
+ *
+ * @param[in] obj The given Evas object
+ * @return #EINA_TRUE if the object is visible, \n
+ * otherwise #EINA_FALSE if the object is not visible
+ *
+ * @see evas_object_show()
+ * @see evas_object_hide() (for an example)
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI Eina_Bool evas_object_visible_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the general or main color of the given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks These color values are expected to be premultiplied by @a a.
+ *
+ * @param[in] obj The given Evas object
+ * @param[in] r The red component of the given color
+ * @param[in] g The green component of the given color
+ * @param[in] b The blue component of the given color
+ * @param[in] a The alpha component of the given color
+ *
+ * @see evas_object_color_get() (for an example)
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the general or main color of the given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Gets the "main" color's RGB component (and alpha channel)
+ * values, <b>which range from 0 to 255</b>. For the alpha channel,
+ * which defines the object's transparency level, @c 0 means totally
+ * transparent, while @c 255 means opaque. These color values are
+ * premultiplied by the alpha value.
+ *
+ * @remarks Usually you use this attribute for text and rectangle objects,
+ * where the "main" color is their unique one. If set for objects
+ * which themselves have colors, like the images one, those colors get
+ * modulated by this one.
+ *
+ * @remarks All newly created Evas rectangles get the default color
+ * values of <code>255 255 255 255</code> (opaque white).
+ *
+ * @remarks Use @c NULL pointers on the components you are not interested
+ * in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas object to retrieve color from
+ * @param[out] r The pointer to an integer in which to store the red component
+ * of the color
+ * @param[out] g The pointer to an integer in which to store the green
+ * component of the color
+ * @param[out] b The pointer to an integer in which to store the blue component
+ * of the color
+ * @param[out] a The pointer to an integer in which to store the alpha
+ * component of the color
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI void evas_object_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the Evas canvas that the given object lives on.
+ *
+ * @details This function is most useful at code contexts where you need to
+ * operate on the canvas but have only the object pointer.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object
+ * @return A pointer to the canvas where the object is on
+ *
+ * @ingroup Evas_Object_Group_Basic
+ */
+EAPI Evas *evas_object_evas_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the type of the given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks For Evas' built-in types, the return strings are one of:
+ * - <c>"rectangle"</c>,
+ * - <c>"line"</c>,
+ * - <c>"polygon"</c>,
+ * - <c>"text"</c>,
+ * - <c>"textblock"</c> and
+ * - <c>"image"</c>.
+ *
+ * @internal
+ * @remarks For Evas smart objects (see @ref Evas_Smart_Group), the name of the
+ * smart class itself is returned on this call. For the built-in smart
+ * objects, these names are:
+ * - <c>"EvasObjectSmartClipped"</c>, for the clipped smart object
+ * - <c>"Evas_Object_Box"</c>, for the box object and
+ * - <c>"Evas_Object_Table"</c>, for the table object.
+ * @endinternal
+ *
+ * @param[in] obj The given object
+ * @return The type of the object
+ */
+EAPI const char *evas_object_type_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Raises @a obj to the top of its layer.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks @a obj is, then, the highest one in the layer it belongs
+ * to. Objects on other layers do not get touched.
+ *
+ * @param[in] obj The object to raise
+ *
+ * @see evas_object_stack_above()
+ * @see evas_object_stack_below()
+ * @see evas_object_lower()
+ */
+EAPI void evas_object_raise(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Lowers @a obj to the bottom of its layer.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks @a obj is, then, the lowest one in the layer it belongs
+ * to. Objects on other layers do not get touched.
+ *
+ * @param[in] obj The object to lower
+ *
+ * @see evas_object_stack_above()
+ * @see evas_object_stack_below()
+ * @see evas_object_raise()
+ */
+EAPI void evas_object_lower(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Stacks @a obj immediately above @a above.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Objects, in a given canvas, are stacked in the order they get added
+ * to it. This means that, if they overlap, the highest ones
+ * cover the lowest ones, in that order. This function is a way to
+ * change the stacking order for the objects.
+ *
+ * @remarks This function is intended to be used with <b>objects belonging to
+ * the same layer</b> in a given canvas, otherwise it fails (and
+ * accomplish nothing).
+ *
+ * @remarks If you have smart objects on your canvas and @a obj is a member of
+ * one of them, then @a above must also be a member of the same
+ * smart object.
+ *
+ * @remarks Similarly, if @a obj is not a member of a smart object, @a above
+ * must not be either.
+ *
+ * @param[in] obj The object to stack
+ * @param[in] above The object above which to stack
+ *
+ * @see evas_object_layer_get()
+ * @see evas_object_layer_set()
+ * @see evas_object_stack_below()
+ */
+EAPI void evas_object_stack_above(Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Stacks @a obj immediately below @a below.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Objects, in a given canvas, are stacked in the order they get added
+ * to it. This means that, if they overlap, the highest ones
+ * cover the lowest ones, in that order. This function is a way to
+ * change the stacking order for the objects.
+ *
+ * @remarks This function is intended to be used with <b>objects belonging to
+ * the same layer</b> in a given canvas, otherwise it fails (and
+ * accomplish nothing).
+ *
+ * @remarks If you have smart objects on your canvas and @a obj is a member of
+ * one of them, then @a below must also be a member of the same
+ * smart object.
+ *
+ * @remarks Similarly, if @a obj is not a member of a smart object, @a below
+ * must not be either.
+ *
+ * @param[in] obj The object to stack
+ * @param[in] below The object below which to stack
+ *
+ * @see evas_object_layer_get()
+ * @see evas_object_layer_set()
+ * @see evas_object_stack_below()
+ */
+EAPI void evas_object_stack_below(Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the Evas object stacked right above @a obj.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function traverses layers in its search, if there are
+ * objects on layers above the one @a obj is placed at.
+ *
+ * @param[in] obj An #Evas_Object
+ * @return The #Evas_Object directly above @a obj, if any, \n
+ * otherwise @c NULL if none
+ *
+ * @see evas_object_layer_get()
+ * @see evas_object_layer_set()
+ * @see evas_object_below_get()
+ *
+ */
+EAPI Evas_Object *evas_object_above_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the Evas object stacked right below @a obj.
+ *
+ * @details This function traverses layers in its search, if there are
+ * objects on layers below the one @a obj is placed at.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj An #Evas_Object
+ * @return The #Evas_Object directly below @a obj, if any, \n
+ * otherwise @c NULL if none
+ *
+ * @see evas_object_layer_get()
+ * @see evas_object_layer_set()
+ * @see evas_object_below_get()
+ */
+EAPI Evas_Object *evas_object_below_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Group_Events Object Events
+ * @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions for object events.
+ *
+ * @remarks Objects generate events when they are moved, resized, when their
+ * visibility change, when they are deleted and so on. These methods
+ * allow you to be notified about and to handle such events.
+ *
+ * @remarks Objects also generate events on input (keyboard and mouse), if they
+ * accept them (are visible, focused, and so on).
+ *
+ * @remarks For each of those events, Evas provides a way for one to register
+ * callback functions to be issued just after they happen.
+ *
+ * @remarks The following figure illustrates some Evas (event) callbacks:
+ *
+ * @image html evas-callbacks.png
+ * @image rtf evas-callbacks.png
+ * @image latex evas-callbacks.eps
+ *
+ * @remarks These events have their values in the #Evas_Callback_Type
+ * enumeration, which also has the happening on the canvas level (see
+ * @ref Evas_Canvas_Events ).
+ *
+ * @{
+ */
+
+/**
+ * @brief Adds or registers a callback function to a given Evas object event.
+ *
+ * @details This function adds a function callback to an object when the event
+ *
+ * @since_tizen 2.3 of type @a type occurs on object @a obj. The function is @a func.
+ *
+ *
+ * @remarks In the event of a memory allocation error during addition of the
+ * callback to the object, evas_alloc_error() should be used to
+ * determine the nature of the error, if any, and the program should
+ * sensibly try and recover.
+ *
+ * @remarks A callback function must have the #Evas_Object_Event_Cb prototype
+ * definition. The first parameter (@a data) in this definition
+ * has the same value passed to evas_object_event_callback_add() as
+ * the @a data parameter, at runtime. The second parameter @a e is the
+ * canvas pointer on which the event occurred. The third parameter is
+ * a pointer to the object on which event occurred. Finally, the
+ * fourth parameter @a event_info is a pointer to a data structure
+ * that may or may not be passed to the callback, depending on the
+ * event type that triggered the callback. This is so because some
+ * events do not carry extra context with them, but others do.
+ *
+ * @remarks The valid event type @a type to trigger the function are
+ * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT,
+ * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP,
+ * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL,
+ * #EVAS_CALLBACK_MULTI_DOWN, #EVAS_CALLBACK_MULTI_UP,
+ * #EVAS_CALLBACK_MULTI_MOVE, #EVAS_CALLBACK_FREE,
+ * #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP,
+ * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT,
+ * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE,
+ * #EVAS_CALLBACK_RESIZE, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL,
+ * #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS,
+ * #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED.
+ *
+ * @remarks This determines the kind of event that triggers the callback.
+ * The event types are explained below along with their associated @a event_info pointers:
+ *
+ * @remarks - #EVAS_CALLBACK_MOUSE_IN: @a event_info is a pointer to an
+ * #Evas_Event_Mouse_In struct\n\n
+ * This event is triggered when the mouse pointer enters the area
+ * (not shaded by other objects) of the object @a obj. This may
+ * occur by the mouse pointer being moved or by the object being shown,
+ * raised, moved, resized, or other objects being moved out of the
+ * way, hidden or lowered, whatever may cause the mouse pointer to
+ * get on top of @a obj, having been on top of another object
+ * previously.
+ *
+ * - #EVAS_CALLBACK_MOUSE_OUT: @a event_info is a pointer to an
+ * #Evas_Event_Mouse_Out struct\n\n
+ * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is,
+ * but it occurs when the mouse pointer exits an object's area. Note
+ * that no mouse out events are reported if the mouse pointer is
+ * implicitly grabbed to an object (mouse buttons are down, having
+ * been pressed while the pointer is over that object). In these
+ * cases, mouse out events are reported once all buttons are
+ * released, if the mouse pointer has left the object's area. The
+ * indirect ways of taking off the mouse pointer from an object,
+ * like cited above, for #EVAS_CALLBACK_MOUSE_IN, also apply here,
+ * naturally.
+ *
+ * - #EVAS_CALLBACK_MOUSE_DOWN: @a event_info is a pointer to an
+ * #Evas_Event_Mouse_Down struct\n\n
+ * This event is triggered by a mouse button being pressed while the
+ * mouse pointer is over an object. If the pointer mode for Evas is
+ * #EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this
+ * object to <b>passively grab the mouse</b> until all mouse buttons
+ * have been released: all future mouse events are reported to
+ * only this object until no buttons are down. That includes mouse
+ * move events, mouse in and mouse out events, and further button
+ * presses. When all buttons are released, event propagation
+ * occurs as normal (see #Evas_Object_Pointer_Mode).
+ *
+ * - #EVAS_CALLBACK_MOUSE_UP: @a event_info is a pointer to an
+ * #Evas_Event_Mouse_Up struct\n\n
+ * This event is triggered by a mouse button being released while
+ * the mouse pointer is over an object's area (or when passively
+ * grabbed to an object).
+ *
+ * - #EVAS_CALLBACK_MOUSE_MOVE: @a event_info is a pointer to an
+ * #Evas_Event_Mouse_Move struct\n\n
+ * This event is triggered by the mouse pointer being moved while
+ * over an object's area (or while passively grabbed to an object).
+ *
+ * - #EVAS_CALLBACK_MOUSE_WHEEL: @a event_info is a pointer to an
+ * #Evas_Event_Mouse_Wheel struct\n\n
+ * This event is triggered by the mouse wheel being rolled while the
+ * mouse pointer is over an object (or passively grabbed to an object).
+ *
+ * - #EVAS_CALLBACK_MULTI_DOWN: @a event_info is a pointer to an
+ * #Evas_Event_Multi_Down struct
+ *
+ * - #EVAS_CALLBACK_MULTI_UP: @a event_info is a pointer to an
+ * #Evas_Event_Multi_Up struct
+ *
+ * - #EVAS_CALLBACK_MULTI_MOVE: @a event_info is a pointer to an
+ * #Evas_Event_Multi_Move struct
+ *
+ * - #EVAS_CALLBACK_FREE: @a event_info is @c NULL \n\n
+ * This event is triggered just before Evas is about to free all
+ * memory used by an object and remove all references to it. This is
+ * useful for programs to use if they attached data to an object and
+ * want to free it when the object is deleted. The object is still
+ * valid when this callback is called, but after it returns, there
+ * is no guarantee on the object's validity.
+ *
+ * - #EVAS_CALLBACK_KEY_DOWN: @a event_info is a pointer to an
+ * #Evas_Event_Key_Down struct\n\n
+ * This callback is called when a key is pressed and the focus is on
+ * the object, or a key has been grabbed to a particular object
+ * which wants to intercept the key press regardless of what object
+ * has the focus.
+ *
+ * - #EVAS_CALLBACK_KEY_UP: @a event_info is a pointer to an
+ * #Evas_Event_Key_Up struct \n\n
+ * This callback is called when a key is released and the focus is
+ * on the object, or a key has been grabbed to a particular object
+ * which wants to intercept the key release regardless of what
+ * object has the focus.
+ *
+ * - #EVAS_CALLBACK_FOCUS_IN: @a event_info is @c NULL \n\n
+ * This event is called when an object gains the focus. When it is
+ * called the object has already gained the focus.
+ *
+ * - #EVAS_CALLBACK_FOCUS_OUT: @a event_info is @c NULL \n\n
+ * This event is triggered when an object loses the focus. When it
+ * is called the object has already lost the focus.
+ *
+ * - #EVAS_CALLBACK_SHOW: @a event_info is @c NULL \n\n
+ * This event is triggered by the object being shown by
+ * evas_object_show().
+ *
+ * - #EVAS_CALLBACK_HIDE: @a event_info is @c NULL \n\n
+ * This event is triggered by an object being hidden by
+ * evas_object_hide().
+ *
+ * - #EVAS_CALLBACK_MOVE: @a event_info is @c NULL \n\n
+ * This event is triggered by an object being
+ * moved. evas_object_move() can trigger this, as can any
+ * object-specific manipulations that would mean the object's origin
+ * could move.
+ *
+ * - #EVAS_CALLBACK_RESIZE: @a event_info is @c NULL \n\n
+ * This event is triggered by an object being resized. Resizes can
+ * be triggered by evas_object_resize() or by any object-specific
+ * calls that may cause the object to resize.
+ *
+ * - #EVAS_CALLBACK_RESTACK: @a event_info is @c NULL \n\n
+ * This event is triggered by an object being re-stacked. Stacking
+ * changes can be triggered by
+ * evas_object_stack_below()/evas_object_stack_above() and others.
+ *
+ * - #EVAS_CALLBACK_DEL: @a event_info is @c NULL.
+ *
+ * - #EVAS_CALLBACK_HOLD: @a event_info is a pointer to an
+ * #Evas_Event_Hold struct
+ *
+ * - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @a event_info is @c NULL.
+ *
+ * - #EVAS_CALLBACK_IMAGE_PRELOADED: @a event_info is @c NULL.
+ *
+ * - #EVAS_CALLBACK_IMAGE_UNLOADED: @a event_info is @c NULL.
+ *
+ * @remarks Be careful not to add the same callback multiple times, if
+ * that is not what you want, because Evas does not check if a callback
+ * existed before exactly as the one being registered (and thus, call
+ * it more than once on the event, in this case). This would make
+ * sense if you passed different functions and/or callback data, only.
+ *
+ * @param[in] obj The object to attach a callback to
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] func The function to be called when the event is triggered
+ * @param[in] data The data pointer to be passed to @a func
+ */
+EAPI void evas_object_event_callback_add(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
+
+/**
+ * @brief Adds or registers a callback function to a given Evas object event with a
+ * non-default priority set. Except for the priority field, it is exactly the
+ * same as @ref evas_object_event_callback_add.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The object to attach a callback to
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] priority The priority of the callback \n
+ * Lower values are called first.
+ * @param[in] func The function to be called when the event is triggered
+ * @param[in] data The data pointer to be passed to @a func
+ *
+ * @see evas_object_event_callback_add
+ */
+EAPI void evas_object_event_callback_priority_add(Evas_Object *obj, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 4);
+
+/**
+ * @brief Deletes a callback function from an object.
+ *
+ * @details This function removes the most recently added callback from the
+ * object @a obj which is triggered by the event type @a type and is
+ * calling the function @a func when triggered. If the removal is
+ * successful it also returns the data pointer that is passed to
+ * evas_object_event_callback_add() when the callback is added to the
+ * object. If not successful @c NULL is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas_Object *object;
+ * void *my_data;
+ * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
+ *
+ * my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
+ * @endcode
+ *
+ * @param[in] obj The object to remove a callback from
+ * @param[in] type The type of event triggering the callback
+ * @param[in] func The function to be called when the event is triggered
+ * @return The data pointer to be passed to the callback
+ */
+EAPI void *evas_object_event_callback_del(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3);
+
+/**
+ * @brief Deletes or unregisters a callback function registered to a given Evas object event.
+ *
+ * @details This function removes the most recently added callback from the
+ * object @a obj, which is triggered by the event type @a type and is
+ * calling the function @a func with data @a data, when triggered. If
+ * the removal is successful it also returns the data pointer that
+ * is passed to evas_object_event_callback_add() (that is the
+ * same as the parameter) when the callback is added to the
+ * object. In case of errors, @c NULL is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks For deletion of Evas object events callbacks filtering by
+ * just type and function pointer, use evas_object_event_callback_del().
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas_Object *object;
+ * void *my_data;
+ * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
+ *
+ * my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
+ * @endcode
+ *
+ * @param[in] obj The object to remove a callback from
+ * @param[in] type The type of event triggering the callback
+ * @param[in] func The function to be called when the event is triggered
+ * @param[in] data The data pointer to be passed to the callback
+ * @return The data pointer to be passed to the callback
+ */
+EAPI void *evas_object_event_callback_del_full(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
+
+/**
+ * @brief Sets whether an Evas object is to pass (ignore) events.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @a pass is #EINA_TRUE, it makes events on @a obj to be @b
+ * ignored. They instead are triggered on the @b next lower object that
+ * is not set to pass events. See evas_object_below_get().
+ *
+ * @remarks If @a pass is #EINA_FALSE, events are processed on that
+ * object as normal.
+ *
+ *
+ * @param[in] obj The Evas object to operate on
+ * @param[in] pass Set #EINA_TRUE for @a obj to pass events, \n
+ * otherwise #EINA_FALSE not to pass events
+ *
+ * @see evas_object_pass_events_get() for an example
+ * @see evas_object_repeat_events_set()
+ * @see evas_object_propagate_events_set()
+ * @see evas_object_freeze_events_set()
+ */
+EAPI void evas_object_pass_events_set(Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether an object is set to pass (ignore) events.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The Evas object to get information from
+ * @return #EINA_TRUE if @a obj is set to pass events, \n
+ * otherwise #EINA_FALSE if it is not set to pass events
+ *
+ * @see evas_object_pass_events_set()
+ * @see evas_object_repeat_events_get()
+ * @see evas_object_propagate_events_get()
+ * @see evas_object_freeze_events_get()
+ */
+EAPI Eina_Bool evas_object_pass_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets whether an Evas object is to repeat events.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @a repeat is #EINA_TRUE, it makes events on @a obj to also
+ * be repeated for the @b next lower object in the objects' stack. See
+ * evas_object_below_get().
+ *
+ * @remarks If @a repeat is #EINA_FALSE, events occurring on @a obj are
+ * processed only on it.
+ *
+ * @param[in] obj The Evas object to operate on
+ * @param[in] repeat Set #EINA_TRUE for @a obj to repeat events, \n
+ * otherwise set #EINA_FALSE
+ *
+ * @see evas_object_repeat_events_get()
+ * @see evas_object_pass_events_set()
+ * @see evas_object_propagate_events_set()
+ * @see evas_object_freeze_events_set()
+ */
+EAPI void evas_object_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether an object is set to repeat events.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object pointer
+ * @return #EINA_TRUE if @a obj is set to repeat events,
+ * otherwise #EINA_FALSE if it is not set to repeat events
+ *
+ * @see evas_object_repeat_events_set() for an example
+ * @see evas_object_pass_events_get()
+ * @see evas_object_propagate_events_get()
+ * @see evas_object_freeze_events_get()
+ */
+EAPI Eina_Bool evas_object_repeat_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets whether events on a smart object's member should get propagated
+ * up to its parent.
+ *
+ * @details This function has @b no effect if @a obj is not a member of a smart object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @a prop is #EINA_TRUE, events occurring on this object is
+ * propagated on to the smart object of which @a obj is a member. If
+ * @a prop is #EINA_FALSE, events occurring on this object is @b
+ * not propagated on to the smart object of which @a obj is a
+ * member. The default value is #EINA_TRUE.
+ *
+ * @param[in] obj The smart object's child to operate on
+ * @param[in] prop Set #EINA_TRUE to propagate events, \n
+ * otherwise #EINA_FALSE to not propagate events
+ *
+ * @see evas_object_propagate_events_get()
+ * @see evas_object_repeat_events_set()
+ * @see evas_object_pass_events_set()
+ * @see evas_object_freeze_events_set()
+ */
+EAPI void evas_object_propagate_events_set(Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether an Evas object is set to propagate events.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object pointer
+ * @return #EINA_TRUE if @a obj is set to propagate events, \n
+ * otherwise #EINA_FALSE it is not set to propagate events
+ *
+ * @see evas_object_propagate_events_set()
+ * @see evas_object_repeat_events_get()
+ * @see evas_object_pass_events_get()
+ * @see evas_object_freeze_events_get()
+ */
+EAPI Eina_Bool evas_object_propagate_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets whether an Evas object is to freeze (discard) events.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @a freeze is #EINA_TRUE, it makes events on @a obj to be @b
+ * discarded. Unlike evas_object_pass_events_set(), events are not
+ * passed to @b next lower object. This API can be used for blocking
+ * events while @a obj is on transiting.
+ *
+ * @remarks If @a freeze is #EINA_FALSE, events are processed on that
+ * object as normal.
+ *
+ * @param[in] obj The Evas object to operate on
+ * @param[in] freeze Set #EINA_TRUE for @a obj to freeze events, \n
+ * otherwise #EINA_FALSE not to freeze events
+ *
+ * @see evas_object_freeze_events_get()
+ * @see evas_object_pass_events_set()
+ * @see evas_object_repeat_events_set()
+ * @see evas_object_propagate_events_set()
+ */
+EAPI void evas_object_freeze_events_set(Evas_Object *obj, Eina_Bool freeze) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether an object is set to freeze (discard) events.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The Evas object to get information from
+ * @return #EINA_TRUE if @a obj is set to freeze events, \n
+ * otherwise #EINA_FALSE if it is not set to freeze events
+ *
+ * @see evas_object_freeze_events_set()
+ * @see evas_object_pass_events_get()
+ * @see evas_object_repeat_events_get()
+ * @see evas_object_propagate_events_get()
+ */
+EAPI Eina_Bool evas_object_freeze_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspective, 3D...)
+ * @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions for UV mapping.
+ *
+ * Evas allows different transformations to be applied to all kinds of
+ * objects. These are applied by means of UV mapping.
+ *
+ * With UV mapping, one maps points in the source object to a 3D space
+ * positioning at target. This allows rotation, perspective, scale and
+ * lots of other effects, depending on the map that is used.
+ *
+ * Each map point may carry a multiplier color. If properly
+ * calculated, these can do shading effects on the object, producing
+ * 3D effects.
+ *
+ * As usual, Evas provides both raw and easy to use methods. The
+ * raw methods allow developers to create their maps somewhere else,
+ * possibly loading them from some file format. The easy to use methods
+ * calculate the points given some high-level parameters such as
+ * rotation angle, ambient light, and so on.
+ *
+ * @remarks Applying mapping reduces performance, so use with
+ * care. The impact on performance depends on the engine in
+ * use. The software is quite optimized, but not as fast as OpenGL.
+ *
+ * @section sec-map-points Map points
+ * @subsection subsec-rotation Rotation
+ *
+ * A map consists of a set of points, currently only four are supported. Each
+ * of these points contains a set of canvas coordinates @c x and @c y that
+ * can be used to alter the geometry of the mapped object, and a @c z
+ * coordinate that indicates the depth of that point. This last coordinate
+ * does not normally affect the map, but it is used by several of the utility
+ * functions to calculate the right position of the point given other
+ * parameters.
+ *
+ * The coordinates for each point are set with evas_map_point_coord_set().
+ * The following image shows a map set to match the geometry of an existing object.
+ *
+ * @image html map-set-map-points-1.png
+ * @image rtf map-set-map-points-1.png
+ * @image latex map-set-map-points-1.eps
+ *
+ * This is a common practice, so there are a few functions that help make it easier.
+ *
+ * evas_map_util_points_populate_from_geometry() sets the coordinates of each
+ * point in the given map to match the rectangle defined by the function parameters.
+ *
+ * evas_map_util_points_populate_from_object() and
+ * evas_map_util_points_populate_from_object_full() both take an object and
+ * set the map points to match its geometry. The difference between the two
+ * is that the first function sets the @c z value of all points to @c 0, while
+ * the latter receives the value to set in said coordinate as a parameter.
+ *
+ * The following lines of code all produce the same result as in the image above.
+ * @code
+ * evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
+ * // Assuming o is our original object
+ * evas_object_move(o, 100, 100);
+ * evas_object_resize(o, 200, 200);
+ * evas_map_util_points_populate_from_object(m, o);
+ * evas_map_util_points_populate_from_object_full(m, o, 0);
+ * @endcode
+ *
+ * Several effects can be applied to an object by simply setting each point
+ * of the map to the right coordinates. For example, a simulated perspective
+ * could be achieve as follows.
+ *
+ * @image html map-set-map-points-2.png
+ * @image rtf map-set-map-points-2.png
+ * @image latex map-set-map-points-2.eps
+ *
+ * As said before, the @c z coordinate is unused here so when setting points
+ * by hand, its value is of no importance.
+ *
+ * @image html map-set-map-points-3.png
+ * @image rtf map-set-map-points-3.png
+ * @image latex map-set-map-points-3.eps
+ *
+ * In all three cases above, setting the map to be used by the object is the same.
+ * @code
+ * evas_object_map_set(o, m);
+ * evas_object_map_enable_set(o, EINA_TRUE);
+ * @endcode
+ *
+ * Doing things this way, however, is a lot of work that can be avoided by
+ * using the provided utility functions, as described in the next section.
+ *
+ * @section map-utils Utility functions
+ *
+ * Utility functions take an already set up map and alter it to produce a
+ * specific effect. For example, to rotate an object around its own center
+ * you would need to take the rotation angle, the coordinates of each corner
+ * of the object and do all the math to get the new set of coordinates that
+ * need to be set in the map.
+ *
+ * Or you can use this code:
+ * @code
+ * evas_object_geometry_get(o, &x, &y, &w, &h);
+ * m = evas_map_new(4);
+ * evas_map_util_points_populate_from_object(m, o);
+ * evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
+ * evas_object_map_set(o, m);
+ * evas_object_map_enable_set(o, EINA_TRUE);
+ * evas_map_free(m);
+ * @endcode
+ *
+ * which rotates the object around its center point in a 45 degree angle
+ * in the clockwise direction, taking it from this
+ *
+ * @image html map-rotation-2d-1.png
+ * @image rtf map-rotation-2d-1.png
+ * @image latex map-rotation-2d-1.eps
+ *
+ * to this
+ *
+ * @image html map-rotation-2d-2.png
+ * @image rtf map-rotation-2d-2.png
+ * @image latex map-rotation-2d-2.eps
+ *
+ * Objects may be rotated around any other point just by setting the last two
+ * parameters of the evas_map_util_rotate() function to the right values. A
+ * circle of roughly the diameter of the object overlaid on each image shows
+ * where the center of rotation is set for each example.
+ *
+ * For example, this code
+ * @code
+ * evas_object_geometry_get(o, &x, &y, &w, &h);
+ * m = evas_map_new(4);
+ * evas_map_util_points_populate_from_object(m, o);
+ * evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
+ * evas_object_map_set(o, m);
+ * evas_object_map_enable_set(o, EINA_TRUE);
+ * evas_map_free(m);
+ * @endcode
+ *
+ * produces something like
+ *
+ * @image html map-rotation-2d-3.png
+ * @image rtf map-rotation-2d-3.png
+ * @image latex map-rotation-2d-3.eps
+ *
+ * And the following
+ * @code
+ * evas_output_size_get(evas, &w, &h);
+ * m = evas_map_new(4);
+ * evas_map_util_points_populate_from_object(m, o);
+ * evas_map_util_rotate(m, 45, w, h);
+ * evas_object_map_set(o, m);
+ * evas_object_map_enable_set(o, EINA_TRUE);
+ * evas_map_free(m);
+ * @endcode
+ *
+ * rotates the object around the center of the window
+ *
+ * @image html map-rotation-2d-4.png
+ * @image rtf map-rotation-2d-4.png
+ * @image latex map-rotation-2d-4.eps
+ *
+ * @subsection subsec-3d 3D Maps
+ *
+ * Maps can also be used to achieve the effect of 3-dimensionality. When doing
+ * this, the @c z coordinate of each point counts, with higher values meaning
+ * the point is further into the screen, and smaller values (negative, usually)
+ * meaning the point is closer towards the user.
+ *
+ * Thinking in 3D also introduces the concept of back-face of an object. An
+ * object is said to be facing the user when all its points are placed in a
+ * clockwise fashion. The next image shows this, with each point showing each
+ * corner of the object with which it is identified within the map.
+ *
+ * @image html map-point-order-face.png
+ * @image rtf map-point-order-face.png
+ * @image latex map-point-order-face.eps
+ *
+ * Rotating this map around the @c Y axis would leave the order of the points
+ * in a counter-clockwise fashion, as seen in the following image.
+ *
+ * @image html map-point-order-back.png
+ * @image rtf map-point-order-back.png
+ * @image latex map-point-order-back.eps
+ *
+ * This way we can say that we are looking at the back face of the object.
+ * This has stronger implications later when we talk about lighting.
+ *
+ * To know if a map is facing towards the user or not it is enough to use
+ * the evas_map_util_clockwise_get() function, but this is normally done
+ * after all the other operations are applied on the map.
+ *
+ * @subsection subsec-3d-rot 3D rotation and perspective
+ *
+ * Much like evas_map_util_rotate(), there is the function
+ * evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
+ * to an object. As in its 2D counterpart, the rotation can be applied around
+ * any point in the canvas, this time with a @c z coordinate too. The rotation
+ * can also be around any of the 3 axis.
+ *
+ * Starting from this simple setup
+ *
+ * @image html map-3d-basic-1.png
+ * @image rtf map-3d-basic-1.png
+ * @image latex map-3d-basic-1.eps
+ *
+ * and setting maps so that the blue square to rotate on all axis around a
+ * sphere that uses the object as its center, and the red square to rotate
+ * around the @c Y axis, we get the following. A simple overlay over the image
+ * shows the original geometry of each object and the axis around which they
+ * are being rotated, with the @c Z one not appearing due to being orthogonal
+ * to the screen.
+ *
+ * @image html map-3d-basic-2.png
+ * @image rtf map-3d-basic-2.png
+ * @image latex map-3d-basic-2.eps
+ *
+ * which does not look very real. This can be helped by adding perspective
+ * to the transformation, which can be simply done by calling
+ * evas_map_util_3d_perspective() on the map after its position has been set.
+ * The result in this case, making the vanishing point the center of each
+ * object:
+ *
+ * @image html map-3d-basic-3.png
+ * @image rtf map-3d-basic-3.png
+ * @image latex map-3d-basic-3.eps
+ *
+ * @section sec-color Color and lighting
+ *
+ * Each point in a map can be set to a color, which is multiplied with
+ * the objects own color and linearly interpolated in between adjacent points.
+ * This is done with evas_map_point_color_set() for each point of the map,
+ * or evas_map_util_points_color_set() to set every point to the same color.
+ *
+ * When using 3D effects, colors can be used to improve the looks of them by
+ * simulating a light source. The evas_map_util_3d_lighting() function makes
+ * this task easier by taking the coordinates of the light source and its
+ * color, along with the color of the ambient light. Evas then sets the color
+ * of each point based on the distance to the light source, the angle with
+ * which the object is facing the light and the ambient light. Here, the
+ * orientation of each point as explained before, becomes more important.
+ * If the map is defined counter-clockwise, the object faces away
+ * from the user and thus become obscured, since no light would be reflecting
+ * from it.
+ *
+ * @image html map-light.png
+ * @image rtf map-light.png
+ * @image latex map-light.eps
+ * @note Object facing the light source
+ *
+ * @image html map-light2.png
+ * @image rtf map-light2.png
+ * @image latex map-light2.eps
+ * @note Same object facing away from the user
+ *
+ * @section Image mapping
+ *
+ * @image html map-uv-mapping-1.png
+ * @image rtf map-uv-mapping-1.png
+ * @image latex map-uv-mapping-1.eps
+ *
+ * Images need some special handling when mapped. Evas can easily take care
+ * of objects and do almost anything with them, but it is completely oblivious
+ * to the content of images, so each point in the map needs to be told to what
+ * pixel in the source image it belongs. Failing to do may sometimes result
+ * in the expected behavior, or it may look like a partial work.
+ *
+ * The next image illustrates one possibility of a map being set to an image
+ * object, without setting the right UV mapping for each point. The objects
+ * themselves are mapped properly to their new geometry, but the image content
+ * may not be displayed correctly within the mapped object.
+ *
+ * @image html map-uv-mapping-2.png
+ * @image rtf map-uv-mapping-2.png
+ * @image latex map-uv-mapping-2.eps
+ *
+ * Once Evas knows how to handle the source image within the map, it
+ * transforms it as needed. This is done with evas_map_point_image_uv_set(),
+ * which tells the map to which pixel in image it maps.
+ *
+ * To match our example images to the maps above all we need is the size of
+ * each image, which can always be found with evas_object_image_size_get().
+ *
+ * @code
+ * evas_map_point_image_uv_set(m, 0, 0, 0);
+ * evas_map_point_image_uv_set(m, 1, 150, 0);
+ * evas_map_point_image_uv_set(m, 2, 150, 200);
+ * evas_map_point_image_uv_set(m, 3, 0, 200);
+ * evas_object_map_set(o, m);
+ * evas_object_map_enable_set(o, EINA_TRUE);
+ *
+ * evas_map_point_image_uv_set(m, 0, 0, 0);
+ * evas_map_point_image_uv_set(m, 1, 120, 0);
+ * evas_map_point_image_uv_set(m, 2, 120, 160);
+ * evas_map_point_image_uv_set(m, 3, 0, 160);
+ * evas_object_map_set(o2, m);
+ * evas_object_map_enable_set(o2, EINA_TRUE);
+ * @endcode
+ *
+ * @image html map-uv-mapping-3.png
+ * @image rtf map-uv-mapping-3.png
+ * @image latex map-uv-mapping-3.eps
+ *
+ * Maps can also be set to use part of an image only, or even map them inverted,
+ * and when combined with evas_object_image_source_set() it can be used to achieve
+ * more interesting results.
+ *
+ * @code
+ * evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
+ * evas_map_point_image_uv_set(m, 0, 0, h);
+ * evas_map_point_image_uv_set(m, 1, w, h);
+ * evas_map_point_image_uv_set(m, 2, w, h / 3);
+ * evas_map_point_image_uv_set(m, 3, 0, h / 3);
+ * evas_object_map_set(o, m);
+ * evas_object_map_enable_set(o, EINA_TRUE);
+ * @endcode
+ *
+ * @image html map-uv-mapping-4.png
+ * @image rtf map-uv-mapping-4.png
+ * @image latex map-uv-mapping-4.eps
+ *
+ * @{
+ */
+
+/**
+ * @brief Enables or disables the map that is set.
+ *
+ * @details This function enables or disables the use of map for the object @a obj.
+ * When enabled, the object geometry is saved, and the new geometry
+ * changes (position and size) to reflect the map geometry set.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the object does not have a map set (with evas_object_map_set()), the
+ * initial geometry is undefined. It is advised to always set a map
+ * to the object first, and then call this function to enable its use.
+ *
+ * @param[in] obj The object to enable the map on
+ * @param[in] enabled Set #EINA_TRUE to enable the map, \n
+ * otherwise #EINA_FALSE to not enable the map
+ */
+EAPI void evas_object_map_enable_set(Evas_Object *obj, Eina_Bool enabled);
+
+/**
+ * @brief Checks whether the map is enabled.
+ *
+ * @details This function returns the currently enabled state of the map on the object indicated.
+ * The default map enable state is off. You can enable and disable it with
+ * evas_object_map_enable_set().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The object to get the map enabled state from
+ * @return #EINA_TRUE of the map is enabled, \n
+ * otherwise #EINA_FALSE of the map is not enabled
+ */
+EAPI Eina_Bool evas_object_map_enable_get(const Evas_Object *obj);
+
+/**
+ * @brief Sets current object transformation map.
+ *
+ * @details This function sets the map on a given object. It is copied from the @a map pointer,
+ * so there is no need to keep the @a map object if you do not need it anymore.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks A map is a set of 4 points which have canvas @c x, @c y coordinates per point,
+ * with an optional @c z point value as a hint for perspective correction, if it
+ * is available. As well each point has @c u and @c v coordinates. These are like
+ * "texture coordinates" in OpenGL in that they define a point in the source
+ * image that is mapped to that map vertex or point. The @c u corresponds to the @c x
+ * coordinate of this mapped point and @c v, the @c y coordinate. Note that these
+ * coordinates describe a bounding region to sample. If you have a 200x100
+ * source image and want to display it at 200x100 with proper pixel
+ * precision, then do the following:
+ *
+ * @code
+ * Evas_Map *m = evas_map_new(4);
+ * evas_map_point_coord_set(m, 0, 0, 0, 0);
+ * evas_map_point_coord_set(m, 1, 200, 0, 0);
+ * evas_map_point_coord_set(m, 2, 200, 100, 0);
+ * evas_map_point_coord_set(m, 3, 0, 100, 0);
+ * evas_map_point_image_uv_set(m, 0, 0, 0);
+ * evas_map_point_image_uv_set(m, 1, 200, 0);
+ * evas_map_point_image_uv_set(m, 2, 200, 100);
+ * evas_map_point_image_uv_set(m, 3, 0, 100);
+ * evas_object_map_set(obj, m);
+ * evas_map_free(m);
+ * @endcode
+ *
+ * @remarks Note that the map points a uv coordinates that match the image geometry. If
+ * the @a map parameter is @c NULL, the stored map is freed and geometry
+ * prior to enabling/setting a map is restored.
+ *
+ * @param[in] obj The object to change transformation map
+ * @param[in] map The new map to use
+ *
+ * @see evas_map_new()
+ */
+EAPI void evas_object_map_set(Evas_Object *obj, const Evas_Map *map);
+
+/**
+ * @brief Gets the current object transformation map.
+ *
+ * @details This function returns the current internal map set on the indicated object. It is
+ * intended for read-only access and is only valid as long as the object is
+ * not deleted or the map on the object is not changed. If you wish to modify
+ * the map and set it back do the following:
+ *
+ * @since_tizen 2.3
+ *
+ * @code
+ * const Evas_Map *m = evas_object_map_get(obj);
+ * Evas_Map *m2 = evas_map_dup(m);
+ * evas_map_util_rotate(m2, 30.0, 0, 0);
+ * evas_object_map_set(obj, m2);
+ * evas_map_free(m2);
+ * @endcode
+ *
+ * @param[in] obj The object to query transformation map
+ * @return The map reference to the map in use \n
+ * This is an internal data structure, so do not modify it.
+ *
+ * @see evas_object_map_set()
+ */
+EAPI const Evas_Map *evas_object_map_get(const Evas_Object *obj);
+
+/**
+ * @brief Populates source and destination map points to exactly match the object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks You initialize the map of an object to match its original
+ * position and size, then transform these with evas_map_util_*
+ * functions, such as evas_map_util_rotate() or
+ * evas_map_util_3d_rotate(). The original set is done by this
+ * function, avoiding code duplication all around.
+ *
+ * @param[in] m The map to change all 4 points (must be of size 4)
+ * @param[in] obj The object to use unmapped geometry to populate map coordinates
+ * @param[in] z The point Z coordinate hint (pre-perspective transform) \n
+ * This value is used for all four points.
+ *
+ * @see evas_map_util_points_populate_from_object()
+ * @see evas_map_point_coord_set()
+ * @see evas_map_point_image_uv_set()
+ */
+EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
+
+/**
+ * @brief Populates the source and destination map points to exactly match the object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks You initialize map of an object to match its original
+ * position and size, then transform these with evas_map_util_*
+ * functions, such as evas_map_util_rotate() or
+ * evas_map_util_3d_rotate(). The original set is done by this
+ * function, avoiding code duplication all around.
+ *
+ * @remarks The Z point coordinate is assumed as @c 0 (zero).
+ *
+ * @param[in] m The map to change all 4 points (must be of size 4)
+ * @param[in] obj The object to use unmapped geometry to populate map coordinates
+ *
+ * @see evas_map_util_points_populate_from_object_full()
+ * @see evas_map_util_points_populate_from_geometry()
+ * @see evas_map_point_coord_set()
+ * @see evas_map_point_image_uv_set()
+ */
+EAPI void evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj);
+
+/**
+ * @brief Populates the source and destination map points to match the given geometry.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Similar to evas_map_util_points_populate_from_object_full(), this
+ * call takes raw values instead of querying object's unmapped
+ * geometry. The given width is used to calculate destination
+ * points (evas_map_point_coord_set()) and set the image uv
+ * (evas_map_point_image_uv_set()).
+ *
+ * @param[in] m The map to change all 4 points (must be of size 4)
+ * @param[in] x The X coordinate
+ * @param[in] y The Y coordinate
+ * @param[in] w The width to use to calculate second and third points
+ * @param[in] h The height to use to calculate third and fourth points
+ * @param[in] z The Z coordinate hint (pre-perspective transform) \n
+ * This value is used for all four points.
+ *
+ * @see evas_map_util_points_populate_from_object()
+ * @see evas_map_point_coord_set()
+ * @see evas_map_point_image_uv_set()
+ */
+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);
+
+/**
+ * @brief Sets the given color for all the points.
+ *
+ * @details This function is useful to reuse maps after they had 3D lightning or
+ * any other colorization applied before.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to change the color of
+ * @param[in] r The red color (0 - 255)
+ * @param[in] g The green color (0 - 255)
+ * @param[in] b The blue color (0 - 255)
+ * @param[in] a The alpha color (0 - 255)
+ *
+ * @see evas_map_point_color_set()
+ */
+EAPI void evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a);
+
+/**
+ * @brief Changes the map to apply the given rotation.
+ *
+ * @details This function rotates the indicated map's coordinates around the center coordinate
+ * given by @a cx and @a cy as the rotation center. The points have their
+ * X and Y coordinates rotated clockwise by @a degrees degrees (@c 360.0 is a
+ * full rotation). Negative values for degrees rotate counter-clockwise
+ * by that amount. All coordinates are canvas global coordinates.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to change
+ * @param[in] degrees The amount of degrees from @c 0.0 to @c 360.0 to rotate
+ * @param[in] cx The rotation's center horizontal position
+ * @param[in] cy The rotation's center vertical position
+ *
+ * @see evas_map_point_coord_set()
+ * @see evas_map_util_zoom()
+ */
+EAPI void evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
+
+/**
+ * @brief Changes the map to apply the given zooming.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Like evas_map_util_rotate(), this zooms the points of the map from a center
+ * point. That center is defined by @a cx and @a cy. The @a zoomx and @a zoomy
+ * parameters specify how much to zoom in the X and Y direction respectively.
+ * A value of @c 1.0 means "don't zoom", @c 2.0 means "double the size", @c 0.5 is
+ * "half the size", and so on. All coordinates are canvas global coordinates.
+ *
+ * @param[in] m The map to change
+ * @param[in] zoomx The horizontal zoom to use
+ * @param[in] zoomy The vertical zoom to use
+ * @param[in] cx The zooming center horizontal position
+ * @param[in] cy The zooming center vertical position
+ *
+ * @see evas_map_point_coord_set()
+ * @see evas_map_util_rotate()
+ */
+EAPI void evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
+
+/**
+ * @brief Rotates the map around 3 axes in 3D.
+ *
+ * @details This function rotates not just around the "Z" axis as in evas_map_util_rotate()
+ * (which is a convenience call for those only wanting 2D). This rotates
+ * around the X, Y and Z axes. The Z axis points "into" the screen with low
+ * values at the screen and higher values further away. The X axis runs from
+ * left to right on the screen and the Y axis from top to bottom. Like with
+ * evas_map_util_rotate() you provide a center point to rotate around (in 3D).
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to change
+ * @param[in] dx The amount of degrees from @c 0.0 to @c 360.0 to rotate around X axis
+ * @param[in] dy The amount of degrees from @c 0.0 to @c 360.0 to rotate around Y axis
+ * @param[in] dz The amount of degrees from @c 0.0 to @c 360.0 to rotate around Z axis
+ * @param[in] cx The rotation's center horizontal position
+ * @param[in] cy The rotation's center vertical position
+ * @param[in] cz The rotation's center vertical position
+ */
+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);
+
+/**
+ * @brief Rotates the map in 3D using a unit quaternion.
+ *
+ * @details This function rotates in 3D using a unit quaternion. Like with
+ * evas_map_util_3d_rotate() you provide a center point
+ * to rotate around (in 3D).
+ * @since 1.8
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Rotations can be done using a unit quaternion. Thus, this
+ * function expects a unit quaternion (i.e. qx² + qy² + qz² + qw² == 1).
+ * If this is not the case the behavior is undefined.
+ *
+ * @param[in] m The map to change
+ * @param[in] qx The x component of the imaginary part of the quaternion
+ * @param[in] qy The y component of the imaginary part of the quaternion
+ * @param[in] qz The z component of the imaginary part of the quaternion
+ * @param[in] qw The w component of the real part of the quaternion
+ * @param[in] cx The rotation's center x
+ * @param[in] cy The rotation's center y
+ * @param[in] cz The rotation's center z
+ *
+ */
+EAPI void evas_map_util_quat_rotate(Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz);
+
+/**
+ * @brief Performs lighting calculations on the given map.
+ *
+ * @details This function is used to apply lighting calculations (from a single light source)
+ * to a given map. The R, G and B values of each vertex is modified to
+ * reflect the lighting based on the lixth point coordinates, the light
+ * color and the ambient color, and at what angle the map is facing the
+ * light source. A surface should have its points declared in a
+ * clockwise fashion if the face is "facing" towards you (as opposed to
+ * away from you) as faces have a "logical" side for lighting.
+ *
+ * @since_tizen 2.3
+ *
+ * @image html map-light3.png
+ * @image rtf map-light3.png
+ * @image latex map-light3.eps
+ * @remarks Grey object, no lighting used
+ *
+ * @image html map-light4.png
+ * @image rtf map-light4.png
+ * @image latex map-light4.eps
+ * @remarks Lights out! Every color set to @c 0
+ *
+ * @image html map-light5.png
+ * @image rtf map-light5.png
+ * @image latex map-light5.eps
+ * @remarks Ambient light to full black, red light coming from close at the
+ * bottom-left vertex.
+ *
+ * @image html map-light6.png
+ * @image rtf map-light6.png
+ * @image latex map-light6.eps
+ * @remarks Same light as before, but not the light is set to 0 and ambient light
+ * is cyan.
+ *
+ * @image html map-light7.png
+ * @image rtf map-light7.png
+ * @image latex map-light7.eps
+ * @remarks Both lights are on.
+ *
+ * @image html map-light8.png
+ * @image rtf map-light8.png
+ * @image latex map-light8.eps
+ * @remarks Both lights again, but this time both are the same color.
+ *
+ * @param[in] m The map to change
+ * @param[in] lx The X coordinate in space of light point
+ * @param[in] ly The Y coordinate in space of light point
+ * @param[in] lz The Z coordinate in space of light point
+ * @param[in] lr The light red value (0 - 255)
+ * @param[in] lg The light green value (0 - 255)
+ * @param[in] lb The light blue value (0 - 255)
+ * @param[in] ar The ambient color red value (0 - 255)
+ * @param[in] ag The ambient color green value (0 - 255)
+ * @param[in] ab The ambient color blue value (0 - 255)
+ */
+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);
+
+/**
+ * @brief Applies a perspective transform to the map.
+ *
+ * @details This function applies a given perspective (3D) to the map coordinates. X, Y and Z
+ * values are used. The px and py points specify the "infinite distance" point
+ * in the 3D conversion (where all lines converge to, like when artists draw
+ * 3D by hand). The @a z0 value specifies the z value at which there is a 1:1
+ * mapping between spatial coordinates and screen coordinates. Any points
+ * on this z value do not have their X and Y values modified in the transform.
+ * Those further away (Z value higher) shrink into the distance, and
+ * those less than this value expand and become bigger. The @a foc value
+ * determines the "focal length" of the camera. This is in reality the distance
+ * between the camera lens plane itself (at or closer than this rendering
+ * results are undefined) and the "z0" z value. This allows for some "depth"
+ * control and @a foc must be greater than @c 0.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to change
+ * @param[in] px The perspective distance X coordinate
+ * @param[in] py The perspective distance Y coordinate
+ * @param[in] z0 The "0" z plane value
+ * @param[in] foc The focal distance
+ */
+EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
+
+/**
+ * @brief Gets the clockwise state of a map.
+ *
+ * @details This function determines if the output points (X and Y. Z is not used) are
+ * clockwise or counter-clockwise. This can be used for "back-face culling". This
+ * is where you hide objects that "face away" from you, in this case, the objects
+ * that are not clockwise.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to query
+ * @return #EINA_TRUE if the output points are clockwise,
+ * otherwise #EINA_FALSE if the output points are not clockwise
+ */
+EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m);
+
+/**
+ * @brief Creates a map of transformation points to be later used with an Evas object.
+ *
+ * @details This function creates a set of points (currently only 4 is supported and no other
+ * number for @a count works). That is empty and ready to be modified
+ * with evas_map calls.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] count The number of points in the map
+ * @return The newly allocated map, \n
+ * otherwise @c NULL on errors
+ *
+ * @see evas_map_free()
+ * @see evas_map_dup()
+ * @see evas_map_point_coord_set()
+ * @see evas_map_point_image_uv_set()
+ * @see evas_map_util_points_populate_from_object_full()
+ * @see evas_map_util_points_populate_from_object()
+ *
+ * @see evas_object_map_set()
+ */
+EAPI Evas_Map *evas_map_new(int count);
+
+/**
+ * @brief Sets the smoothing for map rendering.
+ *
+ * @details This function sets smoothing for map rendering. If the object is a type that has
+ * its own smoothing settings, then both the smooth settings for this object
+ * and the map must be turned off. By default, smooth maps are enabled.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to modify \n
+ * This must not be @c NULL.
+ * @param[in] enabled Set #EINA_TRUE to enable smooth map rendering, \n
+ * otherwise set #EINA_FALSE not to enable smooth map rendering
+ */
+EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled);
+
+/**
+ * Checks whether the smoothing for map rendering is enabled.
+ *
+ * @details This gets smoothing for map rendering.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map for which to get the smoothing status \n
+ * This must not be @c NULL.
+ * @return #EINA_TRUE if smoothing for map rendering is enabled, \n
+ * otherwise #EINA_FALSE if smoothing for map rendering is not enabled
+ */
+EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m);
+
+/**
+ * @brief Sets the alpha flag for map rendering.
+ *
+ * @details This function sets alpha flag for map rendering. If the object is a type that has
+ * its own alpha settings, then this takes precedence. Only image objects
+ * have this currently. Setting this off stops alpha blending of the map area, and is
+ * useful if you know the object and/or all sub-objects is 100% solid.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to modify \n
+ * This must not be @c NULL.
+ * @param[in] enabled Set #EINA_TRUE to enable alpha map rendering, \n
+ * otheriwse set #EINA_FALSE to disable alpha map rendering
+ */
+EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled);
+
+/**
+ * @brief Gets the alpha flag for map rendering.
+ *
+ * @details This gets the alpha flag for map rendering.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to get the alpha from \n
+ * This must not be @c NULL.
+ * @return The alpha flag
+ */
+EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m);
+
+/**
+ * @brief Copies a previously allocated map.
+ *
+ * @details This makes a duplicate of the @a m object and returns it.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to copy \n
+ * This must not be @c NULL.
+ * @return The newly allocated map with the same count and contents as @a m
+ */
+EAPI Evas_Map *evas_map_dup(const Evas_Map *m);
+
+/**
+ * @brief Frees a previously allocated map.
+ *
+ * @details This function frees a given map @a m and all memory associated with it. You must NOT
+ * free a map returned by evas_object_map_get() as this is internal.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to free
+ */
+EAPI void evas_map_free(Evas_Map *m);
+
+/**
+ * @brief Gets a maps size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function returns the number of points in a map. It should be at least be @c 4.
+ *
+ * @param[in] m The map to get the size
+ * @return The number of points in a map, \n
+ * otherwise @c -1 on error
+ */
+EAPI int evas_map_count_get(const Evas_Map *m) EINA_CONST;
+
+/**
+ * @brief Changes the map point's coordinate.
+ *
+ * @details This function sets the fixed point's coordinate in the map. Note that points
+ * describe the outline of a quadrangle and are ordered either clockwise
+ * or counter-clockwise. It is suggested to keep your quadrangles concave and
+ * non-complex, though these polygon modes may work, they may not render
+ * a desired set of output. The quadrangle uses points @c 0 and @c 1 , @c 1 and @c 2,
+ * @c 2 and @c 3, and @c 3 and @c 0 to describe the edges of the quadrangle.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The X, Y, and Z coordinates are in canvas units. Z is optional and may
+ * or may not be honored in drawing. Z is a hint and does not affect the
+ * X and Y rendered coordinates. It may be used for calculating fills with
+ * perspective correct rendering.
+ *
+ * @remarks Remember all coordinates are canvas global ones like with move and resize in evas.
+ *
+ * @param[in] m The map to change point \n
+ * This must not be @c NULL.
+ * @param[in] idx The index of point to change \n
+ * This must be smaller than map size.
+ * @param[in] x The X coordinate
+ * @param[in] y The Y coordinate
+ * @param[in] z The Z coordinate hint (pre-perspective transform)
+ *
+ * @see evas_map_util_rotate()
+ * @see evas_map_util_zoom()
+ * @see evas_map_util_points_populate_from_object_full()
+ * @see evas_map_util_points_populate_from_object()
+ */
+EAPI void evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
+
+/**
+ * @brief Gets the map point's coordinate.
+ *
+ * @details This function returns the coordinates of the given point in the map.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to query point
+ * @param[in] idx The index of point to query \n
+ * This must be smaller than the map size.
+ * @param[out] x The X coordinate
+ * @param[out] y The Y coordinate
+ * @param[out] z The Z coordinate
+ */
+EAPI void evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
+
+/**
+ * @brief Changes the map point's U and V texture source point.
+ *
+ * @details This sets the U and V coordinates for the point. This determines which
+ * coordinate in the source image is mapped to the given point, much like
+ * OpenGL and textures. Note that these points do select the pixel, but
+ * are double floating point values to allow for accuracy and sub-pixel selection.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to change the point of
+ * @param[in] idx The index of point to change \n
+ * This must be smaller than map size.
+ * @param[in] u The X coordinate within the image or texture source
+ * @param[in] v The Y coordinate within the image or texture source
+ *
+ * @see evas_map_point_coord_set()
+ * @see evas_object_map_set()
+ * @see evas_map_util_points_populate_from_object_full()
+ * @see evas_map_util_points_populate_from_object()
+ */
+EAPI void evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v);
+
+/**
+ * @brief Gets the map point's U and V texture source points.
+ *
+ * @details This function returns the texture points set by evas_map_point_image_uv_set().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to query point
+ * @param[in] idx The index of point to query \n
+ * This must be smaller than map size.
+ * @param[out] u The X coordinate within the image or texture source
+ * @param[out] v The Y coordinate within the image or texture source
+ */
+EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v);
+
+/**
+ * @brief Sets the color of a vertex in the map.
+ *
+ * @details This sets the color of the vertex in the map. Colors are linearly
+ * interpolated between vertex points through the map. Color multiplies
+ * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
+ * a vertex in a map is white solid (255, 255, 255, 255) which means it
+ * has no affect on modifying the texture pixels.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to change the color of
+ * @param[in] idx The index of point to change \n
+ * This must be smaller than the map size.
+ * @param[in] r The red color (0 - 255)
+ * @param[in] g The green color (0 - 255)
+ * @param[in] b The blue color (0 - 255)
+ * @param[in] a The alpha color (0 - 255)
+ *
+ * @see evas_map_util_points_color_set()
+ * @see evas_map_point_coord_set()
+ * @see evas_object_map_set()
+ */
+EAPI void evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a);
+
+/**
+ * @brief Gets the color set on a vertex in the map.
+ *
+ * @details This function gets the color set by evas_map_point_color_set() on the given vertex
+ * of the map.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] m The map to get the color of the vertex from
+ * @param[in] idx The index of point get \n
+ * This must be smaller than the map size.
+ * @param[out] r The pointer to red color
+ * @param[out] g The pointer to green color
+ * @param[out] b The pointer to blue color
+ * @param[out] a The pointer to alpha color (0 - 255)
+ *
+ * @see evas_map_point_coord_set()
+ * @see evas_object_map_set()
+ */
+EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Group_Size_Hints Size Hints
+ * @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions for size hints.
+ *
+ * Objects may carry hints, so that another object that acts as a
+ * manager (see @ref Evas_Smart_Object_Group) may know how to properly
+ * position and resize its subordinate objects. The Size Hints provide
+ * a common interface that is recommended as the protocol for such
+ * information.
+ *
+ * For example, box objects use alignment hints to align its
+ * lines or columns inside its container, padding hints to set the
+ * padding between each individual child, and so on.
+ *
+ * @{
+ */
+
+/**
+ * @brief Gets the hints for an object's minimum size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks These are hints on the minimim sizes @a obj should have. This is
+ * not a size enforcement in any way. It is just a hint that should be
+ * used whenever appropriate.
+ *
+ * @remarks Use @c NULL pointers on the hint components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[out] w The pointer to an integer in which to store the minimum width
+ * @param[out] h The pointer to an integer in which to store the minimum height
+ *
+ * @see evas_object_size_hint_min_set() for an example
+ */
+EAPI void evas_object_size_hint_min_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the hints for an object's minimum size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks Values like @c 0 are treated as unset hint components, when queried
+ * by managers.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[in] w The integer to use as the minimum width hint
+ * @param[in] h The integer to use as the minimum height hint
+ *
+ * @see evas_object_size_hint_min_get()
+ */
+EAPI void evas_object_size_hint_min_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the hints for an object's maximum size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks These are hints on the maximum sizes @a obj should have. This is
+ * not a size enforcement in any way. It is just a hint that should be
+ * used whenever appropriate.
+ *
+ * @remarks Use @c NULL pointers on the hint components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[out] w The pointer to an integer in which to store the maximum width
+ * @param[out] h The pointer to an integer in which to store the maximum height
+ * @see evas_object_size_hint_max_set()
+ */
+EAPI void evas_object_size_hint_max_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the hints for an object's maximum size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks Values like @c -1 are treated as unset hint components, when queried
+ * by managers.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[in] w The integer to use as the maximum width hint
+ * @param[in] h The integer to use as the maximum height hint
+ * @see evas_object_size_hint_max_get()
+ */
+EAPI void evas_object_size_hint_max_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the hints for an object's display mode.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks These are hints on the display mode @a obj. This is
+ * not a size enforcement in any way. It is just a hint that can be
+ * used whenever appropriate. This mode can be used with object's display
+ * mode like compress or expand.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @return The display mode hints
+ *
+ * @see evas_object_size_hint_display_mode_set()
+ */
+EAPI Evas_Display_Mode evas_object_size_hint_display_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the hints for an object's display mode.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * can be used whenever appropriate.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[in] dispmode The display mode hint
+ *
+ * @see evas_object_size_hint_display_mode_get()
+ */
+EAPI void evas_object_size_hint_display_mode_set(Evas_Object *obj, Evas_Display_Mode dispmode) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Gets the hints for an object's optimum size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks These are hints on the optimum sizes @a obj should have. This is
+ * not a size enforcement in any way. It is just a hint that should be
+ * used whenever appropriate.
+ *
+ * @remarks Use @c NULL pointers on the hint components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[out] w The pointer to an integer in which to store the requested width
+ * @param[out] h The pointer to an integer in which to store the requested height
+ *
+ * @see evas_object_size_hint_request_set()
+ */
+EAPI void evas_object_size_hint_request_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Sets the hints for an object's optimum size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks Values like @c 0 are treated as unset hint components, when queried
+ * by managers.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[in] w The integer to use as the preferred width hint
+ * @param[in] h The integer to use as the preferred height hint
+ *
+ * @see evas_object_size_hint_request_get()
+ */
+EAPI void evas_object_size_hint_request_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the hints for an object's aspect ratio.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The different aspect ratio policies are documented in the
+ * #Evas_Aspect_Control type. A container respecting these size hints
+ * would @b resize its children accordingly to those policies.
+ *
+ * @remarks For any policy, if any of the given aspect ratio terms are @c 0,
+ * the object's container should ignore the aspect and scale @a obj to
+ * occupy the whole available area. If they are both positive
+ * integers, that proportion is respected, under each scaling policy.
+ *
+ * @remarks These images illustrate some of the #Evas_Aspect_Control policies:
+ *
+ * @image html any-policy.png
+ * @image rtf any-policy.png
+ * @image latex any-policy.eps
+ *
+ * @image html aspect-control-none-neither.png
+ * @image rtf aspect-control-none-neither.png
+ * @image latex aspect-control-none-neither.eps
+ *
+ * @image html aspect-control-both.png
+ * @image rtf aspect-control-both.png
+ * @image latex aspect-control-both.eps
+ *
+ * @image html aspect-control-horizontal.png
+ * @image rtf aspect-control-horizontal.png
+ * @image latex aspect-control-horizontal.eps
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks Use @c NULL pointers on the hint components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[out] aspect The policy or type of aspect ratio applied to @a obj that is returned
+ * @param[out] w The pointer to an integer in which to store the aspect's width
+ * ratio term
+ * @param[out] h The pointer to an integer in which to store the aspect's
+ * height ratio term
+ *
+ * @see evas_object_size_hint_aspect_set()
+ */
+EAPI void evas_object_size_hint_aspect_get(const Evas_Object *obj, Evas_Aspect_Control *aspect, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the hints for an object's aspect ratio.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that should
+ * be used whenever appropriate.
+ *
+ * @remarks If any of the given aspect ratio terms are @c 0,
+ * the object's container ignores the aspect and scale @a obj to
+ * occupy the whole available area, for any given policy.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[in] aspect The policy or type of aspect ratio to apply to @a obj
+ * @param[in] w The integer to use as aspect width ratio term
+ * @param[in] h The integer to use as aspect height ratio term
+ *
+ * @see evas_object_size_hint_aspect_get() for more information.
+ */
+EAPI void evas_object_size_hint_aspect_set(Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the hints for the object's alignment.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks Use @c NULL pointers on the hint components that you are not
+ * interested in: they are ignored by the function.
+ * @remarks If @c obj is invalid, then the hint components are set with @c 0.5
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[out] x The pointer to a double in which to store the horizontal alignment hint
+ * @param[out] y The pointer to a double in which to store the vertical alignment hint
+ *
+ * @see evas_object_size_hint_align_set() for more information
+ */
+EAPI void evas_object_size_hint_align_get(const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the hints for an object's alignment.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks These are hints on how to align an object <b>inside the boundaries
+ * of a container/manager</b>. Accepted values are in the @c 0.0 to @c
+ * 1.0 range, with the special value #EVAS_HINT_FILL used to specify
+ * "justify" or "fill" by some users. In this case, maximum size hints
+ * should be enforced with higher priority, if they are set. Also, any
+ * padding hint set on objects should add up to the alignment space on
+ * the final scene composition.
+ *
+ * @remarks See documentation of possible users: in Evas, they are the @ref
+ * Evas_Object_Box "box" and @ref Evas_Object_Table "table" smart objects.
+ *
+ * @remarks For the horizontal component, @c 0.0 means to the left, @c 1.0
+ * means to the right. Analogously, for the vertical component, @c 0.0
+ * to the top, @c 1.0 means to the bottom.
+ *
+ * @remarks See the following figure:
+ *
+ * @image html alignment-hints.png
+ * @image rtf alignment-hints.png
+ * @image latex alignment-hints.eps
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks The default alignment hint values are @c 0.5, for both axis.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[in] x The horizontal alignment hint as double value ranging from @c 0.0 to @c 1.0 or with the
+ * special value #EVAS_HINT_FILL
+ * @param[in] y The vertical alignment hint as double value ranging from @c 0.0 to @c 1.0 or with the
+ * special value #EVAS_HINT_FILL
+ *
+ * @see evas_object_size_hint_align_get()
+ * @see evas_object_size_hint_max_set()
+ * @see evas_object_size_hint_padding_set()
+ */
+EAPI void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the hints for an object's weight.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Accepted values are @c 0 or positive values. Some users might use
+ * this hint as a boolean, but some might consider it as a @b
+ * proportion. See documentation of possible users, which in Evas are
+ * the @ref Evas_Object_Box "box" and @ref Evas_Object_Table "table"
+ * smart objects.
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks Use @c NULL pointers on the hint components that you are not
+ * interested in: they are ignored by the function.
+ * @remarks If @c obj is invalid, then the hint components are set with @c 0.0
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[out] x The pointer to a double in which to store the horizontal weight
+ * @param[out] y The pointer to a double in which to store the vertical weight
+ *
+ * @see evas_object_size_hint_weight_set() for an example
+ */
+EAPI void evas_object_size_hint_weight_get(const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the hints for an object's weight.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks This is a hint on how a container object should @b resize a given
+ * child within its area. Containers may adhere to the simpler logic
+ * of just expanding the child object's dimensions to fit its own (see
+ * the #EVAS_HINT_EXPAND helper weight macro) or the complete one of
+ * taking each child's weight hint as real @b weights to how much of
+ * its size to allocate for them in each axis. A container is supposed
+ * to, after @b normalizing the weights of its children (with weight
+ * hints), distribute the space it has to layout them by those factors
+ * -- most weighted children get larger in this process than the least ones.
+ *
+ * @remarks Default weight hint values are @c 0.0, for both axis.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[in] x The non-negative double value to use as horizontal weight hint
+ * @param[in] y The non-negative double value to use as vertical weight hint
+ *
+ * @see evas_object_size_hint_weight_get() for more information
+ */
+EAPI void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the hints for an object's padding space.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Padding is extra space that an object takes on each of its delimiting
+ * rectangle sides, in canvas units. This space is rendered
+ * transparent, naturally, as in the following figure:
+ *
+ * @image html padding-hints.png
+ * @image rtf padding-hints.png
+ * @image latex padding-hints.eps
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @remarks Use @c NULL pointers on the hint components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[out] l The pointer to an integer in which to store left padding
+ * @param[out] r The pointer to an integer in which to store right padding
+ * @param[out] t The pointer to an integer in which to store top padding
+ * @param[out] b The pointer to an integer in which to store bottom padding
+ *
+ * @see evas_object_size_hint_padding_set()
+ */
+EAPI void evas_object_size_hint_padding_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the hints for an object's padding space.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is not a size enforcement in any way. It is just a hint that
+ * should be used whenever appropriate.
+ *
+ * @param[in] obj The given Evas object to query hints from
+ * @param[in] l The integer to specify left padding
+ * @param[in] r The integer to specify right padding
+ * @param[in] t The integer to specify top padding
+ * @param[in] b The integer to specify bottom padding
+ *
+ * @see evas_object_size_hint_padding_get() for more information
+ */
+EAPI void evas_object_size_hint_padding_set(Evas_Object *obj, Evas_Coord l, Evas_Coord r, Evas_Coord t, Evas_Coord b) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Group_Extras Extra Object Manipulation
+ * @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions for extra object manipulation.
+ *
+ * Miscellaneous functions that also apply to any object, but are less
+ * used or not implemented by all objects.
+ *
+ * @{
+ */
+
+/**
+ * @brief Sets an attached data pointer to an object with a given string key.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This attaches the pointer @a data to the object @a obj, given the
+ * access string @a key. This pointer stays "hooked" to the object
+ * until a new pointer with the same string key is attached with
+ * evas_object_data_set() or it is deleted with
+ * evas_object_data_del(). On deletion of the object @a obj, the
+ * pointers is not accessible from the object anymore.
+ *
+ * @remarks You can find the pointer attached under a string key using
+ * evas_object_data_get(). It is the job of the calling application to
+ * free any data pointed to by @a data when it is no longer required.
+ *
+ * @remarks If @a data is @c NULL, the old value stored at @a key is
+ * removed but no new value is stored. This is synonymous with
+ * calling evas_object_data_del() with @a obj and @a key.
+ *
+ * @remarks This function is very handy when you have data associated
+ * specifically to an Evas object, being of use only when dealing with
+ * it. You do not have the burden to a pointer to it elsewhere,
+ * using this family of functions.
+ *
+ * @remarks The following is an example:
+ *
+ * @code
+ * int *my_data;
+ * extern Evas_Object *obj;
+ *
+ * my_data = malloc(500);
+ * evas_object_data_set(obj, "name_of_data", my_data);
+ * printf("The data that is attached is %p\n", evas_object_data_get(obj, "name_of_data"));
+ * @endcode
+ *
+ * @param[in] obj The object to attach the data pointer to
+ * @param[in] key The string key for the data to access it
+ * @param[in] data The pointer to the data to be attached
+ *
+ */
+EAPI void evas_object_data_set(Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets an attached data pointer on an Evas object by its given
+ * string key.
+ *
+ * @details This function returns the data pointer attached to the object
+ * @a obj, stored using the string key @a key. If the object is valid
+ * and a data pointer is stored under the given key, that pointer
+ * is returned. If this is not the case, @c NULL is
+ * returned, signifying an invalid object or a non-existent key. It is
+ * possible that a @c NULL pointer is stored given that key, but this
+ * situation is not probable and thus can be considered an error as
+ * well. @c NULL pointers are never stored as this is the return value
+ * if an error occurs.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ *
+ * @code
+ * int *my_data;
+ * extern Evas_Object *obj;
+ *
+ * my_data = evas_object_data_get(obj, "name_of_my_data");
+ * if (my_data) printf("Data stored is %p\n", my_data);
+ * else printf("No data is stored on the object\n");
+ * @endcode
+ *
+ * @param[in] obj The object to which the data is attached
+ * @param[in] key The string key the data is stored under
+ * @return The data pointer stored,
+ * otherwise @c NULL if none are stored
+ */
+EAPI void *evas_object_data_get(const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Deletes an attached data pointer from an object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This removes the stored data pointer from @a obj stored under
+ * @a key and return this same pointer, if actually there is data
+ * there, or @c NULL, if nothing is stored under that key.
+ *
+ * @remarks The following is an example:
+ *
+ * @code
+ * int *my_data;
+ * extern Evas_Object *obj;
+ *
+ * my_data = evas_object_data_del(obj, "name_of_my_data");
+ * @endcode
+ *
+ * @param[in] obj The object to delete the data pointer from
+ * @param[in] key The string key the data is stored under
+ * @return The original data pointer stored at @a key on @a obj
+ */
+EAPI void *evas_object_data_del(Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the pointer behavior.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function has direct effect on event callbacks related to mouse.
+ *
+ * @remarks If @a setting is @c EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse
+ * is down at this object, events are restricted to it as source,
+ * mouse moves, for example, are emitted even if outside this
+ * object area.
+ *
+ * @remarks If @a setting is @c EVAS_OBJECT_POINTER_MODE_NOGRAB, then events are
+ * emitted just when inside this object area.
+ *
+ * @remarks The default value is @c EVAS_OBJECT_POINTER_MODE_AUTOGRAB.
+ *
+ * @param[in] obj The pointer for which behavior is set
+ * @param[in] setting The desired behavior
+ *
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI void evas_object_pointer_mode_set(Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets how the pointer behaves.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The pointer
+ * @return The pointer behavior
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets whether the given Evas object is to be drawn anti-aliased.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object
+ * @param[in] antialias Set #EINA_TRUE for the object to be anti-aliased, \n
+ * otherwise #EINA_FALSE for it not to be anti-aliased
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI void evas_object_anti_alias_set(Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the given Evas object is to be drawn anti-aliased.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object
+ * @return #EINA_TRUE if the object is to be anti-aliased,
+ * otherwise #EINA_FALSE if it is not to be anti-aliased
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI Eina_Bool evas_object_anti_alias_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the scaling factor for an Evas object. \n
+ * Does not affect all objects.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This multiplies the object's dimension by the given factor, thus
+ * altering its geometry (width and height). This is useful when you want
+ * scalable UI elements, possibly at run time.
+ *
+ * @remarks Only text and textblock objects have scaling change
+ * handlers. Other objects do not change visually on this call.
+ *
+ * @param[in] obj The given Evas object
+ * @param[in] scale The scaling factor \n
+ * <c>1.0</c> means no scaling, default size.
+ *
+ * @see evas_object_scale_get()
+ *
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI void evas_object_scale_set(Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the scaling factor for the given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object
+ * @return The scaling factor
+ *
+ * @ingroup Evas_Object_Group_Extras
+ *
+ * @see evas_object_scale_set()
+ */
+EAPI double evas_object_scale_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the render_op to be used for rendering the Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object
+ * @param[in] op An Evas_Render_Op value
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI void evas_object_render_op_set(Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the current value of the operation used for rendering the Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas object
+ * @return An enumerated value in Evas_Render_Op
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI Evas_Render_Op evas_object_render_op_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets whether to use precise (usually expensive) point collision
+ * detection for a given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use this function to make Evas treat objects' transparent areas as
+ * @b not belonging to it with regard to mouse pointer events. By
+ * default, all of the object's boundary rectangle is taken into
+ * account for them.
+ *
+ * @remarks By using precise point collision detection you are
+ * making Evas more resource intensive.
+ *
+ * @param[in] obj The given object
+ * @param[in] precise Set #EINA_TRUE to use precise point collision detection, \n
+ * otherwise set #EINA_FALSE to not use it \n
+ * The default value is #EINA_FALSE.
+ *
+ * @see evas_object_precise_is_inside_get()
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether an object is set to use precise point collision detection.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given object
+ * @return #EINA_TRUE if @a obj is set to use precise point collision detection, \n
+ * otherwise #EINA_FALSE if it is not set to use \n
+ * The default value is #EINA_FALSE.
+ *
+ * @see evas_object_precise_is_inside_set() for an example
+ *
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets a hint flag on the given Evas object that it is used as a "static clipper".
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a hint to Evas that this object is used as a big static
+ * clipper and should not be moved with children and otherwise
+ * considered specially. The default value for new objects is #EINA_FALSE.
+ *
+ * @param[in] obj The given object
+ * @param[in] is_static_clip Set #EINA_TRUE if it is to be used as a static clipper, \n
+ * otherwise set #EINA_FALSE
+ *
+ * @see evas_object_static_clip_get()
+ *
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI void evas_object_static_clip_set(Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the "static clipper" hint flag for a given Evas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given object
+ * @return #EINA_TRUE if it is set as a static clipper, \n
+ * otheriwse #EINA_FALSE
+ *
+ * @see evas_object_static_clip_set() for more details
+ *
+ * @ingroup Evas_Object_Group_Extras
+ */
+EAPI Eina_Bool evas_object_static_clip_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Object_Group_Find Finding Objects
+ * @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions for finding objects.
+ * Functions that allows finding objects by their position, name or
+ * other properties.
+ *
+ * @{
+ */
+
+/**
+ * @brief Gets the object that currently has focus.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Evas can have (at most) one of its objects focused at a time.
+ * Focused objects are the ones having <b>key events</b> delivered
+ * to, which the programmer can act upon by means of
+ * evas_object_event_callback_add() usage.
+ *
+ * @remarks Mostly you would not be dealing directly with Evas focused
+ * objects. Instead, you would be using a higher level library for
+ * that (like a toolkit, as Elementary) to handle focus and who is
+ * receiving input for them.
+ *
+ * @remarks This call returns the object that currently has focus on the canvas
+ * @a e or @c NULL, if none.
+ *
+ * @param[in] e The Evas canvas to query for focused object
+ * @return The object that has focus, \n
+ * otherwise @c NULL if there is no object that has focus
+ *
+ * @see evas_object_focus_set
+ * @see evas_object_focus_get
+ * @see evas_object_key_grab
+ * @see evas_object_key_ungrab
+ * @ingroup Evas_Object_Group_Find
+ */
+EAPI Evas_Object *evas_focus_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the object on the given evas with the given name.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This looks for the evas object given a name by evas_object_name_set(). If
+ * the name is not unique canvas-wide, then which one of the many objects
+ * with that name is returned is undefined. So only use this if you can ensure
+ * the object name is unique.
+ *
+ * @param[in] e The given evas
+ * @param[in] name The given name
+ * @return The Evas object with the given name, \n
+ * otherwise @c NULL on failure
+ *
+ * @ingroup Evas_Object_Group_Find
+ */
+EAPI Evas_Object *evas_object_name_find(const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the object from children of the given object with the given name.
+ *
+ * @details This function looks for the evas object, which has its name set using evas_object_name_set(), but
+ * it ONLY looks at the children of the object @a obj, and only recurse
+ * into those children if @a recurse is greater than @c 0. If the name is not
+ * unique within immediate children (or the whole child tree) then it is not
+ * defined which child object is returned. If @a recurse is set to @c -1 then
+ * it recurses without limit.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The parent (smart) object whose children to search
+ * @param[in] name The given name
+ * @param[in] recurse Set to the number of child levels to recurse \n
+ * (0 == do not recurse, \n
+ * 1 == only look at the children of @a obj or their immediate children and no further etc.).
+ * @return The Evas object with the given name, \n
+ * otherwise @c NULL on failure
+ *
+ * @ingroup Evas_Object_Group_Find
+ */
+EAPI Evas_Object *evas_object_name_child_find(const Evas_Object *obj, const char *name, int recurse) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the Evas object stacked at the top of a given position in a canvas.
+ *
+ * @details This function traverses all the layers of the given canvas,
+ * from top to bottom, querying for objects with areas covering the
+ * given position. The user can remove from the query
+ * objects which are hidden and/or which are set to pass events.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function @b skips objects parented by smart
+ * objects, acting only on the ones at the "top level", with regard to
+ * object parenting.
+ *
+ * @param[in] e A handle to the canvas
+ * @param[in] x The horizontal coordinate of the position
+ * @param[in] y The vertical coordinate of the position
+ * @param[in] include_pass_events_objects Set #EINA_TRUE to include objects which pass events in this calculation, \n
+ * otherwise set #EINA_FALSE to not include the objects
+ * @param[in] include_hidden_objects Set #EINA_TRUE to include hidden objects in this calculation, \n
+ * otherwise set #EINA_FALSE to not include hidden objects
+ * @return The Evas object that is over all other objects at the given position
+ */
+EAPI Evas_Object *evas_object_top_at_xy_get(const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the Evas object stacked at the top at the position of the
+ * mouse cursor, over a given canvas.
+ *
+ * @details This function traverses all the layers of the given canvas,
+ * from top to bottom, querying for objects with areas covering the
+ * mouse pointer's position, over @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function @b skips objects parented by smart
+ * objects, acting only on the ones at the "top level", with regard to
+ * object parenting.
+ *
+ * @param[in] e A handle to the canvas
+ * @return The Evas object that is over all other objects at the mouse pointer's position
+ */
+EAPI Evas_Object *evas_object_top_at_pointer_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the Evas object stacked at the top of a given rectangular
+ * region in a canvas.
+ *
+ * @details This function traverses all the layers of the given canvas,
+ * from top to bottom, querying for objects with areas overlapping
+ * with the given rectangular region inside @a e. The user can remove
+ * from the query objects which are hidden and/or which are set to
+ * pass events.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function @b skips objects parented by smart
+ * objects, acting only on the ones at the "top level", with regard to
+ * object parenting.
+ *
+ * @param[in] e A handle to the canvas
+ * @param[in] x The top left corner's horizontal coordinate for the
+ * rectangular region
+ * @param[in] y The top left corner's vertical coordinate for the
+ * rectangular region
+ * @param[in] w The width of the rectangular region
+ * @param[in] h The height of the rectangular region
+ * @param[in] include_pass_events_objects Set #EINA_TRUE to include objects which pass events in this calculation, \n
+ * otherwise #EINA_FALSE to not include the objects
+ * @param[in] include_hidden_objects Set #EINA_TRUE to include hidden objects in this calculation, \n
+ * otherwise #EINA_FALSE to not include the hidden objects
+ * @return The Evas object that is over all other objects at the given rectangular region
+ */
+EAPI Evas_Object *evas_object_top_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets a list of Evas objects lying over a given position in a canvas.
+ *
+ * @details This function traverses all the layers of the given canvas,
+ * from top to bottom, querying for objects with areas covering the
+ * given position. The user can remove from query
+ * objects which are hidden and/or which are set to pass events.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function @b skips objects parented by smart
+ * objects, acting only on the ones at the "top level", with regard to
+ * object parenting.
+ *
+ * @param[in] e A handle to the canvas
+ * @param[in] x The horizontal coordinate of the position
+ * @param[in] y The vertical coordinate of the position
+ * @param[in] include_pass_events_objects Set #EINA_TRUE to include objects which pass events in this calculation, \n
+ * otherwise set #EINA_FALSE to not include the objects
+ * @param[in] include_hidden_objects Set #EINA_TRUE to include hidden objects in this calculation, \n
+ * otherwise set #EINA_FALSE to not include the hidden objects
+ * @return The list of Evas objects that are over the given position in @a e
+ */
+EAPI Eina_List *evas_objects_at_xy_get(const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+EAPI Eina_List *evas_objects_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the lowest (stacked) Evas object on the canvas @a e.
+ *
+ * @details This function takes all populated layers in the canvas into
+ * account, getting the lowest object for the lowest layer, naturally.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function @b skips objects parented by smart
+ * objects, acting only on the ones at the "top level", with regard to
+ * object parenting.
+ *
+ * @param[in] e A valid canvas pointer
+ * @return A pointer to the lowest object on it, if any, \n
+ * otherwise @c NULL if the pointer is not obtained
+ *
+ * @see evas_object_layer_get()
+ * @see evas_object_layer_set()
+ * @see evas_object_below_get()
+ * @see evas_object_above_get()
+ */
+EAPI Evas_Object *evas_object_bottom_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the highest (stacked) Evas object on the canvas @a e.
+ *
+ * @details This function takes all populated layers in the canvas into
+ * account, getting the highest object for the highest layer, naturally.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function @b skips objects parented by smart
+ * objects, acting only on the ones at the "top level", with regard to
+ * object parenting.
+ *
+ * @param[in] e A valid canvas pointer
+ * @return A pointer to the highest object on it, if any, \n
+ * otherwise @c NULL if the pointer is not obtained
+ *
+ * @see evas_object_layer_get()
+ * @see evas_object_layer_set()
+ * @see evas_object_below_get()
+ * @see evas_object_above_get()
+ */
+EAPI Evas_Object *evas_object_top_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
+ * @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions for method interceptors.
+ *
+ * Evas provides a way to intercept method calls. The interceptor
+ * callback may opt to completely deny the call, or may check and
+ * change the parameters before continuing. The continuation of an
+ * intercepted call is done by calling the intercepted call again,
+ * from inside the interceptor callback.
+ *
+ * @{
+ */
+
+typedef void (*Evas_Object_Intercept_Show_Cb)(void *data, Evas_Object *obj);
+typedef void (*Evas_Object_Intercept_Hide_Cb)(void *data, Evas_Object *obj);
+typedef void (*Evas_Object_Intercept_Move_Cb)(void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
+typedef void (*Evas_Object_Intercept_Resize_Cb)(void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
+typedef void (*Evas_Object_Intercept_Raise_Cb)(void *data, Evas_Object *obj);
+typedef void (*Evas_Object_Intercept_Lower_Cb)(void *data, Evas_Object *obj);
+typedef void (*Evas_Object_Intercept_Stack_Above_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
+typedef void (*Evas_Object_Intercept_Stack_Below_Cb)(void *data, Evas_Object *obj, Evas_Object *above);
+typedef void (*Evas_Object_Intercept_Layer_Set_Cb)(void *data, Evas_Object *obj, int l);
+typedef void (*Evas_Object_Intercept_Color_Set_Cb)(void *data, Evas_Object *obj, int r, int g, int b, int a);
+typedef void (*Evas_Object_Intercept_Clip_Set_Cb)(void *data, Evas_Object *obj, Evas_Object *clip);
+typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj);
+
+/**
+ * @brief Sets the callback function that intercepts a show event of an object.
+ *
+ * @details This function sets a callback function to intercepts a show event
+ * of a canvas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas object pointer
+ * @param[in] func The given function to be the callback function
+ * @param[in] data The data passed to the callback function
+ *
+ * @see evas_object_intercept_show_callback_del().
+ *
+ */
+EAPI void evas_object_intercept_show_callback_add(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Unsets the callback function that intercepts a show event of a object.
+ *
+ * @details This function sets a callback function to intercept a show event
+ * of a canvas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas object pointer
+ * @param[in] func The given callback function
+ *
+ * @see evas_object_intercept_show_callback_add().
+ *
+ */
+EAPI void *evas_object_intercept_show_callback_del(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the callback function that intercepts a hide event of a object.
+ *
+ * @details This function sets a callback function to intercepts a hide event
+ * of a canvas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas object pointer
+ * @param[in] func The given function to be the callback function
+ * @param[in] data The data passed to the callback function
+ *
+ * @see evas_object_intercept_hide_callback_del().
+ *
+ */
+EAPI void evas_object_intercept_hide_callback_add(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Unsets the callback function that intercepts a hide event of a object.
+ *
+ * @details This function sets a callback function to intercepts a hide event
+ * of a canvas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas object pointer
+ * @param[in] func The given callback function
+ *
+ * @see evas_object_intercept_hide_callback_add().
+ *
+ */
+EAPI void *evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the callback function that intercepts a move event of a object.
+ *
+ * @details This function sets a callback function to intercepts a move event
+ * of a canvas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas object pointer
+ * @param[in] func The given function to be the callback function
+ * @param[in] data The data passed to the callback function
+ *
+ * @see evas_object_intercept_move_callback_del().
+ *
+ */
+EAPI void evas_object_intercept_move_callback_add(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Unsets the callback function that intercepts a move event of a object.
+ *
+ * @details This function sets a callback function to intercept a move event
+ * of a canvas object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas object pointer
+ * @param[in] func The given callback function
+ *
+ * @see evas_object_intercept_move_callback_add().
+ *
+ */
+EAPI void *evas_object_intercept_move_callback_del(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2);
+
+EAPI void evas_object_intercept_resize_callback_add(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_resize_callback_del(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2);
+EAPI void evas_object_intercept_raise_callback_add(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_raise_callback_del(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2);
+EAPI void evas_object_intercept_lower_callback_add(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_lower_callback_del(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2);
+EAPI void evas_object_intercept_stack_above_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_stack_above_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2);
+EAPI void evas_object_intercept_stack_below_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_stack_below_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2);
+EAPI void evas_object_intercept_layer_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_layer_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2);
+EAPI void evas_object_intercept_color_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_color_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2);
+EAPI void evas_object_intercept_clip_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_clip_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2);
+EAPI void evas_object_intercept_clip_unset_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
+EAPI void *evas_object_intercept_clip_unset_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Specific Specific Object Functions
+ * @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions that work on specific objects.
+ *
+ */
+
+/**
+ * @defgroup Evas_Object_Rectangle Rectangle Object Functions
+ * @ingroup Evas_Object_Specific
+ *
+ * @brief Function to create evas rectangle objects.
+ *
+ * There is only one function to deal with rectangle objects, this may make this
+ * function seem useless given there are no functions to manipulate the created
+ * rectangle, however the rectangle is actually very useful and should be
+ * manipulated using the generic @ref Evas_Object_Group "evas object functions".
+ *
+ * The evas rectangle serves a number of key functions when working on evas
+ * programs:
+ * @li Background
+ * @li Debugging
+ * @li Clipper
+ *
+ * @section Background
+ *
+ * One extremely common requirement of evas programs is to have a solid color
+ * background. This can be accomplished with the following very simple code:
+ * @code
+ * Evas_Object *bg = evas_object_rectangle_add(evas_canvas);
+ * //Here we set the rectangles red, green, blue and opacity levels
+ * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
+ * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
+ * evas_object_show(bg);
+ * @endcode
+ *
+ * This however has issues if the @c evas_canvas is resized. However most
+ * windows are created using ecore evas and that has a solution to using the
+ * rectangle as a background:
+ * @code
+ * Evas_Object *bg = evas_object_rectangle_add(ecore_evas_get(ee));
+ * //Here we set the rectangles red, green, blue and opacity levels
+ * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
+ * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
+ * evas_object_show(bg);
+ * ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE);
+ * @endcode
+ * So this gives us a white background to our window that is resized
+ * together with it.
+ *
+ * @section Debugging
+ *
+ * Debugging is a major part of any programmers task and when debugging visual
+ * issues with evas programs the rectangle is an extremely useful tool. The
+ * rectangle's simplicity means that it is easier to pinpoint issues with it than
+ * with more complex objects. Therefore a common technique to use when writing
+ * an evas program and not getting the desired visual result is to replace the
+ * misbehaving object for a solid color rectangle and seeing how it interacts
+ * with the other elements, this often allows us to notice clipping, parenting
+ * or positioning issues. Once the issues have been identified and corrected the
+ * rectangle can be replaced for the original part and in all likelihood any
+ * remaining issues are specific to that object's type.
+ *
+ * @section clipping Clipping
+ *
+ * Clipping serves two main functions:
+ * @li Limiting visibility (i.e. hiding portions of an object).
+ * @li Applying a layer of color to an object.
+ *
+ * @subsection hiding Limiting visibility
+ *
+ * It is often necessary to show only parts of an object, while it may be
+ * possible to create an object that corresponds only to the part that must be
+ * shown (and it is not always possible), it is usually easier to use a clipper. A
+ * clipper is a rectangle that defines what is visible and what is not. The way
+ * to do this is to create a solid white rectangle (which is the default, no need
+ * to call evas_object_color_set()) and give it a position and size of what
+ * should be visible. The following code exemplifies showing the center half of
+ * @c my_evas_object:
+ * @code
+ * Evas_Object *clipper = evas_object_rectangle_add(evas_canvas);
+ * evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4);
+ * evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2);
+ * evas_object_clip_set(my_evas_object, clipper);
+ * evas_object_show(clipper);
+ * @endcode
+ *
+ * @subsection color Layer of color
+ *
+ * In the @ref clipping section we used a solid white clipper, which produced no
+ * change in the color of the clipped object, it just hid what is outside the
+ * clippers area. It is however sometimes desirable to change the color of an
+ * object, this can be accomplished using a clipper that has a non-white color.
+ * Clippers with color work by multiplying the colors of clipped object. The
+ * following code shows how to remove all the red from an object:
+ * @code
+ * Evas_Object *clipper = evas_object_rectangle_add(evas);
+ * evas_object_move(clipper, my_evas_object_x, my_evas_object_y);
+ * evas_object_resize(clipper, my_evas_object_width, my_evas_object_height);
+ * evas_object_color_set(clipper, 0, 255, 255, 255);
+ * evas_object_clip_set(obj, clipper);
+ * evas_object_show(clipper);
+ * @endcode
+ *
+ * @remarks We do not guarantee any proper results if you create a Rectangle
+ * object without setting the evas engine.
+ *
+ * @{
+ */
+
+/**
+ * @brief Adds a rectangle to the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @return The new rectangle object
+ */
+EAPI Evas_Object *evas_object_rectangle_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Image Image Object Functions
+ * @ingroup Evas_Object_Specific
+ *
+ * @brief This group provides functions for image objects.
+ *
+ * The functions used to create and manipulate image objects
+ * are grouped together. They are available to whichever occasion one needs
+ * complex imagery on a GUI that could not be achieved by the other
+ * Evas' primitive object types, or to make image manipulations.
+ *
+ * Evas supports whichever image file types it is compiled with
+ * support to (its image loaders) -- check your software packager for
+ * that information and see
+ * evas_object_image_extension_can_load_get().
+ *
+ * @section Evas_Object_Image_Basics Image object basics
+ *
+ * The most common use of image objects -- to display an image on the
+ * canvas -- is achieved by a common function triplet:
+ * @code
+ * img = evas_object_image_add(canvas);
+ * evas_object_image_file_set(img, "path/to/img", NULL);
+ * evas_object_image_fill_set(img, 0, 0, w, h);
+ * @endcode
+ * The first function, naturally, is creating the image object. Then,
+ * one must set a source file on it, so that it knows where to fetch
+ * image data from. Next, one must set <b>how to fill the image
+ * object's area</b> with the given pixel data. One could use just a
+ * sub-region of the original image or even have it tiled repeatedly
+ * on the image object. For the common case of having the whole source
+ * image to be displayed on the image object, stretched to the
+ * destination's size, there is also a function helper, to be used
+ * instead of evas_object_image_fill_set():
+ * @code
+ * evas_object_image_filled_set(img, EINA_TRUE);
+ * @endcode
+ * See those functions' documentation for more details.
+ *
+ * @section Evas_Object_Image_Scale Scale and resizing
+ *
+ * Resizing of image objects scales their respective source images
+ * to their areas, if they are set to "fill" the object's area
+ * (evas_object_image_filled_set()). If you want any control on
+ * the aspect ratio of an image for different sizes, you have to
+ * take care of that yourself. There are functions to make images to
+ * get loaded scaled (up or down) in memory, already, if you are
+ * going to use them at pre-determined sizes and want to save
+ * computations.
+ *
+ * Evas has even a scale cache, which takes care of caching scaled
+ * versions of images with most usage/hits. Finally, you can
+ * have images being rescaled @b smoothly by Evas (more
+ * computationally expensive) or not.
+ *
+ * @section Evas_Object_Image_Performance Performance hints
+ *
+ * When dealing with image objects, there are some tricks to boost the
+ * performance of your application, if it does intense image loading
+ * and/or manipulations, as in animations on a UI.
+ *
+ * @subsection Evas_Object_Image_Load Load hints
+ *
+ * In image viewer applications, for example, the user is looking
+ * at a given image, at full size, and desires that the navigation
+ * to the adjacent images on his/her album be fluid and fast. Thus,
+ * while displaying a given image, the program can be on the
+ * background loading the next and previous images already, so that
+ * displaying them on the sequence is just a matter of repainting the
+ * screen (and not decoding image data).
+ *
+ * Evas addresses this issue with <b>image pre-loading</b>. The code
+ * for the situation above would be something like the following:
+ * @code
+ * prev = evas_object_image_filled_add(canvas);
+ * evas_object_image_file_set(prev, "/path/to/prev", NULL);
+ * evas_object_image_preload(prev, EINA_TRUE);
+ *
+ * next = evas_object_image_filled_add(canvas);
+ * evas_object_image_file_set(next, "/path/to/next", NULL);
+ * evas_object_image_preload(next, EINA_TRUE);
+ * @endcode
+ *
+ * If you are loading images which are too big, consider setting
+ * its loading size to something smaller, in case you do not expose
+ * them in real size. It may speed up the loading considerably:
+ * @code
+ * //To load a scaled down version of the image in memory, if that is
+ * //the size you are displaying anyway
+ * evas_object_image_load_scale_down_set(img, zoom);
+ *
+ * //optional: if you know you are going to show a sub-set of the image's
+ * //pixels, you can avoid loading the complementary data
+ * evas_object_image_load_region_set(img, x, y, w, h);
+ * @endcode
+ * Refer to Elementary's Photocam widget for a high level (smart)
+ * object which does lots of loading speed-ups for you.
+ *
+ * @subsection Evas_Object_Image_Animation Animation hints
+ *
+ * If you want to animate image objects on a UI (what you would get by
+ * concomitant usage of other libraries, like Ecore and Edje), there
+ * are also some tips on how to boost the performance of your
+ * application. If the animation involves resizing of an image (thus,
+ * re-scaling), you would better turn off smooth scaling on it @b during
+ * the animation, turning it back on afterwards, for less
+ * computations. Also, in this case you would better flag the image object
+ * in question not to cache scaled versions of it:
+ * @code
+ * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC);
+ *
+ * // Resizing takes place in between
+ *
+ * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC);
+ * @endcode
+ *
+ * Finally, movement of opaque images through the canvas is less
+ * expensive than of translucid ones, because of blending
+ * computations.
+ *
+ * @section Evas_Object_Image_Borders Borders
+ *
+ * Evas provides facilities for one to specify an image's region to be
+ * treated specially -- as "borders". This makes those regions to be
+ * treated specially on resizing scales, by keeping their aspect. This
+ * makes setting frames around other objects on UIs easy.
+ * See the following figures for a visual explanation:\n
+ *
+ * @image html image-borders.png
+ * @htmlonly
+ * <a href="image-borders.png">Full-size</a>
+ * @endhtmlonly
+ * @image rtf image-borders.png
+ * @image latex image-borders.eps "image borders" width=\textwidth
+ *
+ * @image html border-effect.png
+ * @htmlonly
+ * <a href="border-effect.png">Full-size</a>
+ * @endhtmlonly
+ * @image rtf border-effect.png
+ * @image latex border-effect.eps "border effect" width=\textwidth
+ *
+ * @section Evas_Object_Image_Manipulation Manipulating pixels
+ *
+ * Evas image objects can be used to manipulate raw pixels in many
+ * ways. The meaning of the data in the pixel arrays depends on
+ * the image's color space, be warned (see next section). You can set
+ * your own data as an image's pixel data, fetch an image's pixel data
+ * for saving or altering, convert images between different color spaces
+ * and even advanced operations like setting a native surface as image
+ * objects' data.
+ *
+ * @section Evas_Object_Image_Color_Spaces Color spaces
+ *
+ * Image objects may return or accept "image data" in multiple
+ * formats. This is based on the color space of an object. Here is a
+ * rundown on formats:
+ *
+ * - #EVAS_COLORSPACE_ARGB8888:
+ * This pixel format is a linear block of pixels, starting at the
+ * top-left row by row until the bottom right of the image or pixel
+ * region. All pixels are 32-bit unsigned int with the high-byte
+ * being alpha and the low byte being blue in the format ARGB. Alpha
+ * may or may not be used by evas depending on the alpha flag of the
+ * image, but if not used, should be set to 0xff anyway.
+ * \n\n
+ * This colorspace uses premultiplied alpha. That means that R, G
+ * and B cannot exceed A in value. The conversion from
+ * non-premultiplied colorspace is:
+ * \n\n
+ * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
+ * \n\n
+ * So 50% transparent blue is: 0x80000080. This is not
+ * "dark" - just 50% transparent. Values are 0 == black, 255 ==
+ * solid or full red, green or blue.
+ * .
+ * - #EVAS_COLORSPACE_YCBCR422P601_PL:
+ * This is a pointer-list indirected set of YUV (YCbCr) pixel
+ * data. This means that the data returned or set is not actual
+ * pixel data, but pointers TO lines of pixel data. The list of
+ * pointers are first be N rows of pointers to the Y plane -
+ * pointing to the first pixel at the start of each row in the Y
+ * plane. N is the height of the image data in pixels. Each pixel in
+ * the Y, U and V planes is 1 byte exactly, packed. The next N / 2
+ * pointers points to rows in the U plane, and the next N / 2
+ * pointers points to the V plane rows. U and V planes are half
+ * the horizontal and vertical resolution of the Y plane.
+ * \n\n
+ * Row order is top to bottom and row pixels are stored left to
+ * right.
+ * \n\n
+ * There is a limitation that these images MUST be a multiple of 2
+ * pixels in size horizontally or vertically. This is due to the U
+ * and V planes being half resolution. Also note that this assumes
+ * the itu601 YUV colorspace specification. This is defined for
+ * standard television and mpeg streams. HDTV may use the itu709
+ * specification.
+ * \n\n
+ * Values are @c 0 to @c 255, indicating full or no signal in that plane
+ * respectively.
+ * .
+ * - #EVAS_COLORSPACE_YCBCR422P709_PL:
+ * Not implemented yet.
+ * .
+ * - #EVAS_COLORSPACE_RGB565_A5P:
+ * In the process of being implemented in one engine only. This may
+ * change.
+ * \n\n
+ * This is a pointer to image data for 16-bit half-word pixel data
+ * in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue),
+ * with the high-byte containing red and the low byte containing
+ * blue, per pixel. This data is packed row by row from the top-left
+ * to the bottom right.
+ * \n\n
+ * If the image has an alpha channel enabled there is an extra
+ * alpha plane after the color pixel plane. If not, then this data
+ * does not exist and should not be accessed in any way. This plane
+ * is a set of pixels with 1 byte per pixel defining the alpha
+ * values of all pixels in the image from the top-left to the bottom
+ * right of the image, row by row. Even though the values of the
+ * alpha pixels can be @c 0 to @c 255, only values @c 0 through to @c 32 are
+ * used, @c 32 being solid and 0 being transparent.
+ * \n\n
+ * RGB values can be @c 0 to @c 31 for red and blue and @c 0 to @c 63 for green,
+ * with @c 0 being black and @c 31 or @c 63 being full red, green or blue
+ * respectively. This colorspace is also pre-multiplied like
+ * EVAS_COLORSPACE_ARGB8888 so:
+ * \n\n
+ * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
+ * .
+ * - #EVAS_COLORSPACE_GRY8:
+ * The image is just an alpha mask (8 bits per pixel). This is used
+ * for alpha masking.
+ *
+ * @remarks We do not guarantee any proper results if you create an Image object
+ * without setting the evas engine.
+ *
+ * @{
+ */
+
+/**
+ * @brief Callback of Evas Object Image Pixels
+ * @see evas_object_image_pixels_get_callback_set
+ */
+typedef void (*Evas_Object_Image_Pixels_Get_Cb)(void *data, Evas_Object *o);
+
+/**
+ * @brief Creates a new image object on the given Evas @a e canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you intend to @b display an image somehow in a GUI,
+ * besides binding it to a real image file or source (with
+ * evas_object_image_file_set(), for example), you have to tell
+ * this image object how to fill its space with the pixels it can get
+ * from the source. See evas_object_image_filled_add(), for a helper
+ * on the common case of scaling up an image source to the whole area
+ * of the image object.
+ *
+ * @remarks The following is an example:
+ * @code
+ * img = evas_object_image_add(canvas);
+ * evas_object_image_file_set(img, "/path/to/img", NULL);
+ * @endcode
+ *
+ * @param[in] e The given canvas
+ * @return The created image object handle
+ *
+ * @see evas_object_image_fill_set()
+ */
+EAPI Evas_Object *evas_object_image_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Creates a new image object that @b automatically scales its bound
+ * image to the object's area, on both axis.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a helper function around evas_object_image_add() and
+ * evas_object_image_filled_set(). It has the same effect of applying
+ * those functions in sequence, which is a very common use case.
+ *
+ * @remarks Whenever this object gets resized, the bound image is
+ * rescaled, too.
+ *
+ * @param[in] e The given canvas
+ * @return The created image object handle
+ *
+ * @see evas_object_image_add()
+ * @see evas_object_image_filled_set()
+ * @see evas_object_image_fill_set()
+ */
+EAPI Evas_Object *evas_object_image_filled_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Sets the data for an image from memory to be loaded.
+ *
+ * @details This function is the same as evas_object_image_file_set() but the file to be loaded
+ * may exist at an address in memory (the data for the file, not the filename
+ * itself). The @a data at the address is copied and stored for future use, so
+ * no @a data needs to be kept after this call is made. It is managed and
+ * freed for you when no longer needed. The @a size is limited to 2 gigabytes
+ * in size, and must be greater than @c 0. A @c NULL @a data pointer is also
+ * invalid. Set the filename to @c NULL to reset to empty state and have the
+ * image file data freed from memory using evas_object_image_file_set().
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The @a format is optional (pass @c NULL if you do not need/use it). It is
+ * used to help Evas guess better which loader to use for the data. It may
+ * simply be the "extension" of the file as it would normally be on disk
+ * such as "jpg", "png", and "gif".
+ *
+ * @param[in] obj The given image object
+ * @param[in] data The image file data address
+ * @param[in] size The size of the image file data in bytes
+ * @param[in] format The format of the file (optional), \n
+ * otherwise set @c NULL
+ * @param[in] key The image key in file, \n
+ * otherwise set @c NULL
+ */
+EAPI void evas_object_image_memfile_set(Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the source file from where an image object must fetch the real
+ * image data (it may be an Eet file, besides pure image ones).
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the file supports multiple data stored in it (as Eet files do),
+ * you can specify the key to be used as the index of the image in
+ * this file.
+ *
+ * @remarks The following is an example:
+ * @code
+ * img = evas_object_image_add(canvas);
+ * evas_object_image_file_set(img, "/path/to/img", NULL);
+ * err = evas_object_image_load_error_get(img);
+ * if (err != EVAS_LOAD_ERROR_NONE)
+ * {
+ * fprintf(stderr, "could not load image '%s'. error string is \"%s\"\n",
+ * valid_path, evas_load_error_str(err));
+ * }
+ * else
+ * {
+ * evas_object_image_fill_set(img, 0, 0, w, h);
+ * evas_object_resize(img, w, h);
+ * evas_object_show(img);
+ * }
+ * @endcode
+ *
+ * @param[in] obj The given image object
+ * @param[in] file The image file path
+ * @param[in] key The image key in @a file (if its an Eet one), \n
+ * otherwise set @c NULL
+ */
+EAPI void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the source file from where an image object is to fetch the
+ * real image data (it may be an Eet file, besides pure image ones).
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks You must @b not modify the strings on the returned pointers.
+ *
+ * @remarks Use @c NULL pointers on the file components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given image object
+ * @param[out] file The location to store the image file path
+ * @param[out] key The location to store the image key (if @a file is an Eet one)
+ */
+EAPI void evas_object_image_file_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the dimensions for an image object's border, a region which @b
+ * is not scaled together with its center ever.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When Evas is rendering, an image source may be scaled to fit the
+ * size of its image object. This function sets an area from the
+ * borders of the image inwards which is @b not to be scaled. This
+ * function is useful for making frames and for widget theming, where,
+ * for example, buttons may be of varying sizes, but their border size
+ * must remain constant.
+ *
+ * @remarks The units used for @a l, @a r, @a t and @a b are canvas units.
+ *
+ * @remarks The border region itself @b may be scaled by the
+ * evas_object_image_border_scale_set() function.
+ *
+ * @remarks By default, image objects have no borders set, i. e. @c l, @c
+ * r, @c t and @c b start as @c 0.
+ *
+ * @remarks See the following figures for visual explanation:\n
+ *
+ * @image html image-borders.png
+ * @htmlonly
+ * <a href="image-borders.png">Full-size</a>
+ * @endhtmlonly
+ * @image latex image-borders.eps "image borders" width=\textwidth
+ *
+ * @image html border-effect.png
+ * @htmlonly
+ * <a href="border-effect.png">Full-size</a>
+ * @endhtmlonly
+ * @image rtf border-effect.png
+ * @image latex border-effect.eps "border effect" width=\textwidth
+ *
+ * @param[in] obj The given image object
+ * @param[in] l The border's left width
+ * @param[in] r The border's right width
+ * @param[in] t The border's top width
+ * @param[in] b The border's bottom width
+ *
+ * @see evas_object_image_border_get()
+ * @see evas_object_image_border_center_fill_set()
+ */
+EAPI void evas_object_image_border_set(Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the dimensions for an image object's border, a region
+ * which @b is not scaled together with its center ever.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use @c NULL pointers on the border components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given image object
+ * @param[out] l The location to store the border's left width in
+ * @param[out] r The location to store the border's right width in
+ * @param[out] t The location to store the border's top width in
+ * @param[out] b The location to store the border's bottom width in
+ *
+ * @see evas_object_image_border_set() for more details.
+ */
+EAPI void evas_object_image_border_get(const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets @b how the center part of the given image object (not the
+ * borders) should be drawn when Evas is rendering it.
+ *
+ * @details This function sets how the center part of the image object's source
+ * image is to be drawn, which must be one of the values in
+ * #Evas_Border_Fill_Mode. By center we mean the complementary part of
+ * that defined by evas_object_image_border_set(). This one is very
+ * useful for making frames and decorations. You would most probably
+ * also be using a filled image (as in evas_object_image_filled_set())
+ * to use as a frame.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @param[in] fill The fill mode of the center region of @a obj (a value in
+ * #Evas_Border_Fill_Mode)
+ *
+ * @see evas_object_image_border_center_fill_get()
+ */
+EAPI void evas_object_image_border_center_fill_set(Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets @b how the center part of the given image object (not the
+ * borders) is to be drawn when Evas is rendering it.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @return fill The fill mode of the center region of @a obj (a value in
+ * #Evas_Border_Fill_Mode)
+ *
+ * @see evas_object_image_fill_set()
+ */
+EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets whether the image object's fill property should track the
+ * object's size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @a setting is #EINA_TRUE, then every evas_object_resize()
+ * @b automatically triggers a call to evas_object_image_fill_set()
+ * with the that new size (and @c 0, @c 0 as source image's origin),
+ * so the bound image fills the whole object's area.
+ *
+ * @param[in] obj The given image object
+ * @param[in] setting Set #EINA_TRUE to make the fill property follow object size, \n
+ * otherwise set #EINA_FALSE
+ *
+ * @see evas_object_image_filled_add()
+ * @see evas_object_image_fill_get()
+ */
+EAPI void evas_object_image_filled_set(Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the image object's fill property should track the
+ * object's size.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @return #EINA_TRUE if it is tracking, \n
+ * otherwise #EINA_FALSE if it is not tracking (and
+ * evas_object_fill_set() must be called manually)
+ *
+ * @see evas_object_image_filled_set() for more information
+ */
+EAPI Eina_Bool evas_object_image_filled_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the scaling factor (multiplier) for the borders of an image object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @param[in] scale The scale factor (default is @c 1.0 - i.e. no scaling)
+ *
+ * @see evas_object_image_border_set()
+ * @see evas_object_image_border_scale_get()
+ */
+EAPI void evas_object_image_border_scale_set(Evas_Object *obj, double scale);
+
+/**
+ * @brief Gets the scaling factor (multiplier) for the borders of an image object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @return The scale factor set for its borders
+ *
+ * @see evas_object_image_border_set()
+ * @see evas_object_image_border_scale_set()
+ */
+EAPI double evas_object_image_border_scale_get(const Evas_Object *obj);
+
+/**
+ * @brief Sets how to fill an image object's drawing rectangle given the
+ * (real) image bound to it.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Note that if @a w or @a h are smaller than the dimensions of
+ * @a obj, the displayed image is @b tiled around the object's
+ * area. To have only one copy of the bound image drawn, @a x and @a y
+ * must be @c 0 and @a w and @a h need to be the exact width and height
+ * of the image object itself, respectively.
+ *
+ * @remarks See the following image to better understand the effects of this
+ * call. On this diagram, both image object and original image source
+ * have @c a x @c a dimensions and the image itself is a circle, with
+ * empty space around it:
+ *
+ * @image html image-fill.png
+ * @image rtf image-fill.png
+ * @image latex image-fill.eps
+ *
+ * @remarks The default values for the fill parameters are @a x = 0,
+ * @a y = 0, @a w = 0 and @a h = 0. Thus, if you are not using the
+ * evas_object_image_filled_add() helper and want your image
+ * displayed, you have to set valid values with this function on
+ * your object.
+ *
+ * @remarks evas_object_image_filled_set() is a helper function which
+ * @b overrides the values set here automatically, for you, in a
+ * given way.
+ *
+ * @param[in] obj The given image object to operate on
+ * @param[in] x The x coordinate (from the top left corner of the bound
+ * image) to start drawing from
+ * @param[in] y The y coordinate (from the top left corner of the bound
+ * image) to start drawing from
+ * @param[in] w The width the bound image is displayed at
+ * @param[in] h The height the bound image is displayed at
+ */
+EAPI void evas_object_image_fill_set(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets how an image object is to fill its drawing rectangle,
+ * given the (real) image bound to it.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use @c NULL pointers on the fill components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given image object
+ * @param[out] x The location to store the x coordinate (from the top left
+ * corner of the bound image) to start drawing from
+ * @param[out] y The location to store the y coordinate (from the top left
+ * corner of the bound image) to start drawing from
+ * @param[out] w The location to store the width the bound image is to be
+ * displayed at
+ * @param[out] h The location to store the height the bound image is to be
+ * displayed at
+ *
+ * See @ref evas_object_image_fill_set() for more details.
+ */
+EAPI void evas_object_image_fill_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the tiling mode for the given evas image object's fill.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given evas image object
+ * @param[in] spread One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT,
+ * EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.
+ */
+EAPI void evas_object_image_fill_spread_set(Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the spread (tiling mode) for the given image object's fill.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given evas image object
+ * @return The current spread mode of the image object
+ */
+EAPI Evas_Fill_Spread evas_object_image_fill_spread_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the size of the given image object.
+ *
+ * @details This function scales down or crops the image so that it is
+ * treated as if it were at the given size. If the size given is
+ * smaller than the image, it is cropped. If the size given is
+ * larger, then the image is treated as if it were in the upper
+ * left hand corner of a larger image that is otherwise transparent.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @param[in] w The new width of the image
+ * @param[in] h The new height of the image
+ */
+EAPI void evas_object_image_size_set(Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the size of the given image object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @param[out] w The location to store the width of the image in, or @c NULL
+ * @param[out] h The location to store the height of the image in, or @c NULL
+ *
+ * See @ref evas_object_image_size_set() for more details.
+ */
+EAPI void evas_object_image_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the row stride of the given image object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The row stride is the number of bytes between the start of a row
+ * and the start of the next row for image data.
+ *
+ * @param[in] obj The given image object
+ * @return The stride of the image (<b>in bytes</b>)
+ */
+EAPI int evas_object_image_stride_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets a number representing any error that occurred during the
+ * last loading of the given image object's source image.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @return A value giving the last error that occurred \n
+ * It should be a #Evas_Load_Error value. #EVAS_LOAD_ERROR_NONE
+ * is returned if there is no error.
+ */
+EAPI Evas_Load_Error evas_object_image_load_error_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the raw image data of the given image object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Note that the raw data must be of the same size (see
+ * evas_object_image_size_set(), which has to be called @b before this
+ * one) and colorspace (see evas_object_image_colorspace_set()) of the
+ * image. If data is @c NULL, the current image data is
+ * freed. Naturally, if one does not set an image object's data
+ * manually, it still has one, allocated by Evas.
+ *
+ * @param[in] obj The given image object
+ * @param[in] data The raw data, or @c NULL
+ *
+ * @see evas_object_image_data_get()
+ */
+EAPI void evas_object_image_data_set(Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets a pointer to the raw image data of the given image object.
+ *
+ * @details This function returns a pointer to an image object's internal pixel
+ * buffer, for reading only or read/write. If you request it for
+ * writing, the image is marked as dirty so that it gets redrawn at
+ * the next update.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Each time you call this function on an image object, its data
+ * buffer has an internal reference counter
+ * incremented. Decrement it back by using
+ * evas_object_image_data_set(). This is specially important for the
+ * directfb Evas engine.
+ *
+ * @remarks This is best suited for when you want to modify an existing image,
+ * without changing its dimensions.
+ *
+ * @remarks The contents' format returned by it depend on the color
+ * space of the given image object.
+ *
+ * @remarks You may want to use evas_object_image_data_update_add() to
+ * inform data changes, if you did any.
+ *
+ * @param[in] obj The given image object
+ * @param[in] for_writing Set #EINA_TRUE to set retrieved data as modifiable, \n
+ * otherwise #EINA_FALSE to not set it as modifiable
+ * @return The raw image data
+ *
+ * @see evas_object_image_data_set()
+ */
+EAPI void *evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Converts the raw image data of the given image object to the
+ * specified colorspace.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Note that this function does not modify the raw image data. If the
+ * requested colorspace is the same as the image colorspace nothing is
+ * done and @c NULL is returned. You should use
+ * evas_object_image_colorspace_get() to check the current image
+ * colorspace.
+ *
+ *
+ * @param[in] obj The given image object
+ * @param[in] to_cspace The colorspace to which the image raw data is converted
+ *
+ * @see @ref evas_object_image_colorspace_get
+ */
+EAPI void *evas_object_image_data_convert(Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Replaces the raw image data of the given image object.
+ *
+ * @details This function lets the application replace an image object's
+ * internal pixel buffer with an user-allocated one. For best results,
+ * you should generally first call evas_object_image_size_set() with
+ * the width and height for the new buffer.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This call is best suited for when you are using image data with
+ * different dimensions than the existing image data, if any. If you
+ * only need to modify the existing image in some fashion, then using
+ * evas_object_image_data_get() is probably what you are after.
+ *
+ * @remarks Note that the caller is responsible for freeing the buffer when
+ * finished with it, as user-set image data is not automatically
+ * freed when the image object is deleted.
+ *
+ * @param[in] obj The given image object
+ * @param[in] data The raw data to replace
+ *
+ * @see evas_object_image_data_get()
+ */
+EAPI void evas_object_image_data_copy_set(Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Marks a sub-region of the given image object to be redrawn.
+ *
+ * @details This function schedules a particular rectangular region of an image
+ * object to be updated (redrawn) at the next rendering cycle.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @param[in] x The X-offset of the region to be updated
+ * @param[in] y The Y-offset of the region to be updated
+ * @param[in] w The width of the region to be updated
+ * @param[in] h The height of the region to be updated
+ */
+EAPI void evas_object_image_data_update_add(Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Enables or disables alpha channel usage on the given image object.
+ *
+ * @details This function sets a flag on an image object indicating whether or
+ * not to use alpha channel data. A value of #EINA_TRUE makes it use
+ * alpha channel data, and #EINA_FALSE makes it ignore that
+ * data. Note that this has nothing to do with an object's color as
+ * manipulated by evas_object_color_set().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @param[in] has_alpha Set #EINA_TRUE to use alpha channel () data, \n
+ * otherwise set #EINA_FALSE to not use it
+ *
+ * @see evas_object_image_alpha_get()
+ */
+EAPI void evas_object_image_alpha_set(Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether alpha channel data is being used on the given
+ * image object.
+ *
+ * @details This function returns #EINA_TRUE if the image object's alpha
+ * channel is being used, or #EINA_FALSE otherwise.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks See @ref evas_object_image_alpha_set() for more details.
+ *
+ * @param[in] obj The given image object
+ * @return #EINA_TRUE if the alpha channel data is being used, \n
+ * otherwise #EINA_FALSE if the alpha channel data is not being used
+ *
+ */
+EAPI Eina_Bool evas_object_image_alpha_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets whether to use high-quality image scaling algorithm on the
+ * given image object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When enabled, a higher quality image scaling algorithm is used when
+ * scaling images to sizes other than the source image's original
+ * one. This gives better results but is more computationally expensive.
+ *
+ * @remarks Image objects get created originally with smooth scaling @b on.
+ *
+ * @param[in] obj The given image object
+ * @param[in] smooth_scale Set #EINA_TRUE to use smooth scale, \n
+ * otherwise set #EINA_FALSE to not use it
+ *
+ * @see evas_object_image_smooth_scale_get()
+ */
+EAPI void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the given image object is using high-quality
+ * image scaling algorithm.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @return #EINA_TRUE if smooth scale is being used, \n
+ * otherwise #EINA_FALSE if smooth scale is not being used
+ *
+ * @see evas_object_image_smooth_scale_set()
+ */
+EAPI Eina_Bool evas_object_image_smooth_scale_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Preloads an image object's image data in the background.
+ *
+ * @details This function requests the preload of the data image in the
+ * background. The work is queued before being processed (because
+ * there might be other pending requests of this type).
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Whenever the image data gets loaded, Evas calls
+ * #EVAS_CALLBACK_IMAGE_PRELOADED registered callbacks on @a obj (that
+ * may be immediately, if the data is already preloaded before).
+ *
+ * @remarks Use #EINA_TRUE for @a cancel on scenarios where you do not need
+ * the image data preloaded anymore.
+ *
+ * @remarks Any evas_object_show() call after evas_object_image_preload()
+ * makes the latter to be @b cancelled, with the loading process
+ * now taking place @b synchronously (and, thus, blocking the return
+ * of the former until the image is loaded). It is highly advisable,
+ * then, that the user preload an image with it being @b hidden, just
+ * to be shown on the #EVAS_CALLBACK_IMAGE_PRELOADED event's callback.
+ *
+ * @param[in] obj The given image object
+ * @param[in] cancel Set #EINA_FALSE to add to the preloading work queue, \n
+ * otherwise set #EINA_TRUE to remove it (if it is issued before)
+ */
+EAPI void evas_object_image_preload(Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Reloads an image object's image data.
+ *
+ * @details This function reloads the image data bound to image object @a obj.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ */
+EAPI void evas_object_image_reload(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Saves the given image object's contents to an (image) file.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The extension suffix on @a file determines which <b>saver
+ * module</b> Evas is to use when saving, thus the final file's
+ * format. If the file supports multiple data stored in it (Eet ones),
+ * you can specify the key to be used as the index of the image in it.
+ *
+ * @remarks You can specify some flags when saving the image. Currently
+ * acceptable flags are @c quality and @c compress. Eg.: @c
+ * "quality=100 compress=9"
+ *
+ * @param[in] obj The given image object
+ * @param[in] file The filename to be used to save the image (extension obligatory)
+ * @param[in] key The image key in the file (if an Eet one), \n
+ * otherwise @c NULL
+ * @param[in] flags String containing the flags to be used (@c NULL for none)
+ * @return #EINA_TRUE if the contents are saved successfully, \n
+ * otherwise #EINA_FALSE if it fails
+ */
+EAPI Eina_Bool evas_object_image_save(const Evas_Object *obj, const char *file, const char *key, const char *flags) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Imports pixels from given source to a given canvas image object.
+ *
+ * @details This function imports pixels from a given source to a given canvas image.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas object
+ * @param[in] pixels The pixel's source to be imported
+ * @return #EINA_TRUE if success, otherwise #EINA_FALSE.
+ */
+EAPI Eina_Bool evas_object_image_pixels_import(Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the callback function to get pixels from a canvas' image.
+ *
+ * @details This sets a function to be the callback function that gets
+ * pixels from an image of the canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @param[in] func The callback function
+ * @param[in] data The data pointer to be passed to @a func
+ *
+ */
+EAPI void evas_object_image_pixels_get_callback_set(Evas_Object *obj, Evas_Object_Image_Pixels_Get_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets whether the given image object is dirty and needs to request its pixels.
+ *
+ * @details This function only works properly if a callback for getting pixels has been set.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use this function if you really know what you are doing.
+ *
+ * @param[in] obj The given image object
+ * @param[in] dirty Set #EINA_TRUE to mark the image object as dirty, \n
+ * otherwise set #EINA_FALSE to mark the image object as not dirty
+ *
+ * @see evas_object_image_pixels_get_callback_set()
+ */
+EAPI void evas_object_image_pixels_dirty_set(Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the given image object is dirty (needs to be redrawn).
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @return #EINA_TRUE if the image is dirty, \n
+ * otherwise #EINA_FALSE if the image is not dirty
+ */
+EAPI Eina_Bool evas_object_image_pixels_dirty_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the DPI resolution of an image object's source image.
+ *
+ * @details This function sets the DPI resolution of a given loaded canvas
+ * image. This is useful for the SVG image loader.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @param[in] dpi The new DPI resolution
+ *
+ * @see evas_object_image_load_dpi_get()
+ */
+EAPI void evas_object_image_load_dpi_set(Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the DPI resolution of a loaded image object in the canvas.
+ *
+ * @details This function returns the DPI resolution of the given canvas image.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @return The DPI resolution of the given canvas image
+ *
+ * @see evas_object_image_load_dpi_set() for more details
+ */
+EAPI double evas_object_image_load_dpi_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the load size of a given image object's source image.
+ *
+ * @details This function sets a new geometry size for the given canvas image.
+ * The image will be loaded into memory as if it was the set size instead of
+ * the original size.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The size of a given image object's source image will be less than or
+ * equal to the size of @p w and @p h.
+ *
+ * @param[in] obj The given canvas object
+ * @param[in] w The new width of the image's load size
+ * @param[in] h The new height of the image's load size
+ *
+ * @see evas_object_image_load_size_get()
+ */
+EAPI void evas_object_image_load_size_set(Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the load size of a given image object's source image.
+ *
+ * @details This function gets the geometry size set manually for the given canvas image.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use @c NULL pointers on the size components that you are not
+ * interested in: they are ignored by the function.
+ * @p w and @p h will be set with the image's loading size only if
+ * the image's load size is set manually: if evas_object_image_load_size_set()
+ * has not been called, @p w and @p h will be set with 0.
+ *
+ * @param[in] obj The given image object
+ * @param[out] w The new width of the image's load size that is returned
+ * @param[out] h The new height of the image's load size that is returned
+ *
+ * @see evas_object_image_load_size_set() for more details
+ */
+EAPI void evas_object_image_load_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the scale down factor of a given image object's source image,
+ * when loading it.
+ *
+ * @details This function sets the scale down factor of a given canvas
+ * image. This is useful for the SVG image loader.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @param[in] scale_down The scale down factor
+ *
+ * @see evas_object_image_load_scale_down_get()
+ */
+EAPI void evas_object_image_load_scale_down_set(Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the scale down factor of a given image object's source image,
+ * when loading it.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @return The scale down factor
+ *
+ * @see evas_object_image_load_scale_down_set() for more details
+ */
+EAPI int evas_object_image_load_scale_down_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets a selective region of the source image to load for the given image object.
+ *
+ * @details This function is useful when you are not showing all of an image's
+ * area on its image object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The image loader for the image format in question has to
+ * support selective region loading in order to this function to take effect.
+ *
+ * @param[in] obj The given image object pointer
+ * @param[in] x The X-offset of the region to be loaded
+ * @param[in] y The Y-offset of the region to be loaded
+ * @param[in] w The width of the region to be loaded
+ * @param[in] h The height of the region to be loaded
+ *
+ * @see evas_object_image_load_region_get()
+ */
+EAPI void evas_object_image_load_region_set(Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the coordinates of a given image object's selective
+ * (source image) load region.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use @c NULL pointers on the coordinates that you are not interested
+ * in: they are ignored by the function.
+ *
+ * @param[in] obj The given image object pointer
+ * @param[out] x The X-offset of the region to be loaded
+ * @param[out] y The Y-offset of the region to be loaded
+ * @param[out] w The width of the region to be loaded
+ * @param[out] h The height of the region to be loaded
+ *
+ * @see evas_object_image_load_region_get()
+ */
+EAPI void evas_object_image_load_region_get(const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets whether the orientation information in the image file should be honored.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @param[in] enable Set #EINA_TRUE to honor the orientation information, \n
+ * otherwise #EINA_FALSE to not honor the orientation information
+ */
+EAPI void evas_object_image_load_orientation_set(Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the orientation information in the image file should be honored.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @return #EINA_TRUE if the orientation information is honored, \n
+ * otherwise #EINA_FALSE if it is not honored
+ */
+EAPI Eina_Bool evas_object_image_load_orientation_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the colorspace of a given image of the canvas.
+ *
+ * @details This function sets the colorspace of given canvas image.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @param[in] cspace The new color space
+ *
+ */
+EAPI void evas_object_image_colorspace_set(Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the colorspace of a given image of the canvas.
+ *
+ * @details This function returns the colorspace of given canvas image.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @return The colorspace of the image
+ *
+ */
+EAPI Evas_Colorspace evas_object_image_colorspace_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the support state of a given image.
+ *
+ * @details This function returns the state of the region support of given image
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @return The region support state
+ */
+EAPI Eina_Bool evas_object_image_region_support_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the native surface of a given image of the canvas.
+ *
+ * @details This function sets a native surface of a given canvas image.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @param[in] surf The new native surface
+ *
+ */
+EAPI void evas_object_image_native_surface_set(Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the native surface of a given image of the canvas.
+ *
+ * @details This function returns the native surface of a given canvas image.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @return The native surface of the given canvas image
+ *
+ */
+EAPI Evas_Native_Surface *evas_object_image_native_surface_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the video surface linked to a given image of the canvas.
+ *
+ * @details This function links a video surface to a given canvas image.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @param[in] surf The new video surface
+ *
+ */
+EAPI void evas_object_image_video_surface_set(Evas_Object *obj, Evas_Video_Surface *surf) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the video surface linked to a given image of the canvas.
+ *
+ * @details This function returns the video surface linked to a given canvas image.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @return The video surface of the given canvas image
+ *
+ */
+EAPI const Evas_Video_Surface *evas_object_image_video_surface_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the scale hint of a given image of the canvas.
+ *
+ * @details This function sets the scale hint value of the given image object
+ * in the canvas, which affects how Evas is to cache scaled
+ * versions of its original source image.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @param[in] hint The scale hint \n
+ * A #Evas_Image_Scale_Hint value.
+ *
+ * @see evas_object_image_scale_hint_get()
+ */
+EAPI void evas_object_image_scale_hint_set(Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the scale hint of a given image of the canvas.
+ *
+ * @details This function returns the scale hint value of the given image
+ * object of the canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object pointer
+ * @return The scale hint value set on @a obj \n
+ * A #Evas_Image_Scale_Hint value.
+ *
+ * @see evas_object_image_scale_hint_set() for more details.
+ */
+EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the content hint setting of a given image object of the canvas.
+ *
+ * @details This function sets the content hint value of the given image of the
+ * canvas. For example, if you are on the GL engine and your driver
+ * implementation supports it, setting this hint to
+ * #EVAS_IMAGE_CONTENT_HINT_DYNAMIC makes it need @b zero copies
+ * at texture upload time, which is an "expensive" operation.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @param[in] hint The content hint value \n
+ * Valid values are defined in #Evas_Image_Content_Hint.
+ *
+ * @see evas_object_image_content_hint_get()
+ */
+EAPI void evas_object_image_content_hint_set(Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the content hint setting of a given image object of the canvas.
+ *
+ * @details This function returns the content hint value of the given image of
+ * the canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given canvas pointer
+ * @return The content hint value set on it \n
+ * Valid values are define in #Evas_Image_Content_Hint. \n
+ * #EVAS_IMAGE_CONTENT_HINT_NONE means an error.
+ *
+ * @see evas_object_image_content_hint_set()
+ */
+EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Enables an image to be used as an alpha mask.
+ *
+ * @details This function sets flags, and discard any excess image data not used as an
+ * alpha mask.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Note that there is little point in using a image as alpha mask unless it has an
+ * alpha channel.
+ *
+ * @param[in] obj The object to use as an alpha mask
+ * @param[in] ismask Set #EINA_TRUE to use image as alphamask,
+ * otherwise #EINA_FALSE to not use image as alphamask
+ */
+EAPI void evas_object_image_alpha_mask_set(Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the source object on an image object to used as a @b proxy.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If an image object is set to behave as a @b proxy, it mirrors
+ * the rendering contents of a given @b source object in its drawing
+ * region, without affecting that source in any way. The source must
+ * be another valid Evas object. Other effects may be applied to the
+ * proxy, such as a map (see evas_object_map_set()) to create a
+ * reflection of the original object (for example).
+ *
+ * @remarks Any existing source object on @a obj is removed after this
+ * call. Setting @a src to @c NULL clears the proxy object (not in
+ * "proxy state" anymore).
+ *
+ * @remarks You cannot set a proxy as another proxy's source.
+ *
+ * @param[in] obj The proxy (image) object
+ * @param[in] src The source object to use for the proxy
+ * @return #EINA_TRUE if the source object is set successfully, \n
+ * otherwise #EINA_FALSE on error
+ *
+ * @see evas_object_image_source_get()
+ * @see evas_object_image_source_unset()
+ */
+EAPI Eina_Bool evas_object_image_source_set(Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the current source object of an image object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The Image object
+ * @return The source object (if any), \n
+ * otherwise @c NULL if not in "proxy mode" or on errors
+ *
+ * @see evas_object_image_source_set() for more details
+ */
+EAPI Evas_Object *evas_object_image_source_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Clears the source object on a proxy image object.
+ *
+ * @details This function is equivalent to calling evas_object_image_source_set() with a
+ * @c NULL source.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The Image object to clear source of
+ * @return #EINA_TRUE if the source object is cleared successfully, \n
+ * otherwise #EINA_FALSE on error
+ */
+EAPI Eina_Bool evas_object_image_source_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the source object to be visible.
+ * @since 1.8
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @a visible is set to #EINA_FALSE, the source object of the proxy (@a obj)
+ * is invisible.
+ *
+ * @remarks This function works differently to evas_object_show() and evas_object_hide().
+ * Once the source object is hidden by evas_object_hide() then the proxy object is
+ * hidden as well. Actually in this case both objects are excluded from the
+ * Evas internal update circle.
+ *
+ * @remarks Using this method, you can toggle the visibility of a proxy's source
+ * object keeping the proxy visibility untouched.
+ *
+ * @param[in] obj The proxy (image) object
+ * @param[in] visible Set #EINA_TRUE to show the source object, \n
+ * otherwise set #EINA_FALSE to not show it
+ *
+ * @see evas_object_image_source_visible_get()
+ * @see evas_object_image_source_set()
+ * @see evas_object_show()
+ * @see evas_object_hide()
+ */
+EAPI void evas_object_image_source_visible_set(Evas_Object *obj, Eina_Bool visible) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the state of the source object visibility.
+ * @since 1.8
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The proxy (image) object
+ * @return #EINA_TRUE if source object is visible, \n
+ * otherwise #EINA_FALSE
+ *
+ * @see evas_object_image_source_visible_set()
+ * @see evas_object_image_source_set()
+ * @see evas_object_show()
+ * @see evas_object_hide()
+ */
+EAPI Eina_Bool evas_object_image_source_visible_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Clips the proxy object with the source object's clipper.
+ * @since 1.8
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The proxy (image) object
+ * @param[in] source_clip Set #EINA_TRUE if @a obj must be clipped by the source clipper, \n
+ * otherwise set #EINA_FALSE
+ *
+ * @see evas_object_clip_set()
+ * @see evas_object_image_source_set()
+ */
+EAPI void evas_object_image_source_clip_set(Evas_Object *obj, Eina_Bool source_clip) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether an object is clipped by source object's clipper.
+ * @since 1.8
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The proxy (image) object
+ * @return #EINA_TRUE if source clip is enabled,
+ * otherwise #EINA_FALSE if source clip is not enabled
+ *
+ * @see evas_object_clip_set()
+ * @see evas_object_image_source_set()
+ * @see evas_object_image_source_clip_set()
+ */
+EAPI Eina_Bool evas_object_image_source_clip_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether a file extension is supported by @ref Evas_Object_Image.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If file is a Eina_Stringshare, use @ref evas_object_image_extension_can_load_fast_get directly.
+ *
+ * @remarks This function is threadsafe.
+ *
+ * @param[in] file The file to check
+ * @return #EINA_TRUE if the file extension is supported, \n
+ * otherwise #EINA_FALSE if it is not supported
+ */
+EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
+
+/**
+ * @brief Checks whether a file extension is supported by @ref Evas_Object_Image.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function is threadsafe.
+ * @param[in] file The file to check \n
+ * It should be Eina_Stringshare.
+ * @return #EINA_TRUE if the file extension is supported, \n
+ * otherwise #EINA_FALSE if it is not supported
+ */
+EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
+
+/**
+ * @brief Checks whether an image object can be animated (have multiple frames).
+ *
+ * @details This function returns if the image file of an image object is capable of animation
+ * such as an animated gif file might. This is only useful to be called once
+ * the image object file has been set.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas_Object *obj;
+ *
+ * if (evas_object_image_animated_get(obj))
+ * {
+ * int frame_count;
+ * int loop_count;
+ * Evas_Image_Animated_Loop_Hint loop_type;
+ * double duration;
+ *
+ * frame_count = evas_object_image_animated_frame_count_get(obj);
+ * printf("This image has %d frames\n",frame_count);
+ *
+ * duration = evas_object_image_animated_frame_duration_get(obj,1,0);
+ * printf("Frame 1's duration is %f. You had better set object's frame to 2 after this duration using timer\n");
+ *
+ * loop_count = evas_object_image_animated_loop_count_get(obj);
+ * printf("loop count is %d. You had better run loop %d times\n",loop_count,loop_count);
+ *
+ * loop_type = evas_object_image_animated_loop_type_get(obj);
+ * if (loop_type == EVAS_IMAGE_ANIMATED_HINT_LOOP)
+ * printf("You had better set frame like 1->2->3->1->2->3...\n");
+ * else if (loop_type == EVAS_IMAGE_ANIMATED_HINT_PINGPONG)
+ * printf("You had better set frame like 1->2->3->2->1->2...\n");
+ * else
+ * printf("Unknown loop type\n");
+ *
+ * evas_object_image_animated_frame_set(obj,1);
+ * printf("You set image object's frame to 1. You can see frame 1\n");
+ * }
+ * @endcode
+ *
+ * @param[in] obj The Image object
+ * @return #EINA_TRUE if @a obj supports animation, \n
+ * otherwise #EINA_FALSE if it does not support animation
+ *
+ * @see evas_object_image_animated_get()
+ * @see evas_object_image_animated_frame_count_get()
+ * @see evas_object_image_animated_loop_type_get()
+ * @see evas_object_image_animated_loop_count_get()
+ * @see evas_object_image_animated_frame_duration_get()
+ * @see evas_object_image_animated_frame_set()
+ */
+EAPI Eina_Bool evas_object_image_animated_get(const Evas_Object *obj);
+
+/**
+ * @brief Gets the total number of frames of the image object.
+ *
+ * @details This returns the total number of frames the image object supports (if animated).
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The Image object
+ * @return The number of frames
+ *
+ * @see evas_object_image_animated_get()
+ * @see evas_object_image_animated_frame_count_get()
+ * @see evas_object_image_animated_loop_type_get()
+ * @see evas_object_image_animated_loop_count_get()
+ * @see evas_object_image_animated_frame_duration_get()
+ * @see evas_object_image_animated_frame_set()
+ */
+EAPI int evas_object_image_animated_frame_count_get(const Evas_Object *obj);
+
+/**
+ * @brief Gets the kind of looping the image object does.
+ *
+ * @details This function returns the kind of looping the image object wants to do.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If it returns @c EVAS_IMAGE_ANIMATED_HINT_LOOP, you should display frames in a sequence like:
+ * 1->2->3->1->2->3->1...
+ * If it returns @c EVAS_IMAGE_ANIMATED_HINT_PINGPONG, it is better to
+ * display frames in a sequence like: 1->2->3->2->1->2->3->1...
+ * The default type is EVAS_IMAGE_ANIMATED_HINT_LOOP.
+ *
+ * @param[in] obj The Image object
+ * @return The Loop type of the image object
+ *
+ * @see evas_object_image_animated_get()
+ * @see evas_object_image_animated_frame_count_get()
+ * @see evas_object_image_animated_loop_type_get()
+ * @see evas_object_image_animated_loop_count_get()
+ * @see evas_object_image_animated_frame_duration_get()
+ * @see evas_object_image_animated_frame_set()
+ */
+EAPI Evas_Image_Animated_Loop_Hint evas_object_image_animated_loop_type_get(const Evas_Object *obj);
+
+/**
+ * @brief Gets the number of times the animation of the object loops.
+ *
+ * @details This function returns loop count of image. The loop count is the number of times
+ * the animation plays fully from first to last frame until the animation
+ * should stop (at the final frame).
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @c 0 is returned, then looping should happen indefinitely (no limit to
+ * the number of times it loops).
+ *
+ * @param[in] obj The Image object
+ * @return The number of loop of an animated image object
+ *
+ * @see evas_object_image_animated_get()
+ * @see evas_object_image_animated_frame_count_get()
+ * @see evas_object_image_animated_loop_type_get()
+ * @see evas_object_image_animated_loop_count_get()
+ * @see evas_object_image_animated_frame_duration_get()
+ * @see evas_object_image_animated_frame_set()
+ */
+EAPI int evas_object_image_animated_loop_count_get(const Evas_Object *obj);
+
+/**
+ * @brief Gets the duration of a sequence of frames.
+ *
+ * @details This function returns the total duration that the specified sequence of frames should
+ * take in seconds.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you set start_frame to 1 and frame_num 0, you get frame 1's duration.
+ * If you set start_frame to 1 and frame_num 1, you get frame 1's duration +
+ * frame2's duration.
+ *
+ * @param[in] obj The Image object
+ * @param[in] start_frame The first frame
+ * @param[in] fram_num The number of frames in the sequence
+ * @return The duraction of a sequence of frames.
+ *
+ * @see evas_object_image_animated_get()
+ * @see evas_object_image_animated_frame_count_get()
+ * @see evas_object_image_animated_loop_type_get()
+ * @see evas_object_image_animated_loop_count_get()
+ * @see evas_object_image_animated_frame_duration_get()
+ * @see evas_object_image_animated_frame_set()
+ */
+EAPI double evas_object_image_animated_frame_duration_get(const Evas_Object *obj, int start_frame, int fram_num);
+
+/**
+ * @brief Sets the frame to the current frame of an image object.
+ *
+ * @details This function sets the image object's current frame to frame_num
+ * with 1 being the first frame.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given image object
+ * @param[in] frame_num The index of current frame
+ *
+ * @see evas_object_image_animated_get()
+ * @see evas_object_image_animated_frame_count_get()
+ * @see evas_object_image_animated_loop_type_get()
+ * @see evas_object_image_animated_loop_count_get()
+ * @see evas_object_image_animated_frame_duration_get()
+ * @see evas_object_image_animated_frame_set()
+ */
+EAPI void evas_object_image_animated_frame_set(Evas_Object *obj, int frame_num);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Text Text Object Functions
+ * @ingroup Evas_Object_Specific
+ *
+ * @brief This group provides functions that operate on single line, single style text objects.
+ *
+ * For multiline and multiple style text, see @ref Evas_Object_Textblock.
+ *
+ * @remarks We do not guarantee any proper results if you create a Text object
+ * without setting the evas engine.
+ *
+ * @{
+ */
+
+/* Definition for basic styles (4 bits allocated use 0->10 now, 5 left) */
+#define EVAS_TEXT_STYLE_MASK_BASIC 0xf
+
+/**
+ * @brief Definition for text style type creation macro. Use style types on the 's'
+ * arguments, being 'x' your style variable.
+ */
+#define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
+ do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
+
+#define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
+
+/**
+ * @brief Definition for text style type creation macro. This one imposes shadow
+ * directions on the style type variable -- use the @c
+ * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* values on 's', incrementally.
+ */
+#define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
+ do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
+
+/**
+ * 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
+ */
+typedef enum _Evas_Text_Style_Type
+{
+ EVAS_TEXT_STYLE_PLAIN, /**< Plain, standard text */
+ EVAS_TEXT_STYLE_SHADOW, /**< Text with shadow underneath */
+ EVAS_TEXT_STYLE_OUTLINE, /**< Text with an outline */
+ EVAS_TEXT_STYLE_SOFT_OUTLINE, /**< Text with a soft outline */
+ EVAS_TEXT_STYLE_GLOW, /**< Text with a glow effect */
+ EVAS_TEXT_STYLE_OUTLINE_SHADOW, /**< Text with both outline and shadow effects */
+ EVAS_TEXT_STYLE_FAR_SHADOW, /**< Text with (far) shadow underneath */
+ EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW, /**< Text with outline and soft shadow effects combined */
+ EVAS_TEXT_STYLE_SOFT_SHADOW, /**< Text with (soft) shadow underneath */
+ EVAS_TEXT_STYLE_FAR_SOFT_SHADOW, /**< Text with (far soft) shadow underneath */
+ // TIZEN ONLY (20131106) : Font effect for tizen.
+ EVAS_TEXT_STYLE_TIZEN_GLOW_SHADOW, /** Tizen::Graphics::Effect::EFFECT_FOR_TEXT_ON_HOME_SCREEN_ICON */
+ EVAS_TEXT_STYLE_TIZEN_SOFT_GLOW_SHADOW, /** Tizen::Graphics::Effect::EFFECT_FOR_TEXT_ON_DYNAMIC_BOX_IMPORT_IMAGE */
+ EVAS_TEXT_STYLE_TIZEN_SHADOW, /** Tizen::Graphics::Effect::EFFECT_FOR_TEXT_ON_DYNAMIC_BOX_IMAGE */
+ //////////////////////////////
+
+ /* OR these to modify shadow direction (3 bits needed) */
+ EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< Shadow growing to bottom right */
+ EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< Shadow growing to the bottom */
+ EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< Shadow growing to bottom left */
+ EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< Shadow growing to the left */
+ EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< Shadow growing to top left */
+ EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< Shadow growing to the top */
+ EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< Shadow growing to top right */
+ EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< Shadow growing to the right */
+} Evas_Text_Style_Type;
+
+/**
+ * @brief Creates a new text object on the provided canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Text objects are for simple, single line text elements. If you want
+ * more elaborated text blocks, see @ref Evas_Object_Textblock.
+ *
+ * @param[in] e The canvas to create the text object on
+ * @return A pointer to a new text object on success, \n
+ * otherwise @c NULL on error
+ *
+ * @see evas_object_text_font_source_set()
+ * @see evas_object_text_font_set()
+ * @see evas_object_text_text_set()
+ */
+EAPI Evas_Object *evas_object_text_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Sets the font (source) file to be used on a given text object.
+ *
+ * @details This function allows the font file to be explicitly set for a given
+ * text object, overriding system lookup, which first occurs in
+ * the given file's contents.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The text object to set font for
+ * @param[in] font The font file's path
+ *
+ * @see evas_object_text_font_get()
+ */
+EAPI void evas_object_text_font_source_set(Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the font file's path which is being used on a given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The text object to set the font for
+ * @return The font file's path
+ *
+ * @see evas_object_text_font_get() for more details
+ */
+EAPI const char *evas_object_text_font_source_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the font family and size on a given text object.
+ *
+ * @details This function allows the font name and size of a text object to be
+ * set. The @a font string has to follow fontconfig's convention on
+ * naming fonts, as it is the underlying library used to query system
+ * fonts by Evas (see the @c fc-list command's output, on your system,
+ * to get an idea).
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The text object to set font for
+ * @param[in] font The font (family) name
+ * @param[in] size The font size, in points
+ *
+ * @see evas_object_text_font_get()
+ * @see evas_object_text_font_source_set()
+ */
+EAPI void evas_object_text_font_set(Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the font family and size in use on a given text object.
+ *
+ * @details This function allows the font name and size of a text object to be
+ * queried. Be aware that the font name string is still owned by Evas
+ * and should @b not have free() called on it by the caller of the
+ * function.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The evas text object to query for font information
+ * @param[out] font A pointer to the location to store the font name in
+ * @param[out] size A pointer to the location to store the font size in
+ *
+ * @see evas_object_text_font_set()
+ */
+EAPI void evas_object_text_font_get(const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the text string to be displayed by the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The text object to set text string on
+ * @param[in] text The text string to display on it
+ *
+ * @see evas_object_text_text_get()
+ */
+EAPI void evas_object_text_text_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the text string currently being displayed by the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Do not free() the return value.
+ *
+ * @param[in] obj The given text object
+ * @return The text string currently being displayed on it
+ *
+ * @see evas_object_text_text_set()
+ */
+EAPI const char *evas_object_text_text_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the BiDi delimiters used in the textblock.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks BiDi delimiters are use for in-paragraph separation of bidi segments. This
+ * is useful for example in recipients fields of e-mail clients where bidi
+ * oddities can occur when mixing RTL and LTR.
+ *
+ * @param[in] obj The given text object
+ * @param[in] delim A null terminated string of delimiters, for example ",|"
+ */
+EAPI void evas_object_text_bidi_delimiters_set(Evas_Object *obj, const char *delim);
+
+/**
+ * @brief Gets the BiDi delimiters used in the textblock.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks BiDi delimiters are use for in-paragraph separation of bidi segments. This
+ * is useful for example in recipients fields of e-mail clients where bidi
+ * oddities can occur when mixing RTL and LTR.
+ *
+ * @param[in] obj The given text object
+ * @return A null terminated string of delimiters, for example, ",|", \n
+ * otherwise @c NULL if empty
+ */
+EAPI const char *evas_object_text_bidi_delimiters_get(const Evas_Object *obj);
+
+/**
+ * @brief Sets the ellipsis that should be used for the text object.
+ *
+ * @details This is a value between @c 0.0 and @c 1.0 indicating the position of the text
+ * to be shown. @c 0.0 means the start is shown and the end trimmed, @c 1.0
+ * means the beginning is trimmed and the end is shown, and any value
+ * in between causes ellipsis to be added in both the end of the text and the
+ * requested part to be shown.
+ * @since 1.8
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks @c -1.0 means ellipsis is turned off.
+ *
+ * @param[in] obj The given text object
+ * @param[in] ellipsis The ellipsis
+ */
+EAPI void evas_object_text_ellipsis_set(Evas_Object *obj, double ellipsis);
+
+/**
+ * @brief Gets the ellipsis currently set on the text object.
+ * @since 1.8
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given text object
+ * @return The ellipsis set on the text object
+ * @see evas_object_text_ellipsis_set()
+ */
+EAPI double evas_object_text_ellipsis_get(const Evas_Object *obj);
+
+/**
+ * @internal
+ */
+EAPI Evas_Coord evas_object_text_ascent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ */
+EAPI Evas_Coord evas_object_text_descent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ */
+EAPI Evas_Coord evas_object_text_max_ascent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ */
+EAPI Evas_Coord evas_object_text_max_descent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ */
+EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ */
+EAPI Evas_Coord evas_object_text_vert_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ */
+EAPI Evas_Coord evas_object_text_inset_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the position and dimension information of a character within a text @c Evas_Object.
+ *
+ * @details This function is used to obtain the X, Y, width and height of a the character
+ * located at @a pos within the @c Evas_Object @a obj. @a obj must be a text object
+ * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx,
+ * @a cy, @a cw, @a ch) may be @c NULL in which case no value is assigned to that
+ * parameter.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The text object to retrieve position information for
+ * @param[in] pos The character position to request co-ordinates for
+ * @param[out] cx A pointer to an @c Evas_Coord to store the X value in (can be @c NULL)
+ * @param[out] cy A pointer to an @c Evas_Coord to store the Y value in (can be @c NULL)
+ * @param[out] cw A pointer to an @c Evas_Coord to store the Width value in (can be @c NULL)
+ * @param[out] ch A pointer to an @c Evas_Coord to store the Height value in (can be @c NULL)
+ * @return #EINA_FALSE if the information is obtained successfully,
+ * otherwise #EINA_TRUE on error
+ */
+EAPI Eina_Bool evas_object_text_char_pos_get(const Evas_Object *obj, int pos, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ */
+EAPI int evas_object_text_char_coords_get(const Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the logical position of the last char in the text up to the given position. \n
+ * This is NOT the position of the last char because of the possibility of RTL in the text.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The text object
+ * @param[in] x The X co-ordinate
+ * @param[in] y The Y co-ordinate
+ * @return The logical The positoin of the last char in the text up to the given position
+ */
+EAPI int evas_object_text_last_up_to_pos(const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the style on use on the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given text object to set style on
+ * @return The style type in use
+ *
+ * @see evas_object_text_style_set() for more details.
+ */
+EAPI Evas_Text_Style_Type evas_object_text_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the style to apply on the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Valid text object styles are defined in #Evas_Text_Style_Type.
+ * Some of those values are combinations of more than one style,
+ * and some account for the direction of the rendering of shadow effects.
+ *
+ * @remarks You can use the helper macros #EVAS_TEXT_STYLE_BASIC_SET and
+ * #EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET to assemble a style value.
+ *
+ * @remarks The following figure illustrates the text styles:
+ *
+ * @image html text-styles.png
+ * @image rtf text-styles.png
+ * @image latex text-styles.eps
+ *
+ * @param[in] obj The given text object to set style on
+ * @param[in] type The style type
+ *
+ * @see evas_object_text_style_get()
+ * @see evas_object_text_shadow_color_set()
+ * @see evas_object_text_outline_color_set()
+ * @see evas_object_text_glow_color_set()
+ * @see evas_object_text_glow2_color_set()
+ */
+EAPI void evas_object_text_style_set(Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the shadow color for the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Shadow effects, which are fading colors decorating the text
+ * underneath it, are just shown if the object is set to one of
+ * the following styles:
+ * - #EVAS_TEXT_STYLE_SHADOW
+ * - #EVAS_TEXT_STYLE_OUTLINE_SHADOW
+ * - #EVAS_TEXT_STYLE_FAR_SHADOW
+ * - #EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW
+ * - #EVAS_TEXT_STYLE_SOFT_SHADOW
+ * - #EVAS_TEXT_STYLE_FAR_SOFT_SHADOW
+ *
+ * @remarks You can also change the direction where the shadow grows to, with
+ * evas_object_text_style_set().
+ *
+ * @param[in] obj The given Evas text object
+ * @param[in] r The red component of the given color
+ * @param[in] g The green component of the given color
+ * @param[in] b The blue component of the given color
+ * @param[in] a The alpha component of the given color
+ *
+ * @see evas_object_text_shadow_color_get()
+ */
+EAPI void evas_object_text_shadow_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the shadow color for the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use @c NULL pointers on the color components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas text object
+ * @param[out] r The pointer to variable to hold the red component of the given color
+ * @param[out] g The pointer to variable to hold the green component of the given color
+ * @param[out] b The pointer to variable to hold the blue component of the given color
+ * @param[out] a The pointer to variable to hold the alpha component of the given color
+ *
+ * @see evas_object_text_shadow_color_set() for more details.
+ */
+EAPI void evas_object_text_shadow_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the glow color for the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Glow effects, which are glowing colors decorating the text's
+ * surroundings, are shown if the object is set to the
+ * #EVAS_TEXT_STYLE_GLOW style.
+ *
+ * @remarks Glow effects are placed from a short distance of the text
+ * itself, but no touching it. For glowing effects right on the
+ * borders of the glyphs, see 'glow 2' effects
+ * (evas_object_text_glow2_color_set()).
+ *
+ * @param[in] obj The given Evas text object
+ * @param[in] r The red component of the given color
+ * @param[in] g The green component of the given color
+ * @param[in] b The blue component of the given color
+ * @param[in] a The alpha component of the given color
+ *
+ * @see evas_object_text_glow_color_get()
+ */
+EAPI void evas_object_text_glow_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the glow color for the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use @c NULL pointers on the color components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas text object.
+ * @param[out] r The pointer to variable to hold the red component of the given color
+ * @param[out] g The pointer to variable to hold the green component of the given color
+ * @param[out] b The pointer to variable to hold the blue component of the given color
+ * @param[out] a The pointer to variable to hold the alpha component of the given color
+ *
+ * @see evas_object_text_glow_color_set() for more details.
+ */
+EAPI void evas_object_text_glow_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the 'glow 2' color for the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks 'Glow 2' effects, which are glowing colors decorating the text's
+ * (immediate) surroundings, are shown if the object is set
+ * to the #EVAS_TEXT_STYLE_GLOW style. See also
+ * evas_object_text_glow_color_set().
+ *
+ * @param[in] obj The given Evas text object
+ * @param[in] r The red component of the given color
+ * @param[in] g The green component of the given color
+ * @param[in] b The blue component of the given color
+ * @param[in] a The alpha component of the given color
+ *
+ * @see evas_object_text_glow2_color_get()
+ */
+EAPI void evas_object_text_glow2_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the 'glow 2' color for the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use @c NULL pointers on the color components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas text object
+ * @param[out] r The pointer to variable to hold the red component of the given color
+ * @param[out] g The pointer to variable to hold the green component of the given color
+ * @param[out] b The pointer to variable to hold the blue component of the given color
+ * @param[out] a The pointer to variable to hold the alpha component of the given color
+ *
+ * @see evas_object_text_glow2_color_set() for more details.
+ */
+EAPI void evas_object_text_glow2_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the outline color for the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Outline effects (colored lines around text glyphs) are just
+ * shown if the object is set to one of the following styles:
+ * - #EVAS_TEXT_STYLE_OUTLINE
+ * - #EVAS_TEXT_STYLE_SOFT_OUTLINE
+ * - #EVAS_TEXT_STYLE_OUTLINE_SHADOW
+ * - #EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW
+ *
+ * @param[in] obj The given Evas text object
+ * @param[in] r The red component of the given color
+ * @param[in] g The green component of the given color
+ * @param[in] b The blue component of the given color
+ * @param[in] a The alpha component of the given color
+ *
+ * @see evas_object_text_outline_color_get()
+ */
+EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the outline color for the given text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use @c NULL pointers on the color components that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The given Evas text object
+ * @param[out] r The pointer to the variable to hold the red component of the given color
+ * @param[out] g The pointer to the variable to hold the green component of the given color
+ * @param[out] b The pointer to the variable to hold the blue component of the given color
+ * @param[out] a The pointer to the variable to hold the alpha component of the given color
+ *
+ * @see evas_object_text_outline_color_set() for more details.
+ */
+EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the text style pad of a text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given text object
+ * @param[out] l The left pad (or @c NULL)
+ * @param[out] r The right pad (or @c NULL)
+ * @param[out] t The top pad (or @c NULL)
+ * @param[out] b The bottom pad (or @c NULL)
+ *
+ */
+EAPI void evas_object_text_style_pad_get(const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the direction of the text currently being displayed in the text object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given evas text object
+ * @return The direction of the text
+ */
+EAPI Evas_BiDi_Direction evas_object_text_direction_get(const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Sets an Evas filter program on this Text Object.
+ * @since 1.9. Backported for Tizen (1.7.99).
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the program fails to compile (syntax error, invalid buffer name, etc...),
+ * the standard text effects are applied instead (SHADOW, etc...).
+ *
+ * @remarks EXPERIMENTAL FEATURE. This is an unstable API, please use this only for testing purposes.
+ *
+ * @param[in] obj The given evas text object
+ * @param[in] arg The program code, as defined by the "Evas filters script language".
+ * Pass @c NULL to remove the former program and
+ * switch back to the standard text effects.
+ *
+ * @internal
+ * @see @ref evasfiltersref "Evas filters reference"
+ * @endinternal
+ */
+EAPI void evas_object_text_filter_program_set(Evas_Object *obj, const char *arg);
+
+/**
+ * @brief Binds an object to use as a mask or texture with Evas Filters. This
+ * automatically creates a new RGBA buffer containing the source object's
+ * pixels (as it is rendered).
+ * @since 1.9. Backported for Tizen (1.7.99).
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks EXPERIMENTAL FEATURE. This is an unstable API, please use this only for testing purposes.
+ *
+ * @param[in] obj The given evas object
+ * @param[in] name The object name as used in the program code
+ * @param[in] source The evas object to use through proxy rendering
+ *
+ * @see evas_obj_text_filter_program_set
+ * @internal
+ * @see @ref evasfiltersref "Evas filters reference"
+ * @endinternal
+ */
+EAPI void evas_object_text_filter_source_set(Evas_Object *obj, const char *name, Evas_Object *source);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Textblock Textblock Object Functions
+ * @ingroup Evas_Object_Specific
+ *
+ * @brief This group provides functions used to create and manipulate textblock objects.
+ *
+ * Unlike @ref Evas_Object_Text, these handle complex text, doing multiple
+ * styles and multiline text based on HTML-like tags. Of these extra
+ * features are heavier on memory and processing cost.
+ *
+ * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
+ *
+ * This part explains about the textblock object's API and proper usage.
+ * The main user of the textblock object is the edje entry object in Edje. So
+ * that is a good place to learn from, but this document is more than
+ * enough. If it is not, please contact the developer to update it.
+ *
+ * @subsection textblock_intro Introduction
+ * The textblock object is, as implied, an object that can show big chunks of
+ * text. Textblock supports many features including: Text formatting, automatic
+ * and manual text alignment, embedding items (for example icons) and more.
+ * Textblock has three important parts: the text paragraphs, the format nodes,
+ * and the cursors.
+ *
+ * You can use markup to format text, for example: "<font_size=50>Big!</font_size>".
+ * You can also put more than one style directive in one tag:
+ * "<font_size=50 color=#F00>Big and Red!</font_size>".
+ * Please notice that we used "</font_size>" although the format also included
+ * color. This is because the first format determines the matching closing tag's
+ * name. You can also use anonymous tags, like: "<font_size=30>Big</>" which
+ * just pop any type of format, but it is advised to use the named alternatives
+ * instead.
+ *
+ * @subsection textblock_cursors Textblock Object Cursors
+ * A textblock cursor is the data type that represents
+ * a position in a textblock. Each cursor contains information about the
+ * paragraph it points to, the position in that paragraph, and the object itself.
+ * Cursors register to textblock objects upon creation. This means that once
+ * you created a cursor, it belongs to a specific object and you cannot, for example,
+ * copy a cursor "into" a cursor of a different object. Registered cursors
+ * also have the added benefit of updating automatically upon textblock changes,
+ * this means that if you have a cursor pointing to a specific character, it
+ * still points to it even after you change the whole object completely (as long
+ * as the char is not deleted). This is not possible without updating, because
+ * as mentioned, each cursor holds a character position. There are many
+ * functions that handle cursors. See the evas_textblock_cursor*
+ * functions. For creation and deletion of cursors, see:
+ * @see evas_object_textblock_cursor_new()
+ * @see evas_textblock_cursor_free()
+ * @remarks 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).
+ *
+ * @subsection textblock_paragraphs Textblock Object Paragraphs
+ * The textblock object is made out of text split to paragraphs (delimited
+ * by the paragraph separation character). Each paragraph has many (or none)
+ * format nodes associated with it which are responsible for the formatting
+ * of that paragraph.
+ *
+ * @subsection textblock_format_nodes Textblock Object Format Nodes
+ * As explained in @ref textblock_paragraphs each one of the format nodes
+ * is associated with a paragraph.
+ * There are two types of format nodes: visible and invisible.
+ * Visible: Formats that a cursor can point to, that is, the formats that
+ * occupy space. For example: newlines, tabs, items and so on. Some visible items
+ * are made of two parts. In this case, only the opening tag is visible.
+ * A closing tag (i.e a \</tag\> tag) should NEVER be visible.
+ * Invisible: Formats that do not occupy space. For example: bold and underline.
+ * Being able to access format nodes is very important for some uses. For
+ * example, edje uses the "<a>" format to create links in the text (and pop
+ * popups above them when clicked). For the textblock object a is just a
+ * formatting instruction (how to color the text), but edje utilizes the access
+ * to the format nodes to make it do more.
+ * For more information, see all the evas_textblock_node_format_* functions.
+ * The translation of "<tag>" tags to actual format is done according to the
+ * tags defined in the style, see @ref evas_textblock_style_set
+ *
+ * @subsection textblock_special_formats Special Formats
+ * Textblock supports various format directives that can be used in markup. In
+ * addition to the mentioned format directives, textblock allows creating
+ * additional format directives using "tags" that can be set in the style. See
+ * @ref evas_textblock_style_set .
+ *
+ * Textblock supports the following formats:
+ * @li font - Font description in fontconfig like format. Example: "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
+ * @li font_weight - Overrides the weight defined in "font". Example: "font_weight=Bold" is the same as "font=:style=Bold". Supported weights: "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack".
+ * @li font_style - Overrides the style defined in "font". Example: "font_style=Italic" is the same as "font=:style=Italic". Supported styles: "normal", "oblique", and "italic".
+ * @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".
+ * @li lang - Overrides the language defined in "font". Example: "lang=he" is the same as "font=:lang=he".
+ * @li font_fallbacks - A comma delimited list of fonts to try if finding the main font fails.
+ * @li font_size - The font size in points.
+ * @li font_source - The source of the font. Example: An eet file.
+ * @li color - Text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li underline_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li underline2_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li outline_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li shadow_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li glow_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li glow2_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li strikethrough_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li align - Either "auto" (meaning according to text direction), "left", "right", "center", "middle", a value between @c 0.0 and @c 1.0, or a value between 0% to 100%.
+ * @li valign - Either "top", "bottom", "middle", "center", "baseline", "base", a value between @c 0.0 and @c 1.0, or a value between 0% to 100%.
+ * @li wrap - "word", "char", "mixed", or "none".
+ * @li left_margin - Either "reset", or a pixel value indicating the margin.
+ * @li right_margin - Either "reset", or a pixel value indicating the margin.
+ * @li underline - "on", "off", "single", or "double".
+ * @li strikethrough - "on" or "off"
+ * @li backing_color - Background color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
+ * @li backing - Enable or disable background color. Example: "on" or "off"
+ * @li style - Either "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow", or "far_soft_shadow".
+ * @li tabstops - Pixel value for tab width.
+ * @li linesize - Force a line size in pixels.
+ * @li linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
+ * @li linegap - Force a line gap in pixels.
+ * @li linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
+ * @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.
+ * @li linefill - Either a float value or percentage indicating how much to fill the line.
+ * @li ellipsis - Value between @c 0.0-@c 1.0 to indicate the type of ellipsis, or @c -1.0 to indicate that ellipsis is not wanted.
+ * @li password - "on" or "off". This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off.
+ *
+ * @remarks There is no guarantee of any proper results if you create a Textblock
+ * object without setting the evas engine.
+ *
+ * @todo put here some usage examples
+ *
+ * @{
+ */
+
+typedef struct _Evas_Textblock_Style Evas_Textblock_Style; /**< @brief handle for Evas Textblock Style */
+typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor; /**< @brief handle for Evas Textblock Cursor */
+/**
+ * @typedef Evas_Object_Textblock_Node_Format
+ * @brief The structure type containing a format node.
+ */
+typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format;
+typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle;
+
+struct _Evas_Textblock_Rectangle
+{
+ Evas_Coord x, y, w, h;
+};
+
+typedef enum _Evas_Textblock_Text_Type
+{
+ EVAS_TEXTBLOCK_TEXT_RAW,
+ EVAS_TEXTBLOCK_TEXT_PLAIN,
+ EVAS_TEXTBLOCK_TEXT_MARKUP
+} Evas_Textblock_Text_Type;
+
+typedef enum _Evas_Textblock_Cursor_Type
+{
+ EVAS_TEXTBLOCK_CURSOR_UNDER,
+ EVAS_TEXTBLOCK_CURSOR_BEFORE
+} Evas_Textblock_Cursor_Type;
+
+/**
+ * @brief Adds a textblock to the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @return The new textblock object
+ */
+EAPI Evas_Object *evas_object_textblock_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets the unescaped version of escape.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] escape The string to be escaped
+ * @return The unescaped version of escape
+ */
+EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the escaped version of the string.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] string The string to escape
+ * @param[out] len_ret The len of the part of the string that is used
+ * @return The escaped string
+ */
+EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the unescaped version of the string between start and end.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] escape_start The start of the string
+ * @param[in] escape_end The end of the string
+ * @return The unescaped version of the range
+ */
+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);
+
+/**
+ * @brief Gets the plain version of the markup.
+ *
+ * @details This function works as if you set the markup to a textblock and then retrieve the plain
+ * version of the text. That is: <br> and <\n> is replaced with \n, &...; with
+ * the actual char and so on.
+ *
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textblock object to work with \n
+ * If @c NULL, it tries the default.
+ * @param[in] text The markup text \n
+ * If @c NULL, it returns @c NULL.
+ * @return An allocated plain text version of the markup
+ */
+EAPI char *evas_textblock_text_markup_to_utf8(const Evas_Object *obj, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
+
+/**
+ * @brief Gets the markup version of the plain text.
+ *
+ * @details This function replaces \\n -\> \<br/\> \\t -\> \<tab/\> and so on.
+ * This is generally needed before you pass plain text to be set in a textblock.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textblock object to work with \n
+ * If @c NULL, it just does the default behaviour, i.e with no extra object information.
+ * @param[in] text The markup text \n
+ * If @c NULL, it returns @c NULL.
+ * @return An allocated plain text version of the markup
+ */
+EAPI char *evas_textblock_text_utf8_to_markup(const Evas_Object *obj, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
+
+/**
+ * @brief Creates a new textblock style.
+ *
+ * @since_tizen 2.3
+ *
+ * @return The new textblock style
+ */
+EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
+
+/**
+ * @brief Destroys a textblock style.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] ts The textblock style to free
+ */
+EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the style @a ts to the style passed as text by text.
+ * @details This function expects a string consisting of many (or none) tag='format' pairs.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] ts The style to set
+ * @param[in] text The text to parse \n
+ * This should be NOT NULL.
+ */
+EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the text of the style @a ts.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] ts The style to get the text
+ * @return The text of the style, \n
+ * otherwise @c NULL on error
+ */
+EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the object style to @a ts.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The Evas object to set the style to
+ * @param[in] ts The style to set
+ */
+EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the style of an object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The object to get the style from
+ * @return The style of the object
+ */
+EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Pushes @a ts to the top of the user style stack.
+ *
+ * FIXME: API is solid but currently only supports 1 style in the stack.
+ *
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The user style overrides the corresponding elements of the regular style.
+ * This is the proper way to do theme overrides in code.
+ * @param[in] obj The Evas object to set the style to
+ * @param[in] ts The style to set
+ * @see evas_object_textblock_style_set
+ */
+EAPI void evas_object_textblock_style_user_push(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Deletes the style from the top of the user style stack.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The object to get the style from
+ * @see evas_object_textblock_style_get
+ */
+EAPI void evas_object_textblock_style_user_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets (does not remove) the style at the top of the user style stack.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The object to get the style from
+ * @return The style of the object
+ * @see evas_object_textblock_style_get
+ */
+EAPI const Evas_Textblock_Style *evas_object_textblock_style_user_peek(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the "replacement character" to use for the given textblock object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given textblock object
+ * @param[in] ch The charset name
+ */
+EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the "replacement character" for given textblock object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given textblock object
+ * @return The replacement character, \n
+ * otherwise @c NULL if no replacement character is in use
+ */
+EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the vertical alignment of text within the textblock object as a whole.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Normally alignment is @c 0.0 (top of object). Values given should be
+ * between @c 0.0 and @c 1.0 , where @c 1.0 is bottom of object, @c 0.5 is
+ * vertically centered, and so on.
+ *
+ * @param[in] obj The given textblock object
+ * @param[in] align A value between @c 0.0 and @c 1.0
+ */
+EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align);
+
+/**
+ * @brief Gets the vertical alignment of a textblock.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given textblock object
+ * @return The alignment set for the object
+ */
+EAPI double evas_object_textblock_valign_get(const Evas_Object *obj);
+
+/**
+ * @brief Sets the BiDi delimiters used in the textblock.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks BiDi delimiters are uses for in-paragraph separation of bidi segments. This
+ * is useful, for example, in recipients fields of e-mail clients where bidi
+ * oddities can occur when mixing RTL and LTR.
+ *
+ * @param[in] obj The given textblock object
+ * @param[in] delim A null terminated string of delimiters, for example ",|"
+ */
+EAPI void evas_object_textblock_bidi_delimiters_set(Evas_Object *obj, const char *delim);
+
+/**
+ * @brief Gets the BiDi delimiters used in the textblock.
+ *
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks BiDi delimiters are used for in-paragraph separation of bidi segments. This
+ * is useful, for example, in recipients fields of e-mail clients where bidi
+ * oddities can occur when mixing RTL and LTR.
+ *
+ * @param[in] obj The given textblock object
+ * @return A null terminated string of delimiters, for example ",|", \n
+ * otherwise @c NULL if it is empty
+ */
+EAPI const char *evas_object_textblock_bidi_delimiters_get(const Evas_Object *obj);
+
+/**
+ * @brief Sets the newline mode.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When @c true, newline character behaves as a paragraph separator.
+ *
+ * @param[in] obj The given textblock object
+ * @param[in] mode Set #EINA_TRUE for legacy mode, \n
+ * otherwise set #EINA_FALSE
+ */
+EAPI void evas_object_textblock_legacy_newline_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the newline mode.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When true, newline character behaves as a paragraph separator.
+ *
+ * @param[in] obj The given textblock object
+ * @return #EINA_TRUE if it is in legacy mode, \n
+ * otherwise #EINA_FALSE
+
+ */
+EAPI Eina_Bool evas_object_textblock_legacy_newline_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the textblock's text to the markup text.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This assumes that the text does not include the unicode object replacement char (0xFFFC).
+ *
+ * @param[in] obj The textblock object
+ * @param[in] text The markup text to use
+ */
+EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Prepends markup to the cursor @a cur.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This assumes that the text does not include the unicode object replacement char (0xFFFC).
+ *
+ * @param[in] cur The cursor to prepend to
+ * @param[in] text The markup text to prepend
+ */
+EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the markup of the object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The Evas object
+ * @return The markup text of the object
+ */
+EAPI const char *evas_object_textblock_text_markup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the object's main cursor.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The object
+ * @return @a obj's main cursor
+ */
+EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Creates a new cursor, associates it to the obj and inits it to point
+ * to the start of the textblock.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Association to the object means the cursor is updated when the object changes.
+ *
+ * @remarks If you need speed and you know what you are doing, it is slightly faster to
+ * just allocate the cursor yourself and not associate it.
+ *
+ * @param[in] obj The object to associate to
+ * @return The new cursor
+ */
+EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Frees the cursor and unassociates it from the object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Do not use it to free the unassociated cursors.
+ *
+ * @param[in] cur The cursor to free
+ */
+EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the cursor to the start of the first text node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to update
+ */
+EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the cursor to the end of the last text node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to set
+ */
+EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Advances to the start of the next text node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to update
+ * @return #EINA_TRUE if the cursor advances a paragraph, \n
+ * otherwise #EINA_FALSE
+ */
+EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Goes to the end of the previous text node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to update
+ * @return #EINA_TRUE if the cursor goes to the end of the previous paragraph, \n
+ * otherwise #EINA_FALSE
+ */
+EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the the list format node corresponding to @a anchor.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The evas object \n
+ * This must not be @c NULL.
+ * @param[in] anchor The anchor name to get
+ * @return The list format node corresponding to the anchor, \n
+ * otherwise @c NULL if there is no list format node
+ */
+EAPI const Eina_List *evas_textblock_node_format_list_get(const Evas_Object *obj, const char *anchor) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the first format node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The evas object \n
+ * This must not be @c NULL.
+ * @return The first format node, \n
+ * otherwise @c NULL if there is no first format node
+ */
+EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the last format node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The evas textblock \n
+ * This must not be @c NULL.
+ * @return The last format node, \n
+ * otherwise @c NULL if there is no last format node
+ */
+EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the next format node (after n).
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] n The current format node \n
+ * This must not be @c NULL.
+ * @return The next format node, \n
+ * otherwise @c NULL if there is no next format node
+ */
+EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the previous format node (after n).
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] n The current format node \n
+ * This is must not be @c NULL.
+ * @return The previous format node, \n
+ * otherwise @c NULL if there is no previous format node
+ */
+EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Removes a format node and its match. \n
+ * That is it removes a \<tag\> \</tag\> pair.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Assumes that the node is the first part of \<tag\>.
+ * This does not work if @a n is a closing tag.
+ *
+ * @param[in] obj The Evas object of the textblock \n
+ * This must not be @c NULL.
+ * @param[in] n The current format node \n
+ * This must not be @c NULL.
+ */
+EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the cursor to point to the place where format points to.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to update
+ * @param[in] n The format node to update according
+ * @deprecated Duplicate of evas_textblock_cursor_at_format_set
+ */
+EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the format node at the position pointed by @a cur.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The position to look at
+ * @return The format node, \n
+ * otherwise @c NULL if it is not found
+ * @see evas_textblock_cursor_format_is_visible_get()
+ */
+EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the text format representation of the format node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] fnode The format node
+ * @return The textual format of the format node
+ */
+EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fnode) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the cursor to point to the position of @a fmt.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to update
+ * @param[in] fmt The format to update according to
+ */
+EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Checks whether the current cursor position is a visible format.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This way is more efficient than evas_textblock_cursor_format_get() to check for the existence
+ * of a visible format.
+ *
+ * @param[in] cur The cursor to look at
+ * @return #EINA_TRUE if the cursor points to a visible format, \n
+ * otherwise #EINA_FALSE if the cursor does not point to a visible format
+ * @see evas_textblock_cursor_format_get()
+ */
+EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Advances the cursor to the next format node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to be updated
+ * @return #EINA_TRUE if the cursor is advanced successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Advances the cursor to the previous format node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to update
+ * @return #EINA_TRUE if the cursor is advanced successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether the cursor points to a format.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to check
+ * @return #EINA_TRUE if the cursor points to a format, \n
+ * otherwise #EINA_FALSE if the cursor does not point to a format
+ */
+EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Advances the cursor 1 cluster forward.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to advance
+ * @return #EINA_TRUE if the cursor is advanced successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_cluster_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Advances the cursor 1 cluster backward.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to advance
+ * @return #EINA_TRUE if the cursor is advanced successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_cluster_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Advances the cursor 1 char forward.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to advance
+ * @return #EINA_TRUE if the cursor is advanced successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Advances the cursor 1 char backward.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to advance
+ * @return #EINA_TRUE if the cursor is advanced successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Moves the cursor to the start of the word under the cursor.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to move
+ * @return #EINA_TRUE if the cursor is moved successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_word_start(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Moves the cursor to the end of the word under the cursor.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to move
+ * @return #EINA_TRUE if the cursor is moved successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_word_end(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Moves the cursor to the first char in the node the cursor is pointing on.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to move
+ */
+EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Moves the cursor to the last char in a text node.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to move
+ */
+EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Moves the cursor to the start of the current line.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to move
+ */
+EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Moves the cursor to the end of the current line.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to move
+ */
+EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the current cursor position.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor
+ * @return The cursor position, \n
+ * otherwise @c -1 on error
+ */
+EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the cursor position.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to be set
+ * @param[in] pos The position to set
+ */
+EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Moves the cursor to the start of the line passed.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor
+ * @param[in] line The line number
+ * @return #EINA_TRUE if the cursor is moved successfully, \n
+ * otherwise #EINA_FALSE on error
+ */
+EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Compares two cursors.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur1 The first cursor
+ * @param[in] cur2 The second cursor
+ * @return @c -1 if cur1 < cur2, @c 0 if cur1 == cur2, \n
+ * otherwise @c 1
+ */
+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);
+
+/**
+ * @brief Makes @a cur_dest point to the same point as @a cur.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This does not work if they do not point to the same object.
+ *
+ * @param[in] cur The source cursor
+ * @param[in] cur_dest The destination cursor
+ */
+EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Adds text to the current cursor position and sets the cursor to *before*
+ * the start of the text just added.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to the position to add text at
+ * @param[in] text The text to add
+ * @return The length of the text added
+ * @see evas_textblock_cursor_text_prepend()
+ */
+EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Adds text to the current cursor position and sets the cursor to *after*
+ * the start of the text just added.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to the position to add text at
+ * @param[in] text The text to add
+ * @return The length of the text added
+ * @see evas_textblock_cursor_text_append()
+ */
+EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Adds format to the current cursor position.
+ * @details If the format being added is a visible format,
+ add it *before* the cursor position, otherwise, add it after.
+ * This behavior is because visible formats are like characters and invisible
+ * should be stacked in a way that the last one is added last.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function works with native formats, that means that style defined
+ * tags like <br> won't work here. For those kind of things use markup prepend.
+ *
+ * @param[in] cur the cursor to where to add format at.
+ * @param[in] format the format to add.
+ * @return Returns true if a visible format was added, false otherwise.
+ * @see evas_textblock_cursor_format_prepend()
+ */
+EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Adds the format to the current cursor position.
+ * @details If the format being added is a visible format,
+ * add it *before* the cursor position, otherwise, add it after.
+ * This behavior is because visible formats are like characters and invisible
+ * should be stacked in a way that the last one is added last.
+ * If the format is visible the cursor is advanced after it.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function works with native formats, that means that style defined
+ * tags like <br> does not work here. For those, use markup prepend.
+ *
+ * @param[in] cur The cursor to where to add format at
+ * @param[in] format The format to add
+ * @return #EINA_TRUE if the visible format is added, \n
+ * otherwise #EINA_FALSE if the visible format is not added
+ * @see evas_textblock_cursor_format_prepend()
+ */
+EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Deletes the character at the location of the cursor.
+ * @details If there is a format pointing to this position, delete it as well.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor pointing to the current location
+ */
+EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Deletes the range between @a cur1 and @a cur2.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur1 Starting point of the range
+ * @param[in] cur2 Ending point of the range
+ */
+EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the text of the paragraph @a cur points to.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor pointing to the paragraph
+ * @return The text in markup, \n
+ * otherwise @c NULL on error
+ */
+EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the length of the paragraph.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is cheaper that the eina_unicode_strlen().
+ *
+ * @param[in] cur The position of the paragraph
+ * @return The length of the paragraph on success, \n
+ * otherwise @c -1 on error
+ */
+EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the currently visible range.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] start The start of the range
+ * @param[in] end The end of the range
+ * @return #EINA_TRUE if the range is obtained successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_visible_range_get(Evas_Textblock_Cursor *start, Evas_Textblock_Cursor *end) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets the format nodes in the range between @a cur1 and @a cur2.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur1 The start of the range
+ * @param[in] cur2 The end of the range
+ * @return The format nodes in the range \n
+ * You have to free it.
+ */
+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);
+
+/**
+ * @brief Gets the text in the range between @a cur1 and @a cur2.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur1 The start of the range
+ * @param[in] cur2 The end of the range
+ * @param[in] format The format in which to return the text \n
+ * Markup - in textblock markup. Plain - UTF8.
+ * @return The text in the range
+ * @see elm_entry_markup_to_utf8()
+ */
+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);
+
+/**
+ * @internal
+ * // TIZEN_ONLY(20131218)
+ * // Add evas_textblock_cursor_range_text_valid_markup_get API.
+ * @brief Gets the text and markup tags in the range between @a cur1 and @a cur2.
+ *
+ * @param cur1 The start of the range
+ * @param cur2 The end of the range
+ * @return The text in the range and the markup tags that affect the text
+ * @see elm_entry_markup_to_utf8()
+ */
+EAPI char *evas_textblock_cursor_range_text_valid_markup_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+/****************************************************/
+/************* TIZEN ONLY END *********************/
+/****************************************************/
+
+/**
+ * @brief Gets the content of the cursor.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Frees the returned string pointer when done if it is not @c NULL.
+ *
+ * @param[in] cur The cursor
+ * @return The text in the range, terminated by a null byte (may be utf8)
+ */
+EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets the geometry of two cursors ("split cursor"), if logical cursor is
+ * between LTR/RTL text, also considering paragraph direction.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The upper cursor is shown for the text of the same direction as paragraph,
+ * lower cursor - for the opposite.
+ *
+ * @remarks The split cursor geometry is valid only in '|' cursor mode.
+ * In this case #EINA_TRUE is returned and @a cx2, @a cy2, @a cw2, @a ch2 are set,
+ * otherwise it behaves like cursor_geometry_get.
+ *
+ * @param[in] cur The cursor
+ * @param[out] cx The x coordinate of the cursor (or upper cursor)
+ * @param[out] cy The y coordinate of the cursor (or upper cursor)
+ * @param[out] cw The width of the cursor (or upper cursor)
+ * @param[out] ch The height of the cursor (or upper cursor)
+ * @param[out] cx2 The x coordinate of the lower cursor
+ * @param[out] cy2 The y coordinate of the lower cursor
+ * @param[out] cw2 The width of the lower cursor
+ * @param[out] ch2 The height of the lower cursor
+ * @param[in] ctype The type of the cursor
+ * @return #EINA_TRUE if split cursor,
+ * otherwise #EINA_FALSE
+ */
+EAPI Eina_Bool 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);
+
+/**
+ * @brief Gets the geometry of the cursor.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks It depends on the type of cursor requested.
+ * This should be used instead of char_geometry_get because there are weird
+ * special cases with BiDi text.
+ *
+ * @remarks In '_' cursor mode (i.e a line below the char) it is the same as char_geometry_get,
+ * except for the case of the last char of a line which depends on the
+ * paragraph direction.
+ *
+ * @remarks In '|' cursor mode (i.e a line between two chars) it is very variable.
+ * For example, consider the following visual string:
+ * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
+ * a '|' between the c and the C.
+ *
+ * @param[in] cur The cursor
+ * @param[out] cx The x coordinate of the cursor
+ * @param[out] cy The y coordinate of the cursor
+ * @param[out] cw The width of the cursor
+ * @param[out] ch The height of the cursor
+ * @param[in] dir The direction of the cursor \n
+ * This can be @c NULL.
+ * @param[in] ctype The type of the cursor
+ * @return The line number of the char on success, \n
+ * otherwise @c -1 on error
+ */
+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);
+
+/**
+ * @brief Gets the geometry of the char at @a cur.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The position of the char
+ * @param[out] cx The x coordinate of the char
+ * @param[out] cy The y coordinate of the char
+ * @param[out] cw The width of the char
+ * @param[out] ch The height of the char
+ * @return The line number of the char, \n
+ * otherwise @c -1 on error
+ */
+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);
+
+/**
+ * @brief Gets the geometry of the pen at @a cur.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The position of the char
+ * @param[out] cpen_x The pen_x of the char
+ * @param[out] cy The y of the char
+ * @param[out] cadv The adv of the char
+ * @param[out] ch The h of the char
+ * @return The line number of the char, \n
+ * otherwise @c -1 on error
+ */
+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);
+
+/**
+ * @brief Gets the geometry of the line at @a cur.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The position of the line
+ * @param[out] cx The x coordinate of the line
+ * @param[out] cy The y coordinate of the line
+ * @param[out] cw The width of the line
+ * @param[out] ch The height of the line
+ * @return The line number of the line, \n
+ * otherwise @c -1 on error
+ */
+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);
+
+/**
+ * @internal
+ * @brief Sets the position of the cursor at a proper cluster according to the X and Y coordinates.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to set
+ * @param[in] x The x coordinate to set
+ * @param[in] y The y coordinate to set
+ * @return #EINA_TRUE if the position of the cursor is set successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_cluster_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the position of the cursor according to the X and Y coordinates.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to set
+ * @param[in] x The x coordinate to set
+ * @param[in] y The y coordinate to set
+ * @return #EINA_TRUE if the position of the cursor is set successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the cursor position according to the y coordinate.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cur to be set
+ * @param[in] y The y coordinate to set
+ * @return The line number found, \n
+ * otherwise @c -1 on error
+ */
+EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the geometry of a range.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur1 The start of the range
+ * @param[in] cur2 The end of the range
+ * @return A list of rectangles representing the geometry of the range
+ */
+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);
+
+/**
+ * @brief Get the simple geometry of a range.
+ * The simple geometry is the geomtry in which rectangles in middle
+ * lines of range are merged into one big rectangle.
+ *
+ * @since_tizen 2.3
+ *
+ * @param cur1 one side of the range.
+ * @param cur2 other side of the range.
+ * @return an iterator of rectangles representing the geometry of the range.
+ */
+EAPI Eina_Iterator *evas_textblock_cursor_range_simple_geometry_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+
+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);
+
+/**
+ * @brief Checks whether the cursor points to the end of the line.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cur The cursor to check
+ * @return #EINA_TRUE if the cursor points to the end of the line, \n
+ * otherwise #EINA_FALSE
+ */
+EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the geometry of a line number.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The object
+ * @param[in] line The line number
+ * @param[out] cx The x coordinate of the line
+ * @param[out] cy The y coordinate of the line
+ * @param[out] cw The w coordinate of the line
+ * @param[out] ch The h coordinate of the line
+ * @return #EINA_TRUE if the geometry of the line is obtained successfully,
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_textblock_line_number_geometry_get(const Evas_Object *obj, int line, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Clears the textblock object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Does *NOT* free the Evas object itself.
+ *
+ * @param[in] obj The object to clear
+ */
+EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the formatted width and height.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This calculates the actual size after restricting
+ * the textblock to the current size of the object.
+ * The main difference between this and @ref evas_object_textblock_size_native_get
+ * is that the "native" function does not take wrapping into account.
+ * It just calculates the real width of the object if it is placed on an
+ * infinite canvas, while this function gives the size after wrapping
+ * according to the size restrictions of the object.
+ *
+ * @remarks For example, a textblock containing the text: "You shall not pass!"
+ * with no margins or padding and assuming a monospace font and a size of
+ * 7x10 char widths (for simplicity) has a native size of 19x1
+ * and a formatted size of 5x4.
+ *
+ *
+ * @param[in] obj The Evas object
+ * @param[out] w The width of the object
+ * @param[out] h The height of the object
+ * @see evas_object_textblock_size_native_get
+ */
+EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the native width and height.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This calculates the actual size without taking into account
+ * the current size of the object.
+ * The main difference between this and @ref evas_object_textblock_size_formatted_get
+ * is that the "native" function does not take wrapping into account.
+ * It just calculates the real width of the object if it is placed on an
+ * infinite canvas, while the "formatted" function gives the size after
+ * wrapping text according to the size restrictions of the object.
+ *
+ * @remarks For example, a textblock containing the text: "You shall not pass!"
+ * with no margins or padding and assuming a monospace font and a size of
+ * 7x10 char widths (for simplicity) has a native size of 19x1
+ * and a formatted size of 5x4.
+ *
+ * @param[in] obj The Evas object of the textblock
+ * @param[out] w The width returned
+ * @param[out] h The height returned
+ */
+EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ */
+EAPI void evas_object_textblock_style_insets_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+
+/**
+ * @internal
+ * @defgroup Evas_Object_Textgrid Textgrid Object Functions
+ * @ingroup Evas_Object_Specific
+ *
+ * @todo put here some usage examples
+ *
+ * @since 1.7
+ *
+ * @{
+ */
+
+/**
+ * @typedef Evas_Textgrid_Palette
+ *
+ * @brief Enumeration for the palette to use for the foreground and background colors.
+ *
+ * @since 1.7
+ */
+typedef enum
+{
+ EVAS_TEXTGRID_PALETTE_NONE, /**< No palette is used */
+ EVAS_TEXTGRID_PALETTE_STANDARD, /**< Standard palette (around 16 colors) */
+ EVAS_TEXTGRID_PALETTE_EXTENDED, /**< Extended palette (at max 256 colors) */
+ EVAS_TEXTGRID_PALETTE_LAST /**< Ignore this */
+} Evas_Textgrid_Palette;
+
+/**
+ * @typedef Evas_Textgrid_Font_Style
+ *
+ * @brief Enumeration for the style to give to each character of the grid.
+ *
+ * @since 1.7
+ */
+typedef enum
+{
+ EVAS_TEXTGRID_FONT_STYLE_NORMAL = (1 << 0), /**< Normal style */
+ EVAS_TEXTGRID_FONT_STYLE_BOLD = (1 << 1), /**< Bold style */
+ EVAS_TEXTGRID_FONT_STYLE_ITALIC = (1 << 2) /**< Oblique style */
+} Evas_Textgrid_Font_Style;
+
+/**
+ * @typedef Evas_Textgrid_Cell
+ *
+ * @brief The structure type containing the values that describe each cell.
+ *
+ * @since 1.7
+ */
+typedef struct _Evas_Textgrid_Cell Evas_Textgrid_Cell;
+
+/**
+ * @internal
+ * @struct _Evas_Textgrid_Cell
+ *
+ * @brief The structure type containing the values that describe each cell.
+ *
+ * @since 1.7
+ */
+struct _Evas_Textgrid_Cell
+{
+ Eina_Unicode codepoint; /**< The UNICODE value of the character */
+ unsigned char fg; /**< The index of the palette for the foreground color */
+ unsigned char bg; /**< The index of the palette for the background color */
+ unsigned short bold : 1; /**< The character is bold */
+ unsigned short italic : 1; /**< The character is oblique */
+ unsigned short underline : 1; /**< The character is underlined */
+ unsigned short strikethrough : 1; /**< The character is struck through */
+ unsigned short fg_extended : 1; /**< The extended palette is used for the foreground color */
+ unsigned short bg_extended : 1; /**< The extended palette is used for the background color */
+ unsigned short double_width : 1; /**< 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) */
+};
+
+/**
+ * @brief Adds a textgrid to the given Evas.
+ *
+ * @details This function adds a new textgrid object to the Evas @a e and returns the object.
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @return The new textgrid object
+ *
+ */
+EAPI Evas_Object *evas_object_textgrid_add(Evas *e);
+
+/**
+ * @brief Sets the size of the textgrid object.
+ *
+ * @details This function sets the number of lines @a h and the number
+ * of columns @a w to the textgrid object @a obj. If
+ * @a w or @a h are less or equal than @c 0, this
+ * function does nothing.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object
+ * @param[in] w The number of columns (width in cells) of the grid
+ * @param[in] h The number of rows (height in cells) of the grid
+ */
+EAPI void evas_object_textgrid_size_set(Evas_Object *obj, int w, int h);
+
+/**
+ * @brief Gets the size of the textgrid object.
+ *
+ * @details This function retrieves the number of lines in the buffer @a
+ * h and the number of columns in the buffer @a w of
+ * the textgrid object @a obj. @a w or @a h can be
+ * @c NULL. On error, their value is @c 0.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object
+ * @param[out] w The number of columns of the grid
+ * @param[out] h The number of rows of the grid
+ */
+EAPI void evas_object_textgrid_size_get(const Evas_Object *obj, int *w, int *h);
+
+/**
+ * @brief Sets the font (source) file to be used on a given textgrid object.
+ *
+ * @details This function allows the font file @a font_source to be explicitly
+ * set for the textgrid object @a obj, overriding system lookup, which
+ * first occurs in the given file's contents. If @a font_source is
+ * @c NULL or is an empty string, or the same @a font_source has already
+ * been set, or on error, this function does nothing.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to set font for
+ * @param[in] font_source The font file's path
+ *
+ * @see evas_object_textgrid_font_get()
+ * @see evas_object_textgrid_font_set()
+ * @see evas_object_textgrid_font_source_get()
+ */
+EAPI void evas_object_textgrid_font_source_set(Evas_Object *obj, const char *font_source);
+
+/**
+ * @brief Gets the font file's path which is being used on a given textgrid object.
+ *
+ * @details This function returns the font source path of the textgrid object
+ * @a obj. If the font source path has not been set, or on error,
+ * @c NULL is returned.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to set font for
+ * @return The font file's path
+ *
+ * @see evas_object_textgrid_font_get()
+ * @see evas_object_textgrid_font_set()
+ * @see evas_object_textgrid_font_source_set()
+ */
+EAPI const char *evas_object_textgrid_font_source_get(const Evas_Object *obj);
+
+/**
+ * @brief Sets the font family and size on a given textgrid object.
+ *
+ * @details This function allows the font name @a font_name and size
+ * @a font_size of the textgrid object @a obj to be set. The @a font_name
+ * string has to follow fontconfig's convention on naming fonts, as
+ * it is the underlying library used to query system fonts by Evas (see
+ * the @c fc-list command's output, on your system, to get an
+ * idea). It also has to be a monospace font. If @a font_name is
+ * @c NULL, or if it is an empty string, or if @a font_size is less or
+ * equal than @c 0, or on error, this function does nothing.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to set font for
+ * @param[in] font_name The font (family) name
+ * @param[in] font_size The font size, in points
+ *
+ * @see evas_object_textgrid_font_get()
+ * @see evas_object_textgrid_font_source_set()
+ * @see evas_object_textgrid_font_source_get()
+ */
+EAPI void evas_object_textgrid_font_set(Evas_Object *obj, const char *font_name, Evas_Font_Size font_size);
+
+/**
+ * @brief Gets the font family and size in use on a given textgrid object.
+ *
+ * @details This function allows the font name and size of a textgrid object
+ * @a obj to be queried and stored respectively in the buffers
+ * @a font_name and @a font_size. Be aware that the font name string is
+ * still owned by Evas and should @b not have free() called on it by
+ * the caller of the function. On error, the font name is the empty
+ * string and the font size is @c 0. @a font_name and @a font_source can
+ * be @c NULL.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to query for font information
+ * @param[out] font_name A pointer to the location to store the font name in
+ * @param[out] font_size A pointer to the location to store the font size in
+ *
+ * @see evas_object_textgrid_font_set()
+ * @see evas_object_textgrid_font_source_set()
+ * @see evas_object_textgrid_font_source_get()
+ */
+EAPI void evas_object_textgrid_font_get(const Evas_Object *obj, const char **font_name, Evas_Font_Size *font_size);
+
+/**
+ * @brief Gets the size of a cell of the given textgrid object in pixels.
+ *
+ * @details This functions retrieves the width and height, in pixels, of a cell
+ * of the textgrid object @a obj and store them respectively in the
+ * buffers @a width and @a height. Their value depends on the
+ * monospace font used for the textgrid object, as well as the
+ * style. @a width and @a height can be @c NULL. On error, they are
+ * set to @c 0.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to query for font information
+ * @param[out] w A pointer to the location to store the width in pixels of a cell
+ * @param[out] h A pointer to the location to store the height in pixels of a cell
+ *
+ * @see evas_object_textgrid_font_set()
+ * @see evas_object_textgrid_supported_font_styles_set()
+ */
+EAPI void evas_object_textgrid_cell_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
+
+/**
+ * @brief Sets the color to the given palette at the given index of the given textgrid object.
+ *
+ * @details This function sets the color for the palette of type @a pal at the
+ * index @a idx of the textgrid object @a obj. The ARGB components are
+ * given by @a r, @a g, @a b and @a a. This color can be used when
+ * setting the #Evas_Textgrid_Cell structure. The components must set
+ * a pre-multiplied color. If pal is #EVAS_TEXTGRID_PALETTE_NONE or
+ * #EVAS_TEXTGRID_PALETTE_LAST, or if @a idx is not between @c 0 and @c 255,
+ * or on error, this function does nothing. The color components are
+ * clamped between @c 0 and @c 255. If @a idx is greater than the latest set
+ * color, the colors between this last index and @a idx - 1 are set to
+ * black (0, 0, 0, 0).
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to query for font information
+ * @param[in] pal The type of the palette to set the color
+ * @param[in] idx The index of the paletter to which the color is stored
+ * @param[in] r The red component of the color
+ * @param[in] g The green component of the color
+ * @param[in] b The blue component of the color
+ * @param[in] a The alpha component of the color
+ *
+ * @see evas_object_textgrid_palette_get()
+ */
+EAPI void evas_object_textgrid_palette_set(Evas_Object *obj, Evas_Textgrid_Palette pal, int idx, int r, int g, int b, int a);
+
+/**
+ * @brief Gets the color to the given palette at the given index of the given textgrid object.
+ *
+ * @details This function retrieves the color for the palette of type @a pal at the
+ * index @a idx of the textgrid object @a obj. The ARGB components are
+ * stored in the buffers @a r, @a g, @a b and @a a. If @a idx is not
+ * between @c 0 and the index of the latest set color, or if @a pal is
+ * #EVAS_TEXTGRID_PALETTE_NONE or #EVAS_TEXTGRID_PALETTE_LAST, the
+ * values of the components are @c 0. @a r, @a g, @a b and @a a can be
+ * @c NULL.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to query for font information
+ * @param[in] pal The type of the palette to set the color
+ * @param[in] idx The index of the paletter to which the color is stored
+ * @param[out] r A pointer to the red component of the color
+ * @param[out] g A pointer to the green component of the color
+ * @param[out] b A pointer to the blue component of the color
+ * @param[out] a A pointer to the alpha component of the color
+ *
+ * @see evas_object_textgrid_palette_set()
+ */
+EAPI void evas_object_textgrid_palette_get(const Evas_Object *obj, Evas_Textgrid_Palette pal, int idx, int *r, int *g, int *b, int *a);
+
+EAPI void evas_object_textgrid_supported_font_styles_set(Evas_Object *obj, Evas_Textgrid_Font_Style styles);
+EAPI Evas_Textgrid_Font_Style evas_object_textgrid_supported_font_styles_get(const Evas_Object *obj);
+
+/**
+ * @brief Sets the string at the given row of the given textgrid object.
+ *
+ * @details This function returns cells to the textgrid taken by
+ * evas_object_textgrid_cellrow_get(). The row pointer @a row should be the
+ * same row pointer returned by evas_object_textgrid_cellrow_get() for the
+ * same row @a y.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to query for font information
+ * @param[in] y The row index of the grid
+ * @param[in] row The string as a sequence of #Evas_Textgrid_Cell
+ *
+ * @see evas_object_textgrid_cellrow_get()
+ * @see evas_object_textgrid_size_set()
+ * @see evas_object_textgrid_update_add()
+ */
+EAPI void evas_object_textgrid_cellrow_set(Evas_Object *obj, int y, const Evas_Textgrid_Cell *row);
+
+/**
+ * @brief Gets the string at the given row of the given textgrid object.
+ *
+ * @details This function returns a pointer to the first cell of the line @a y
+ * of the textgrid object @a obj. If @a y is not between @c 0 and the
+ * number of lines of the grid - 1, or on error, this function return @c NULL.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The textgrid object to query for font information
+ * @param[in] y The row index of the grid
+ * @return A pointer to the first cell of the given row
+ *
+ * @see evas_object_textgrid_cellrow_set()
+ * @see evas_object_textgrid_size_set()
+ * @see evas_object_textgrid_update_add()
+ */
+EAPI Evas_Textgrid_Cell *evas_object_textgrid_cellrow_get(const Evas_Object *obj, int y);
+
+/**
+ * @brief Indicates to evas that part of a textgrid region (cells) has been updated.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function declares to evas that a region of cells is updated by
+ * code and needs refreshing. An application should modify cells like this
+ * as an example:
+ *
+ * @code
+ * Evas_Textgrid_Cell *cells;
+ * int i;
+ *
+ * cells = evas_object_textgrid_cellrow_get(obj, row);
+ * for (i = 0; i < width; i++) cells[i].codepoint = 'E';
+ * evas_object_textgrid_cellrow_set(obj, row, cells);
+ * evas_object_textgrid_update_add(obj, 0, row, width, 1);
+ * @endcode
+ *
+ * @param[in] obj The textgrid object
+ * @param[in] x The rect region of cells top-left x (column)
+ * @param[in] y The rect region of cells top-left y (row)
+ * @param[in] w The rect region size in number of cells (columns)
+ * @param[in] h The rect region size in number of cells (rows)
+ *
+ * @see evas_object_textgrid_cellrow_set()
+ * @see evas_object_textgrid_cellrow_get()
+ * @see evas_object_textgrid_size_set()
+ */
+EAPI void evas_object_textgrid_update_add(Evas_Object *obj, int x, int y, int w, int h);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Line_Group Line Object Functions
+ * @ingroup Evas_Object_Specific
+ *
+ * @brief This group provides functions to deal with evas line objects.
+ *
+ * @remarks We do not guarantee any proper results if you create a Line object
+ * without setting the evas engine.
+ *
+ * @{
+ */
+
+/**
+ * @brief Adds a new evas line object to the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @return The new evas line object
+ */
+EAPI Evas_Object *evas_object_line_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Sets the coordinates of the end points of the given evas line object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given evas line object
+ * @param[in] x1 The X coordinate of the first point
+ * @param[in] y1 The Y coordinate of the first point
+ * @param[in] x2 The X coordinate of the second point
+ * @param[in] y2 The Y coordinate of the second point
+ */
+EAPI void evas_object_line_xy_set(Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2);
+
+/**
+ * @brief Gets the coordinates of the end points of the given evas line object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given line object
+ * @param[out] x1 The pointer to an integer in which to store the X coordinate of the
+ * first end point
+ * @param[out] y1 The pointer to an integer in which to store the Y coordinate of the
+ * first end point
+ * @param[out] x2 The pointer to an integer in which to store the X coordinate of the
+ * second end point
+ * @param[out] y2 The pointer to an integer in which to store the Y coordinate of the
+ * second end point
+ */
+EAPI void evas_object_line_xy_get(const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Polygon Polygon Object Functions
+ * @ingroup Evas_Object_Specific
+ *
+ * @brief This group provides functions that operate on evas polygon objects.
+ *
+ * Hint: as evas does not provide ellipse, smooth paths or circle, one
+ * can calculate points and convert these to a polygon.
+ *
+ * @remarks We do not guarantee any proper results if you create a Polygon
+ * object without setting the evas engine.
+ *
+ * @{
+ */
+
+/**
+ * @brief Adds a new evas polygon object to the given evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The given evas
+ * @return A new evas polygon object
+ */
+EAPI Evas_Object *evas_object_polygon_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Adds the given point to the given evas polygon object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given evas polygon object
+ * @param[in] x The X coordinate of the given point
+ * @param[in] y The Y coordinate of the given point
+ * @ingroup Evas_Polygon_Group
+ */
+EAPI void evas_object_polygon_point_add(Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Removes all of the points from the given evas polygon object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given polygon object
+ */
+EAPI void evas_object_polygon_points_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @since 1.2
+ *
+ * Need description
+ * @ingroup Evas_Object_Group
+ */
+EAPI void evas_object_is_frame_object_set(Evas_Object *obj, Eina_Bool is_frame);
+
+/**
+ * @internal
+ * @since 1.2
+ *
+ * Need description
+ * @ingroup Evas_Object_Group
+ */
+EAPI Eina_Bool evas_object_is_frame_object_get(Evas_Object *obj);
+
+/**
+ * @internal
+ * @defgroup Evas_Smart_Group Smart Functions
+ @ingroup Evas
+ *
+ * This group provides functions that deal with #Evas_Smart structs, creating definition
+ * (classes) of objects that have customized behavior for methods
+ * like evas_object_move(), evas_object_resize(),
+ * evas_object_clip_set() and others.
+ *
+ * These objects accept the generic methods defined in @ref
+ * Evas_Object_Group and the extensions defined in @ref
+ * Evas_Smart_Object_Group. There are a couple of existent smart
+ * objects in Evas itself (see @ref Evas_Object_Box, @ref
+ * Evas_Object_Table and @ref Evas_Smart_Object_Clipped).
+ *
+ * @{
+ */
+
+/**
+ * @def EVAS_SMART_CLASS_VERSION
+ *
+ * The version you have to put into the version field in the
+ * #Evas_Smart_Class struct. Used to safeguard from binaries with old
+ * smart object intefaces running with newer ones.
+ */
+#define EVAS_SMART_CLASS_VERSION 4
+
+/**
+ * @internal
+ * @struct _Evas_Smart_Class
+ *
+ * @brief The structure type containing a smart object's @b base class definition.
+ */
+struct _Evas_Smart_Class
+{
+ const char *name; /**< The name string of the class */
+ int version;
+ void (*add)(Evas_Object *o); /**< Code to be run when adding object to a canvas */
+ void (*del)(Evas_Object *o); /**< Code to be run when removing object from a canvas */
+ 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 are new coordinates you apply to the object. Use evas_object_geometry_get() if you need the old values, during this call. After that, the old values are lost */
+ 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 are new dimensions you apply to the object. Use evas_object_geometry_get() if you need the old values, during this call. After that, the old values are lost */
+ void (*show)(Evas_Object *o); /**< Code to be run when showing object on a canvas */
+ void (*hide)(Evas_Object *o); /**< Code to be run when hiding object on a canvas */
+ 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 are 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 are lost */
+ void (*clip_set)(Evas_Object *o, Evas_Object *clip); /**< Code to be run when setting clipper of object on a canvas. @a clip is a new clipper you apply to the object. Use evas_object_clip_get() if you need the old one, during this call. After that, the old (object pointer) value is lost */
+ 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 is lost */
+ void (*calculate)(Evas_Object *o); /**< Code to be run when object has rendering updates on a canvas */
+ void (*member_add)(Evas_Object *o, Evas_Object *child); /**< Code to be run when a child member is added to object */
+ void (*member_del)(Evas_Object *o, Evas_Object *child); /**< Code to be run when a child member is removed from object */
+
+ const Evas_Smart_Class *parent; /**< This class inherits from this parent */
+ const Evas_Smart_Cb_Description *callbacks; /**< Callbacks at this level, @c NULL terminated */
+ const Evas_Smart_Interface **interfaces; /**< #Evas_Smart_Interface pointers array, @c NULL terminated. These are the interfaces supported at this level for an object (parents may have others) @since 1.7 */
+ const void *data;
+};
+
+/**
+ * @internal
+ * @struct _Evas_Smart_Interface
+ *
+ * @brief The structure type containing a smart object's @b base interface definition
+ * @since 1.7
+ *
+ * @remarks Every Evas interface must have a name field, pointing to a global,
+ * constant string variable. This string pointer is the only way
+ * of retrieving back a given interface from a smart object. Two
+ * function pointers must be defined, too, which is called at
+ * object creation and deletion times.
+ *
+ *
+ * @ingroup Evas_Smart_Group
+ */
+struct _Evas_Smart_Interface
+{
+ const char *name; /**< Name of the given interface */
+ unsigned private_size; /**< Size, in bytes, of the interface's private data blob. This is allocated and freed automatically for you. Get it with evas_object_smart_interface_data_get() */
+ Eina_Bool (*add)(Evas_Object *obj); /**< Function to be called at object creation time. This takes place @b before the object's smart @c add() function */
+ void (*del)(Evas_Object *obj); /**< Function to be called at object deletion time. This takes place @b after the object's smart @c del() function */
+};
+
+/**
+ * @internal
+ * @struct _Evas_Smart_Cb_Description
+ *
+ * @brief The structure type that describes a callback issued by a smart object
+ * (evas_object_smart_callback_call()), as defined in its smart object
+ * class. This is particularly useful to explain to end users and
+ * their code (i.e., introspection) what the parameter @a event_info
+ * points to.
+ */
+struct _Evas_Smart_Cb_Description
+{
+ const char *name; /**< callback name ("changed", for example) */
+
+ /**
+ * @brief Hint on the type of @a event_info parameter's contents on
+ * a #Evas_Smart_Cb callback.
+ *
+ * @remarks The type string uses the pattern similar to
+ * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures,
+ * but extended to optionally include variable names within
+ * brackets preceding types. Example:
+ *
+ * @li Structure with two integers:
+ * @c "(ii)"
+ *
+ * @li Structure called 'x' with two integers named 'a' and 'b':
+ * @c "[x]([a]i[b]i)"
+ *
+ * @li Array of integers:
+ * @c "ai"
+ *
+ * @li Array called 'x' of struct with two integers:
+ * @c "[x]a(ii)"
+ *
+ * @remarks This type string is used as a hint and is @b not validated
+ * or enforced in any way. Implementors should make the best
+ * use of it to help bindings, documentation and other users
+ * of introspection features.
+ */
+ const char *type;
+};
+
+/**
+ * @def EVAS_SMART_CLASS_INIT_NULL
+ * @brief Definition for initializing to zero a whole Evas_Smart_Class structure.
+ *
+ * @see EVAS_SMART_CLASS_INIT_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
+ */
+#define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
+
+/**
+ * @def EVAS_SMART_CLASS_INIT_VERSION
+ * @brief Definition for initializing to zero a whole Evas_Smart_Class structure and set version.
+ *
+ * @remarks Similar to EVAS_SMART_CLASS_INIT_NULL, but sets version field to
+ * latest EVAS_SMART_CLASS_VERSION.
+ *
+ * @see EVAS_SMART_CLASS_INIT_NULL
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
+ */
+#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}
+
+/**
+ * @def EVAS_SMART_CLASS_INIT_NAME_VERSION
+ * @brief Definition for initializing to zero a whole Evas_Smart_Class structure and set name
+ * and version.
+ *
+ * @remarks Similar to EVAS_SMART_CLASS_INIT_NULL, but sets version field to
+ * latest EVAS_SMART_CLASS_VERSION and name to the specified value.
+ *
+ * @remarks It keeps a reference to name field as a "const char *", that is,
+ * name must be available while the structure is used (hint: static or global!)
+ * and is not modified.
+ *
+ * @see EVAS_SMART_CLASS_INIT_NULL
+ * @see EVAS_SMART_CLASS_INIT_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
+ */
+#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}
+
+/**
+ * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
+ * @brief Definition for initializing to zero a whole Evas_Smart_Class structure and set name,
+ * version and parent class.
+ *
+ * @remarks Similar to EVAS_SMART_CLASS_INIT_NULL, but sets version field to
+ * latest EVAS_SMART_CLASS_VERSION, name to the specified value and
+ * parent class.
+ *
+ * @remarks It keeps a reference to name field as a "const char *", that is,
+ * name must be available while the structure is used (hint: static or global!)
+ * and is not modified. Similarly, parent reference is kept.
+ *
+ * @see EVAS_SMART_CLASS_INIT_NULL
+ * @see EVAS_SMART_CLASS_INIT_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
+ */
+#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}
+
+/**
+ * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
+ * @brief Definition for initializing to zero a whole Evas_Smart_Class structure and set name,
+ * version, parent class and callbacks definition.
+ *
+ * @remarks Similar to EVAS_SMART_CLASS_INIT_NULL, but sets version field to
+ * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
+ * class and callbacks at this level.
+ *
+ * @remarks It keeps a reference to name field as a "const char *", that is,
+ * name must be available while the structure is used (hint: static or global!)
+ * and is not modified. Similarly, parent and callbacks reference
+ * is kept.
+ *
+ * @see EVAS_SMART_CLASS_INIT_NULL
+ * @see EVAS_SMART_CLASS_INIT_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
+ */
+#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}
+
+/**
+ * @def EVAS_SMART_SUBCLASS_NEW
+ *
+ * @brief Convenience macro to subclass a given Evas smart class.
+ *
+ * @details This macro saves some typing when writing a smart class derived
+ * from another one. In order to work, the user @b must provide some
+ * functions adhering to the following guidelines:
+ * - @<prefix@>_smart_set_user(): The @b internal @c _smart_set
+ * function (defined by this macro) calls this one, provided by
+ * the user, after inheriting everything from the parent, which
+ * should <b>take care of setting the right member functions for
+ * the class</b>, both overrides and extensions, if any.
+ * - If this new class should be subclassable as well, a @b public
+ * @c _smart_set() function is desirable to fill in the class used as
+ * parent by the children. It is up to the user to provide this
+ * interface, which most likely calls @<prefix@>_smart_set() to
+ * get the job done.
+ *
+ * After the macro's usage, the following are defined for use:
+ * - @<prefix@>_parent_sc: A pointer to the @b parent smart
+ * class. When calling parent functions from overloaded ones, use
+ * this global variable.
+ * - @<prefix@>_smart_class_new(): This function returns the
+ * #Evas_Smart needed to create smart objects with this class,
+ * which should be passed to evas_object_smart_add().
+ *
+ * @remarks @a smart_name has to be a pointer to a globally available
+ * string. The smart class created here just has a pointer set
+ * to that, and all object instances depend on it for smart class
+ * name lookup.
+ *
+ * @param smart_name The name used for the smart class \n
+ * For example, @c "Evas_Object_Box".
+ * @param prefix Prefix used for all variables and functions defined
+ * and referenced by this macro
+ * @param api_type Type of the structure used as API for the smart class \n
+ * Either #Evas_Smart_Class or something derived from it.
+ * @param parent_type Type of the parent class API
+ * @param parent_func Function that gets the parent class \n
+ * For example, evas_object_box_smart_class_get().
+ * @param cb_desc Array of callback descriptions for this smart class
+ */
+#define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \
+ static const parent_type * prefix##_parent_sc = NULL; \
+ static void prefix##_smart_set_user(api_type * api); \
+ static void prefix##_smart_set(api_type * api) \
+ { \
+ Evas_Smart_Class *sc; \
+ if (!(sc = (Evas_Smart_Class *)api)) \
+ return; \
+ if (!prefix##_parent_sc) \
+ prefix##_parent_sc = parent_func(); \
+ evas_smart_class_inherit(sc, prefix##_parent_sc); \
+ prefix##_smart_set_user(api); \
+ } \
+ static Evas_Smart *prefix##_smart_class_new(void) \
+ { \
+ static Evas_Smart *smart = NULL; \
+ static api_type api; \
+ if (!smart) \
+ { \
+ Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
+ memset(&api, 0, sizeof(api_type)); \
+ sc->version = EVAS_SMART_CLASS_VERSION; \
+ sc->name = smart_name; \
+ sc->callbacks = cb_desc; \
+ prefix##_smart_set(&api); \
+ smart = evas_smart_class_new(sc); \
+ } \
+ return smart; \
+ }
+
+/**
+ * @def EVAS_SMART_SUBCLASS_IFACE_NEW
+ *
+ * @brief Convenience macro to subclass a given Evas smart class. This is the
+ * same as #EVAS_SMART_SUBCLASS_NEW, but <b>declares smart
+ * interfaces</b> besides the smart callbacks.
+ *
+ * @details This macro saves some typing when writing a smart class derived
+ * from another one. In order to work, the user @b must provide some
+ * functions adhering to the following guidelines:
+ * - @<prefix@>_smart_set_user(): The @b internal @c _smart_set
+ * function (defined by this macro) calls this one, provided by
+ * the user, after inheriting everything from the parent, which
+ * should <b>take care of setting the right member functions for
+ * the class</b>, both overrides and extensions, if any.
+ * - If this new class should be subclassable as well, a @b public
+ * @c _smart_set() function is desirable to fill in the class used as
+ * parent by the children. It is up to the user to provide this
+ * interface, which most likely calls @<prefix@>_smart_set() to
+ * get the job done.
+ *
+ * After the macro's usage, the following is defined for use:
+ * - @<prefix@>_parent_sc: A pointer to the @b parent smart
+ * class. When calling parent functions from overloaded ones, use
+ * this global variable.
+ * - @<prefix@>_smart_class_new(): This function returns the
+ * #Evas_Smart needed to create smart objects with this class,
+ * which should be passed to evas_object_smart_add().
+ *
+ * @since 1.7
+ *
+ * @remarks @a smart_name has to be a pointer to a globally available
+ * string. The smart class created here just has a pointer set
+ * to that, and all object instances depend on it for smart class
+ * name lookup.
+ *
+ * @param smart_name The name used for the smart class \n
+ * For example, @c "Evas_Object_Box".
+ * @param prefix Prefix used for all variables and functions defined
+ * and referenced by this macro
+ * @param api_type Type of the structure used as API for the smart class
+ * Either #Evas_Smart_Class or something
+ * derived from it.
+ * @param parent_type Type of the parent class API
+ * @param parent_func Function that gets the parent class \n
+ * For example, evas_object_box_smart_class_get().
+ * @param cb_desc Array of smart callback descriptions for this smart class
+ * @param ifaces Array of Evas smart interfaces for this smart class
+ */
+#define EVAS_SMART_SUBCLASS_IFACE_NEW(smart_name, \
+ prefix, \
+ api_type, \
+ parent_type, \
+ parent_func, \
+ cb_desc, \
+ ifaces) \
+ static const parent_type * prefix##_parent_sc = NULL; \
+ static void prefix##_smart_set_user(api_type * api); \
+ static void prefix##_smart_set(api_type * api) \
+ { \
+ Evas_Smart_Class *sc; \
+ if (!(sc = (Evas_Smart_Class *)api)) \
+ return; \
+ if (!prefix##_parent_sc) \
+ prefix##_parent_sc = parent_func(); \
+ evas_smart_class_inherit(sc, prefix##_parent_sc); \
+ prefix##_smart_set_user(api); \
+ } \
+ static Evas_Smart *prefix##_smart_class_new(void) \
+ { \
+ static Evas_Smart *smart = NULL; \
+ static api_type api; \
+ if (!smart) \
+ { \
+ Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
+ memset(&api, 0, sizeof(api_type)); \
+ sc->version = EVAS_SMART_CLASS_VERSION; \
+ sc->name = smart_name; \
+ sc->callbacks = cb_desc; \
+ sc->interfaces = ifaces; \
+ prefix##_smart_set(&api); \
+ smart = evas_smart_class_new(sc); \
+ } \
+ return smart; \
+ }
+
+/**
+ * @def EVAS_SMART_DATA_ALLOC
+ *
+ * @brief Convenience macro to allocate smart data only if needed.
+ *
+ * @remarks When writing a subclassable smart object, the @c .add() function
+ * needs to check if the smart private data is already allocated
+ * by some child object or not. This macro makes it easier to do it.
+ *
+ * @remarks This is an idiom used when one calls the parent's @c .add()
+ * after the specialized code. Naturally, the parent's base smart data
+ * has to be contemplated as the specialized one's first member, for
+ * things to work.
+ *
+ * @param o The Evas object passed to the @c .add() function
+ * @param priv_type The type of the data to allocate
+ */
+#define EVAS_SMART_DATA_ALLOC(o, priv_type) \
+ priv_type * priv; \
+ priv = evas_object_smart_data_get(o); \
+ if (!priv) { \
+ priv = (priv_type *)calloc(1, sizeof(priv_type)); \
+ if (!priv) return; \
+ evas_object_smart_data_set(o, priv); \
+ }
+
+/**
+ * @brief Frees an #Evas_Smart struct.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If this smart handle is created using evas_smart_class_new(),
+ * the associated #Evas_Smart_Class is not freed.
+ *
+ * @remarks If you are using the #EVAS_SMART_SUBCLASS_NEW schema to create your
+ * smart object, note that an #Evas_Smart handle is shared amongst all
+ * instances of the given smart class, through a static variable.
+ * Evas internally counts references on #Evas_Smart handles and free them
+ * when they are not referenced any more. Thus, this function is mostly of no use
+ * for Evas users.
+ *
+ * @param[in] s The #Evas_Smart struct to free
+ */
+EAPI void evas_smart_free(Evas_Smart *s) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Creates a new #Evas_Smart from a given #Evas_Smart_Class struct.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks #Evas_Smart handles are necessary to create new @b instances of
+ * smart objects belonging to the class described by @a sc. That
+ * handle contains, besides the smart class interface definition,
+ * all its smart callbacks infrastructure set, too.
+ *
+ * @remarks If you are willing to subclass a given smart class to
+ * construct yours, consider using the #EVAS_SMART_SUBCLASS_NEW macro,
+ * which makes use of this function automatically for you.
+ *
+ * @param[in] sc The smart class definition
+ * @return A new #Evas_Smart pointer
+ */
+EAPI Evas_Smart *evas_smart_class_new(const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets the #Evas_Smart_Class handle of an #Evas_Smart struct.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] s A valid #Evas_Smart pointer
+ * @return The #Evas_Smart_Class
+ */
+EAPI const Evas_Smart_Class *evas_smart_class_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the data pointer set on an #Evas_Smart struct.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This data pointer is set as the data field in the #Evas_Smart_Class
+ * passed in to evas_smart_class_new().
+ *
+ * @param[in] s A valid #Evas_Smart handle
+ */
+EAPI void *evas_smart_data_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the smart callbacks known by this #Evas_Smart handle's smart
+ * class hierarchy.
+ *
+ * @details This function is likely different from
+ * evas_object_smart_callbacks_descriptions_get() as it contains
+ * the callbacks of @b all this class hierarchy sorted, while the
+ * direct smart class member refers only to that specific class and
+ * should not include the parent's.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If no callbacks are known, this function returns @c NULL.
+ *
+ * @remarks The array elements and thus their contents are @b references to
+ * original values given to evas_smart_class_new() as
+ * Evas_Smart_Class::callbacks.
+ *
+ * @remarks The array is sorted by Evas_Smart_Cb_Description::name. The last
+ * array element is a @c NULL pointer and is not accounted for in @a
+ * count. Loop iterations can check any of these size indicators.
+ *
+ * @remarks Objects may provide per-instance callbacks. Use
+ * evas_object_smart_callbacks_descriptions_get() to get those
+ * as well.
+ *
+ * @param[in] s A valid #Evas_Smart handle.
+ * @param[out] count The number of elements in the returned array
+ * @return The array with callback descriptions known by this smart
+ * class, with its size returned in @a count parameter \n
+ * It should not be modified in any way. If no callbacks are
+ * known, @c NULL is returned. The array is sorted by event
+ * names and elements refer to the original values given to
+ * evas_smart_class_new()'s Evas_Smart_Class::callbacks
+ * (pointer to them).
+ *
+ * @see evas_object_smart_callbacks_descriptions_get()
+ */
+EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1);
+
+/**
+ * @brief Finds a callback description for the callback named @a name.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] s The #Evas_Smart where to search for class registered smart
+ * event callbacks
+ * @param[in] name The name of the desired callback, which must @b not be @c
+ * NULL. The search has a special case for @a name being the
+ * same pointer as registered with #Evas_Smart_Cb_Description.
+ * You can use it to avoid excessive use of strcmp().
+ * @return A reference to the description if found, \n
+ * otherwise @c NULL if no description is found
+ *
+ * @see evas_smart_callbacks_descriptions_get()
+ */
+EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * brief Sets one class to inherit from the other.
+ *
+ * @since_tizen 2.3
+ * everything after sizeof(Evas_Smart_Class) present in @a parent_sc,
+ * using @a parent_sc_size as reference.
+ *
+ * @remarks This is recommended instead of a single memcpy() since it takes
+ * care to not modify @a sc name, version, callbacks and possible
+ * other members.
+ *
+ * @param[in] sc The child class
+ * @param[in] parent_sc The parent class, provides attributes
+ * @param[in] parent_sc_size The size of parent_sc structure \n
+ * The child should be at least this size. \n
+ * Everything after @c Evas_Smart_Class size is copied
+ * using regular memcpy().
+ */
+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);
+
+/**
+ * @brief Gets the number of users of the smart instance.
+ *
+ * @details This function tells you how many more uses of the smart instance are in
+ * existence. This should be used before freeing or clearing any of the
+ * Evas_Smart_Class that is used to create the smart instance. The smart
+ * instance refers to data in the Evas_Smart_Class used to create it and
+ * thus you cannot remove the original data until all users of it are gone.
+ * When the usage count goes to @c 0, you can evas_smart_free() the smart
+ * instance @a s and remove from memory any of the Evas_Smart_Class that
+ * is used to create the smart instance, if you desire. Removing it from
+ * memory without doing this causes problems (crashes, undefined
+ * behavior, and so on). So either never remove the original
+ * Evas_Smart_Class data from memory (have it be a constant structure and
+ * data), or use this API call and be very careful.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] s The Evas_Smart to get the usage count of
+ * @return The number of uses of the smart instance
+ */
+EAPI int evas_smart_usage_get(const Evas_Smart *s);
+
+/**
+ * @def evas_smart_class_inherit
+ * @brief Easy to use version of evas_smart_class_inherit_full().
+ *
+ * @remarks This version uses sizeof(parent_sc), copying everything.
+ *
+ * @param sc The child class \n
+ * It has methods copied from @a parent_sc.
+ * @param parent_sc The parent class \n
+ * It provides contents to be copied.
+ * @return @c 1 if everything is copied successfully, \n
+ * otherwise @c 0 on failure
+ * @ingroup Evas_Smart_Group
+ */
+#define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, (Evas_Smart_Class *)parent_sc, sizeof(*parent_sc))
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Smart_Object_Group Smart Object Functions
+ @ingroup Evas_Object_Group
+ *
+ * @brief This group provides functions dealing with Evas smart objects (instances).
+ *
+ * Smart objects are groupings of primitive Evas objects that behave
+ * as a cohesive group. For instance, a file manager icon may be a
+ * smart object composed of an image object, a text label, and two
+ * rectangles that appear behind the image and text when the icon is
+ * selected. As a smart object, the normal Evas object API could be
+ * used on the icon object.
+ *
+ * Besides that, generally smart objects implement a <b>specific
+ * API</b>, so that users interact with its own custom features. The
+ * API takes the form of explicit exported functions one may call and
+ * <b>smart callbacks</b>.
+ *
+ * @section Evas_Smart_Object_Group_Callbacks Smart events and callbacks
+ *
+ * Smart objects can elect events (smart events, from now on) occurring
+ * inside of them to be reported back to their users via callback
+ * functions (smart callbacks). This way, you can extend Evas' own
+ * object events. They are defined by an <b>event string</b>, which
+ * identifies them uniquely. There is also a function prototype
+ * definition for the callback functions: Evas_Smart_Cb.
+ *
+ * When defining an #Evas_Smart_Class, smart object implementors are
+ * strongly encouraged to properly set the Evas_Smart_Class::callbacks
+ * callbacks description array, so that the users of the smart object
+ * can have introspection on its events API <b>at run time</b>.
+ *
+ * @internal
+ * @see @ref Evas_Smart_Group for class definitions.
+ * @endinternal
+ *
+ * @{
+ */
+
+/**
+ * @brief Instantiates a new smart object described by @a s.
+ *
+ * @details This is the function that you should use when defining the public
+ * function @b adding an instance of the new smart object to a given
+ * canvas.
+ * @internal
+ * It takes care of setting all of its internals to work
+ * as they should, if the user set things properly, like
+ * #EVAS_SMART_SUBCLASS_NEW, for example.
+ * @endinternal
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The canvas on which to add the object
+ * @param[in] s The #Evas_Smart describing the smart object
+ * @return A new #Evas_Object handle
+ */
+EAPI Evas_Object *evas_object_smart_add(Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC;
+
+/**
+ * @brief Sets an Evas object as a member of a given smart object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Members are automatically stacked and layered together with the
+ * smart object. The various stacking functions operate on
+ * members relative to the other members instead of the entire canvas,
+ * since they now live on an exclusive layer (see
+ * evas_object_stack_above(), for more details).
+ *
+ * @remarks Any @a smart_obj object's specific implementation of the @c
+ * member_add() smart function takes place too, naturally.
+ *
+ * @param[in] obj The member object
+ * @param[in] smart_obj The smart object
+ *
+ * @see evas_object_smart_member_del()
+ * @see evas_object_smart_members_get()
+ */
+EAPI void evas_object_smart_member_add(Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes a member object from a given smart object.
+ *
+ * @details This function removes a member object from a smart object, if it is added
+ * to any. The object is still on the canvas, but no longer
+ * associated with whichever smart object it is associated with.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The member object
+ *
+ * @see evas_object_smart_member_add() for more details
+ * @see evas_object_smart_members_get()
+ */
+EAPI void evas_object_smart_member_del(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the list of the member objects of a given Evas smart object.
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The returned list should be freed with @c eina_list_free() when you
+ * no longer need it.
+ *
+ * @param[in] obj The smart object to get members from
+ * @return The list of the member objects of @a obj, \n
+ * otherwise @c NULL when a non-smart object is passed
+ *
+ * @see evas_object_smart_member_add()
+ * @see evas_object_smart_member_del()
+ */
+EAPI Eina_List *evas_object_smart_members_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the parent smart object of a given Evas object, if it has one.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The Evas object to get the parent smart object from
+ * @return The parent smart object of @a obj \n
+ * otherwise @c NULL if @a obj is not a smart member of any Evas object
+ */
+EAPI Evas_Object *evas_object_smart_parent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether a given smart object or any of its smart object
+ * parents is of a given smart class.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @a obj is not a smart object, this call fails
+ * immediately. Otherwise, make sure evas_smart_class_inherit() or its
+ * sibling functions were used correctly when creating the smart
+ * object's class, so it has a valid @b parent smart class pointer set.
+ *
+ * @remarks The checks use smart classes names and <b>string
+ * comparison</b>. There is a version of this same check using
+ * <b>pointer comparison</b>, since a smart class' name is a single
+ * string in Evas.
+ *
+ * @param[in] obj An Evas smart object to check the type of
+ * @param[in] type The @b name (type) of the smart class to check for
+ * @return #EINA_TRUE if @a obj or any of its parents is of type @a type, \n
+ * otherwise #EINA_FALSE
+ *
+ * @see evas_object_smart_type_check_ptr()
+ * @internal
+ * @see #EVAS_SMART_SUBCLASS_NEW
+ * @endinternal
+ */
+EAPI Eina_Bool evas_object_smart_type_check(const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @internal
+ * @brief Checks whether a given smart object or any of its smart object
+ * parents is of a given smart class, <b>using pointer comparison</b>.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj An Evas smart object to check the type of
+ * @param[in] type The type (name string) to check for \n
+ * Must be the name.
+ * @return #EINA_TRUE if @a obj or any of its parents is of type @a type, \n
+ * otherwise #EINA_FALSE
+ *
+ * @see evas_object_smart_type_check() for more details
+ *
+ * @ingroup Evas_Smart_Object_Group
+ */
+EAPI Eina_Bool evas_object_smart_type_check_ptr(const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @internal
+ * @brief Gets the #Evas_Smart from which @a obj smart object is created.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj A smart object
+ * @return The #Evas_Smart handle, \n
+ * otherwise @c NULL on errors
+ */
+EAPI Evas_Smart *evas_object_smart_smart_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the user data stored on a given smart object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The smart object's handle
+ * @return A pointer to data stored using evas_object_smart_data_set(), \n
+ * otherwise @c NULL if none has been set
+ *
+ * @see evas_object_smart_data_set()
+ */
+EAPI void *evas_object_smart_data_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets a pointer to the user data for a given smart object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This data is stored @b independently of the one set by
+ * evas_object_data_set(), naturally.
+ *
+ * @param[in] obj The smart object's handle
+ * @param[in] data A pointer to user data
+ *
+ * @see evas_object_smart_data_get()
+ */
+EAPI void evas_object_smart_data_set(Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Adds or registers a callback function to the smart event specified by
+ * @a event on the smart object @a obj.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Smart callbacks look very similar to Evas callbacks, but are
+ * implemented as smart object's custom ones.
+ *
+ * @remarks This function adds a function callback to an smart object when the
+ * event named @a event occurs in it. The function is @a func.
+ *
+ * @remarks In the event of a memory allocation error during addition of the
+ * callback to the object, evas_alloc_error() should be used to
+ * determine the nature of the error, if any, and the program should
+ * sensibly try and recover.
+ *
+ * @remarks A smart callback function must have the ::Evas_Smart_Cb prototype
+ * definition. The first parameter (@a data) in this definition
+ * has the same value passed to evas_object_smart_callback_add() as
+ * the @a data parameter, at runtime. The second parameter @a obj is a
+ * handle to the object on which the event occurred. The third
+ * parameter, @a event_info, is a pointer to data which is totally
+ * dependent on the smart object's implementation and semantic for the
+ * given event.
+ *
+ * @remarks There is an infrastructure for introspection on smart objects'
+ * events (see evas_smart_callbacks_descriptions_get()), but no
+ * internal smart objects on Evas implement them yet.
+ *
+ * @remarks The event's name strings are implemented by each smart object.
+ * Please refer the documentation of a smart object which you are
+ * insterested in.
+ *
+ * @param[in] obj A smart object
+ * @param[in] event The event's name string
+ * @param[in] func The callback function
+ * @param[in] data The user data to be passed to the callback function
+ *
+ * @see @ref Evas_Smart_Object_Group_Callbacks for more details.
+ *
+ * @see evas_object_smart_callback_del()
+ */
+EAPI void evas_object_smart_callback_add(Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1, 2, 3);
+
+/**
+ * @internal
+ * @brief Adds or registers a callback function to the smart event specified by
+ * @a event on the smart object @a obj.
+ *
+ * @details Except for the priority field, it is exactly the same as @ref evas_object_smart_callback_add.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj A smart object
+ * @param[in] event The event's name string
+ * @param[in] priority The priority of the callback \n
+ * Lower values are called first.
+ * @param[in] func The callback function
+ * @param[in] data The user data to be passed to the callback function
+ *
+ * @see evas_object_smart_callback_add
+ */
+EAPI void evas_object_smart_callback_priority_add(Evas_Object *obj, const char *event, Evas_Callback_Priority priority, Evas_Smart_Cb func, const void *data);
+
+/**
+ * @brief Deletes or unregisters a callback function from the smart event
+ * specified by @a event on the smart object @a obj.
+ *
+ * @details This function removes <b>the first</b> added smart callback on the
+ * object @a obj matching the event name @a event and the registered
+ * function pointer @a func. If the removal is successful it also
+ * returns the data pointer that is passed to
+ * evas_object_smart_callback_add() (that is the same as the
+ * parameter) when the callback(s) is(are) added to the canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj A smart object
+ * @param[in] event The event's name string
+ * @param[in] func The callback function
+ * @return The data pointer, \n
+ * otherwise @c NULL if it is not successful
+ *
+ * @see evas_object_smart_callback_add() for more details.
+ */
+EAPI void *evas_object_smart_callback_del(Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3);
+
+/**
+ * @brief Deletes or unregisters a callback function from the smart event
+ * specified by @a event on the smart object @a obj.
+ *
+ * @details This function removes <b>the first</b> added smart callback on the
+ * object @a obj matching the event name @a event, the registered
+ * function pointer @a func and the callback data pointer @a data. If
+ * the removal is successful, it also returns the data pointer that
+ * is passed to evas_object_smart_callback_add() (that is the same
+ * as the parameter) when the callback(s) is(are) added to the canvas.
+ * If not successful @c NULL is returned. A common use would be to
+ * remove an exact match of a callback
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks To delete all smart event callbacks which match @a type and @a func,
+ * use evas_object_smart_callback_del().
+ *
+ * @param[in] obj A smart object
+ * @param[in] event The event's name string
+ * @param[in] func The callback function
+ * @param[in] data The data pointer that is passed to the callback
+ * @return The data pointer
+ *
+ * @see evas_object_smart_callback_add() for more details.
+ */
+EAPI void *evas_object_smart_callback_del_full(Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1, 2, 3);
+
+/**
+ * @brief Calls a given smart callback on the smart object @a obj.
+ *
+ * @details This function should be called @b internally, from the smart object's own
+ * code, when some specific event has occurred and the implementor
+ * wants to listen to the object's events API (see @ref
+ * Evas_Smart_Object_Group_Callbacks). The documentation for the smart
+ * object should include a list of possible events and what type of @a
+ * event_info to expect for each of them. Also, when defining an
+ * #Evas_Smart_Class, smart object implementors are strongly
+ * encouraged to properly set the Evas_Smart_Class::callbacks
+ * callbacks description array, so that the users of the smart object
+ * can have introspection on its events API <b>at run time</b>.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The smart object
+ * @param[in] event The event's name string
+ * @param[in] event_info The pointer to an event specific struct or information to
+ * pass to the callback functions registered on this smart event
+ */
+EAPI void evas_object_smart_callback_call(Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets an smart object @b instance's smart callbacks descriptions.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks These descriptions are hints to be used by introspection and are
+ * not enforced in any way.
+ *
+ * @remarks It is not checked if instance callbacks descriptions have the
+ * same name as respective possibly registered in the smart object
+ * @b class. Both are kept in different arrays and users of
+ * evas_object_smart_callbacks_descriptions_get() should handle this
+ * case as they wish.
+ *
+ * @remarks Because @a descriptions must be @c NULL terminated, and
+ * because a @c NULL name makes little sense, too,
+ * Evas_Smart_Cb_Description::name must @b not be @c NULL.
+ *
+ * @remarks While instance callbacks descriptions are possible, they are
+ * @b not recommended. Use @b class callbacks descriptions
+ * instead as they make it easier for you to use smart objects
+ * and use less memory, as descriptions and arrays are
+ * shared among all instances.
+ *
+ * @param[in] obj A smart object
+ * @param[in] descriptions @c NULL terminated array with #Evas_Smart_Cb_Description descriptions \n
+ * Array elements are not modified at run time, but references to
+ * them and their contents are made, so this array should be kept
+ * alive during the whole object's lifetime.
+ * @return #EINA_TRUE if the descriptions are set successfully,
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets a smart object's smart callback descriptions (both
+ * instance and class ones).
+ *
+ * @details This function searches for registered callback descriptions for both
+ * instance and class of the given smart object. These arrays are
+ * sorted by Evas_Smart_Cb_Description::name and also @c NULL
+ * terminated, so both @a class_count and @a instance_count can be
+ * ignored, if the caller wishes so. The terminator @c NULL is not
+ * counted in these values.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If just class descriptions are of interest, try
+ * evas_smart_callbacks_descriptions_get() instead.
+ *
+ * @remarks Use @c NULL pointers on the descriptions or counters that you are not
+ * interested in: they are ignored by the function.
+ *
+ * @param[in] obj The smart object to get callback descriptions from
+ * @param[in] class_descriptions The class callbacks descriptions array, if any, that is returned \n
+ * If no descriptions are known, @c NULL is returned.
+ * @param[in] class_count The number of class callbacks descriptions, that is returned
+ * @param[in] instance_descriptions The instance callbacks descriptions array, if any, that is returned \n
+ * If no descriptions are known, @c NULL is returned.
+ * @param[in] instance_count The number of instance callbacks descriptions, that is returned
+ *
+ * @see evas_smart_callbacks_descriptions_get()
+ */
+EAPI void evas_object_smart_callbacks_descriptions_get(const Evas_Object *obj, const Evas_Smart_Cb_Description ***class_descriptions, unsigned int *class_count, const Evas_Smart_Cb_Description ***instance_descriptions, unsigned int *instance_count) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Finds the callback description for callback called @a name.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The smart object
+ * @param[in] name The name of desired callback, \n
+ * This must @b not be @c NULL. The search has a special case
+ * for @a name being the same pointer as registered with
+ * Evas_Smart_Cb_Description; you can use it to avoid excessive
+ * use of strcmp().
+ * @param[in] class_description The pointer to return class description or @c NULL, if not found \n
+ * If parameter is @c NULL, no search is done on class descriptions.
+ * @param[in] instance_description The pointer to return instance description or @c NULL if not found \n
+ * If parameter is @c NULL, no search is done on instance descriptions.
+ * @return The reference to description if found, \n
+ * otherwise @c NULL if not found
+ */
+EAPI void evas_object_smart_callback_description_find(const Evas_Object *obj, const char *name, const Evas_Smart_Cb_Description **class_description, const Evas_Smart_Cb_Description **instance_description) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @internal
+ * @brief Gets an Evas smart object's interface, by name string pointer.
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj An Evas smart object.
+ * @param[in] name The name string of the desired interface \n
+ * This must be the same pointer used at the interface's declaration,
+ * when creating the smart object @a obj.
+ * @return The interface's handle pointer, \n
+ * otherwise @c NULL if not found
+ */
+EAPI const void *evas_object_smart_interface_get(const Evas_Object *obj, const char *name);
+
+/**
+ * @internal
+ * @brief Gets an Evas smart object interface's <b>private data</b>.
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj An Evas smart object
+ * @param[in] iface The given object's interface handle
+ * @return The object interface's private data blob pointer, \n
+ * otherwise @c NULL if not found
+ */
+EAPI void *evas_object_smart_interface_data_get(const Evas_Object *obj, const Evas_Smart_Interface *iface);
+
+/**
+ * @brief Marks smart object as changed, dirty.
+ *
+ * @details This function flags the given object as needing recalculation,
+ * forcefully. As an effect, on the next rendering cycle its @b
+ * calculate() (see #Evas_Smart_Class) smart function is called.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The given Evas smart object
+ *
+ * @see evas_object_smart_need_recalculate_set().
+ * @see evas_object_smart_calculate().
+ */
+EAPI void evas_object_smart_changed(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Sets or unsets the flag signalling that a given smart object needs to
+ * get recalculated.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If this flag is set, then the @c calculate() smart function of @a
+ * obj is called, if one is provided, during rendering phase of
+ * Evas (see evas_render()), after which this flag is
+ * automatically unset.
+ *
+ * @remarks If that smart function is not provided for the given object, this
+ * flag is left unchanged.
+ *
+ * @remarks Just setting this flag does not make the canvas' whole scene
+ * dirty, by itself, and evas_render() has no effect. To
+ * force that, use evas_object_smart_changed(), that also
+ * automatically calls this function, with
+ * #EINA_TRUE as parameter.
+ *
+ * @param[in] obj The smart object
+ * @param[in] value Set #EINA_TRUE to recalculate the smart object, \n
+ * otherwise set #EINA_FALSE to not recalculate the smart object
+ *
+ * @see evas_object_smart_need_recalculate_get()
+ * @see evas_object_smart_calculate()
+ * @see evas_smart_objects_calculate()
+ */
+EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Gets the value of the flag signalling that a given smart object needs to
+ * get recalculated.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This flag is unset during the rendering phase, when the
+ * @c calculate() smart function is called, if one is provided.
+ * If it is not provided, then the flag is left unchanged
+ * after the rendering phase.
+ *
+ * @param[in] obj The smart object
+ * @return #EINA_TRUE if flag is set to recalculate, \n
+ * otherwise #EINA_FALSE if flag is not set to recalculate
+ *
+ * @see evas_object_smart_need_recalculate_set()
+ */
+EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Calls the @b calculate() smart function immediately on a given smart object.
+ *
+ * @details This function forces immediate calculations (see #Evas_Smart_Class)
+ * needed for rendering of this object and, besides, unset the
+ * flag on it telling it needs recalculation for the next rendering phase.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] obj The smart object's handle
+ *
+ * @see evas_object_smart_need_recalculate_set()
+ */
+EAPI void evas_object_smart_calculate(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Calls user-provided @c calculate() smart functions and unset the
+ * flag signalling that the object needs to get recalculated to @b all
+ * smart objects in the canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The canvas to calculate all smart objects in
+ *
+ * @see evas_object_smart_need_recalculate_set()
+ */
+EAPI void evas_smart_objects_calculate(Evas *e);
+
+/**
+ * @brief Gets the internal counter that counts the number of smart calculations.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Whenever evas performs smart object calculations on the whole canvas
+ * it increments a counter by @c 1. This is the smart object calculate counter
+ * that this function returns the value of. It starts at the value of @c 0 and
+ * increases (and eventually wrap around to negative values and so on) by
+ * @c 1 every time objects are calculated. You can use this counter to ensure
+ * that you do not re-do calculations within the same calculation generation or run
+ * if the calculations maybe cause self-feeding effects.
+ *
+ * @param[in] e The canvas to get the calculate counter from
+ * @return The number of smart calculations
+ */
+EAPI int evas_smart_objects_calculate_count_get(const Evas *e);
+
+/**
+ * @internal
+ * @brief Moves all children objects of a given smart object relative to a
+ * given offset.
+ *
+ * @details This function makes each of @a obj object's children to move, from where
+ * they before, with those delta values (offsets) on both directions.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is most useful on custom smart @c move() functions.
+ *
+ * @remarks Clipped smart objects already make use of this function on
+ * their @c move() smart function definition.
+ *
+ * @param[in] obj The smart object
+ * @param[in] dx The horizontal offset (delta)
+ * @param[in] dy The vertical offset (delta)
+ */
+EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object
+ * @ingroup Evas_Smart_Object_Group
+ *
+ * @brief This group provides functions for clipped smart objects.
+ *
+ * Clipped smart object is a base to construct other smart objects
+ * based on the concept of having an internal clipper that is applied
+ * to all children objects. This clipper controls the visibility,
+ * clipping and color of sibling objects (remember that the clipping
+ * is recursive, and clipper color modulates the color of its
+ * clippees). By default, this base also moves children relatively
+ * to the parent, and delete them when parent is deleted. In other
+ * words, it is the base for simple object grouping.
+ *
+ * @see evas_object_smart_clipped_smart_set()
+ *
+ * @{
+ */
+
+/**
+ * @brief The strcuture type that every subclass should provide this at the beginning of their own
+ * data set with evas_object_smart_data_set().
+ */
+typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data;
+struct _Evas_Object_Smart_Clipped_Data
+{
+ Evas_Object *clipper;
+ Evas *evas;
+};
+
+/**
+ * @brief Gets the clipper object for the given clipped smart object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Use this function if you want to change any of this clipper's
+ * properties, like colors.
+ *
+ * @param[in] obj The clipped smart object to retrieve associated clipper from
+ * @return The clipper object
+ *
+ * @see evas_object_smart_clipped_smart_add()
+ */
+EAPI Evas_Object *evas_object_smart_clipped_clipper_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Sets a given smart class' callbacks so it implements the <b>clipped smart
+ * object</b>'s interface.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This call assigns all the required methods of the @a sc
+ * #Evas_Smart_Class instance to the implementations set for clipped
+ * smart objects. If one wants to "subclass" it, call this function
+ * and then override desired values. If one wants to call any original
+ * method, save it somewhere.
+ *
+ * @remarks The following is an example:
+ *
+ * @code
+ * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL;
+ *
+ * static void my_class_smart_add(Evas_Object *o)
+ * {
+ * parent_sc.add(o);
+ * evas_object_color_set(evas_object_smart_clipped_clipper_get(o),
+ * 255, 0, 0, 255);
+ * }
+ *
+ * Evas_Smart_Class *my_class_new(void)
+ * {
+ * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass");
+ * if (!parent_sc.name)
+ * {
+ * evas_object_smart_clipped_smart_set(&sc);
+ * parent_sc = sc;
+ * sc.add = my_class_smart_add;
+ * }
+ * return &sc;
+ * }
+ * @endcode
+ *
+ * @remarks The default behavior for each of #Evas_Smart_Class functions on a
+ * clipped smart object are:
+ * - @c add: creates a hidden clipper with "infinite" size, to clip any incoming members;
+ * - @c del: delete all children objects;
+ * - @c move: move all objects relative relatively;
+ * - @c resize: <b>not defined</b>;
+ * - @c show: if there are children objects, show clipper;
+ * - @c hide: hides clipper;
+ * - @c color_set: set the color of clipper;
+ * - @c clip_set: set clipper of clipper;
+ * - @c clip_unset: unset the clipper of clipper;
+ *
+ * @remarks There are other means of assigning parent smart classes to
+ * child ones, like the #EVAS_SMART_SUBCLASS_NEW macro or the
+ * evas_smart_class_inherit_full() function.
+ *
+ * @param[in] sc The smart class handle to operate on
+ */
+EAPI void evas_object_smart_clipped_smart_set(Evas_Smart_Class *sc) EINA_ARG_NONNULL(1);
+
+/**
+ * @internal
+ * @brief Gets a pointer to the <b>clipped smart object's</b> class, to use
+ * for proper inheritance.
+ *
+ * @since_tizen 2.3
+ *
+ * @see #Evas_Smart_Object_Clipped for more information on this smart class.
+ */
+EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get(void) EINA_CONST;
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Box Box Smart Object
+ * @ingroup Evas_Smart_Object_Group
+ *
+ * @brief This group provides functions for bos smart objects.
+ *
+ * A box is a convenience smart object that packs children inside it
+ * in @b sequence, using a layouting function specified by the
+ * user. There are a couple of pre-made layouting functions <b>built-in
+ * in Evas</b>, all of them using children size hints to define their
+ * size and alignment inside their cell space.
+ *
+ * @see @ref Evas_Object_Group_Size_Hints
+ *
+ * @{
+ */
+
+/**
+ * @typedef Evas_Object_Box_Api
+ *
+ * @brief The structure type containing the smart class extension, providing extra box object requirements.
+ */
+typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api;
+
+/**
+ * @typedef Evas_Object_Box_Data
+ *
+ * @brief The structure type containing the smart object instance data, providing box object requirements.
+ */
+typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data;
+
+/**
+ * @typedef Evas_Object_Box_Option
+ *
+ * @brief The structure type containing the base structure for a box option.
+ * Box options are a way of extending box items properties, which are taken into account
+ * for layouting decisions. The box layouting functions provided by
+ * Evas only relies on objects' canonical size hints to layout
+ * them, so the basic box option has @b no (custom) property set.
+ *
+ * Users creating their own layouts, but not depending on extra child
+ * items' properties, would be fine just using
+ * evas_object_box_layout_set(). But if one desires a layout depending
+ * on extra child properties, he or she has to @b subclass the box smart
+ * object. Thus, by using evas_object_box_smart_class_get() and
+ * evas_object_box_smart_set(), the @c option_new() and @c
+ * option_free() smart class functions should be properly
+ * redefined or extended.
+ *
+ * Object properties are bound to an integer identifier and must have
+ * a name string. Their values are open to any data. See the API on
+ * option properties for more details.
+ */
+typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option;
+
+/**
+ * @typedef Evas_Object_Box_Layout
+ *
+ * @brief Called for the function signature for an Evas box object layouting routine.
+ * @a o is the box object in question, @a priv is the box's internal data
+ * and, @a user_data is any custom data you could have set to
+ * a given box layouting function, with evas_object_box_layout_set().
+ */
+typedef void (*Evas_Object_Box_Layout)(Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data);
+
+/**
+ * @def EVAS_OBJECT_BOX_API_VERSION
+ *
+ * @brief Definition of the current version for Evas box object smart class, a value which goes
+ * to _Evas_Object_Box_Api::version.
+ */
+#define EVAS_OBJECT_BOX_API_VERSION 1
+
+/**
+ * @struct _Evas_Object_Box_Api
+ *
+ * @brief The structure type that should be used by any smart class inheriting from
+ * the box's one, to provide custom box behavior which could not be
+ * achieved only by providing a layout function, with evas_object_box_layout_set().
+ *
+ * @extends Evas_Smart_Class
+ */
+struct _Evas_Object_Box_Api
+{
+ Evas_Smart_Class base; /**< Base smart class struct, need for all smart objects */
+ int version; /**< Version of this smart class definition */
+ Evas_Object_Box_Option *(*append)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to append child elements in boxes */
+ Evas_Object_Box_Option *(*prepend)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to prepend child elements in boxes */
+ 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 */
+ 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 */
+ 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 */
+ Evas_Object *(*remove)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to remove a child element from boxes */
+ 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 */
+ 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 */
+ 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 */
+ const char *(*property_name_get)(const Evas_Object * o, int property); /**< Smart function to get the name of a custom property of box children */
+ 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 */
+ 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 */
+ void (*option_free)(Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt); /**< Smart function to delete a box option struct */
+};
+
+/**
+ * @def EVAS_OBJECT_BOX_API_INIT
+ *
+ * @brief Definition for initializing for a whole #Evas_Object_Box_Api structure, with
+ * @c NULL values on its specific fields.
+ *
+ * @param smart_class_init The initializer to use for the "base" field
+ * (#Evas_Smart_Class)
+ *
+ * @see EVAS_SMART_CLASS_INIT_NULL
+ * @see EVAS_SMART_CLASS_INIT_VERSION
+ * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
+ * @see EVAS_OBJECT_BOX_API_INIT_NULL
+ * @see EVAS_OBJECT_BOX_API_INIT_VERSION
+ * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
+ */
+#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}
+
+/**
+ * @def EVAS_OBJECT_BOX_API_INIT_NULL
+ *
+ * @brief Definition for initializing to zero out a whole #Evas_Object_Box_Api structure.
+ *
+ * @see EVAS_OBJECT_BOX_API_INIT_VERSION
+ * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
+ * @see EVAS_OBJECT_BOX_API_INIT
+ */
+#define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL)
+
+/**
+ * @def EVAS_OBJECT_BOX_API_INIT_VERSION
+ *
+ * @brief Definition for initializing to zero out a whole #Evas_Object_Box_Api structure and
+ * set a specific version on it.
+ *
+ * @remarks This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it sets
+ * the version field of #Evas_Smart_Class (base field) to the latest
+ * EVAS_SMART_CLASS_VERSION.
+ *
+ * @see EVAS_OBJECT_BOX_API_INIT_NULL
+ * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
+ * @see EVAS_OBJECT_BOX_API_INIT
+ */
+#define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION)
+
+/**
+ * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION
+ *
+ * @brief Definition for initializing to zero out a whole #Evas_Object_Box_Api structure and
+ * set its name and version.
+ *
+ * @remarks This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it also
+ * sets the version field of #Evas_Smart_Class (base field) to the
+ * latest EVAS_SMART_CLASS_VERSION and name it to the specific value.
+ *
+ * @remarks It keeps a reference to the name field as a <c>"const char *"</c>,
+ * i.e., the name must be available while the structure is
+ * used (hint: static or global variable) and must not be modified.
+ *
+ * @see EVAS_OBJECT_BOX_API_INIT_NULL
+ * @see EVAS_OBJECT_BOX_API_INIT_VERSION
+ * @see EVAS_OBJECT_BOX_API_INIT
+ */
+#define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name))
+
+/**
+ * @struct _Evas_Object_Box_Data
+ *
+ * @brief The structure type that augments clipped smart object's instance data,
+ * providing extra members required by generic box implementation. If
+ * a subclass inherits from #Evas_Object_Box_Api, then it may augment
+ * #Evas_Object_Box_Data to fit its own needs.
+ *
+ * @extends Evas_Object_Smart_Clipped_Data
+ */
+struct _Evas_Object_Box_Data
+{
+ Evas_Object_Smart_Clipped_Data base;
+ const Evas_Object_Box_Api *api;
+ struct
+ {
+ double h, v;
+ } align;
+ struct
+ {
+ Evas_Coord h, v;
+ } pad;
+ Eina_List *children;
+ struct
+ {
+ Evas_Object_Box_Layout cb;
+ void *data;
+ void (*free_data)(void *data);
+ } layout;
+ Eina_Bool layouting : 1;
+ Eina_Bool children_changed : 1;
+};
+
+/**
+ * @brief Evas_Object_Box_Option struct fields
+ */
+struct _Evas_Object_Box_Option
+{
+ Evas_Object *obj; /**< Pointer to the box child object, itself */
+ Eina_Bool max_reached : 1;
+ Eina_Bool min_reached : 1;
+ Evas_Coord alloc_size;
+};
+
+/**
+ * @brief Sets the default box @a api struct (Evas_Object_Box_Api)
+ * with the default values. This may be used to extend that API.
+ *
+ * @param api The box API struct to set back, most probably with
+ * overridden fields (on class extensions scenarios)
+ */
+EAPI void evas_object_box_smart_set(Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the Evas box smart class, for inheritance purposes.
+ *
+ * @remarks The returned value is @b not to be modified, just use it as your
+ * parent class.
+ * @return The (canonical) Evas box smart class
+ */
+EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get(void) EINA_CONST;
+
+/**
+ * @brief Sets a new layouting function to a given box object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks A box layout function affects how a box object displays child
+ * elements within its area. The list of pre-defined box layouts
+ * available in Evas is:
+ * - evas_object_box_layout_horizontal()
+ * - evas_object_box_layout_vertical()
+ * - evas_object_box_layout_homogeneous_horizontal()
+ * - evas_object_box_layout_homogeneous_vertical()
+ * - evas_object_box_layout_homogeneous_max_size_horizontal()
+ * - evas_object_box_layout_homogeneous_max_size_vertical()
+ * - evas_object_box_layout_flow_horizontal()
+ * - evas_object_box_layout_flow_vertical()
+ * - evas_object_box_layout_stack()
+ * See each of their documentation texts for details on them.
+ *
+ * @remarks A box layouting function is triggered by the @c
+ * 'calculate' smart callback of the box's smart class.
+ *
+ * @param[in] o The box object to operate on
+ * @param[in] cb The new layout function to set on @a o
+ * @param[in] data The data pointer to be passed to @a cb
+ * @param[in] free_data The function to free @a data, if need be
+ */
+EAPI void evas_object_box_layout_set(Evas_Object *o, Evas_Object_Box_Layout cb, const void *data, void (*free_data)(void *data)) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Adds a new box object on the provided canvas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks After instantiation, if a box object has not its layout function
+ * set, via evas_object_box_layout_set(), it has it by default
+ * set to evas_object_box_layout_horizontal(). The remaining
+ * properties of the box must be set/retrieved via
+ * <c>evas_object_box_{h,v}_{align,padding}_{get,set)()</c>.
+ *
+ * @param[in] evas The canvas to create the box object on
+ * @return A pointer to a new box object, \n
+ * otherwise @c NULL on error
+ */
+EAPI Evas_Object *evas_object_box_add(Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Adds a new box as a @b child of a given smart object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function is a helper function that has the same effect of putting a new
+ * box object into @a parent by use of evas_object_smart_member_add().
+ *
+ * @param[in] parent The parent smart object to put the new box in
+ * @return A pointer to a new box object, \n
+ * otherwise @c NULL on error
+ *
+ * @see evas_object_box_add()
+ */
+EAPI Evas_Object *evas_object_box_add_to(Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Layout function which sets the box @a o to a (basic) horizontal box.
+ *
+ * In this layout, the box object's overall behavior is controlled by
+ * its padding/alignment properties, which are set by the
+ * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
+ * functions. The size hints of the elements in the box -- set by the
+ * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
+ * -- also control the way this function works.
+ *
+ * @par Box's properties:
+ * @c align_h controls the horizontal alignment of the child objects
+ * relative to the containing box. When set to @c 0.0, children are
+ * aligned to the left. A value of @c 1.0 makes them aligned to the
+ * right border. Values in between align them proportionally. Note
+ * that if the size required by the children, which is given by their
+ * widths and the @c padding_h property of the box, is bigger than the
+ * their container's width, the children are displayed out of the
+ * box's bounds. A negative value of @c align_h makes the box to
+ * @b justify its children. The padding between them, in this case, is
+ * corrected so that the leftmost one touches the left border and the
+ * rightmost one touches the right border (even if they must
+ * overlap). The @c align_v and @c padding_v properties of the box
+ * @b do not contribute to its behaviour when this layout is chosen.
+ *
+ * @par Child element's properties:
+ * @c align_x does @b not influence the box's behavior. @c padding_l
+ * and @c padding_r sum up to the container's horizontal padding
+ * between elements. The child's @c padding_t, @c padding_b and
+ * @c align_y properties apply for padding or alignment relative to the
+ * overall height of the box. Finally, there is the @c weight_x
+ * property, which, if set to a non-zero value, tells the container
+ * that the child width is @b not pre-defined. If the container can not
+ * accommodate all its children, it sets the widths of the ones
+ * <b>with weights</b> to sizes as small as they can all fit into
+ * it. If the size required by the children is less than the
+ * available, the box increases its childrens' (which have weights)
+ * widths as to fit the remaining space. The @c weight_x property,
+ * besides telling the element is resizable, gives a @b weight for the
+ * resizing process. The parent box tries to distribute (or take
+ * off) widths accordingly to the @b normalized list of weights: most
+ * weighted children remain or get larger in this process than the least
+ * ones. @c weight_y does not influence the layout.
+ *
+ * If you desire that, besides having weights, child elements must be
+ * resized bounded to a minimum or maximum size, those size hints must
+ * be set, by the <c>evas_object_size_hint_{min,max}_set()</c>
+ * functions.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ */
+EAPI void evas_object_box_layout_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the box @a o to a (basic) vertical box.
+ *
+ * @details This Layout function behaves analogously to
+ * evas_object_box_layout_horizontal(). The description of its
+ * behaviour can be derived from that function's documentation.
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ *
+ * @since_tizen 2.3
+ *
+ */
+EAPI void evas_object_box_layout_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the box @a o to a @b homogeneous vertical box.
+ *
+ * @details This Layout function behaves analogously to
+ * evas_object_box_layout_homogeneous_horizontal(). The description
+ * of its behaviour can be derived from that function's documentation.
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ *
+ * @since_tizen 2.3
+ *
+ */
+EAPI void evas_object_box_layout_homogeneous_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the box @a o to a @b homogeneous horizontal box.
+ *
+ * In a homogeneous horizontal box, its width is divided @b equally
+ * between the contained objects. The box's overall behavior is
+ * controlled by its padding or alignment properties, which are set by
+ * the <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
+ * functions. The size hints the elements in the box -- set by the
+ * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
+ * -- also control the way this function works.
+ *
+ * @par Box's properties:
+ * @c align_h has no influence on the box for this layout.
+ * @c padding_h tells the box to draw empty spaces of that size, in
+ * pixels, between the (equal) child objects' cells. The @c align_v
+ * and @c padding_v properties of the box do not contribute to its
+ * behaviour when this layout is chosen.
+ *
+ * @par Child element's properties:
+ * @c padding_l and @c padding_r sum up to the required width of the
+ * child element. The @c align_x property tells the relative position
+ * of this overall child width in its allocated cell (@c 0.0 to
+ * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to
+ * @c align_x makes the box try to resize this child element to the exact
+ * width of its cell (respecting the minimum and maximum size hints on
+ * the child's width and accounting for its horizontal padding
+ * hints). The child's @c padding_t, @c padding_b and @c align_y
+ * properties apply for padding or alignment relative to the overall
+ * height of the box. A value of @c -1.0 to @c align_y makes the box
+ * try to resize this child element to the exact height of its parent
+ * (respecting the maximum size hint on the child's height).
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ */
+EAPI void evas_object_box_layout_homogeneous_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the box @a o to a <b>maximum size, homogeneous</b> horizontal box
+ *
+ * In a maximum size, homogeneous horizontal box, besides having cells
+ * of <b>equal size</b> reserved for the child objects, this size is
+ * defined by the size of the @b largest child in the box (in
+ * width). The box's overall behavior is controlled by its properties,
+ * which are set by the
+ * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
+ * functions. The size hints of the elements in the box -- set by the
+ * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
+ * -- also control the way this function works.
+ *
+ * @par Box's properties:
+ * @c padding_h tells the box to draw empty spaces of that size, in
+ * pixels, between the child objects' cells. @c align_h controls the
+ * horizontal alignment of the child objects, relative to the
+ * containing box. When set to @c 0.0, children are aligned to the
+ * left. A value of @c 1.0 lets them aligned to the right
+ * border. Values in between align them proportionally. A negative
+ * value of @c align_h makes the box to @b justify its children
+ * cells. The padding between them, in this case, is corrected so that
+ * the leftmost one touches the left border and the rightmost one
+ * touches the right border (even if they must overlap). The
+ * @c align_v and @c padding_v properties of the box do not contribute to
+ * its behaviour when this layout is chosen.
+ *
+ * @par Child element's properties:
+ * @c padding_l and @c padding_r sum up to the required width of the
+ * child element. The @c align_x property tells the relative position
+ * of this overall child width in its allocated cell (@c 0.0 to
+ * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to
+ * @c align_x makes the box try to resize this child element to the exact
+ * width of its cell (respecting the minimum and maximum size hints on
+ * the child's width and accounting for its horizontal padding
+ * hints). The child's @c padding_t, @c padding_b and @c align_y
+ * properties apply for padding/alignment relative to the overall
+ * height of the box. A value of @c -1.0 to @c align_y makes the box
+ * try to resize this child element to the exact height of its parent
+ * (respecting the max hint on the child's height).
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ */
+EAPI void evas_object_box_layout_homogeneous_max_size_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the box @a o to a <b>maximum size, homogeneous</b> vertical box.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function behaves analogously to
+ * evas_object_box_layout_homogeneous_max_size_horizontal(). The
+ * description of its behaviour can be derived from that function's
+ * documentation.
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ */
+EAPI void evas_object_box_layout_homogeneous_max_size_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the box @a o to a @b flow horizontal box.
+ *
+ * In a flow horizontal box, the box's child elements are placed in
+ * @b rows (think of text as an analogy). A row has as much elements as
+ * can fit into the box's width. The box's overall behavior is
+ * controlled by its properties, which are set by the
+ * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of
+ * functions. The size hints of the elements in the box -- set by the
+ * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions
+ * -- also control the way this function works.
+ *
+ * @par Box's properties:
+ * @c padding_h tells the box to draw empty spaces of that size, in
+ * pixels, between the child objects' cells. @c align_h dictates the
+ * horizontal alignment of the rows (@c 0.0 to left align them, @c 1.0
+ * to right align). A value of @c -1.0 to @c align_h lets the rows
+ * @b justified horizontally. @c align_v controls the vertical alignment
+ * of the entire set of rows (@c 0.0 to top, @c 1.0 to bottom). A
+ * value of @c -1.0 to @c align_v makes the box to @b justify the rows
+ * vertically. The padding between them, in this case, is corrected so
+ * that the first row touches the top border and the last one touches
+ * the bottom border (even if they must overlap). @c padding_v has no
+ * influence on the layout.
+ *
+ * @par Child element's properties:
+ * @c padding_l and @c padding_r sum up to the required width of the
+ * child element. The @c align_x property has no influence on the
+ * layout. The child's @c padding_t and @c padding_b sum up to the
+ * required height of the child element and is the only means (besides
+ * row justifying) of setting space between rows. Note, however, that
+ * @c align_y dictates positioning relative to the <b>largest
+ * height</b> required by a child object in the actual row.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ */
+EAPI void evas_object_box_layout_flow_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the box @a o to a @b flow vertical box.
+ *
+ * @details This function behaves analogously to
+ * evas_object_box_layout_flow_horizontal(). The description of its
+ * behaviour can be derived from that function's documentation.
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ *
+ * @since_tizen 2.3
+ *
+ */
+EAPI void evas_object_box_layout_flow_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the box @a o to a @b stacking box.
+ *
+ * In a stacking box, all children are given the same size -- the
+ * box's own size -- and they are stacked one above the other, so
+ * that the first object in @a o's internal list of child elements
+ * are the bottommost in the stack.
+ *
+ * @par Box's properties:
+ * No box properties are used.
+ *
+ * @par Child element's properties:
+ * @c padding_l and @c padding_r sum up to the required width of the
+ * child element. The @c align_x property tells the relative position
+ * of this overall child width in its allocated cell (@c 0.0 to
+ * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to @c
+ * align_x makes the box try to resize this child element to the exact
+ * width of its cell (respecting the min and max hints on the child's
+ * width and accounting for its horizontal padding properties). The
+ * same applies to the vertical axis.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The box object in question
+ * @param[in] priv The smart data of the @a o
+ * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any
+ */
+EAPI void evas_object_box_layout_stack(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets the alignment of the whole bounding box of contents, for a
+ * given box object.
+ *
+ * @details This influences how a box object is to align its bounding box
+ * of contents within its own area. The values @b must be in the range
+ * @c 0.0 - @c 1.0, or undefined behavior is expected. For horizontal
+ * alignment, @c 0.0 means to the left, with @c 1.0 meaning to the
+ * right. For vertical alignment, @c 0.0 means to the top, with @c 1.0
+ * meaning to the bottom.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The default values for both alignments is @c 0.5.
+ *
+ * @param[in] o The given box object to set alignment from
+ * @param[in] horizontal The horizontal alignment, in pixels
+ * @param[in] vertical The vertical alignment, in pixels
+ *
+ * @see evas_object_box_align_get()
+ */
+EAPI void evas_object_box_align_set(Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the alignment of the whole bounding box of contents, for a
+ * given box object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The given box object to get alignment from
+ * @param[out] horizontal The pointer to a variable where to store the
+ * horizontal alignment
+ * @param[out] vertical The pointer to a variable where to store the vertical alignment
+ *
+ * @see evas_object_box_align_set() for more information
+ */
+EAPI void evas_object_box_align_get(const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the (space) padding between cells set for a given box object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The default values for both padding components is @c 0.
+ *
+ * @param[in] o The given box object to set padding from
+ * @param[in] horizontal The horizontal padding, in pixels
+ * @param[in] vertical The vertical padding, in pixels
+ *
+ * @see evas_object_box_padding_get()
+ */
+EAPI void evas_object_box_padding_set(Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the (space) padding between cells set for a given box object.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The given box object to get padding from
+ * @param[out] horizontal The pointer to a variable where to store the
+ * horizontal padding
+ * @param[out] vertical The pointer to a variable where to store the vertical padding
+ *
+ * @see evas_object_box_padding_set()
+ */
+EAPI void evas_object_box_padding_get(const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Appends a new @a child object to the given box object @a o.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks On success, the @c "child,added" smart event takes place.
+ *
+ * @remarks The actual placing of the item relative to the area of @a o
+ * depends on the layout set to it. For example, on horizontal layouts
+ * an item in the end of the box's list of children appear on its right.
+ *
+ * @remarks This call triggers the box's _Evas_Object_Box_Api::append
+ * smart function.
+ *
+ * @param[in] o The given box object
+ * @param[in] child A child Evas object to be made a member of @a o
+ * @return A box option bound to the recently added box item, \n
+ * otherwise @c NULL on errors
+ */
+EAPI Evas_Object_Box_Option *evas_object_box_append(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Prepends a new @a child object to the given box object @a o.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks On success, the @c "child,added" smart event takes place.
+ *
+ * @remarks The actual placing of the item relative to the area of @a o
+ * depends on the layout set to it. For example, on horizontal layouts
+ * an item in the beginning of the box's list of children appear
+ * on its left.
+ *
+ * @remarks This call triggers the box's
+ * _Evas_Object_Box_Api::prepend smart function.
+ *
+ * @param[in] o The given box object
+ * @param[in] child A child Evas object to be made a member of @a o
+ * @return A box option bound to the recently added box item, \n
+ * otherwise @c NULL on errors
+ */
+EAPI Evas_Object_Box_Option *evas_object_box_prepend(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Inserts a new @a child object <b>before another existing one</b>, in
+ * a given box object @a o.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks On success, the @c "child,added" smart event takes place.
+ *
+ * @remarks This function fails if @a reference is not a member of @a o.
+ *
+ * @remarks The actual placing of the item relative to the area of @a o
+ * depends on the layout set to it.
+ *
+ * @remarks This call triggers the box's
+ * _Evas_Object_Box_Api::insert_before smart function.
+ *
+ * @param[in] o The given box object
+ * @param[in] child A child Evas object to be made a member of @a o
+ * @param[in] reference The child object to place this new one before
+ * @return A box option bound to the recently added box item, \n
+ * otherwise @c NULL on errors
+ */
+EAPI Evas_Object_Box_Option *evas_object_box_insert_before(Evas_Object *o, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1, 2, 3);
+
+/**
+ * @brief Inserts a new @a child object <b>after another existing one</b>, in
+ * a given box object @a o.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks On success, the @c "child,added" smart event takes place.
+ *
+ * @remarks This function fails if @a reference is not a member of @a o.
+ *
+ * @remarks The actual placing of the item relative to the area of @a o
+ * depends on the layout set to it.
+ *
+ * @remarks This call triggers the box's
+ * _Evas_Object_Box_Api::insert_after smart function.
+ *
+ * @param[in] o The given box object
+ * @param[in] child A child Evas object to be made a member of @a o
+ * @param[in] reference The child object to place this new one after
+ * @return A box option bound to the recently added box item, \n
+ * otherwise @c NULL on errors
+ */
+EAPI Evas_Object_Box_Option *evas_object_box_insert_after(Evas_Object *o, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1, 2, 3);
+
+/**
+ * @brief Inserts a new @a child object <b>at a given position</b>, in a given
+ * box object @a o.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks On success, the @c "child,added" smart event takes place.
+ *
+ * @remarks This function fails if the given position is invalid,
+ * given the internal list of elements of @a o.
+ *
+ * @remarks The actual placing of the item relative to the area of @a o
+ * depends on the layout set to it.
+ *
+ * @remarks This call triggers the box's
+ * _Evas_Object_Box_Api::insert_at smart function.
+ *
+ * @param[in] o The given box object
+ * @param[in] child A child Evas object to be made a member of @a o
+ * @param[in] pos The numeric position (starting from @c 0) to place the
+ * new child object at
+ * @return A box option bound to the recently added box item, \n
+ * otherwise @c NULL on errors
+ */
+EAPI Evas_Object_Box_Option *evas_object_box_insert_at(Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes a given object from a box object, unparenting it again.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks On removal, you get an unparented object again, just as it is
+ * before you inserted it in the box. The
+ * _Evas_Object_Box_Api::option_free box smart callback is called
+ * automatically for you and, also, the @c "child,removed" smart event
+ * takes place.
+ *
+ * @remarks This call triggers the box's _Evas_Object_Box_Api::remove
+ * smart function.
+ *
+ * @param[in] o The box object to remove a child object from
+ * @param[in] child The handle to the child object to be removed
+ * @return #EINA_TRUE if the object is removed from the box object successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_box_remove(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes an object, <b>bound to a given position</b> in a box object,
+ * unparenting it again.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks On removal, you get an unparented object again, just as it is
+ * before you inserted it in the box. The @c option_free() box smart
+ * callback is called automatically for you and, also, the
+ * @c "child,removed" smart event takes place.
+ *
+ * @remarks This function fails if the given position is invalid,
+ * given the internal list of elements of @a o.
+ *
+ * @remarks This call triggers the box's
+ * _Evas_Object_Box_Api::remove_at smart function.
+ *
+ * @param[in] o The box object to remove a child object from
+ * @param[in] pos The numeric position (starting from @c 0) of the child
+ * object to be removed
+ * @return #EINA_TRUE if the object is removed successfully,
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_box_remove_at(Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Removes @b all child objects from a box object, unparenting them again.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This has the same effect of calling evas_object_box_remove() on
+ * each of @a o's child objects, in sequence. If, and only if, all
+ * those calls succeed, so does this one.
+ *
+ * @param[in] o The box object to remove a child object from
+ * @param[in] clear Set #EINA_TRUE to delete the just removed children, \n
+ * otherwise set #EINA_FALSE to not delete the children
+ * @return #EINA_TRUE if the child objects are removed successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_box_remove_all(Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets an iterator to walk the list of children of a given box object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Do @b not remove or delete objects while walking the list.
+ *
+ * @param[in] o The box to retrieve an items iterator from
+ * @return An iterator on @a o's child objects, \n
+ * otherwise @c NULL on errors
+ */
+EAPI Eina_Iterator *evas_object_box_iterator_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets an accessor (a structure providing random items access) to the
+ * list of children of a given box object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Do not remove or delete objects while walking the list.
+ *
+ * @param[in] o The box to retrieve an items iterator from
+ * @return An accessor on @a o's child objects, \n
+ * otherwise @c NULL on errors
+ */
+EAPI Eina_Accessor *evas_object_box_accessor_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets the list of children objects in a given box object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The returned list should be freed with @c eina_list_free() when you
+ * no longer need it.
+ *
+ * @remarks This is a duplicate of the list kept by the box internally.
+ * It is up to the user to destroy it when it no longer needs it.
+ * It is possible to remove objects from the box when walking
+ * this list, but these removals are not reflected on it.
+ *
+ * @param[in] o The box to retrieve an items list from
+ * @return A list of @a o's child objects, \n
+ * otherwise @c NULL on errors or if it has no child objects
+ */
+EAPI Eina_List *evas_object_box_children_get(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets the name of the property of the child elements of the box @a o
+ * which have @a id as identifier.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This call does not do anything for a canonical Evas box. Only
+ * users which have @b subclassed it, setting custom box items options
+ * (see #Evas_Object_Box_Option) on it, would benefit from this
+ * function. They would have to implement it and set it to be the
+ * _Evas_Object_Box_Api::property_name_get smart class function of the
+ * box, which is originally set to @c NULL.
+ *
+ * @param[in] o The box to search child options from
+ * @param[in] property The numerical identifier of the option being searched,
+ * for its name
+ * @return The name of the given property, \n
+ * otherwise @c NULL on errors
+ */
+EAPI const char *evas_object_box_option_property_name_get(const Evas_Object *o, int property) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the numerical identifier of the property of the child elements
+ * of the box @a o which have @a name as name string.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This call does not do anything for a canonical Evas box. Only
+ * users which have @b subclassed it, setting custom box items options
+ * (see #Evas_Object_Box_Option) on it, would benefit from this
+ * function. They would have to implement it and set it to be the
+ * _Evas_Object_Box_Api::property_id_get smart class function of the
+ * box, which is originally set to @c NULL.
+ *
+ * @param[in] o The box to search child options from
+ * @param[in] name The name string of the option being searched, for its ID
+ * @return The numerical ID of the given property, \n
+ * otherwise @c -1 on errors
+ */
+EAPI int evas_object_box_option_property_id_get(const Evas_Object *o, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets a property value (by its given numerical identifier), on a
+ * given box child element
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This call does not do anything for a canonical Evas box. Only
+ * users which have @b subclassed it, setting custom box items options
+ * (see #Evas_Object_Box_Option) on it, would benefit from this
+ * function. They would have to implement it and set it to be the
+ * _Evas_Object_Box_Api::property_set smart class function of the box,
+ * which is originally set to @c NULL.
+ *
+ * @remarks This function internally creates a variable argument
+ * list, with the values passed after @a property, and call
+ * evas_object_box_option_property_vset() with this list and the same
+ * previous arguments.
+ *
+ * @param[in] o The box parenting the child element
+ * @param[in] opt The box option structure bound to the child box element
+ * to set a property on
+ * @param[in] property The numerical ID of the given property
+ * @param[in] ... (List of) actual value(s) to be set for this property \n
+ * It (they) @b must be of the same type the user has
+ * defined for it (them).
+ * @return #EINA_TRUE if the property value is set successfully,
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_box_option_property_set(Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Sets a property value (by its given numerical identifier), on a
+ * given box child element -- by a variable argument list
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a variable argument list variant of the
+ * evas_object_box_option_property_set(). See its documentation for
+ * more details.
+ *
+ * @param[in] o The box parenting the child element
+ * @param[in] opt The box option structure bound to the child box element
+ * to set a property on
+ * @param[in] property The numerical ID of the given property
+ * @param[in] args The variable argument list implementing the value to
+ * be set for this property. It @b must be of the same type the user has
+ * defined for it.
+ * @return #EINA_TRUE if teh property value is set successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_box_option_property_vset(Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets a property's value (by its given numerical identifier), on a
+ * given box child element.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This call does not do anything for a canonical Evas box. Only
+ * users which have @b subclassed it, getting custom box items options
+ * (see #Evas_Object_Box_Option) on it, would benefit from this
+ * function. They would have to implement it and get it to be the
+ * _Evas_Object_Box_Api::property_get smart class function of the
+ * box, which is originally get to @c NULL.
+ *
+ * @remarks This function internally creates a variable argument
+ * list, with the values passed after @a property, and call
+ * evas_object_box_option_property_vget() with this list and the same
+ * previous arguments.
+ *
+ * @param[in] o The box parenting the child element
+ * @param[in] opt The box option structure bound to the child box element
+ * to get a property from
+ * @param[in] property The numerical ID of the given property
+ * @param[in] ... (List of) pointer(s) where to store the value(s) set for this property, \n
+ * It (they) @b must point to variable(s) of the same type the user
+ * has defined for it (them).
+ * @return #EINA_TRUE if the property values are obtained successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_box_option_property_get(const Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Gets a property's value (by its given numerical identifier), on a
+ * given box child element -- by a variable argument list
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a variable argument list variant of the
+ * evas_object_box_option_property_get(). See its documentation for
+ * more details.
+ *
+ * @param[in] o The box parenting the child element
+ * @param[in] opt The box option structure bound to the child box element
+ * to get a property from
+ * @param[in] property The numerical ID of the given property
+ * @param[in] args The variable argument list with pointers to where to
+ * store the values of this property \n
+ * They @b must point to variables
+ * of the same type the user has defined for them.
+ * @return #EINA_TRUE if the property values are obtained successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_box_option_property_vget(const Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Table Table Smart Object.
+ * @ingroup Evas_Smart_Object_Group
+ *
+ * @brief This group provides functions for table smart objects.
+ *
+ * @remarks Convenience smart object that packs children using a tabular
+ * layout using children size hints to define their size and
+ * alignment inside their cell space.
+ *
+ * @see @ref Evas_Object_Group_Size_Hints
+ *
+ * @{
+ */
+
+/**
+ * @brief Creates a new table.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] evas The canvas in which table are added
+ * @return The new table object
+ */
+EAPI Evas_Object *evas_object_table_add(Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Creates a table that is child of a given element @a parent.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] parent The parent element
+ * @return The new table object
+ *
+ * @see evas_object_table_add()
+ */
+EAPI Evas_Object *evas_object_table_add_to(Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Sets how this table should layout children.
+ *
+ * @todo consider aspect hint and respect it.
+ *
+ * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE
+ * If table does not use homogeneous mode then columns and rows
+ * are calculated based on hints of individual cells. This operation
+ * mode is more flexible, but more complex and heavy to calculate as
+ * well. @b Weight properties are handled as a boolean expand. Negative
+ * alignment is considered as @c 0.5. This is the default.
+ *
+ * @todo @c EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE should balance weight.
+ *
+ * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE
+ * When homogeneous is relative to table, the own table size is divided
+ * equally among children, filling the whole table area. That is, if
+ * table has @c WIDTH and @c COLUMNS, each cell gets <tt>WIDTH /
+ * COLUMNS</tt> pixels. If children have minimum size that is larger
+ * than this amount (including padding), then it overflows and is
+ * aligned respecting the alignment hint, possible overlapping sibling
+ * cells. @b Weight hint is used as a boolean, if greater than zero it
+ * makes the child expand in that axis, taking as much space as
+ * possible (bounded to maximum size hint). Negative alignment is
+ * considered as @c 0.5.
+ *
+ * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM
+ * When homogeneous is relative to item, it means the greatest minimum
+ * cell size is used. That is, if no element is set to expand,
+ * the table has its contents to a minimum size, the bounding
+ * box of all these children is aligned relatively to the table
+ * object using evas_object_table_align_get(). If the table area is
+ * too small to hold this minimum bounding box, then the objects
+ * keep their size and the bounding box overflows the box area,
+ * still respecting the alignment. @b Weight hint is used as a
+ * boolean, if greater than zero it makes that cell expand in that
+ * axis, toggling the <b>expand mode</b>, which makes the table behave
+ * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the
+ * bounding box overflows and items do not overlap siblings. If
+ * no minimum size is provided at all then the table fallsback to
+ * expand mode as well.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The table object
+ * @param[in] homogeneous The homogeneous mode
+ */
+EAPI void evas_object_table_homogeneous_set(Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the current layout homogeneous mode.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The table object
+ * @return The homogeneous mode
+
+ * @see evas_object_table_homogeneous_set()
+ */
+EAPI Evas_Object_Table_Homogeneous_Mode evas_object_table_homogeneous_get(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets padding between cells.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The table object
+ * @param[in] horizontal The horizontal padding to set
+ * @param[in] vertical The vertical padding to set
+ *
+ */
+EAPI void evas_object_table_padding_set(Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets padding between cells.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The table object
+ * @param[out] horizontal The horizontal padding that is obtained
+ * @param[out] vertical The vertical padding that is obtained
+ */
+EAPI void evas_object_table_padding_get(const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the alignment of the whole bounding box of contents.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The table object
+ * @param[in] horizontal The horizontal alignment to set
+ * @param[in] vertical The vertical alignment to set
+ */
+EAPI void evas_object_table_align_set(Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the alignment of the whole bounding box of contents.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The table object
+ * @param[out] horizontal The horizontal alignment that is obtained
+ * @param[out] vertical The vertical alignment that is obtained
+ */
+EAPI void evas_object_table_align_get(const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the mirrored mode of the table.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * remarks In mirrored mode the table items go from right to left instead of left to right.
+ * That is, 1,1 is top right, not top left.
+ *
+ * @param[in] o The table object
+ * @param[in] mirrored The mirrored mode to set
+ */
+EAPI void evas_object_table_mirrored_set(Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the mirrored mode of the table.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The table object
+ * @return #EINA_TRUE if it is a mirrored table, \n
+ * otherwise #EINA_FALSE if it is not a mirrored table
+ * @see evas_object_table_mirrored_set()
+ */
+EAPI Eina_Bool evas_object_table_mirrored_get(const Evas_Object *o) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets packing location of a child of table.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The given table object
+ * @param[in] child The child object to add
+ * @param[out] col The pointer to store relative-horizontal position to place child
+ * @param[out] row The pointer to store relative-vertical position to place child
+ * @param[out] colspan The pointer to store how many relative-horizontal position to use for this child
+ * @param[out] rowspan The pointer to store how many relative-vertical position to use for this child
+ *
+ * @return #EINA_TRUE if the packing location is obtained successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_table_pack_get(const Evas_Object *o, Evas_Object *child, unsigned short *col, unsigned short *row, unsigned short *colspan, unsigned short *rowspan);
+
+/**
+ * @brief Adds a new child to a table object or set its current packing.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The given table object
+ * @param[in] child The child object to add
+ * @param[in] col The relative-horizontal position to place the child
+ * @param[in] row The relative-vertical position to place the child
+ * @param[in] colspan The number of relative-horizontal position to use for this child
+ * @param[in] rowspan The number of relative-vertical position to use for this child
+ * @return #EINA_TRUE if the new child is added successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_table_pack(Evas_Object *o, Evas_Object *child, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes child from table.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Removing a child immediately calls a walk over children in order
+ * to recalculate the numbers of columns and rows. If you plan to remove
+ * all children, use evas_object_table_clear() instead.
+ *
+ * @param[in] o The given table object
+ * @param[in] child The child object to remove
+ * @return #EINA_TRUE if the child is removed successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_table_unpack(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes all child objects from a table object.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a faster way to remove the child objects.
+ *
+ * @param[in] o The given table object
+ * @param[in] clear Set #EINA_TRUE to delete the just removed children, \n
+ * otherwise set #EINA_FALSE to not delete the removed children
+ */
+EAPI void evas_object_table_clear(Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the number of columns and rows this table takes.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The columns and rows are virtual entities, one can specify a table
+ * with a single object that takes 4 columns and 5 rows. The only
+ * difference for a single cell table is that paddings are
+ * accounted proportionally.
+ *
+ * @param[in] o The table object
+ * @param[out] cols The number of columns
+ * @param[out] rows The number of rows
+ */
+EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets an iterator to walk through the list of children for the table.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Do not remove or delete objects while walking the list.
+ *
+ * @param[in] o The table object
+ * @return An iterator to walk through the children of the object, \n
+ * otherwise @c NULL in case of errors
+ */
+EAPI Eina_Iterator *evas_object_table_iterator_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets an accessor to get random access to the list of children for the table.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Do not remove or delete objects while walking the list.
+ *
+ * @param[in] o The table object
+ * @return An accessor on @a o's child objects, \n
+ * otherwise @c NULL in case of errors
+ */
+EAPI Eina_Accessor *evas_object_table_accessor_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets the list of children for the table.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a duplicate of the list kept by the table internally.
+ * It is up to the user to destroy it when it no longer needs it.
+ * It is possible to remove objects from the table when walking this
+ * list, but these removals are not reflected on it.
+ *
+ * @param[in] o The table object
+ * @return The list of the children, \n
+ * otherwise @c NULL in case of errors
+ */
+EAPI Eina_List *evas_object_table_children_get(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets the child of the table at the given coordinates.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This does not take into account col or row spanning.
+ *
+ * @param[in] o The table object
+ * @param[in] col The number of columns
+ * @param[in] row The number of rows
+ * @return A child of the table object
+ */
+EAPI Evas_Object *evas_object_table_child_get(const Evas_Object *o, unsigned short col, unsigned short row) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Object_Grid Grid Smart Object.
+ * @ingroup Evas_Smart_Object_Group
+ *
+ * @brief This group provides functions for grid smart objects.
+ * @since 1.1
+ *
+ * @remarks Convenience smart object that packs children under a regular grid
+ * layout, using their virtual grid location and size to determine
+ * children's positions inside the grid object's area.
+ *
+ * @{
+ */
+
+/**
+ * @brief Creates a new grid.
+ *
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks It is set to a virtual size of 1x1 by default and add children with
+ * evas_object_grid_pack().
+ *
+ * @param[in] evas The given evas
+ * @return The new grid object
+ */
+EAPI Evas_Object *evas_object_grid_add(Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Creates a grid that is child of a given element @a parent.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] parent The parent element
+ * @return The new grid object
+ *
+ * @see evas_object_grid_add()
+ */
+EAPI Evas_Object *evas_object_grid_add_to(Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Sets the virtual resolution for the grid.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The grid object to modify
+ * @param[in] w The virtual horizontal size (resolution) in integer units
+ * @param[in] h The virtual vertical size (resolution) in integer units
+ */
+EAPI void evas_object_grid_size_set(Evas_Object *o, int w, int h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the current virtual resolution.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The grid object to query
+ * @param[out] w A pointer to an integer to store the virtual width
+ * @param[out] h A pointer to an integer to store the virtual height
+ * @see evas_object_grid_size_set()
+ */
+EAPI void evas_object_grid_size_get(const Evas_Object *o, int *w, int *h) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Sets the mirrored mode of the grid.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks In mirrored mode the grid items go from right to left
+ * instead of left to right. That is, 0,0 is top right, not to left.
+ *
+ * @param[in] o The grid object
+ * @param[in] mirrored The mirrored mode to set
+ */
+EAPI void evas_object_grid_mirrored_set(Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the mirrored mode of the grid.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The grid object
+ * @return #EINA_TRUE if it is a mirrored grid, \n
+ * otherwise #EINA_FALSE if it is not a mirrored grid
+ *
+ * @see evas_object_grid_mirrored_set()
+ */
+EAPI Eina_Bool evas_object_grid_mirrored_get(const Evas_Object *o) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Adds a new child to a grid object.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] o The given grid object
+ * @param[in] child The child object to add
+ * @param[in] x The virtual x coordinate of the child
+ * @param[in] y The virtual y coordinate of the child
+ * @param[in] w The virtual width of the child
+ * @param[in] h The virtual height of the child
+ * @return #EINA_TRUE if the child is added successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_grid_pack(Evas_Object *o, Evas_Object *child, int x, int y, int w, int h) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes child from grid.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Removing a child immediately calls a walk over children in order
+ * to recalculate numbers of columns and rows. If you plan to remove
+ * all children, use evas_object_grid_clear() instead.
+ *
+ * @param[in] o The given grid object
+ * @param[in] child The child object to remove
+ * @return #EINA_TRUE if the child is removed successfully, \n
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_grid_unpack(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes all child objects from a grid object.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a faster way to remove all child objects.
+ *
+ * @param[in] o The given grid object
+ * @param[in] clear Set #EINA_TRUE to delete the just removed children, \n
+ * otherwise set #EINA_FALSE to not delete them
+ */
+EAPI void evas_object_grid_clear(Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the pack options for a grid child.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Gets the pack x, y, width and height in virtual coordinates set by
+ * evas_object_grid_pack().
+ *
+ * @param[in] o The grid object
+ * @param[in] child The grid child to query for coordinates
+ * @param[out] x The pointer to where the x coordinate to be returned
+ * @param[out] y The pointer to where the y coordinate to be returned
+ * @param[out] w The pointer to where the width to be returned
+ * @param[out] h The pointer to where the height to be returned
+ * @return #EINA_TRUE if the pack options are obtained successfully,
+ * otherwise #EINA_FALSE on failure
+ */
+EAPI Eina_Bool evas_object_grid_pack_get(const Evas_Object *o, Evas_Object *child, int *x, int *y, int *w, int *h);
+
+/**
+ * @brief Gets an iterator to walk the list of children for the grid.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Do not remove or delete objects while walking the list.
+ *
+ * @param[in] o The grid object
+ * @return An iterator to walk through the children of the object, \n
+ * otherwise @c NULL in case of errors
+ */
+EAPI Eina_Iterator *evas_object_grid_iterator_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets an accessor to get random access to the list of children for the grid.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Do not remove or delete objects while walking the list.
+ *
+ * @param[in] o The grid object
+ * @return An accessor to get random access to the list of children for the grid, \n
+ * otherwise @c NULL in case of errors
+ */
+EAPI Eina_Accessor *evas_object_grid_accessor_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @brief Gets the list of children for the grid.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is a duplicate of the list kept by the grid internally.
+ * It is up to the user to destroy it when it no longer needs it.
+ * It is possible to remove objects from the grid when walking this
+ * list, but these removals are not reflected on it.
+ *
+ * @param[in] o The grid object
+ * @return The list of children for the grid
+ */
+EAPI Eina_List *evas_object_grid_children_get(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Cserve Shared Image Cache Server
+ * @ingroup Evas
+ *
+ * @brief This group provides functions for shared image cache server
+ *
+ * Evas has an (optional) module which provides client-server
+ * infrastructure to <b>share bitmaps across multiple processes</b>,
+ * saving data and processing power.
+ *
+ * Be warned that it @b does not work when <b>threaded image
+ * preloading</b> is enabled for Evas, though.
+ *
+ * @{
+ */
+typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats;
+typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache;
+typedef struct _Evas_Cserve_Image Evas_Cserve_Image;
+typedef struct _Evas_Cserve_Config Evas_Cserve_Config;
+
+/**
+ * @brief The structure type containing the statistics about the server that shares cached bitmaps.
+ */
+struct _Evas_Cserve_Stats
+{
+ int saved_memory; /**< The current amount of saved memory, in bytes */
+ int wasted_memory; /**< The current amount of wasted memory, in bytes */
+ int saved_memory_peak; /**< The peak amount of saved memory, in bytes */
+ int wasted_memory_peak; /**< The peak amount of wasted memory, in bytes */
+ double saved_time_image_header_load; /**< The time, in seconds, saved in header loads by sharing cached loads instead */
+ double saved_time_image_data_load; /**< The time, in seconds, saved in data loads by sharing cached loads instead */
+};
+
+/**
+ * @brief The structure type containing a handle of a cache of images shared by a server.
+ */
+struct _Evas_Cserve_Image_Cache
+{
+ struct
+ {
+ int mem_total;
+ int count;
+ } active, cached;
+ Eina_List *images;
+};
+
+/**
+ * @brief The structure type containing a handle to an image shared by a server.
+ */
+struct _Evas_Cserve_Image
+{
+ const char *file, *key;
+ int w, h;
+ time_t file_mod_time;
+ time_t file_checked_time;
+ time_t cached_time;
+ int refcount;
+ int data_refcount;
+ int memory_footprint;
+ double head_load_time;
+ double data_load_time;
+ Eina_Bool alpha : 1;
+ Eina_Bool data_loaded : 1;
+ Eina_Bool active : 1;
+ Eina_Bool dead : 1;
+ Eina_Bool useless : 1;
+};
+
+/**
+ * @brief The structure type containing the configuration that controls the server that shares cached bitmaps.
+ */
+struct _Evas_Cserve_Config
+{
+ int cache_max_usage;
+ int cache_item_timeout;
+ int cache_item_timeout_check;
+};
+
+/**
+ * @brief Checks whether the system shares bitmaps using the server.
+ *
+ * @since_tizen 2.3
+ *
+ * @return #EINA_TRUE if the system shares bitmaps using the server, \n
+ * otherwise #EINA_FALSE if the system does not share bitmaps
+ */
+EAPI Eina_Bool evas_cserve_want_get(void) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Checks whether the system is connected to the server used to share bitmaps.
+ *
+ * @since_tizen 2.3
+ *
+ * @return #EINA_TRUE if the system is connected to the server, \n
+ * otherwise #EINA_FALSE if it is not connected
+ */
+EAPI Eina_Bool evas_cserve_connected_get(void) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Gets the statistics from a running bitmap sharing server.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] stats The pointer to the structure to fill the statistics about the
+ * bitmap cache server
+ * @return #EINA_TRUE if @a stats is filled with data, \n
+ * otherwise #EINA_FALSE when @a stats is untouched
+ */
+EAPI Eina_Bool evas_cserve_stats_get(Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Completely discards or cleans a given images cache, thus re-setting it.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] cache A handle to the given images cache
+ */
+EAPI void evas_cserve_image_cache_contents_clean(Evas_Cserve_Image_Cache *cache);
+
+/**
+ * @brief Gets the current configuration of the Evas image caching server.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The fields of @a config are altered to reflect the current
+ * configuration's values.
+ *
+ * @param[in] config The current image caching server's configuration
+ *
+ * @return #EINA_TRUE if @a config is filled with data, \n
+ * otherwise #EINA_FALSE when @a config is untouched
+ *
+ * @see evas_cserve_config_set()
+ */
+EAPI Eina_Bool evas_cserve_config_get(Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Sets the configurations of the Evas image caching server.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] config A bitmap cache configuration handle with fields set
+ * to desired configuration values
+ * @return #EINA_TRUE if @a config is applied successfully,
+ * otherwise #EINA_FALSE
+ *
+ * @see evas_cserve_config_get()
+ */
+EAPI Eina_Bool evas_cserve_config_set(const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Forces the system to disconnect from the bitmap caching server.
+ *
+ * @since_tizen 2.3
+ */
+EAPI void evas_cserve_disconnect(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Utils General Utilities
+ * @ingroup Evas
+ * @brief This group provides general utilities functions.
+ * @remarks Some functions that are handy but are not specific to canvas or objects.
+ *
+ * @{
+ */
+
+/**
+ * @brief Converts the given Evas image load error code into a string
+ * describing it in English.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Mostly evas_object_image_file_set() would be the function setting
+ * that error value afterwards, but also evas_object_image_load(),
+ * evas_object_image_save(), evas_object_image_data_get(),
+ * evas_object_image_data_convert(), evas_object_image_pixels_import()
+ * and evas_object_image_is_inside(). This function is meant to be
+ * used in conjunction with evas_object_image_load_error_get(), as in:
+ *
+ * @remarks The following is an example code:
+ * @skip img1 =
+ * @until ecore_main_loop_begin(
+ *
+ * @remarks Here, @c valid_path is the path to a valid image and @c
+ * bogus_path is a path to a file which does not exist. The two outputs
+ * of evas_load_error_str() would be (if no other errors occur):
+ * <code>"No error on load"</code> and <code>"File (or file path) does
+ * not exist"</code>, respectively.
+ *
+ *
+ * @param[in] error The error code \n
+ * A value in #Evas_Load_Error.
+ * @return A valid string \n
+ * If the given @a error is not supported, <code>"Unknown error"</code> is returned.
+ */
+EAPI const char *evas_load_error_str(Evas_Load_Error error);
+
+/* Evas utility routines for color space conversions */
+/* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
+/* rgb color space has r,g,b in the range 0 to 255 */
+
+/**
+ * @brief Converts a given color from HSV to RGB format.
+ *
+ * @details This function converts a given color in HSV color format to RGB
+ * color format.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] h The Hue component of the color
+ * @param[in] s The Saturation component of the color
+ * @param[in] v The Value component of the color
+ * @param[out] r The Red component of the color
+ * @param[out] g The Green component of the color
+ * @param[out] b The Blue component of the color
+ **/
+EAPI void evas_color_hsv_to_rgb(float h, float s, float v, int *r, int *g, int *b);
+
+/**
+ * @brief Converts a given color from RGB to HSV format.
+ *
+ * @details This function converts a given color in RGB color format to HSV
+ * color format.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] r The Red component of the color
+ * @param[in] g The Green component of the color
+ * @param[in] b The Blue component of the color
+ * @param[out] h The Hue component of the color
+ * @param[out] s The Saturation component of the color
+ * @param[out] v The Value component of the color
+ **/
+EAPI void evas_color_rgb_to_hsv(int r, int g, int b, float *h, float *s, float *v);
+
+/* argb color space has a,r,g,b in the range 0 to 255 */
+
+/**
+ * @brief Pre-multiplies a rgb triplet by an alpha factor.
+ * @details This function pre-multiplies a given rgb triplet by an alpha
+ * factor. Alpha factor is used to define transparency.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] a The alpha factor
+ * @param[out] r The Red component of the color
+ * @param[out] g The Green component of the color
+ * @param[out] b The Blue component of the color
+ **/
+EAPI void evas_color_argb_premul(int a, int *r, int *g, int *b);
+
+/**
+ * @brief Undoes pre-multiplication of a rgb triplet by an alpha factor.
+ *
+ * @details This function undoes pre-multiplication a given rbg triplet by an
+ * alpha factor. Alpha factor is used to define transparency.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] a The alpha factor
+ * @param[out] r The Red component of the color
+ * @param[out] g The Green component of the color
+ * @param[out] b The Blue component of the color
+ *
+ * @see evas_color_argb_premul().
+ **/
+EAPI void evas_color_argb_unpremul(int a, int *r, int *g, int *b);
+
+/**
+ * @brief Pre-multiplies data by an alpha factor.
+ * @details This function pre-multiplies a given data by an alpha
+ * factor. Alpha factor is used to define transparency.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data The data value
+ * @param[in] len The length value
+ **/
+EAPI void evas_data_argb_premul(unsigned int *data, unsigned int len);
+
+/**
+ * @brief Undoes pre-multiplication data by an alpha factor.
+ *
+ * @details This function undoes the pre-multiplication of a given data by an alpha
+ * factor. Alpha factor is used to define transparency.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data The data value
+ * @param[in] len The length value
+ **/
+EAPI void evas_data_argb_unpremul(unsigned int *data, unsigned int len);
+
+/**
+ * @internal
+ * @remarks Tizen only feature
+ * @remarks TIZEN_ONLY(20140822): Added evas_bidi_direction_hint_set, get APIs and applied to textblock, text.
+ * @brief Set BiDi direction hint to the given evas canvas.
+ *
+ * @details Evas has a BiDi direction hint value which affect to textblock, text object.
+ * If a text that has only neutral BiDi direction is set to textblock or text,
+ * the BiDi direction hint will be used to decide alignment of paragraphs.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] dir The BiDi direction hint
+ **/
+EAPI void evas_bidi_direction_hint_set(Evas *e, Evas_BiDi_Direction dir);
+
+/**
+ * @internal
+ * @remarks Tizen only feature
+ * @remarks TIZEN_ONLY(20140822): Added evas_bidi_direction_hint_set, get APIs and applied to textblock, text.
+ * @brief Get BiDi direction hint of the given evas canvas.
+ *
+ * @details Evas has a BiDi direction hint value which affect to textblock, text object.
+ * If a text that has only neutral BiDi direction is set to textblock or text,
+ * the BiDi direction hint will be used to decide alignment of paragraphs.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @return BiDi direction hint
+ *
+ * @see evas_bidi_direction_hint_set().
+ **/
+EAPI Evas_BiDi_Direction evas_bidi_direction_hint_get(Evas *e);
+
+
+/* string and font handling */
+
+/**
+ * @brief Gets the next character in the string.
+ *
+ * @remarks Given the UTF-8 string in @a str, and starting byte position in @a pos,
+ * this function places in @a decoded the decoded code point at @a pos
+ * and return the byte index for the next character in the string.
+ * The only boundary check done is that @a pos must be >= 0. Other than that,
+ * no checks are performed, so passing an index value that is not within the
+ * length of the string results in undefined behavior.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] str The UTF-8 string
+ * @param[in] pos The byte index where to start
+ * @param[out] decoded The address to store the decoded code point \n
+ * This is optional.
+ * @return The byte index of the next character
+ */
+EAPI int evas_string_char_next_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the previous character in the string
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Given the UTF-8 string in @a str, and starting byte position in @a pos,
+ * this function places in @a decoded the decoded code point at @a pos
+ * and return the byte index for the previous character in the string.
+ *
+ * @remarks The only boundary check done is that @a pos must be >= 1. Other than that,
+ * no checks are performed, so passing an index value that is not within the
+ * length of the string results in undefined behavior.
+ *
+ * @param[in] str The UTF-8 string
+ * @param[in] pos The byte index where to start
+ * @param[out] decoded The address where to store the decoded code point \n
+ * This is optional.
+ * @return The byte index of the previous character
+ */
+EAPI int evas_string_char_prev_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the length in characters of the string.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] str The string to get the length of
+ * @return The length in characters (not bytes)
+ */
+EAPI int evas_string_char_len_get(const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Evas_Keys Key Input Functions
+ * @ingroup Evas_Canvas
+ *
+ * @brief This group provides functions which feed key events to the canvas.
+ *
+ * Evas is @b not aware of input
+ * systems at all. Then, the user, if using it crudely (evas_new()),
+ * has to feed it with input events, so that it can react
+ * somehow. If, however, the user creates a canvas by means of the
+ * Ecore_Evas wrapper, it automatically binds the chosen display
+ * engine's input events to the canvas, for you.
+ *
+ * This group presents the functions dealing with the feeding of key
+ * events to the canvas. On most of them, one has to reference a given
+ * key by a name (<code>keyname</code> argument). Those are
+ * <b>platform dependent</b> symbolic names for the keys. Sometimes
+ * you get the right <code>keyname</code> by simply using an ASCII
+ * value of the key name, but it is not like that always.
+ *
+ * Typical platforms are Linux frame buffer (Ecore_FB) and X server
+ * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
+ * to your display engine's documentation when using evas through an
+ * Ecore helper wrapper when you need the <code>keyname</code>s.
+ *
+ * @{
+ */
+
+/**
+ * @brief Gets a handle to the list of modifier keys registered in the canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is required to check for which modifiers are set
+ * at a given time with the evas_key_modifier_is_set() function.
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @return An Evas_Modifier handle to query Evas' keys subsystem with evas_key_modifier_is_set(), \n
+ * otherwise @c NULL on error
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_del
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set
+ */
+EAPI const Evas_Modifier *evas_key_modifier_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets a handle to the list of lock keys registered in the canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is required to check for which locks are set at a given
+ * time with the evas_key_lock_is_set() function.
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @return An Evas_Lock handle to query Evas' keys subsystem with evas_key_lock_is_set(), \n
+ * otherwise @c NULL on error
+ *
+ * @see evas_key_lock_add
+ * @see evas_key_lock_del
+ * @see evas_key_lock_on
+ * @see evas_key_lock_off
+ * @see evas_key_lock_is_set
+ *
+ */
+EAPI const Evas_Lock *evas_key_lock_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Checks whether a given modifier key is set at the time of the call.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the modifier is set, such as shift being pressed, this
+ * function returns @c Eina_True.
+ *
+ * @param[in] m The current modifiers set, as returned by evas_key_modifier_get()
+ * @param[in] keyname The name of the modifier key to check status for
+ * @return #EINA_TRUE if the modifier key named @a keyname is on, \n
+ * otherwise #EINA_FALSE if the modifier key is not on
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_del
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ */
+EAPI Eina_Bool evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Checks whether the given lock key is set at the time of the call.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the lock is set, such as caps lock, this function returns @c Eina_True.
+ *
+ * @param[in] l The current locks set, as returned by evas_key_lock_get()
+ * @param[in] keyname The name of the lock key to check status for
+ * @return #EINA_TRUE if the @a keyname lock key is set, \n
+ * otherwise @c Eina_False if the lock key is not set
+ *
+ * @see evas_key_lock_get
+ * @see evas_key_lock_add
+ * @see evas_key_lock_del
+ * @see evas_key_lock_on
+ * @see evas_key_lock_off
+ */
+EAPI Eina_Bool evas_key_lock_is_set(const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Adds the @a keyname key to the current list of modifier keys.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Modifiers are keys like shift, alt and ctrl, that is, keys which are
+ * meant to be pressed together with others, altering the behavior of
+ * the secondly pressed keys somehow. Evas allows these keys to be
+ * user defined.
+ *
+ * @remarks This call allows custom modifiers to be added to the Evas system at
+ * run time. It is then possible to set and unset modifier keys
+ * programmatically for other parts of the program to check and act
+ * on. Programmers using Evas would check for modifier keys on key
+ * event callbacks using evas_key_modifier_is_set().
+ *
+ * @remarks If you instantiate the canvas by means of the
+ * ecore_evas_new() family of helper functions, Ecore takes
+ * care of registering on it all standard modifiers: "Shift",
+ * "Control", "Alt", "Meta", "Hyper", "Super".
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] keyname The name of the modifier key to add to the list of
+ * Evas modifiers
+ *
+ * @see evas_key_modifier_del
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set
+ *
+ */
+EAPI void evas_key_modifier_add(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes the @a keyname key from the current list of modifier keys
+ * on canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] keyname The name of the key to remove from the modifiers list
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set
+ */
+EAPI void evas_key_modifier_del(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Adds the @a keyname key to the current list of lock keys.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Locks are keys like caps lock, num lock or scroll lock, that is, keys
+ * which are meant to be pressed once -- toggling a binary state which
+ * is bound to it -- and thus altering the behavior of all
+ * subsequently pressed keys somehow, depending on its state. Evas is
+ * so that these keys can be defined by the user.
+ *
+ * @remarks This allows custom locks to be added to the evas system at run
+ * time. It is then possible to set and unset lock keys
+ * programmatically for other parts of the program to check and act
+ * on. Programmers using Evas would check for lock keys on key event
+ * callbacks using evas_key_lock_is_set().
+ *
+ * @remarks If you instantiate the canvas by means of the
+ * ecore_evas_new() family of helper functions, Ecore takes
+ * care of registering on it all standard lock keys: "Caps_Lock",
+ * "Num_Lock", "Scroll_Lock".
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] keyname The name of the key to add to the locks list
+ *
+ * @see evas_key_lock_get
+ * @see evas_key_lock_del
+ * @see evas_key_lock_on
+ * @see evas_key_lock_off
+ * @see evas_key_lock_is_set
+ */
+EAPI void evas_key_lock_add(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes the @a keyname key from the current list of lock keys on
+ * canvas @a e.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] keyname The name of the key to remove from the locks list
+ *
+ * @see evas_key_lock_get
+ * @see evas_key_lock_add
+ * @see evas_key_lock_on
+ * @see evas_key_lock_off
+ */
+EAPI void evas_key_lock_del(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Enables or turns on programmatically the modifier key with name @a keyname.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The effect is as if the key is pressed for the whole time
+ * between this call and a matching evas_key_modifier_off().
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] keyname The name of the modifier to enable
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set
+ */
+EAPI void evas_key_modifier_on(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Disables or turns off programmatically the modifier key with name @a keyname.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] keyname The name of the modifier to disable
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_is_set
+ */
+EAPI void evas_key_modifier_off(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Enables or turns on programmatically the lock key with name @a keyname.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The effect is as if the key is put on its active state after
+ * this call.
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] keyname The name of the lock to enable
+ *
+ * @see evas_key_lock_get
+ * @see evas_key_lock_add
+ * @see evas_key_lock_del
+ * @see evas_key_lock_off
+ */
+EAPI void evas_key_lock_on(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Disables or turns off programmatically the lock key with name @a keyname.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The effect is as if the key is put on its inactive state
+ * after this call.
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] keyname The name of the lock to disable
+ *
+ * @see evas_key_lock_get
+ * @see evas_key_lock_add
+ * @see evas_key_lock_del
+ * @see evas_key_lock_on
+ */
+EAPI void evas_key_lock_off(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Creates a bit mask from the @a keyname @b modifier key.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Values returned from different calls to it may be ORed together,
+ * naturally.
+ *
+ * @remarks This function is meant to be used in conjunction with
+ * evas_object_key_grab()/evas_object_key_ungrab(). See their
+ * documentation for more information.
+ *
+ * @param[in] e The canvas to query the bit mask from
+ * @param[in] keyname The name of the modifier key to create the mask for
+ * @returns The bit mask or @c 0 if the @a keyname key is not registered as a
+ * modifier for canvas @a e
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set
+ * @see evas_object_key_grab
+ * @see evas_object_key_ungrab
+ */
+EAPI Evas_Modifier_Mask evas_key_modifier_mask_get(const Evas *e, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Requests @a keyname key events be directed to @a obj.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Key grabs allow one or more objects to receive key events for
+ * specific key strokes even if other objects have focus. Whenever a
+ * key is grabbed, only the objects grabbing it gets the events
+ * for the given keys.
+ *
+ * @remarks @a keyname is a platform dependent symbolic name for the key
+ * pressed (see @ref Evas_Keys for more information).
+ *
+ * @remarks @a modifiers and @a not_modifiers are bit masks of all the
+ * modifiers that must and must not, respectively, be pressed along
+ * with @a keyname key in order to trigger this new key
+ * grab. Modifiers can be things such as Shift and Ctrl as well as
+ * user defined types via evas_key_modifier_add(). Retrieve them with
+ * evas_key_modifier_mask_get() or use @c 0 for empty masks.
+ *
+ * @remarks @a exclusive makes the given object the only one permitted to
+ * grab the given key. If given #EINA_TRUE, subsequent calls on this
+ * function with different @a obj arguments it fails, unless the key
+ * is ungrabbed again.
+ *
+ * @remarks Providing impossible modifier sets creates undefined behavior.
+ *
+ * @param[in] obj The object to direct @a keyname events to
+ * @param[in] keyname The key to request events for
+ * @param[in] modifiers A mask of modifiers that must be present to
+ * trigger the event
+ * @param[in] not_modifiers A mask of modifiers that must @b not be present
+ * to trigger the event
+ * @param[in] exclusive Set #EINA_TRUE to request that the @a obj is the only object
+ * receiving the @a keyname events, \n
+ * otherwise set #EINA_FALSE
+ * @return #EINA_TRUE if the call succeeded, \n
+ * otherwise #EINA_FALSE on failure
+ *
+ * @see evas_object_key_ungrab
+ * @see evas_object_focus_set
+ * @see evas_object_focus_get
+ * @see evas_focus_get
+ * @see evas_key_modifier_add
+ */
+EAPI Eina_Bool evas_object_key_grab(Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers, Eina_Bool exclusive) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Removes the grab on @a keyname key events by @a obj.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Removes a key grab on @a obj if @a keyname, @a modifiers,
+ * and @a not_modifiers match.
+ *
+ * @param[in] obj The object that has an existing key grab
+ * @param[in] keyname The key the grab is set for
+ * @param[in] modifiers A mask of modifiers that must be present to
+ * trigger the event
+ * @param[in] not_modifiers A mask of modifiers that must not be
+ * present to trigger the event
+ *
+ * @see evas_object_key_grab
+ * @see evas_object_focus_set
+ * @see evas_object_focus_get
+ * @see evas_focus_get
+ */
+EAPI void evas_object_key_ungrab(Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Evas_Touch_Point_List Touch Point List Functions
+ * @ingroup Evas_Canvas
+ *
+ * @brief This group provides functions to get information of touched points in the Evas.
+ *
+ * @remarks Evas maintains list of touched points on the canvas. Each point has
+ * its co-ordinates, ID and state. You can get the number of touched
+ * points and information of each point using evas_touch_point_list functions.
+ *
+ * @{
+ */
+
+/**
+ * @brief Gets the number of touched point in the evas.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks New touched point is added to the list whenever touching the evas
+ * and point is removed whenever removing touched point from the evas.
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * int count;
+ *
+ * count = evas_touch_point_list_count(evas);
+ * printf("The count of touch points: %i\n", count);
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @return The number of touched point on the evas
+ *
+ * @see evas_touch_point_list_nth_xy_get()
+ * @see evas_touch_point_list_nth_id_get()
+ * @see evas_touch_point_list_nth_state_get()
+ */
+EAPI unsigned int evas_touch_point_list_count(Evas *e) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the nth touch point's co-ordinates.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Touch point's co-ordinates is updated whenever moving that point
+ * on the canvas.
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * Evas_Coord x, y;
+ *
+ * if (evas_touch_point_list_count(evas))
+ * {
+ * evas_touch_point_nth_xy_get(evas, 0, &x, &y);
+ * printf("The first touch point's co-ordinate: (%i, %i)\n", x, y);
+ * }
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] n The number of the touched point (0 being the first)
+ * @param[out] x The pointer to a Evas_Coord to be filled in
+ * @param[out] y The pointer to a Evas_Coord to be filled in
+ *
+ * @see evas_touch_point_list_count()
+ * @see evas_touch_point_list_nth_id_get()
+ * @see evas_touch_point_list_nth_state_get()
+ */
+EAPI void evas_touch_point_list_nth_xy_get(Evas *e, unsigned int n, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the @a id of nth touch point.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The point which comes from Mouse Event has @a id 0 and The point
+ * which comes from Multi Event has @a id that is same as Multi
+ * Event's device ID.
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * int id;
+ *
+ * if (evas_touch_point_list_count(evas))
+ * {
+ * id = evas_touch_point_nth_id_get(evas, 0);
+ * printf("The first touch point's id: %i\n", id);
+ * }
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] n The number of the touched point (@c 0 being the first)
+ * @return The ID of nth touch point, \n
+ * otherwise @c -1
+ *
+ * @see evas_touch_point_list_count()
+ * @see evas_touch_point_list_nth_xy_get()
+ * @see evas_touch_point_list_nth_state_get()
+ */
+EAPI int evas_touch_point_list_nth_id_get(Evas *e, unsigned int n) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Gets the @a state of nth touch point.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The point's @a state is EVAS_TOUCH_POINT_DOWN when pressed,
+ * EVAS_TOUCH_POINT_STILL when the point is not moved after pressed,
+ * EVAS_TOUCH_POINT_MOVE when moved at least once after pressed and
+ * EVAS_TOUCH_POINT_UP when released.
+ *
+ * @remarks The following is an example:
+ * @code
+ * extern Evas *evas;
+ * Evas_Touch_Point_State state;
+ *
+ * if (evas_touch_point_list_count(evas))
+ * {
+ * state = evas_touch_point_nth_state_get(evas, 0);
+ * printf("The first touch point's state: %i\n", state);
+ * }
+ * @endcode
+ *
+ * @param[in] e The pointer to the Evas canvas
+ * @param[in] n The number of the touched point (@c 0 being the first)
+ * @return @a state of nth touch point, \n
+ * otherwise EVAS_TOUCH_POINT_CANCEL
+ *
+ * @see evas_touch_point_list_count()
+ * @see evas_touch_point_list_nth_xy_get()
+ * @see evas_touch_point_list_nth_id_get()
+ */
+EAPI Evas_Touch_Point_State evas_touch_point_list_nth_state_get(Evas *e, unsigned int n) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
#ifdef __cplusplus
}
#endif